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>

diff --git a/man3/intro.3 b/man3/intro.3
index ce0d6e294bd0fed37452515ad49a3081db02bdcf..b08eca5ac2a713f282b76ac911cc2099d04ef458 100644 (file)
--- 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.