[PATCH v3 13/13] intro.3: Revise discussion

[PATCH v3 13/13] intro.3: Revise discussion

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2816 bytes --]

* Recast introduction to discuss the purpose of section 3 as a whole
  instead of focussing solely on the standard C library.
* Explain basic principles of usage of any C library to the novice.
  (This page _is_ called "intro".)
* Drop material about organization of glibc, now moved to libc(7).
* Make crystal clear what Alex's new subsections are for.

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man3/intro.3 | 67 +++++++++++++++++++++++++++-------------------------
 1 file changed, 35 insertions(+), 32 deletions(-)

diff --git a/man3/intro.3 b/man3/intro.3
index d2c8c132e..d28dee4cc 100644
--- a/man3/intro.3
+++ b/man3/intro.3
@@ -7,34 +7,34 @@
 .SH NAME
 intro \- introduction to library functions
 .SH DESCRIPTION
-Section 3 of the manual describes all library functions
-excluding the library functions
-(system call wrappers)
-described in Section 2,
-which implement system calls.
-.PP
-Many of the functions described in the section are part of the
-Standard C Library
-.RI ( libc ).
-Some functions are part of other libraries
-(e.g.,
-the math library,
-.IR libm ,
-or the real-time library,
-.IR librt )
-in which case the manual page will indicate
-the linker option needed to link against the required library
-(e.g.,
-.I \-lm
+Section 3 of the manual describes library functions
+generally useful to programmers,
+excluding the system calls described in section 2.
+Use of a C\~language library entails two requirements:
+its symbol names must be exposed to the compiler
+through the inclusion of a
+.IR "header file" ,
+presented at the beginning of a man page's \(lqSynopsis\(rq section;
 and
-.IR \-lrt ,
-respectively,
-for the aforementioned libraries).
+(with one exception)
+to the linker through the specification of an
+.I \-l
+flag,
+documented in the page's \(lqLibrary\(rq section.
+.PP
+Many of the functions described are part of the Standard C Library
+(see
+.BR libc (7)).
+C\~linkers link with
+.I libc
+implicitly by default;
+an
+.I \-lc
+option is redundant.
 .PP
-In some cases,
-the programmer must define a feature test macro in order to obtain
-the declaration of a function from the header file specified
-in the man page SYNOPSIS section.
+Sometimes,
+the programmer must define a C\~preprocessor macro
+to access the declaration of a symbol from a header file.
 (Where required,
 these
 .I feature test macros
@@ -86,12 +86,15 @@ difficult history frequently makes it a poor example to follow
 in design,
 implementation,
 and presentation.
-.IP \(bu 3
-3const
-.IP \(bu
-3head
-.IP \(bu
-3type
+.TP 10n
+.B 3const
+Constants.
+.TP
+.B 3head
+Header files.
+.TP
+.B 3type
+Data types.
 .PP
 Ideally,
 a library for the C language
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]