[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: man/info debate
I hope man pages don't go away. For a lot of things, I've found them to be
most useful since they display from the bash command line. The xman program
is effective, especially for looking at system calls and other library
documentation. If SGML/DocBook can do everything, including output man pages,
that would be the best. I still have a lot to learn about this stuff. I've
found that documentation software really is complex since there are some many
to deal with. It would be nice to know what is the best to use and stick with
it.
On Fri, 25 Aug 2000, Sandy Harris wrote:
> 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
--
-------- Robert B. Easter reaster@comptechnews.com ---------
- CompTechNews Message Board http://www.comptechnews.com/ -
- CompTechServ Tech Services http://www.comptechserv.com/ -
---------- http://www.comptechnews.com/~reaster/ ------------
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org