Re: writing man pages or texinfo documentation
Michael Bacarella wrote:
> On Tue, 25 May 1999, Adam Sampson wrote:
>
> > Info isn't exactly ideal. Why not use a different solution, as we're
> > starting over?
>
> Yes. If it's supposed to be a NEW system, why repeat the past? Even if it
> is just placeholder, people will expect it to be there and that will just
> make it harder to move away from when we decide "cool, let's innovate!"
>
> > As everybody knows how to use "The Web", why not use SGML as the "standard"
> > documentation format? That way, we can convert to HTML for interactive
> > info-style viewing using Lynx, Netscape or another browser of choice (or fo
r
> > Web publishing, obviously), we can produce a printable version, and we can
> > produce a flat-text version that "man" could show using a pager.
>
> I agree. Wholeheartedly. Although I probably would've suggested HTML.
> (Because of my ignorance [What's SGML?])
The DocBook SGML application would be preferable to the HTML SGML application
because DocBook is *considerably* more expressive.
HTML may be acceptable for creating mishmashes of web pages; with DocBook,
there are additional tags to actually provide considerable additional
document structure.
Moving to HTML would significantly diminish the expressiveness of
documentation in comparison to TeXinfo, because TeXinfo provides the
ability to provide sorts of references that HTML can't.
> I like the idea of reading documentation via lynx, which is well
> established and just plain cool. Plus, the HTML leaves room to do nicer
> formatting for the manual, and even (gasp) introduce modern topics such as
> color and pictures! :) That is.. if it plans on being used outside of
> a basic text output environment.
"Nicer formatting" is one of the reasons to go with TeXinfo. You can use
TeXinfo to produce quite decently structured *books.* With a table of
contents. Index. *Very* nicely formatted and typeset.
> I also like the idea of easily centralizing such a thing and leaving it on
> a web server residing at, for example manual.cyberdyne.net . Out of all
> of the things that a web server can send back to the browser, it'll
> probably understand HTML with the least difficulty.
>
> Yea, fine, lynx lacks some features, but I can tell you right now I'm not
> going to sit down and try to figure out "yet another text presentation
> scheme" like info just to read documentation. Especially if the investment
> of time will only benefit me on the GNU system. I'm not the only one.
If the tools exist, and in the case of DocBook, they are maturing
nicely, it's worth it.
I would certainly approve of the notion of documenting Hurd using
DocBook.
I may, of course, be biased; my web site is one giant DocBook document
2.7MB in size, which expands into over 3MB of HTML. Maintaining links
between portions of it without an SGML parser to help me validate it
would be an absolute *nightmare.* The move from HTML to SGML was a
*big* improvement.
--
Christopher B. Browne, cbbrowne@hex.net, chris_browne@sabre.com
Web: http://www.ntlug.org/~cbbrowne/ SAP Basis Consultant, UNIX Guy
Windows NT - How to make a 100 MIPS Linux workstation perform like an 8 MHz 286
Reply to: