Hi BRanden, On 1/7/23 13:45, Alejandro Colomar wrote:
Hi Branden, On 1/7/23 10:55, G. Branden Robinson wrote:* Tighten cross reference. It wastes words to tell people to look elsewhere "for further information". Why else would they look there? * Use passive voice less. * Relocate sentence for more coherent discussion. * Say "application _programming_ interface".I noticed that when you sent it, but thought that maybe it was just another way of saying it. Duckduckgo seemed to have several instances of that alternative expansion of API, so I accepted it. I'm curious about "application program interace", since I hadn't heard about it before your patch; is it a normal expansion of API?Signed-off-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>Patch applied. Cheers, Alex
See a few comments below (as you asked in another email). Cheers, ALex
--- man3/intro.3 | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/man3/intro.3 b/man3/intro.3 index d6d91f6bd..bbaef525e 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -42,9 +42,8 @@ must be defined before including .I any header files.) In such cases, -the required macro is described in the man page. -For further information on feature test macros, -see +the relevant function's man page describes the required macro. +See
OK.
.BR feature_test_macros (7). .\" .\" There @@ -77,9 +76,16 @@ see .\" Various special libraries. The manual pages documenting their functions .\" specify the library names. .SS Subsections -Section 3 of this manual is organized into subsections +The Linux +.I man-pages
The Linux man-pages is a singular noun that denominates the project. Using it as a plural noun that refers to the pages contained in it sounds weird.
I find the new wording more confusing than the original.
+organize section 3 into subsections that reflect the complex structure of the standard C library -and its many implementations: +and its many implementations. +.IR libc 's +difficult history frequently makes it a poor example to follow +in design, +implementation, +and presentation. .IP \(bu 3 3const .IP \(bu @@ -87,11 +93,6 @@ and its many implementations: .IP \(bu 3type .PP
The list of subsections seems more connected to "organize section 3 into subsections", rather than with the comment about libc's organization being crap. I think that is fine after reading the list, stating that what you just read is crap, but necessary crap due to libc's history.
-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 @@ -101,7 +102,7 @@ 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" . +.IR "application programming interface" .
OK
Types and constants to be shared among multiple APIs should be placed in header files that declare no functions. This organization permits a C library module
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
