Re: [OT] Re: how do i make my program better?

[Tollef Fog Heen <tollef@add.no>]

* An Thi-Nguyen Le 

| On Sun, Nov 19, 2000 at 02:12:29PM +0100, Tollef Fog Heen typed:
| } | I use man pages all the time.  Maybee for strictly GUI programs man
| } | pages are less usefull, certainly not useless though.  for CLI man
| } | pages are a must.
| } 
| } And if you write them in docbook or texinfo they aren't just man pages
| } - they can easily be converted into other kinds of documentation.
| 
| There's a tool called Rosetta Man, or rman, that converts manpages to
| html and other formats.  Yes, there are navigation links to each section,
| and navigation links to other manpages.  Groff can also convert a manpage
| to postscript or text.  So what's the problem?

Asking out of curiosity:  Is rman reliable?

| Just because something is written in texinfo or docbook doesn't mean 
| it's the epitome of good documentation either.  There are good manpages 
| out there, and there are horrible (and the worst part is that it's long 
| AND horrible AND has a useless index) info pages out there.  C'est la vie.

By all means - I'm not saying that man pages are useless - far from
it.  And I don't say that having documentation as info or docbook
automatically makes it better. (And you didn't say that I did :)

 But docbook (which is the thing I've been using the most) RefEntries
allows one to put in lots of _structured_ information, which makes it
possible to automatically process the man pages in a much wider way
than whats possible to do reliably with plain man pages.  Suppose I'd
like to make a book (both online and on paper) with all the man pages
on my system.  This is easier to do than to parse man pages with a
program.  Computers are bad at increasing the amount of information in
a document, but very good at reducing it.

The whole point here is the right to choose - if you want everything
lumped together in one big man page, be my guest.  If somebody wants
this as info documents - that's their call.  If somebody wants to have
it as HTML..  I think you get the idea.

| I want a pager like less when I read my docs, or possibly reed if I
| have time.  I'm also not going to be very fond of docbook output at
| this stage.

Not even if you get the output of docbook as a man page?

-- 

Tollef Fog Heen
Unix _IS_ user friendly... It's just selective about who its friends are.