[PATCH] intro.3: Document subchapters of man3

[PATCH] intro.3: Document subchapters of man3

[Alejandro Colomar]

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>
---

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