Hi Branden and Ingo!Per the request of Branden that I should discourage programmers of writing their manuals with subchapters, which fundamentally means discouraging programmers of writing their libraries (or modules, or whatever a given language uses) in a way that you can't document a header in a single page, I wrote the following introductory page intro(3type).
The caveat that you'll read should go either in all intro([23]\w+) pages. We could put it in the main section into pages too. I want to hear some opinions about this.
I used temporarily the term [sub]chapter to see how it fits.
Cheers,
Alex
---
intro(3type) intro(3type)
NAME
intro - introduction to library types
DESCRIPTION
Subchapter 3type of the manual describes the types pro‐
vided by C libraries.
CAVEATS
The separation of chapter 3 of this manual into subchap‐
ters is only a consequence of the organization in the
Standard C Library. Probably, a better design for a li‐
brary would be such that each header file is minimal, and
contains only one or a few APIs, and the types and con‐
stants that are intrinsic to that API. Types and con‐
stants that are to be used by many APIs can go in sepa‐
rate header files that provide no APIs. That organiza‐
tion permits writing manual pages that document exactly
one header file per manual page, which will improve the
readability of the documentation, and thereby the usabil‐
ity of the software.
SEE ALSO
intro(3)
Linux man‐pages (unreleased) (date) intro(3type)
--
<http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
