[PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Alejandro Colomar]

Reported-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/man-pages.7 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 547ed660a..4da2dfe5c 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -578,6 +578,11 @@ project.
 For details not covered below, the Chicago Manual of Style
 is usually a good source;
 try also grepping for preexisting usage in the project source tree.
+.PP
+.UR https://www.ualberta.ca/\:computing-science/\:media-library/\:docs/\:unix-beginners.pdf
+UNIX for Beginners [2nd ed., Brian W. Kernighan]
+.UE
+also contains an interesting section on "Hints for Preparing Documents".
 .SS Use of gender-neutral language
 As far as possible, use gender-neutral language in the text of man
 pages.
-- 
2.30.2

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[G. Branden Robinson]

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

At 2022-06-10T12:51:41+0200, Alejandro Colomar wrote:
> +also contains an interesting section on "Hints for Preparing Documents".

I would use real (typographer's) quotation marks to cite the section
title, and since you are doing so, that's what the section _is_ even
more than what it's _on_.

Thus,

also contains an interesting section,
\[lq]Hints for Preparing Documents\[rq].

I would also find a more specific adjective than
"interesting"--"helpful", "noteworthy", "exemplary" are all
possibilities.

Regards,
Branden

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

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Alejandro Colomar]

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

Hi Branden!

On 6/10/22 14:21, G. Branden Robinson wrote:
> At 2022-06-10T12:51:41+0200, Alejandro Colomar wrote:
>> +also contains an interesting section on "Hints for Preparing Documents".
> 
> I would use real (typographer's) quotation marks to cite the section
> title, and since you are doing so, that's what the section _is_ even
> more than what it's _on_.
> 
> Thus,
> 
> also contains an interesting section,
> \[lq]Hints for Preparing Documents\[rq].
> 
> I would also find a more specific adjective than
> "interesting"--"helpful", "noteworthy", "exemplary" are all
> possibilities.

Sure! Thanks.

BTW, is the [2nd ed., BWK] thingy correct?  I did it from memory.

Cheers,

Alex

> 
> Regards,
> Branden


-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[G. Branden Robinson]

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

Hi Alex,

At 2022-06-10T16:37:18+0200, Alejandro Colomar wrote:
> BTW, is the [2nd ed., BWK] thingy correct?  I did it from memory.

Yes.  The origin of this document is the Unix Programmer's Manual for
the Version 7 release (1979).  The manual was published in two volumes:
volume 1 was a compilation of all the man pages, and volume 2 was a
compilation of whitepapers (all, or nearly all, composed using the "ms"
macro package).

"UNIX for Beginners--Second Edition" appeared early in volume 2.  (AT&T
lawyers insisted on the full capitalization, but several Murray Hill
Bell Labs veterans have gone on record as preferring "Unix" to be
spelled in mixed case as an ordinary proper noun.)

Some copies of this document on the Internet have been re-typeset, and
some of them have misleading dates due to a technical detail of ms(7)
usage.  The date on the copy that was typeset for the published manual
is "October 2, 1978".

Regards,
Branden

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

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Alejandro Colomar]

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

Hi Branden,

On 6/18/22 17:58, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-06-10T16:37:18+0200, Alejandro Colomar wrote:
>> BTW, is the [2nd ed., BWK] thingy correct?  I did it from memory.

Oh, I just meant if the style (the brackets, the comma) was correct for 
references like this.  You probably have much more experience quoting 
than I do.

> 
> Yes.  The origin of this document is the Unix Programmer's Manual for
> the Version 7 release (1979).  The manual was published in two volumes:
> volume 1 was a compilation of all the man pages, and volume 2 was a
> compilation of whitepapers (all, or nearly all, composed using the "ms"
> macro package).
> 
> "UNIX for Beginners--Second Edition" appeared early in volume 2.  (AT&T
> lawyers insisted on the full capitalization, but several Murray Hill
> Bell Labs veterans have gone on record as preferring "Unix" to be
> spelled in mixed case as an ordinary proper noun.)
> 
> Some copies of this document on the Internet have been re-typeset, and
> some of them have misleading dates due to a technical detail of ms(7)
> usage.  The date on the copy that was typeset for the published manual
> is "October 2, 1978".

But thanks for the interesting history class! :)

And, considering that Bell Labs veterans prefer Unix over UNIX, I'll 
start using Unix (it's their thingy, after all).

Cheers,

Alex

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

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

[PATCH v2] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Alejandro Colomar]

Reported-by: Peter Xu <peterx@redhat.com>
[gbr: style fixes]
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/man-pages.7 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 547ed660a..138fda5fe 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -578,6 +578,12 @@ project.
 For details not covered below, the Chicago Manual of Style
 is usually a good source;
 try also grepping for preexisting usage in the project source tree.
+.PP
+.UR https://www.ualberta.ca/\:computing-science/\:media-library/\:docs/\:unix-beginners.pdf
+UNIX for Beginners [2nd ed., Brian W. Kernighan]
+.UE
+also contains a noteworthy section,
+\[lq]Hints for Preparing Documents\[rq].
 .SS Use of gender-neutral language
 As far as possible, use gender-neutral language in the text of man
 pages.
-- 
2.30.2

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Peter Xu]

On Fri, Jun 10, 2022 at 12:51:41PM +0200, Alejandro Colomar wrote:
> Reported-by: Peter Xu <peterx@redhat.com>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man7/man-pages.7 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index 547ed660a..4da2dfe5c 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -578,6 +578,11 @@ project.
>  For details not covered below, the Chicago Manual of Style
>  is usually a good source;
>  try also grepping for preexisting usage in the project source tree.
> +.PP
> +.UR https://www.ualberta.ca/\:computing-science/\:media-library/\:docs/\:unix-beginners.pdf
> +UNIX for Beginners [2nd ed., Brian W. Kernighan]
> +.UE
> +also contains an interesting section on "Hints for Preparing Documents".
>  .SS Use of gender-neutral language
>  As far as possible, use gender-neutral language in the text of man
>  pages.
> -- 

Thanks for adding this!

There's a little bit of a pity though on that the PDF version will IMHO
loose one very important aspect of being an live example of how to do
semantics newlines itself.  Personally after I read the format I don't even
need to read the groff man page because the example is the best to describe
that this rule means.

I meant the possibility to quote the thing behind generated PDF just as you
did in the commit message:

---8<---
Brian W. Kernighan, 1974 [UNIX For Beginners]:

[
Hints for Preparing Documents

Most documents go through several versions
(always more than you expected)
before they are finally finished.
Accordingly,
you should do whatever possible
to make the job of changing them easy.

First,
when you do the purely mechanical operations of typing,
type so subsequent editing will be easy.
Start each sentence on a new line.
Make lines short,
and break lines at natural places,
such as after commas and semicolons,
rather than randomly.
Since most people change documents
by rewriting phrases and
adding, deleting and rearranging sentences,
these precautions simplify any editing you have to do later.
]
---8<---

So I was wondering whether this section (along with its newline formats,
which is IMHO even more helpful) can be quoted altogether, because both the
content and format could help the reader in this case.

Thanks,

-- 
Peter Xu

Re: [PATCH] man-pages.7: STYLE GUIDE: Mention UNIX for Beginners

[Alejandro Colomar]

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

Hi Peter and Branden,

On 6/10/22 15:55, Peter Xu wrote:
> Thanks for adding this!
> 
> There's a little bit of a pity though on that the PDF version will IMHO
> loose one very important aspect of being an live example of how to do
> semantics newlines itself.  Personally after I read the format I don't even
> need to read the groff man page because the example is the best to describe
> that this rule means.
> 
> I meant the possibility to quote the thing behind generated PDF just as you
> did in the commit message:
> 
> ---8<---
> Brian W. Kernighan, 1974 [UNIX For Beginners]:
> 
> [
> Hints for Preparing Documents
> 
> Most documents go through several versions
> (always more than you expected)
> before they are finally finished.
> Accordingly,
> you should do whatever possible
> to make the job of changing them easy.
> 
> First,
> when you do the purely mechanical operations of typing,
> type so subsequent editing will be easy.
> Start each sentence on a new line.
> Make lines short,
> and break lines at natural places,
> such as after commas and semicolons,
> rather than randomly.
> Since most people change documents
> by rewriting phrases and
> adding, deleting and rearranging sentences,
> these precautions simplify any editing you have to do later.
> ]
> ---8<---
> 
> So I was wondering whether this section (along with its newline formats,
> which is IMHO even more helpful) can be quoted altogether, because both the
> content and format could help the reader in this case.

Sure, I was thinking of adding that to man-pages(7)::EXAMPLES after your 
comment.  But I didn't know how to properly quote it, so I waited to see 
Branden's great advise first :)

Branden, might you want to send a patch yourself.  I have no idea of how 
to correctly quote someone :/

Cheers,

Alex

> 
> Thanks,
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

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