Another update on the undocument stuff
Hi All,
The more manpages I drop on the list the response I get. Please
continue. ".BI" was suggested by Dirk and Someone else suggested to
include a reference to the mini-Howto on how to write manpages (but
stupid me deleted that mailmessage and don't know who deserves the
credits, please mail me again).
I would like to suggest another change as well. In the mini-Howto I
found out about the source mechanism:
3) symbolic links pointing to the actual man page.
4) use groff's `source' mechanism provided by the `.so' macro.
[snap]
all man pages so that they can be displayed more quickly.) The third
alternative has a slight drawback: if flexibility is a concern, you
have to be aware that there are file systems that do not support
symbolic links. The upshot of this is that the Best Thing (TM) is
using groff's source mechanism.
Here's how to do it:
If you want to have your man page available under the names `foo' and
`bar' in section 1, then put the man page in foo.1 and have bar.1 look
like this:
.so man1/foo.1
It is important to specify the `man1/' directory part as well as the
file name `foo.1' because when groff is run by the browser it will
have the manual base directory as its current working directory (cwd)
and groff interprets .so arguments relative to the cwd.
Last time proposal:
Proposal for convention: If no manual page is available for a
particular program and this is reported as a bug on debian-bugs, the
package maintainer may/should add a symbolic link from the requested
manpage to this undocumented one in the package containing the
particular program or a related package.
from /usr/man/man[1-9]
ln -s ../man7/undocumented.7 requested_man_page.[1-9]
or from /usr/X11R6/man/man[1-9]
ln -s ../../../man/man7/undocumented.7 requested_man_page.[1-9]
--
Would it be better to use the source mechanism as described above? Is
this a waste of diskspace, i.e. is a symbolic link consuming less
diskspace than one tiny file?
With the source mechanism we could include the bugreport number with
the manpage like this:
./" Reported as bug#???? on debian-bugs@pixar.com
.so man7/undocumented.7
Erick
PS: formatted output and source included.
NAME
undocumented - No manpage for this program, utility or
function.
DESCRIPTION
This program, utility or function does not have a useful
manpage. Please do not report this as a bug, because this
has already been reported as a bug; when a manpage becomes
available it will be included, and the bug report closed
<http://www.debian.org/Bugs/>.
If you are a competent and accurate writer and are willing
to spend the time reading the source code and writing good
manpages please write a better man page than this one.
Please contact the package maintainer in order to avoid
several people working on the same manpage. More informa-
tion on how to write manpages can be found in
/usr/doc/HOWTO/mini/Man-Page.gz (package: doc-linux).
Try the following options if you want more information.
foo --help
foo -h
foo -?
info foo
whatis foo
apropos foo
check directories /usr/doc/foo, /usr/doc/examples/foo,
/usr/lib/foo
dpkg --listfiles foo
dpkg --search foo
locate '*foo*'
find / -name '*foo*'
If you still didn't find the information you are looking
for you might consider posting a call for help to debian-
user@pixar.com.
AUTHOR
Erick Branderhorst <branderhorst@heel.fgg.eur.nl>.
THANKS
Someone who suggested to include a reference to Man-
Page.gz mini-Howto, Dirk Eddelbuettel, Kai Henningsen, Ian
Jackson, David H. Silber, Carl Streeter.
SEE ALSO
info(1), whatis(1), apropos(1), dpkg(8), locate(1),
find(1), updatedb(1), undocumented(2).
source:
.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\"
.\" Copyright (C) 1996 Erick Branderhorst <branderhorst@heel.fgg.eur.nl>
.\"
.\" This is free software; you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation; either version 2, or (at your option) any later
.\" version.
.\"
.\" This is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License with
.\" your Debian GNU/Linux system, in /usr/doc/copyright/GPL, or with the
.\" dpkg source package as the file COPYING. If not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\" This manpage is created thanks to:
.\" Someone who suggested to include a reference to Man-Page.gz mini-Howto
.\" (but I deleted the mailmessage too quickly and now I don't
.\" know who it was, stupid me. Please mail me again).
.\" Dirk Eddelbuettel <edd@qed.econ.queensu.ca>,
.\" Kai Henningsen <kai@khms.westfalen.de>,
.\" Ian Jackson <iwj10@cus.cam.ac.uk>,
.\" David H. Silber <dhs@firefly.com> &
.\" Carl Streeter <streeter@cae.wisc.edu>.
.\"
.TH undocumented 7 "13th February 1996" "Debian Project" "Debian GNU/Linux"
.SH NAME
undocumented \- No manpage for this program, utility or function.
.SH DESCRIPTION
This
.B program, utility
or
.B function
does not have a useful manpage. Please do
.B not
report this as a bug, because this has already been reported as a bug;
when a manpage becomes available it will be included, and the bug
report closed <\c
.I http://www.debian.org/Bugs/\c
>.
If you are a competent and accurate writer and are willing to spend
the time reading the source code and writing good manpages please
write a better man page than this one. Please
.B contact
the
.B package maintainer
in order to avoid several people working on the same manpage. More
information on how to write manpages can be found in
.I /usr/doc/HOWTO/mini/Man-Page.gz
(package: doc-linux).
Try the following options if you want more information.
.BI foo " \-\-help"
.BI foo " \-h"
.BI foo " \-?"
.BI info " foo"
.BI whatis " foo"
.BI apropos " foo"
check directories /usr/doc/foo, /usr/doc/examples/foo, /usr/lib/foo
.BI "dpkg \-\-listfiles" " foo"
.BI "dpkg \-\-search" " foo"
.BI locate " '*foo*'"
.BI "find / \-name" " '*foo*'"
If you still didn't find the information you are looking for you might
consider posting a call for help to debian-user@pixar.com.
.SH AUTHOR
Erick Branderhorst <branderhorst@heel.fgg.eur.nl>.
.SH THANKS
Someone who suggested to include a reference to Man-Page.gz mini-Howto,
Dirk Eddelbuettel,
Kai Henningsen,
Ian Jackson,
David H. Silber,
Carl Streeter.
.SH "SEE ALSO"
.BR info (1),
.BR whatis (1),
.BR apropos (1),
.BR dpkg (8),
.BR locate (1),
.BR find (1),
.BR updatedb (1),
.BR undocumented (2).
--
Erick Branderhorst@heel.fgg.eur.nl +31-10-4635142
Department of General Surgery (Intensive Care) University Hospital Rotterdam NL
Reply to: