Re: CVS commit: src/lib/libc/stdio

[Jukka Ruohonen <jruohonen%iki.fi@localhost>]

On Wed, May 05, 2010 at 01:03:49PM +1000, Luke Mewburn wrote:
> I disagree; a list of all the public APIs for a given library in
> the main man page for that library is very useful.

One more note I have made while skimming through the manual pages.

Few examples of pages that are badly and *systematically* behind:

        intro(3)
        intro(4)
        pci(4)
        usb(4)
        mk.conf(5)
        sysctl(7)
        
All of these are a nightmare to maintain.

From these, sysctl(7) is probably the only one where I see value in having
the list; perhaps mk.conf(5) too, if there would not be "bsd.README" where
everything is duplicated.

Otherwise, given the resources we have for documentation, we should try to
do our best to avoid clearly more or less unmaintainable documentation, no
matter how nice it would be in the ideal case, IMHO. A good example is a
listing where things are directly and manually cut-and-pasted from a header
file; this is destined to always play a catch-up with the changes in the
actual code.

- Jukka.