[PATCH v3 10/13] intro.3: srcfix

[PATCH v3 10/13] intro.3: srcfix

[G. Branden Robinson]

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

* Break input lines at phrase boundaries more often.
* Break input lines after commas.
* Set multi-word parentheticals on their own input lines.
* Protect man page cross reference from hyphenation.  (This will not be
  necessary upon migration to groff 1.23's `MR` macro.)

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

diff --git a/man3/intro.3 b/man3/intro.3
index e85c0677a..3bf5035cf 100644
--- a/man3/intro.3
+++ b/man3/intro.3
@@ -7,20 +7,23 @@
 .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,
+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.,
+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
+in which case the manual page will indicate
+the linker option needed to link against the required library
 (e.g.,
 .I \-lm
 and
@@ -32,19 +35,24 @@ 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.
-(Where required, these feature test macros must be defined before including
+(Where required,
+these feature test macros 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
-.BR feature_test_macros (7).
+In such cases,
+the required macro is described in the man page.
+For further information on feature test macros,
+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
+.\" 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)
@@ -55,9 +63,11 @@ For further information on feature test macros, see
 .\" 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
+.\" FORTRAN compiler by default,
+.\" but not by the
 .\" .BR cc (1)
-.\" C compiler, which needs the option \fI\-lm\fP.
+.\" 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.
@@ -76,7 +86,9 @@ and its many implementations:
 3type
 .PP
 This difficult history frequently makes it a poor example to follow
-in design, implementation, and presentation.
+in design,
+implementation,
+and presentation.
 .PP
 Ideally,
 a library for the C language
@@ -102,8 +114,8 @@ See
 .BR standards (7).
 .SH NOTES
 .SS Authors and copyright conditions
-Look at the header of the manual page source for the author(s) and copyright
-conditions.
+Look at the header of the manual page source
+for the author(s) and copyright conditions.
 Note that these can be different from page to page!
 .SH SEE ALSO
 .BR intro (2),
-- 
2.30.2


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

Re: [PATCH v3 10/13] intro.3: srcfix

[Alejandro Colomar]

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

Hi Branden,

On 1/5/23 23:53, G. Branden Robinson wrote:
> * Break input lines at phrase boundaries more often.
> * Break input lines after commas.
> * Set multi-word parentheticals on their own input lines.
> * Protect man page cross reference from hyphenation.  (This will not be
>    necessary upon migration to groff 1.23's `MR` macro.)

I plan to migrate as soon as it is in Debian, so maybe it's not worth doing that.

Cheers,

Alex

> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> ---
>   man3/intro.3 | 44 ++++++++++++++++++++++++++++----------------
>   1 file changed, 28 insertions(+), 16 deletions(-)
> 
> diff --git a/man3/intro.3 b/man3/intro.3
> index e85c0677a..3bf5035cf 100644
> --- a/man3/intro.3
> +++ b/man3/intro.3
> @@ -7,20 +7,23 @@
>   .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,
> +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.,
> +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
> +in which case the manual page will indicate
> +the linker option needed to link against the required library
>   (e.g.,
>   .I \-lm
>   and
> @@ -32,19 +35,24 @@ 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.
> -(Where required, these feature test macros must be defined before including
> +(Where required,
> +these feature test macros 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
> -.BR feature_test_macros (7).
> +In such cases,
> +the required macro is described in the man page.
> +For further information on feature test macros,
> +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
> +.\" 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)
> @@ -55,9 +63,11 @@ For further information on feature test macros, see
>   .\" 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
> +.\" FORTRAN compiler by default,
> +.\" but not by the
>   .\" .BR cc (1)
> -.\" C compiler, which needs the option \fI\-lm\fP.
> +.\" 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.
> @@ -76,7 +86,9 @@ and its many implementations:
>   3type
>   .PP
>   This difficult history frequently makes it a poor example to follow
> -in design, implementation, and presentation.
> +in design,
> +implementation,
> +and presentation.
>   .PP
>   Ideally,
>   a library for the C language
> @@ -102,8 +114,8 @@ See
>   .BR standards (7).
>   .SH NOTES
>   .SS Authors and copyright conditions
> -Look at the header of the manual page source for the author(s) and copyright
> -conditions.
> +Look at the header of the manual page source
> +for the author(s) and copyright conditions.
>   Note that these can be different from page to page!
>   .SH SEE ALSO
>   .BR intro (2),

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

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

Re: [PATCH v3 10/13] intro.3: srcfix

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-06T00:55:41+0100, Alejandro Colomar wrote:
> On 1/5/23 23:53, G. Branden Robinson wrote:
> > * Break input lines at phrase boundaries more often.
> > * Break input lines after commas.
> > * Set multi-word parentheticals on their own input lines.
> > * Protect man page cross reference from hyphenation.  (This will not
> >   be necessary upon migration to groff 1.23's `MR` macro.)
> 
> I plan to migrate as soon as it is in Debian, so maybe it's not worth
> doing that.

I regard hyphenation suppression as correct (and harmless) practice with
font macros; do you want that change backed out?

Regards,
Branden

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

Re: [PATCH v3 10/13] intro.3: srcfix

[Alejandro Colomar]

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



On 1/6/23 01:19, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-06T00:55:41+0100, Alejandro Colomar wrote:
>> On 1/5/23 23:53, G. Branden Robinson wrote:
>>> * Break input lines at phrase boundaries more often.
>>> * Break input lines after commas.
>>> * Set multi-word parentheticals on their own input lines.
>>> * Protect man page cross reference from hyphenation.  (This will not
>>>    be necessary upon migration to groff 1.23's `MR` macro.)
>>
>> I plan to migrate as soon as it is in Debian, so maybe it's not worth
>> doing that.
> 
> I regard hyphenation suppression as correct (and harmless) practice with
> font macros; do you want that change backed out?

At least separated.  Could you put it last in the set?

Thanks,

Alex

> 
> Regards,
> Branden

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

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

Re: [PATCH v3 10/13] intro.3: srcfix

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-06T01:40:20+0100, Alejandro Colomar wrote:
> On 1/6/23 01:19, G. Branden Robinson wrote:
> > I regard hyphenation suppression as correct (and harmless) practice
> > with font macros; do you want that change backed out?
> 
> At least separated.  Could you put it last in the set?

Sure, I'll do that for v4.

Regards,
Branden

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