Re: [PATCH v4 08/10] intro.3: wfix

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3579 bytes --]

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@gmail.com>
> 
> 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]