diff options
author | Alejandro Colomar <alx@kernel.org> | 2022-12-11 18:17:00 +0100 |
---|---|---|
committer | Alejandro Colomar <alx@kernel.org> | 2022-12-12 12:26:50 +0100 |
commit | ef7434ef53ee3b40a70e72a4e3814bcf6721dd09 (patch) | |
tree | 29668d292e1240420a8f0c761544672ddaf74664 | |
parent | b27acc76d5f3e33a0a9a831132e9a8efbc3034bd (diff) |
intro.3: Document subsections of man3
Cowritten-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ingo Schwarze <schwarze@openbsd.org>
Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
-rw-r--r-- | man3/intro.3 | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/man3/intro.3 b/man3/intro.3 index ce0d6e294..b08eca5ac 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -64,6 +64,37 @@ For further information on feature test macros, see .\" .IP (3X) .\" Various special libraries. The manual pages documenting their functions .\" specify the library names. +.SS Subsections +Section 3 of this manual is organized into subsections +that reflect the complex structure of the standard C library +and its many implementations: +.IP \(bu 3 +3const +.IP \(bu +3head +.IP \(bu +3type +.PP +This difficult history frequently makes it a poor example to follow +in design, implementation, and presentation. +.PP +Ideally, +a library for the C language +is designed such that each header file +presents the interface to a coherent software module. +It provides a small number of function declarations +and exposes only data types and constants that +are required for use of those functions. +Together, +these are termed an API or +.IR "application program interface" . +Types and constants to be shared among multiple APIs +shopuld be placed in header files that declare no functions. +This organization permits a C library module +to be documented concisely with one header file per manual page. +Such an approach +improves the readability and accessibility of library documentation, +and thereby the usability of the software. .SH STANDARDS Certain terms and abbreviations are used to indicate UNIX variants and standards to which calls in this section conform. |