Splitting large pages to smaller ones

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

Hello.

Any opinions about splitting large manual pages to several smaller ones?

I recall a debate about this some time ago, but can't recall the resolution
(if any). Examples where this might apply: kauth(9), ukfs(9), fileassoc(9),
and uvm(9).

Few points:

        1. The manual page format lends itself badly to anything bigger than
           three or four pages. This is especially evident when a page is
           viewed from a terminal and the content is mostly discussion
           around function prototypes. $PAGER has also poor search
           capabilities, etc.

        2. I have personally tried to follow a format where there is a
           single introductory page with references to the actual functions
           and other technical details. In my opinion this works well. And
           of course this format appears also in some older pages; take
           stdio(3) as an example. It is also the format used by the
           standard committees such as the Open Group (POSIX).

        3. If pages are small, it is possible to follow the standard manual
           page format; function prototypes appear in the synopsis and not
           in the body of the text, etc. This should also ensure that proper
           links are build for the functions (in the big pages it is a rule
           rather than an exception that some links are missing).

I am inclined to think that (1) is supported by some human (pedagogical?)
condition. An analogy: if you are writing a tough math book, you ought to
give the reader room to breath between the equations and derivations.

- Jukka.