[PATCH v3 07/13] libc.7: ffix

[PATCH v3 07/13] libc.7: ffix

[G. Branden Robinson]

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

* Set page topic in lowercase.
* Use typographer's quotation marks instead of '"' for quotation.
* Hyperlink the text "GNU C Library" to its website.

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man7/libc.7 | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/man7/libc.7 b/man7/libc.7
index 5deba0a8e..43ec0269f 100644
--- a/man7/libc.7
+++ b/man7/libc.7
@@ -3,21 +3,22 @@
 .\"
 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
 .\"
-.TH LIBC 7 (date) "Linux man-pages (unreleased)"
+.TH libc 7 (date) "Linux man-pages (unreleased)"
 .SH NAME
 libc \- overview of standard C libraries on Linux
 .SH DESCRIPTION
-The term "libc" is commonly used as a shorthand for
-the "standard C library",
+The term \(lqlibc\(rq is commonly used as a shorthand for
+the \(lqstandard C library\(rq
 a library of standard functions that can be used by all C programs
 (and sometimes by programs in other languages).
 Because of some history
 (see below),
-use of the term "libc"
+use of the term \(lqlibc\(rq
 to refer to the standard C library is somewhat ambiguous on Linux.
 .SS glibc
-By far the most widely used C library on Linux is the GNU C Library
+By far the most widely used C library on Linux is the
 .UR http://www.gnu.org\:/software\:/libc/
+GNU C Library
 .UE ,
 often referred to as
 .IR glibc .
@@ -50,7 +51,7 @@ there was for a while
 a fork of glibc 1.x created by Linux developers who felt that glibc
 development at the time was not sufficing for the needs of Linux.
 Often,
-this library was referred to (ambiguously) as just "libc".
+this library was referred to (ambiguously) as just \(lqlibc\(rq.
 Linux libc released major versions 2, 3, 4, and 5,
 as well as many minor versions of those releases.
 Linux libc4 was the last version to use the a.out binary format,
-- 
2.30.2


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

Re: [PATCH v3 07/13] libc.7: ffix

[Alejandro Colomar]

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

Hi Branden,

On 1/5/23 23:53, G. Branden Robinson wrote:
> * Set page topic in lowercase.
> * Use typographer's quotation marks instead of '"' for quotation.

Isn't it equivalent in running text?  '"' is simpler to type.

> * Hyperlink the text "GNU C Library" to its website.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

Cheers,

Alex

> ---
>   man7/libc.7 | 13 +++++++------
>   1 file changed, 7 insertions(+), 6 deletions(-)
> 
> diff --git a/man7/libc.7 b/man7/libc.7
> index 5deba0a8e..43ec0269f 100644
> --- a/man7/libc.7
> +++ b/man7/libc.7
> @@ -3,21 +3,22 @@
>   .\"
>   .\" SPDX-License-Identifier: Linux-man-pages-copyleft
>   .\"
> -.TH LIBC 7 (date) "Linux man-pages (unreleased)"
> +.TH libc 7 (date) "Linux man-pages (unreleased)"
>   .SH NAME
>   libc \- overview of standard C libraries on Linux
>   .SH DESCRIPTION
> -The term "libc" is commonly used as a shorthand for
> -the "standard C library",
> +The term \(lqlibc\(rq is commonly used as a shorthand for
> +the \(lqstandard C library\(rq
>   a library of standard functions that can be used by all C programs
>   (and sometimes by programs in other languages).
>   Because of some history
>   (see below),
> -use of the term "libc"
> +use of the term \(lqlibc\(rq
>   to refer to the standard C library is somewhat ambiguous on Linux.
>   .SS glibc
> -By far the most widely used C library on Linux is the GNU C Library
> +By far the most widely used C library on Linux is the
>   .UR http://www.gnu.org\:/software\:/libc/
> +GNU C Library
>   .UE ,
>   often referred to as
>   .IR glibc .
> @@ -50,7 +51,7 @@ there was for a while
>   a fork of glibc 1.x created by Linux developers who felt that glibc
>   development at the time was not sufficing for the needs of Linux.
>   Often,
> -this library was referred to (ambiguously) as just "libc".
> +this library was referred to (ambiguously) as just \(lqlibc\(rq.
>   Linux libc released major versions 2, 3, 4, and 5,
>   as well as many minor versions of those releases.
>   Linux libc4 was the last version to use the a.out binary format,

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

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

Re: [PATCH v3 07/13] libc.7: ffix

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-06T00:53:11+0100, Alejandro Colomar wrote:
> On 1/5/23 23:53, G. Branden Robinson wrote:
> > * Set page topic in lowercase.
> > * Use typographer's quotation marks instead of '"' for quotation.
> 
> Isn't it equivalent in running text?  '"' is simpler to type.

No, it's not equivalent anywhere except on the "ascii", "latin1", and
"cp1047" output devices.

$ groff -man -Tpdf <<EOF > quote.pdf
.TH foo 1 2023-01-05 "groff test suite"
.SH Name
foo \- "frobnicate" a \(lqbar\(rq
EOF
$ evince quote.pdf

It _is_ simpler to type just ", and many other man page authors seem to
have found it so.  That is why I have proposed a `Q` quotation macro,
because without it, man page authors seem to forego quotation entirely
in favor of italics, bold, or nothing.

https://lists.gnu.org/archive/html/groff/2022-12/msg00078.html

Historically, TeX-style quotation ``like this'' has been seen in *roff
documents, but the practice is almost nonexistent in the Linux man-pages
corpus.

``This'' is so ugly on ISO 8859 and later character set-based terminals
that I don't wonder why people avoid it.

https://www.open-std.org/JTC1/SC2/WG3/docs/n411.pdf

...is a copy of part 1 of ECMA-94, the gratis equivalent of ISO 8859,
and shows what the ' and ` glyphs are supposed to look like.

Regards,
Branden

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

Re: [PATCH v3 07/13] libc.7: ffix

[Alejandro Colomar]

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

Hi Branden,

On 1/6/23 01:17, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-06T00:53:11+0100, Alejandro Colomar wrote:
>> On 1/5/23 23:53, G. Branden Robinson wrote:
>>> * Set page topic in lowercase.
>>> * Use typographer's quotation marks instead of '"' for quotation.
>>
>> Isn't it equivalent in running text?  '"' is simpler to type.
> 
> No, it's not equivalent anywhere except on the "ascii", "latin1", and
> "cp1047" output devices.
> 
> $ groff -man -Tpdf <<EOF > quote.pdf
> .TH foo 1 2023-01-05 "groff test suite"
> .SH Name
> foo \- "frobnicate" a \(lqbar\(rq
> EOF
> $ evince quote.pdf

For some reason, I momentarily though that those would produce the same code.
I think I was confused by some other thing: in some cases you can use '"', but 
in others you must use \(dq (macro arguments).  Probably that triggered a wrong 
connection in my brain...

Which by the way reminds me that in language, we use the ellipses together with 
the last word.  Where did this idea of separating it in synopses come from? 
Maybe logic thinking, such as placing the period outside of quotes...

So, I guess I'll pick that patch.  I'll tell you if I do.

Cheers,

Alex

> 
> It _is_ simpler to type just ", and many other man page authors seem to
> have found it so.  That is why I have proposed a `Q` quotation macro,
> because without it, man page authors seem to forego quotation entirely
> in favor of italics, bold, or nothing.
> 
> https://lists.gnu.org/archive/html/groff/2022-12/msg00078.html
> 
> Historically, TeX-style quotation ``like this'' has been seen in *roff
> documents, but the practice is almost nonexistent in the Linux man-pages
> corpus.
> 
> ``This'' is so ugly on ISO 8859 and later character set-based terminals
> that I don't wonder why people avoid it.
> 
> https://www.open-std.org/JTC1/SC2/WG3/docs/n411.pdf
> 
> ...is a copy of part 1 of ECMA-94, the gratis equivalent of ISO 8859,
> and shows what the ' and ` glyphs are supposed to look like.
> 
> Regards,
> Branden

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

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

How Groupe Bull screwed French with ISO 8859-1 (was: [PATCH v3 07/13] libc.7: ffix)

[G. Branden Robinson]

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

[This is a resend without the attachment, which kernel.org rejected.]

Hi Alex,

I've been meaning to share this story with more people since to figure
it out I had to resort to literature in a language I don't read.

At 2023-01-05T18:17:21-0600, G. Branden Robinson wrote:
> ``This'' is so ugly on ISO 8859 and later character set-based
> terminals that I don't wonder why people avoid it.
> 
> https://www.open-std.org/JTC1/SC2/WG3/docs/n411.pdf
> 
> ...is a copy of part 1 of ECMA-94, the gratis equivalent of ISO 8859,
> and shows what the ' and ` glyphs are supposed to look like.

So I give you:

How Groupe Bull Screwed French with ISO 8859-1

https://www.dropbox.com/s/oizx6vgbw01za0h/How%20Groupe%20Bull%20Screwed%20Latin-1_CG_1996___25_65_0.pdf?dl=0

I hope some day the name of the ignorant and indifferent conference
attendee will be made public.

Regards,
Branden

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

Re: [PATCH v3 07/13] libc.7: ffix

[G. Branden Robinson]

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

[This is a re-send without the attachment, which kernel.org rejected.]

Hi Alex,

At 2023-01-06T01:39:09+0100, Alejandro Colomar wrote:
> On 1/6/23 01:17, G. Branden Robinson wrote:
> > $ groff -man -Tpdf <<EOF > quote.pdf
> > .TH foo 1 2023-01-05 "groff test suite"
> > .SH Name
> > foo \- "frobnicate" a \(lqbar\(rq
> > EOF
> > $ evince quote.pdf
> 
> For some reason, I momentarily though that those would produce the
> same code.  I think I was confused by some other thing: in some cases
> you can use '"', but in others you must use \(dq (macro arguments).
> Probably that triggered a wrong connection in my brain...

Right.  \(dq is strictly equivalent to " (as a glyph) everywhere, but in
arguments to macros and some requests, " serves as a quotation operator
in the language.

groff 1.23's Texinfo manual says:

--begin snip--
5.6.3 Calling Macros
--------------------

If a macro of the desired name does not exist when called, it is
created, assigned an empty definition, and a warning in category 'mac'
is emitted.  Calling an undefined macro _does_ end a macro definition
naming it as its end macro (*note Writing Macros::).

   To embed spaces _within_ a macro argument, enclose the argument in
neutral double quotes '"'.  Horizontal motion escape sequences are
sometimes a better choice for arguments to be formatted as text.

   Consider calls to a hypothetical section heading macro 'uh'.

     .uh The Mouse Problem
     .uh "The Mouse Problem"
     .uh The\~Mouse\~Problem
     .uh The\ Mouse\ Problem

The first line calls 'uh' with three arguments: 'The', 'Mouse', and
'Problem'.  The remainder call the 'uh' macro with one argument, 'The
Mouse Problem'.  The last solution, using escaped spaces, can be found
in documents prepared for AT&T 'troff'.  It can cause surprise when text
is adjusted, because '\SP' inserts a _fixed-width_, non-breaking space.
GNU 'troff''s '\~' escape sequence inserts an adjustable, non-breaking
space.(1)  (*note Calling Macros-Footnote-1::)

   The foregoing raises the question of how to embed neutral double
quotes or backslashes in macro arguments when _those_ characters are
desired as literals.  In GNU 'troff', the special character escape
sequence '\[rs]' produces a backslash and '\[dq]' a neutral double
quote.

   In GNU 'troff''s AT&T compatibility mode, these characters remain
available as '\(rs' and '\(dq', respectively.  AT&T 'troff' did not
consistently define these special characters, but its descendants can be
made to support them.  *Note Device and Font Description Files::.
--end snip--

> Which by the way reminds me that in language, we use the ellipses
> together with the last word. 

In English, yes.  I won't promise you that French doesn't surround it
with   (non-breaking spaces).  Natural languages may vary here.

> Where did this idea of separating it in synopses come from? Maybe
> logic thinking, such as placing the period outside of quotes...

My _guess_ as to the _reason_ is as I said earlier--to reinforce the
idea that the optional arguments are whitespace-separated.  As for where
it came from, the strongest historical claim I can readily make is that
it appears in the earliest Unix man pages for which we have hard copy.

So that would be the ar(I) page in the (First Edition) Unix Programmer's
Manual, dated 3 November 1971.  Let me know if you don't have ready
access to a copy and I can email it privately.

> So, I guess I'll pick that patch.  I'll tell you if I do.

When you've reported one as applied, should I drop it from my further
revisions of the patch group?

Regards,
Branden

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

Re: [PATCH v3 07/13] libc.7: ffix

[Alejandro Colomar]

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

Hi Branden,

On 1/6/23 08:16, G. Branden Robinson wrote:
>> Where did this idea of separating it in synopses come from? Maybe
>> logic thinking, such as placing the period outside of quotes...
> 
> My _guess_ as to the _reason_ is as I said earlier--to reinforce the
> idea that the optional arguments are whitespace-separated.  As for where
> it came from, the strongest historical claim I can readily make is that
> it appears in the earliest Unix man pages for which we have hard copy.
> 
> So that would be the ar(I) page in the (First Edition) Unix Programmer's
> Manual, dated 3 November 1971.  (Image attached.)

Interesting.

> 
>> So, I guess I'll pick that patch.  I'll tell you if I do.
> 
> When you've reported one as applied, should I drop it from my further
> revisions of the patch group?

Yes.  When I report that I applied a patch, it means that I applied it to my 
main branch, and that it will imminently be pushed to the master branch at 
kernel.org.  Some times it is immediate, and some times I delay it for a few 
hours or days, if I have patches that concern me in the branch.

I pushed my main branch to my own remote so that you can rebase on top of that 
(if I later remove the bzero patch from there, it shouldn't create any conflicts 
to your patches).

<http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/log/>
<git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git>

> 
> Regards,
> Branden

Cheers,

Alex

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

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

Re: [PATCH v3 07/13] libc.7: ffix

[Alejandro Colomar]

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

Hi Branden,

I've already pushed the changes to kernel.org.  Please rebase and prepare v4 
when you're ready.

On 1/5/23 23:53, G. Branden Robinson wrote:
> * Set page topic in lowercase.
> * Use typographer's quotation marks instead of '"' for quotation.
> * Hyperlink the text "GNU C Library" to its website.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> ---
>   man7/libc.7 | 13 +++++++------
>   1 file changed, 7 insertions(+), 6 deletions(-)
> 
> diff --git a/man7/libc.7 b/man7/libc.7
> index 5deba0a8e..43ec0269f 100644
> --- a/man7/libc.7
> +++ b/man7/libc.7
> @@ -3,21 +3,22 @@
>   .\"
>   .\" SPDX-License-Identifier: Linux-man-pages-copyleft
>   .\"
> -.TH LIBC 7 (date) "Linux man-pages (unreleased)"
> +.TH libc 7 (date) "Linux man-pages (unreleased)"
>   .SH NAME
>   libc \- overview of standard C libraries on Linux
>   .SH DESCRIPTION
> -The term "libc" is commonly used as a shorthand for
> -the "standard C library",
> +The term \(lqlibc\(rq is commonly used as a shorthand for
> +the \(lqstandard C library\(rq

The comma was accidentally removed, right?

>   a library of standard functions that can be used by all C programs
>   (and sometimes by programs in other languages).
>   Because of some history
>   (see below),
> -use of the term "libc"
> +use of the term \(lqlibc\(rq
>   to refer to the standard C library is somewhat ambiguous on Linux.
>   .SS glibc
> -By far the most widely used C library on Linux is the GNU C Library
> +By far the most widely used C library on Linux is the

I think this "by far" deserves a comma.

Cheers,

Alex

>   .UR http://www.gnu.org\:/software\:/libc/
> +GNU C Library
>   .UE ,
>   often referred to as
>   .IR glibc .
> @@ -50,7 +51,7 @@ there was for a while
>   a fork of glibc 1.x created by Linux developers who felt that glibc
>   development at the time was not sufficing for the needs of Linux.
>   Often,
> -this library was referred to (ambiguously) as just "libc".
> +this library was referred to (ambiguously) as just \(lqlibc\(rq.
>   Linux libc released major versions 2, 3, 4, and 5,
>   as well as many minor versions of those releases.
>   Linux libc4 was the last version to use the a.out binary format,

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

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

Re: [PATCH v3 07/13] libc.7: ffix

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-07T00:40:50+0100, Alejandro Colomar wrote:
> I've already pushed the changes to kernel.org.  Please rebase and
> prepare v4 when you're ready.

Thanks!  Will do.

> > -The term "libc" is commonly used as a shorthand for
> > -the "standard C library",
> > +The term \(lqlibc\(rq is commonly used as a shorthand for
> > +the \(lqstandard C library\(rq
> 
> The comma was accidentally removed, right?

Whoops.  But it comes back in:

libc.7: Revise content
> 
> > -By far the most widely used C library on Linux is the GNU C Library
> > +By far the most widely used C library on Linux is the
> 
> I think this "by far" deserves a comma.

In a subsequent commit,

libc.7: wfix

I recast the phrase away entirely.

Regards,
Branden

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