Cowritten-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx> Cc: Ingo Schwarze <schwarze@xxxxxxxxxxx> Cc: Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> --- Hi Branden, I took your suggestion with few modifications. Would you please review and sign if you are okay with it? Cheers, Alex man3/intro.3 | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) 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 @@ .SH DESCRIPTION .\" .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. -- 2.38.1
