Hi Branden, On 1/15/23 06:44, G. Branden Robinson wrote:
* Recast introduction to discuss the purpose of section 3 as a whole instead of focussing solely on the standard C library. * Provide historical context for usage of subsections in section 3. Resurrect information from comments, in rewritten form, of section 3 subsections, so as to contrast them with the current approach developed by Alex. Be even more emphatic that those documenting other C libraries should not mess with subsections. * 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). Signed-off-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> --- man3/intro.3 | 122 +++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 63 deletions(-) diff --git a/man3/intro.3 b/man3/intro.3 index bbaef525e..f5a47b566 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:
I prefer C library. C language library seems redundant. And C library is common enough. I guess you want to avoid confusion with the standard C library. For that, I'd just use standard C library more consistently.
+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;
We're still using uppercase. BTW, I thought by sentence case you meant that if it goes in the middle of a sentence it would be lowercase. Is this hybrid between title case and sentence case something usual in English?
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
Is ld(1) a C linker? I'd call it just a linker, since it links object code, wherever it comes from (code could have been written in assembly). In fact, I'm not sure if it knows about -lc (maybe it does, I don't remember). It's only when you call the compiler (not the linker) to link code, when the compiler calls the linker with the appropriate C libraries. The same as when you compile C++ with g++, which calls the linker with the appropriate libraries for C++.
+.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 @@ -45,54 +45,50 @@ In such cases, the relevant function's man page describes the required macro. See .BR feature_test_macros (7). -.\" -.\" There -.\" are various function groups which can be identified by a letter which -.\" is appended to the chapter number: -.\" .IP (3C) -.\" These functions, -.\" the functions from chapter 2 and from chapter 3S are -.\" contained in the C standard library libc, -.\" which will be used by -.\" .BR cc (1) -.\" by default. -.\" .IP (3S) -.\" These functions are parts of the -.\" .BR stdio (3) -.\" library. They are contained in the standard C library libc. -.\" .IP (3M) -.\" These functions are contained in the arithmetic library libm. They are -.\" used by the -.\" .BR f77 (1) -.\" FORTRAN compiler by default, -.\" but not by the -.\" .BR cc (1) -.\" C compiler, -.\" which needs the option \fI\-lm\fP. .\" .IP (3F) .\" These functions are part of the FORTRAN library libF77. There are no .\" special compiler flags needed to use these functions. -.\" .IP (3X) -.\" Various special libraries. The manual pages documenting their functions -.\" specify the library names. .SS Subsections +In Unix systems circa 1980, +section 3 of the programmer's manual documented +.I libc +functions in subsections; +.\" V7 (1979-01) used an unsuffixed "3"; System III (1980-06) used 3C. +.\" BSD at first ignored this shift; it is not seen in 3BSD (late 1979) +.\" or 4BSD (1980-11), but both conventions are documented in 4.1cBSD's +.\" intro(3) (1983-04). +\(lq3C\(rq was used for most, +with +\(lq3M\(rq for those from the math library, +and +\(lq3S\(rq for the standard I/O package. +\(lq3X\(rq was reserved for \(lqvarious specialized libraries\(rq. +.PP The Linux .I man-pages -organize section 3 into subsections -that reflect the complex structure of the standard C library -and its many implementations. +project prefers to employ subsections differently, +recognizing that the many constants, +data types, +and header file names +defined by +.I libc +are as important as the names of its functions. +.TP 10n
I'd prefer to avoid this.
+.B 3const +Constants. +.TP +.B 3head +Header files. +.TP +.B 3type +Data types. +.PP +We discourage use of these subsections to document any other library.
I'd clarify that it's not the documentation that is wrong, but rather the design of the library. There are likely many libraries that are as badly designed as libc, and for those, I'd recommend reusing these subsections.
Cheers, Alex
.IR libc 's 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 -.PP Ideally, a library for the C language is designed such that each header file
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
