* Sean O'Rourke <sorou...@cs.ucsd.edu> [2007-05-21 17:25]: > David Cantrell <da...@cantrell.org.uk> writes: > > The big problem with emacs is that it looks like that most > > unhelpful of "help" systems, GNU info. > > Meh, I personally prefer it to a wad of randomly-structured > HTML,
My ideal looks like this: * Manpage with usage/synopsis * For simple software, an overview/examples and full reference in the manpage * For anything complex, a brief reference in the manpage and narrative docs written in DocBook or something similar and rendered to HTML for perusal You can generate any number of other useful things out of DocBook, including PDF. As the sole format it would be hateful, but as an option for printing it's handy, and that is a nice thing to be able to do with docs for software complex enough to need a narrative manual. Needless to say, very few projects attain this level of perfection. The GNU crew openly *refuse* to produce docs you can actually use (with the sole and lonely exception of the Make manual -- the only tolerable Info doc I've ever seen). Regards, -- Aristotle Pagaltzis // <http://plasmasturm.org/>
