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

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

[G. Branden Robinson]

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

* 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".

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 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
 .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
+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
-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" .
 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
-- 
2.30.2


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

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

[Alejandro Colomar]

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

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

> ---
>   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
>   .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
> +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
> -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" .
>   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 --]

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

[Alejandro Colomar]

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



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.

Hmm, after reconsideration, I've dropped the patch.  I'm not sure about it.

> 
> 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
>>   .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
>> +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
>> -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" .
>>   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 --]

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

[G. Branden Robinson]

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

At 2023-01-07T13:45:30+0100, Alejandro Colomar wrote:
> On 1/7/23 10:55, G. Branden Robinson wrote:
> > * 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?

It's simply a lazy abbreviation as far as I know.  The reason I believe
"application programming interface" to be more correct is that an API is
an interface for the _activity_ of _programming_ for the purpose of
applying it (the interface).  It is not merely an interface for the
development of "application programs".

The novice programmer will not perceive much of a distinction here.

The obvious counterexample is the writing of one library that uses
another's API.

Beyond that, there exist many library-using programs that are not
properly considered "applications" in the classical sense, which is a
program usable by relatively untrained users for the purpose of
achieving some goal outside the purpose of maintaining the system (or
developing software).  In this sense, ed(1) and roff(1) were the
original Unix applications. :)

     The prime reason for Unix was the desire of Ken [Thompson], Dennis
     [Ritchie], and Joe Ossanna to have a pleasant environment for
     software development.  The fig leaf that got the nod from ...
     management was that an early use would be to develop a
     "stand-alone" word-processing system for use in typing pools and
     secretarial offices.  Perhaps they had in mind "dedicated", as
     distinct from "stand-alone"; that's what eventuated in various
     cases, most notably in the legal/patent department and in the AT&T
     CEO's office.

     Both those systems were targets of opportunity, not foreseen from
     the start.  When Unix was up and running on the PDP-11, Joe got
     wind of the legal department having installed a commercial word
     processor.  He went to pitch Unix as an alternative and clinched a
     trial by promising to make 'roff' able to number lines by tomorrow
     in order to fulfill a patent-office requirement that the commercial
     system did not support.

     Modems were installed so legal-department secretaries could try the
     Research machine.  They liked it and Joe's superb customer service.
     Soon the legal department got a system of their own.  Joe went on
     to create 'nroff' and 'troff'.  Document preparation became a
     widespread use of Unix, but no stand-alone word-processing system
     was ever undertaken.

     -- Doug McIlroy

> Patch applied.

Thanks!

Regards,
Branden

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

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

[G. Branden Robinson]

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

Hi ALex,
At 2023-01-07T13:57:36+0100, Alejandro Colomar wrote:
> > 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".
> 
> Hmm, after reconsideration, I've dropped the patch.  I'm not sure about it.

What is causing you concern?

Regards,
Branden

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

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

[Alejandro Colomar]

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-07T20:47:20+0100, Alejandro Colomar wrote:
> See a few comments below (as you asked in another email).
> > > +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.

In English this is a slippery area.  In U.S. English nouns referring to
collections tend to be singularized, whereas in Commonwealth English
they tend to the plural, but exceptions are seen in both dialects[1] and
the meaning is usually clear.

> I find the new wording more confusing than the original.

I'll recast, then.

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

It read more poorly to me that way.  My presentation was grounded on my
recollection that we agreed that these new subsections of yours would
not be necessary if the standard C library were not (1) huge and (2)
disorganized.

I'll take another crack at it, supplying a bit more motivation but
trying not to recapitulate our discussion, which doesn't demand that
degree of preservation.  :P

Regards,
Branden

[1] https://languagelog.ldc.upenn.edu/nll/?p=877

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

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

[Alejandro Colomar]

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

Hi Branden,

On 1/9/23 00:08, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-07T20:47:20+0100, Alejandro Colomar wrote:
>> See a few comments below (as you asked in another email).
>>>> +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.
> 
> In English this is a slippery area.  In U.S. English nouns referring to
> collections tend to be singularized, whereas in Commonwealth English
> they tend to the plural, but exceptions are seen in both dialects[1] and
> the meaning is usually clear.

Ahh, didn't know that about Commonwealth English.  I'm way more used to US 
English (and the man-pages also uses US).

> 
>> I find the new wording more confusing than the original.
> 
> I'll recast, then.
> 
>>>> +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.
> 
> It read more poorly to me that way.  My presentation was grounded on my
> recollection that we agreed that these new subsections of yours would
> not be necessary if the standard C library were not (1) huge and (2)
> disorganized.

I still agree on that.  However, think about a reader: it when it's reading the 
list, it needs to remember that you said two paragraphs above that you were 
going to show a list.  If the list is shown right after you say you're going to 
show it, there's less cognitive load, isn't it?

Cheers,

Alex

> 
> I'll take another crack at it, supplying a bit more motivation but
> trying not to recapitulate our discussion, which doesn't demand that
> degree of preservation.  :P
> 
> Regards,
> Branden
> 
> [1] https://languagelog.ldc.upenn.edu/nll/?p=877

-- 
<http://www.alejandro-colomar.es/>

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