on Sun, Sep 02, 2001 at 01:44:45PM +0200, Cliff Sarginson (cliff@raggedclown.net) wrote:
> On Sun, Sep 02, 2001 at 11:49:11AM +0100, Colin Watson wrote:
> > On Sat, Sep 01, 2001 at 10:31:47PM +0800, Rino Mardo wrote:
> > > getting a little OT here but can all the man databases be converted to
> > > info files? what can a "python" newbie do or have to follow in order
> > > to do this?
> >
> > You might be able to do it, but then I'd have to kill you ;)
> >
> > Besides, the info client can read man pages already. Anything beyond
> > that can't be done automatically, as the style of info documents is
> > different to man pages (man pages go for simplicity and quick reference,
> > info documents are vast sprawling hypertext things).
> GNU is of course wonderful (seriously)
> But what insanity drove them to try and abandon man pages ? It
> remains the most eccentric of decisions. Info pages are great if you
> want to know all about something when you know little, but man pages
> are better when you need that quick reminder and do not want to tread
> through treacle first...
I asked Bradley Kuhn about this yesterday (didn't feel like broaching
the topic with RMS). It's also a topic that's been raised a few times
elsewhere.
First, Debian Policy states that packages should have manpages. So
there's a frontline response to the GNU position.
Bradley cited a number advantages of the Info format, largely: it's a
more complete, comprehensive, documentation source, and it's browseable
in a hypertext format.
The problem is that this is often specifically what is *not* sought by
those who are looking for manpages. What's wanted is a short, concise,
but illustrative reference providing:
- A functional description of the command.
- A synopsis of all options and/or switches for the command.
- EXAMPLES!!! Examples of (typical) usage are essential.
- Additional sections: FILES, SEE ALSO, BUGS, and AUTHOR, typically.
There is a utility to convert the man page equivalent portion of a
typical info page to something resembling manpage format.
Personally, I'd strongly recommend that the GNU project revisit the
issue of info pages altogether. They're not popular, they don't
adequately replace man pages, and there is a far more successful and
ubiquitous hypertext model (HTML) in use now. Moreover, the standard
info navigation keybindings (and even the simplified bindings offered by
tools such as pinfo) are neither ubiquitous, corrospondent to other SW
tools (emacs excepted), nor self evident.
There are other projects which have been suggested on a comprehensive
documentation front, one of the more interesting (if less motile) being
the META project initated by Rich Morin:
http://www.cfcl.com/rdm/Meta
The FSF needs to revisit this policy, specifically its GNU Coding
Standards recommendation that man pages be considered optional:
http://www.gnu.org/prep/standards_46.html#SEC46
Man Pages
In the GNU project, man pages are secondary. It is not necessary or
expected for every GNU program to have a man page, but some of them
do. It's your choice whether to include a man page in your program.
This I disagree with strongly.
When you make this decision, consider that supporting a man page
requires continual effort each time the program is changed. The time
you spend on the man page is time taken away from more useful work.
Specious: applies to any documentation.
For a simple program which changes little, updating the man page may
be a small job. Then there is little reason not to include a man
page, if you have one.
For a large program that changes a great deal, updating a man page
may be a substantial burden. If a user offers to donate a man page,
you may find this gift costly to accept. It may be better to refuse
the man page unless the same person agrees to take full
responsibility for maintaining it--so that you can wash your hands
of it entirely. If this volunteer later ceases to do the job, then
don't feel obliged to pick it up yourself; it may be better to
withdraw the man page from the distribution until someone else
agrees to update it.
This argument I consider to be highly problematic. A sufficiently
complex program isn't going to be well represented by a manpage, and is
going to require ancilary documentation in any event. In this case, an
info page is a good fit, but a man page, both covering essential
concepts and pointing to additional documentation, is quite helpful.
Even relatively complex systems (sed, awk, vi clones, and procmail come
to mind) can be relatively well addressed by man pages.
When a program changes only a little, you may feel that the
discrepancies are small enough that the man page remains useful
without updating. If so, put a prominent note near the beginning of
the man page explaining that you don't maintain it and that the
Texinfo manual is more authoritative. The note should say how to
access the Texinfo documentation.
In such a case, GNU should rethink its info process such that providing
a foundation, updated, man page is clearly provided for.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What part of "Gestalt" don't you understand? There is no K5 cabal
http://gestalt-system.sourceforge.net/ http://www.kuro5hin.org
Free Dmitry! Boycott Adobe! Repeal the DMCA! http://www.freesklyarov.org
Geek for Hire http://kmself.home.netcom.com/resume.html
Attachment:
pgpz2jkndkQ28.pgp
Description: PGP signature