[v2,1/3] system_data_types.7: ffix

  Normally, text under a section header starts in the next line after the
header, without a blank line.  Follow that pattern.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

I had been using .PP because I hadn't seen .br before.

I think .br is the correct format,
following the pattern in already existing man pages.

BTW, is there any way to copy the CC list with git send-email
from the email I'm answering to?
Right now I'm manually copying all of them each time from Thunderbird.

Regards,

Alex

 man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)
  

Hi Alex,

On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Normally, text under a section header starts in the next line after the
> header, without a blank line.  Follow that pattern.
>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> I had been using .PP because I hadn't seen .br before.
>
> I think .br is the correct format,
> following the pattern in already existing man pages.

I don't disagree with the formatting change, but I am wondering if
there's a better way to do it. I tend to consider (perhaps wrongly)
that the use of .sp and .br is unidiomatic, and over the years I have
replaced a large of them with alternatives. (For example, in many
cases, .sp was being used when .PP should have been.)

If Branden does not tell us of something better, I will just apply
your patch as is.

> BTW, is there any way to copy the CC list with git send-email
> from the email I'm answering to?
> Right now I'm manually copying all of them each time from Thunderbird.

Sorry, I don't know. (Not really an answer to your question,
but are you also aware of "git format-patch --to=... --cc=..." ?)

Thanks,

Michael
  

Hi Michael,

On 2020-09-28 12:34, Michael Kerrisk (man-pages) wrote:
>> BTW, is there any way to copy the CC list with git send-email
>> from the email I'm answering to?
>> Right now I'm manually copying all of them each time from Thunderbird.
> 
> Sorry, I don't know. (Not really an answer to your question,
> but are you also aware of "git format-patch --to=... --cc=..." ?)

Nope, I didn't. I'll try them :)

Thanks!

Alex
  

Hi Michael and Alex!

At 2020-09-28T12:34:40+0200, Michael Kerrisk (man-pages) wrote:
> On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
> > I had been using .PP because I hadn't seen .br before.
> >
> > I think .br is the correct format,
> > following the pattern in already existing man pages.
> 
> I don't disagree with the formatting change, but I am wondering if
> there's a better way to do it.

There are a few ways to skin cats in even the restricted dialect of
man(7) that I advocate.  (The other groff developers seem to generally
agree, but I will admit that I am probably more puritanical and maniacal
than most of them. :) )

> I tend to consider (perhaps wrongly) that the use of .sp and .br is
> unidiomatic,

In my book you're certainly right.  There are a few reasons for keeping
the lexicon of macros/requests appearing in man pages small.

1. man pages, far more than any other type of *roff source document, get
   parsed by things are not *roff typesetting engines.  The less *roff
   they have to simulate, the easier it will be for them to achieve
   intelligible rendering.  mandoc(1) is probably the premier example in
   this respect, and I believe I understand from its current developer
   Ingo Schwarze that it handles rather more *roff than we would prefer.
   There have also been numerous "man2html" processors developed over
   the years, typically of somewhat dispiriting quality.

2. Even in the world of *roff typesetters there is diversity.  For a
   long time groff was the only freely-licensed game in town, but
   nowadays I know of Heirloom Doctools, Plan 9, Solaris 10, DWB 3.3,
   and neatroff implementations.  The smaller the language, the easier
   it is to get consensus and parity around portable constructs.

3. A smaller language is easier to learn and easier to retain for
   people who are part-time documenters.  A person who only tackles
   documentation maintenance once every four to six months, say, is
   going to have an easier time with a language with maybe two dozen
   tags, several of which fall into groupings with a predictable naming
   pattern, than they will with, say, the 417 tags of DocBook[1].

   For groff 1.22.4, released in December 2018, I made sure to
   front-load the groff_man(7) page with a quick reference for all
   non-deprecated tags.  My hope is that man page writers who have been
   around the block with the man(7) language once before can type "man
   groff_man" and be refreshed after having to hit the space bar at most
   twice.

A corollary of point (3), especially when it comes to the mixing of
*roff requests with macros, is that their subtle interactions can be
frustrating to learners--and even to experienced users.  Someone who
leans what .sp does may be surprised to find it not working between a
section heading (.SH) and the first line of text afterwards.  Similar
frustrations can arise with the .in request when mixed with .RS and .RE.

> and over the years I have replaced a large of them with alternatives.
> (For example, in many cases, .sp was being used when .PP should have
> been.)
> 
> If Branden does not tell us of something better, I will just apply
> your patch as is.

_Personally_, I prefer system_data_types(7) as of
efbe7900b931789849a978c619106a8973e679cd to any intrusion of .br
requests.  And as a C programmer I find it clear enough.

I do wonder about the huge list of header files providing `size_t`, but
I guess my raised eyebrow is better aimed at the ISO C committee than
here.  :)

Regards,
Branden

[1] https://tdg.docbook.org/tdg/4.5/docbook.html
  

Hi Alex!

At 2020-09-28T11:03:23+0200, Alejandro Colomar wrote:
> Normally, text under a section header starts in the next line after
> the header, without a blank line.  Follow that pattern.

I think your terminology could confuse some people.  A section heading
in a man page is what is typeset by the .SH macro.  For instance, ".SH
Name", ".SH See also", and so forth[1].

In the below, "aiocb" (in italics) is properly termed a "paragraph tag",
hence the mnemonic for the macro right before it: "TP" for "tagged
paragraph".

Just FYI.

[...]
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 361e8d411..ff0403df9 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
>  .TP
>  .I aiocb
>  .RS
> -.PP
> +.br
>  Include:
>  .IR <aio.h> .
>  .PP
> @@ -101,7 +101,7 @@ See also:

Regards,
Branden

[1] Often section headings are written in full capitals in man page
source documents, which loses information.  The next release of groff
will feature support for mixed-case section headings with optional
full-caps rendering under user control.
  

Hi Branden & Michael,

On 2020-09-28 15:06, G. Branden Robinson wrote:
 > Hi Alex!
 >
 > At 2020-09-28T11:03:23+0200, Alejandro Colomar wrote:
 >> Normally, text under a section header starts in the next line after
 >> the header, without a blank line.  Follow that pattern.
 >
 > I think your terminology could confuse some people.  A section heading
 > in a man page is what is typeset by the .SH macro.  For instance, ".SH
 > Name", ".SH See also", and so forth[1].
 >
 > In the below, "aiocb" (in italics) is properly termed a "paragraph tag",
 > hence the mnemonic for the macro right before it: "TP" for "tagged
 > paragraph".
 >
 > Just FYI.

I did mean .SH:

For each type we're separating the paragraphs by description,
conforming to, see also, ...  similar to the .SH sections.

And therefore, I thought that we should use the same format for
consistency: After the title, or in this case the tag,
there should be no blank line.

However, if using .br is a big headache, I would rather not use
workarounds (as you proposed in an earlier email),
and instead just live with the blank line.  It's not much of a problem.

But Michael did already apply the patch (was it by mistake? or did you
agree with the patch, Michael?)

I leave it up to you to decide what to do, Michael.

My proposals:
If you prefer consistency in the source, I'd rather not use
workarounds: I'd just leave .PP, and accept the blank line
I see those workarounds uglier than .br.
If you however prefer consistency in the visual page,
I'd use .br, or something that doesn't look like a workaround.

Regards,

Alex

 >
 > [...]
 >> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
 >> index 361e8d411..ff0403df9 100644
 >> --- a/man7/system_data_types.7
 >> +++ b/man7/system_data_types.7
 >> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 >>   .TP
 >>   .I aiocb
 >>   .RS
 >> -.PP
 >> +.br
 >>   Include:
 >>   .IR <aio.h> .
 >>   .PP
 >> @@ -101,7 +101,7 @@ See also:
 >
 > Regards,
 > Branden
 >
 > [1] Often section headings are written in full capitals in man page
 > source documents, which loses information.  The next release of groff
 > will feature support for mixed-case section headings with optional
 > full-caps rendering under user control.
 >
  

At 2020-09-28T15:44:46+0200, Alejandro Colomar wrote:
> I did mean .SH:
> 
> For each type we're separating the paragraphs by description,
> conforming to, see also, ...  similar to the .SH sections.

Okay, I see; you were using an analogy.

> And therefore, I thought that we should use the same format for
> consistency: After the title, or in this case the tag,
> there should be no blank line.
> 
> However, if using .br is a big headache, I would rather not use
> workarounds (as you proposed in an earlier email),
> and instead just live with the blank line.  It's not much of a
> problem.

Was an actual decision taken on this?  I see patches continuing to roll
in containing this .br-based pattern.  I think if the extra line is
live-withable, it should be lived with (or one of my four proposed
alternatives could be used :) ), in preference to setting the bad
example of the "naked" .br requests.

man page markup is highly prone to cargo-culting; on the groff list not
too long ago, some sleuthing revealed an example of a typo that crept
into the X Window System man pages over 30 years ago and was not only
diligently retained there but faithfully copied elsewhere by people who
didn't realize what they were copying[1].

> I leave it up to you to decide what to do, Michael.
> 
> My proposals:
> If you prefer consistency in the source, I'd rather not use
> workarounds: I'd just leave .PP, and accept the blank line
> I see those workarounds uglier than .br.

Too bad for me.  But I admit I'm not proud of that .TQ thing.  :P

> If you however prefer consistency in the visual page,

That's not how it appears to me; I may be bringing too much insider
knowledge to the question, but I know when I see them that the things
you've termed section headings aren't true section headings.  Primarily
I can tell by the fact that their indentation is wrong for an .SH macro.

But the knowledge isn't all that far inside.  The worst hand-written man
page I have ever seen in my life, or expect to see, was written by
Albert Cahalan, who hated *roff with a passion I have reserved only for
love affairs.  He learned just enough of the language to subvert man-db
and groff into accepting his plain-text document as a man page[2].

I don't know what ever became of Mr. Cahalan, but I imagine that he is
somewhere working on processing Markdown with XML:FO and enjoying
himself immensely.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
[2] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
  

Hi Branden & Michael,

On 2020-09-30 12:43, G. Branden Robinson wrote:
 >> However, if using .br is a big headache, I would rather not use
 >> workarounds (as you proposed in an earlier email),
 >> and instead just live with the blank line.  It's not much of a
 >> problem.
 >
 > Was an actual decision taken on this?  I see patches continuing to roll
 > in containing this .br-based pattern.  I think if the extra line is
 > live-withable, it should be lived with (or one of my four proposed
 > alternatives could be used :) ), in preference to setting the bad
 > example of the "naked" .br requests.

No decision yet.
We continued with the patch,
considering that we might revert it
or change it to a different approach in the future.
Actually I thought Michael would have hold the patches until the decision,
but he merged them, and it may be easier this way...
we'll fix it when we decide.

For me, I can live with the extra blank line.
Michael, what are your thoughts?

 >
 > man page markup is highly prone to cargo-culting; on the groff list not
 > too long ago, some sleuthing revealed an example of a typo that crept
 > into the X Window System man pages over 30 years ago and was not only
 > diligently retained there but faithfully copied elsewhere by people who
 > didn't realize what they were copying[1].

As someone who has written man-pages only for about a month,
I completely ignore the problems about using .br.
I see it easy in my mind:
I want a line break (without fancy paragraph stuff), I write .br.
I guess it's somewhat more complicated than that :-)
You could probably convince me otherwise,
and in fact you may have already...

 >
 >> I leave it up to you to decide what to do, Michael.
 >>
 >> My proposals:
 >> If you prefer consistency in the source, I'd rather not use
 >> workarounds: I'd just leave .PP, and accept the blank line
 >> I see those workarounds uglier than .br.
 >
 > Too bad for me.  But I admit I'm not proud of that .TQ thing.  :P
 >
 >> If you however prefer consistency in the visual page,
 >
 > That's not how it appears to me; I may be bringing too much insider
 > knowledge to the question, but I know when I see them that the things
 > you've termed section headings aren't true section headings.  Primarily
 > I can tell by the fact that their indentation is wrong for an .SH macro.
 >
 > But the knowledge isn't all that far inside.  The worst hand-written man
 > page I have ever seen in my life, or expect to see, was written by
 > Albert Cahalan, who hated *roff with a passion I have reserved only for
 > love affairs.  He learned just enough of the language to subvert man-db
 > and groff into accepting his plain-text document as a man page[2].
 >
 > I don't know what ever became of Mr. Cahalan, but I imagine that he is
 > somewhere working on processing Markdown with XML:FO and enjoying
 > himself immensely.

8-O

I'm curious as to how that man page displays...

 >
 > Regards,
 > Branden
 >
 > [1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
 > [2] 
https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
 >


I was writing about the different options and testing them,
when by accident I discovered that .RS alone, which I introduced lately,
already fixed the problem we had in the beginning:
.RS forces a line break after the tag
(so .br is actually redundant right now).

I guess we'll all be happy with just .RS, right? :-}

Cheers,

Alex
  

Hi Alex, Branden,
On 9/30/20 11:32 PM, Alejandro Colomar wrote:
> Hi Branden & Michael,
> 
> On 2020-09-30 12:43, G. Branden Robinson wrote:
>  >> However, if using .br is a big headache, I would rather not use
>  >> workarounds (as you proposed in an earlier email),
>  >> and instead just live with the blank line.  It's not much of a
>  >> problem.
>  >
>  > Was an actual decision taken on this?  I see patches continuing to roll
>  > in containing this .br-based pattern.  I think if the extra line is
>  > live-withable, it should be lived with (or one of my four proposed
>  > alternatives could be used :) ), in preference to setting the bad
>  > example of the "naked" .br requests.
> 
> No decision yet.
> We continued with the patch,
> considering that we might revert it
> or change it to a different approach in the future.

Yes. I figure we can easily clean up the inconsistency later.

> Actually I thought Michael would have hold the patches until the decision,

I didn't want to slow you down,...

> but he merged them, and it may be easier this way...
> we'll fix it when we decide.

Yes.

> For me, I can live with the extra blank line.
> Michael, what are your thoughts?

I can live with it too.

[...]


> 
>  >
>  > Regards,
>  > Branden
>  >
>  > [1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
>  > [2] 
> https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
>  >
> 
> 
> I was writing about the different options and testing them,
> when by accident I discovered that .RS alone, which I introduced lately,
> already fixed the problem we had in the beginning:
> .RS forces a line break after the tag
> (so .br is actually redundant right now).
> 
> I guess we'll all be happy with just .RS, right? :-}

I think so.

Cheers,

Michael

PS Alex, I believe we are at a sync point right now (i.e., I think
that I do not have any unprocessed patches from you). Let me know if
I'm wrong.
  

Hi Michael,

On 2020-10-01 09:37, Michael Kerrisk (man-pages) wrote:
> PS Alex, I believe we are at a sync point right now (i.e., I think
> that I do not have any unprocessed patches from you). Let me know if
> I'm wrong.
> 

There's only one patch missing:

https://lore.kernel.org/linux-man/20200929151047.GN6642@arm.com/T/#m7e7fe3066750196cfe26afd53a1a2a7896ddfa96

I hope it still applies.

Thanks,

Alex
  

On 10/1/20 9:52 AM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 2020-10-01 09:37, Michael Kerrisk (man-pages) wrote:
>> PS Alex, I believe we are at a sync point right now (i.e., I think
>> that I do not have any unprocessed patches from you). Let me know if
>> I'm wrong.
>>
> 
> There's only one patch missing:
> 
> https://lore.kernel.org/linux-man/20200929151047.GN6642@arm.com/T/#m7e7fe3066750196cfe26afd53a1a2a7896ddfa96
> 
> I hope it still applies.

It does. Applied and pushed.

Thanks,

Michael