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.
