manpages v.s. info v.s. html...(was Re: [TCLUG:15481] Faeriedist)

[chewie@wookimus.net]

On Tue, Apr 04, 2000 at 03:34:35PM -0500, Luke Francl wrote:
> Personally, I agree with you, but the man vs info issue is an interesting
> one. info is nice because it's hypertext, which is _very_ helpfully for
> documentations (how often to you find yourself starting and restarting man
> sessions cross referencing documentation?). info pages provide functionality
> that man pages never can. Also, if you are familiar with Emacs, info pages
> allow you to interface with yet another part of your computer via Emacs. If
> you notice who wrote all the man pages which say "This man page is no longer
> maintained. Please read the info pages", they are all from the FSF, the
> bigest proponents of Emacs. In their view, info supercedes man.

You can bring this argument one step further.  Everything that you install
should have the source for the manpages, HOWTO's, and such written in SGML
DocBook or in a format that can be used to generate the man pages, HTML
reference, info pages, etc.

The fact of the matter is this.  Not all software is written by hard-core
developers, and not all package maintainers are meticulous.  Some software
developers don't even comment their code well, and we expect them to write man
pages or SGML documents?  Why should Joe Package Maintainer have to write all
of the manuals and documentation for a software he simply wants to distribute
in binary format?  These are arguments that you will receive about this type of
movement.  Regardless, if you're a package maintainer or developer, you should
give serious thought to SGML-like document tools for generating all of the
necessary documentation.

----------------------------------------------------------------
Chad Walstrom                         mailto:chewie@wookimus.net 
a.k.a ^chewie, gunnarr                http://wookimus.net/chewie

   Gnupg: B4AB D627 9CBD 687E 7A31  1950 0CC7 0B18 206C 5AFD
----------------------------------------------------------------