Re: [Groff] RE: Simplifying groff documentation

[Michael(tm) Smith]

Peter Schaffter <address@hidden>, 2006-12-23 12:12 -0500:

> I don't see any problem with the proposal of DocBook XML as the
> source from which manpages are actually rendered--provided
> engines exist to render XML manpages *at the terminal* as well
> as groff does.

If you mean to render man pages from DocBook XML source on the
fly, in real time, then no such engine exists. Not a good one
at least -- and at least not for large documents. There is a
streaming processor that can do quick work (created by Fred
Dalrymple and modified by David Bolen), but the streaming nature
of it and other limitation make it not particularly useful for
rendering most real-world DocBook documents.

The manpages stylesheet in the DocBook Project XSLT stylesheets
distribution can handle most real-world DocBook documents but will
never be usable for on-the-fly rendering. It generally takes at
least 2 seconds to generate output, and sometimes significantly
longer. Part of the reason for that is that it's actually a
customization of the DocBook HTML stylesheets, and has to import
all of those (several megabytes worth) in order to run a
transformation (there are good reasons why it's made that way but
I don't think this is place to discuss them).

The process of generating output from DocBook sources is generally
done as a build, and the DocBook Project stylesheets were never
designed with the expectation that they'd be used for generating
output on the fly.

> Eric's Web-centric, fully- hypertexted
> documentation is the ideal, methinks, but not at the cost of
> losing the ability to type "man <whatever>" at the command line.

I think we could have a system in which man pages were stored on
local systems simply as HTML (which could be HTML originally
generated from DocBook or generated by some other means or even
just authored directly in HTML), and "man <whatever>" would just
cause a browser (be it a curses-based browser or a GUI one) to be
envoked and the page displayed in that.

  --Mike

-- 
Michael(tm) Smith
http://www.w3.org/People/Smith/