Re: man/info debate

[Sandy Harris <sandy@storm.ca>]

Matt Nelson wrote:
 
> is this the correct forum to discuss the problems with the current state
> of Linux documentation?

It is /a/ correct forum, quite likely the best one, but not the only one.
One other is the Open Source Writers' Group, http://www.oswg.org. This
topic was talked about in great detail on the oswg-discuss list some months
back. See their archives.

> as i see it, the fact that there are several
> methods used to document the OS is a big problem.

I quite agree.

> we have:
> 
>  - man
>  - Info
>  - GNOME help
>  - (there must be a KDE equivalent)
>  - HOWTO's, guides, etc.

which are SGML with at least two DTDs, likely some XML now or soon,
some HTML-only docs in the mini-HowTo section, ... This is being
dealt with, looks like it will come out just fine. DocBook will
become the standard there.

>  - /usr/doc miscellany

There's likely some Latex-only stuff around too, and with SGI, IBM
etc. starting to contribute to Linux, there'll be docs we want that
exist in whatever format they use. Framemaker, Interleaf, Word, ...  
 
> for new users in particular, this is a mess.  i learned Unix with man
> pages, but more and more, this returns "No manual entry for xxx".  if you
> use the GNOME help system, you have access to several types of
> documentation, but they are all segregated from one another, and the user
> interface, imho, is kinda klunky.  especially when compared to the speed
> at which you can bring up docs w/ man.
> 
> how about this for an idea:  make the content of ALL common documentation
> available to ALL common help interfaces.  how could this be done?  some
> ideas:
> 
>  - modify texinfo to generate man pages as well as info docs
>  - enhance info to deal w/ man pages
>  - develop a code to convert HTML docs into info and man pages

It is easier to go the other way. Convert everything to HTML.

There is already a useful man2html tool. For a sample of its
output, see:
http://www.freeswan.org/freeswan_trees/freeswan-1.5/doc/manpages.html

DocBook to HTML is standard. There's an info2html tool. ...

So put everything into HTML. People can then get at it with
standard browsers. Of course you can provide other output formats too,
whatever the input format and available tools allow, but HTML is the
only easy way to make everything available in one format.

The hard parts are indexing and cross-referencing. Other posts in the
thread deal with indexing and search tools.

I've got a small contribution. The tools that automatically generate
the permuted index in the FreeS/WAN docs:

http://www.freeswan.org/freeswan_trees/freeswan-1.5/doc/perm.html.html

are GPLd. They are far from production quality code, but might be a
decent starting point for better tools.

Cross-references are a whole other problem. As a start, put HTML
manual pages in a standard place and turn all the manpage references
in other docs into links to those. Likely references to HowTos
could be handled in a similar way.

Then there's the question of common reference material. Any large
Linux doc is going to need a glossary and most of them overlap.
Could we build a common glossary? A common bibliography? Methinks
a common list of web links would be too large and too volatile.

> and most important
> 
>  - start an effort to create comprehensive documentation packages in all
>    the formats,

This strikes me as a waste of time. Instead, concentrate on moving to
DocBook XML for new docs, and on building indexes for existing docs
converted to HTML.

> and
>  - convince the distro builders to include those packages
> 
> comments?  if this is the wrong forum, let me know and i'll go away.
>


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org