From: Alejandro Colomar Date: Sun, 11 Dec 2022 17:17:00 +0000 (+0100) Subject: intro.3: Document subsections of man3 X-Git-Tag: man-pages-6.02~24 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ef7434ef53ee3b40a70e72a4e3814bcf6721dd09;p=thirdparty%2Fman-pages.git intro.3: Document subsections of man3 Cowritten-by: "G. Branden Robinson" Cc: Ingo Schwarze Cc: Douglas McIlroy Signed-off-by: Alejandro Colomar --- diff --git a/man3/intro.3 b/man3/intro.3 index ce0d6e294b..b08eca5ac2 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.