libinn documentation ideas?

[Todd Olson]

Hi Russ

At 18:40 -0800 2001/02/07, Russ Allbery wrote:
>Does anyone have a good idea on how to document the various bits of libinn
>in terms of installable man pages?  If I just write something called
>error(3) or hashtab(3) for some of the stuff in libinn, it's almost
>certain to conflict with other installed header files, but having man
>pages for the various functions insofar as I can find time to write them
>or other people contribute them would help people developing new bits of
>INN quite a bit.
>
>Should we use something like inn_error(3) or libinn_error(3)?  That gets
>kind of ugly and long.

I like the model used by perl
     perl(1)   gives a table of contents
then you have things like

     perlrun
     perlop
     perlfunc
     perltoot

etc

Since the original sin of man(1) ... of having a flat name space ...
appears to have never been fixed, I think the only realistic and
usable option is perl's model.


Of course perl goes further in provided a separate utility that
lets you specify a function/module/etc  and it will find the place
in the man page for you ....  but perhaps inn does not have to go
just yet.

>
>Having one really long libinn(3) man page seems less than ideal.

most certainly.

>
>-- 
>Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>