[PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[G. Branden Robinson]

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

Hi Alex,

v2:

* No longer migrates `PP` macros to `P`.
* No longer migrates ASCII "arrow" `->` to troff special character.
* Changes to each page split into markup, style, and content changes.

For reference, this trichotomy is one that evolved for me over the past
5-6 years while working on groff man pages.  Here is how I define them,
for reference.

+ Markup changes affect "only" the document source and are not visible
  in formatted output.  There is some imprecision in this category; I
  would regard a change to word breakpoints or hyphenation as a "markup"
  fix even though these _might_ be visible in the output depending on
  the line length of the output device (which, for terminals, is highly
  flexible).  Alterations to indentation would probably also qualify.

+ Style changes are a broad category encompassing corrections to
  spelling and grammar in natural language, but also things like
  typeface changes or changes to the style of a source code example.

+ Content changes significantly alter the informational substance of the
  page.  These include corrections to matters of fact or exposure of
  previously undocumented information.

Regards,
Branden

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

Re: [PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[Alejandro Colomar]

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

Hi Branden,

On 1/4/23 08:37, G. Branden Robinson wrote:
> Hi Alex,
> 
> v2:
> 
> * No longer migrates `PP` macros to `P`.
> * No longer migrates ASCII "arrow" `->` to troff special character.
I'd like this change, if you can apply it globally.  But we'll leave it for a 
separate patch set.

> * Changes to each page split into markup, style, and content changes.
> 
> For reference, this trichotomy is one that evolved for me over the past
> 5-6 years while working on groff man pages.  Here is how I define them,
> for reference.
> 
> + Markup changes affect "only" the document source and are not visible
>    in formatted output.  There is some imprecision in this category; I
>    would regard a change to word breakpoints or hyphenation as a "markup"
>    fix even though these _might_ be visible in the output depending on
>    the line length of the output device (which, for terminals, is highly
>    flexible).  Alterations to indentation would probably also qualify.\

This more or less corresponds to what we call srcfix (although some might 
qualify as ffix; the ones you called imprecise).

> 
> + Style changes are a broad category encompassing corrections to
>    spelling

This more or less corresponds to what we call tfix.

> and grammar in natural language,

This more or less corresponds to what we call wfix.  wfix can englobe tfix normally.

> but also things like
>    typeface changes or changes to the style of a source code example.

This more or less corresponds to what we call ffix.  It might be good to break 
such changes in two or three separate categories, although sometimes one needs 
the other, and it's simpler to just apply one patch that does all of them.

> 
> + Content changes significantly alter the informational substance of the
>    page.  These include corrections to matters of fact or exposure of
>    previously undocumented information.

And these are non-trivial patches that have their own description.


See the CONTRIBUTING file:

        -  For trivial patches, you can use subject tags:

           -  ffix: Formatting fix.
           -  tfix: Typo fix.
           -  wfix: Minor wording fix.
           -  srcfix: Change to manual page source that doesn't affect output.

           Example:

               [patch] tcp.7: tfix

Previously, we also has wsfix (white-space fix) and pfix (punctuation fix), but 
those got assimilated by the extant categories.

> 
> Regards,
> Branden

Cheers,

Alex

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

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

Re: [PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-04T13:34:59+0100, Alejandro Colomar wrote:
> > v2:
> > 
> > * No longer migrates `PP` macros to `P`.
> > * No longer migrates ASCII "arrow" `->` to troff special character.
> I'd like this change, if you can apply it globally.  But we'll leave
> it for a separate patch set.

Yes.  I already chased it down.  "Globally" affects 2 pages.

There is more elaborate ASCII art in sched(7).  That can be made
relatively pretty with Unicode arrow characters; the four orthogonal
single-stemmed arrows even happen to have portable special character
identifiers going back to 1976 AT&T troff.

But I'm not sure about chewing that one off.  Using special character
escape sequences would make the source looked weirder and misaligned.
There's a way around that (the `tr` request) but that's a fairly chunky
breach of the "no *roff requests in man page sources) rule that Ingo
Schwarze and I try to hold to.

Still, it's worth thinking about whether you'd like to have pic(1)
diagrams in the Linux man-pages, with ASCII/Unicode-art fallbacks for
terminal devices.

> This more or less corresponds to what we call srcfix (although some might
> qualify as ffix; the ones you called imprecise).
[...]
> This more or less corresponds to what we call tfix.
[...]
> This more or less corresponds to what we call wfix.  wfix can englobe
> tfix normally.
[...]
> This more or less corresponds to what we call ffix.  It might be good
> to break such changes in two or three separate categories, although
> sometimes one needs the other, and it's simpler to just apply one
> patch that does all of them.

I will recast my characterizations in the commit messages.  I used to
know the above categories, but they bit-rotted in my brain due to my
feverish rush to get groff 1.23 ready.  Context switches are expensive
in meatspace, too...

Do you continue to practice Michael's indifference to Git's first-line
"limit" to commit messages?  I have some pending patches that look like
this.

commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Jan 4 02:31:37 2023 -0600

    adjtimex.2, eventfd.2, mmap2.2, perf_event_open.2, quotactl.2, shmget.2, times.2, drand48.3, ldexp.3, random.3, tgamma.3, proc.5, mount_namespaces.7, random.7, sched.7, tcp.7, udplite.7, units.7, unix.7, utf-8.7: srcfix

    Use correct *roff special character for hat/caret/circumflex accent.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

Regards,
Branden

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

Re: [PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[Alejandro Colomar]

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

Hi Branden,

On 1/4/23 17:05, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T13:34:59+0100, Alejandro Colomar wrote:
>>> v2:
>>>
>>> * No longer migrates `PP` macros to `P`.
>>> * No longer migrates ASCII "arrow" `->` to troff special character.
>> I'd like this change, if you can apply it globally.  But we'll leave
>> it for a separate patch set.
> 
> Yes.  I already chased it down.  "Globally" affects 2 pages.
> 
> There is more elaborate ASCII art in sched(7).  That can be made
> relatively pretty with Unicode arrow characters; the four orthogonal
> single-stemmed arrows even happen to have portable special character
> identifiers going back to 1976 AT&T troff.
> 
> But I'm not sure about chewing that one off.  Using special character
> escape sequences would make the source looked weirder and misaligned.
> There's a way around that (the `tr` request) but that's a fairly chunky
> breach of the "no *roff requests in man page sources) rule that Ingo
> Schwarze and I try to hold to.
> 
> Still, it's worth thinking about whether you'd like to have pic(1)
> diagrams in the Linux man-pages, with ASCII/Unicode-art fallbacks for
> terminal devices.

I don't know.  Can you show source code and formatted output of some examples, 
so I can compare?

> 
>> This more or less corresponds to what we call srcfix (although some might
>> qualify as ffix; the ones you called imprecise).
> [...]
>> This more or less corresponds to what we call tfix.
> [...]
>> This more or less corresponds to what we call wfix.  wfix can englobe
>> tfix normally.
> [...]
>> This more or less corresponds to what we call ffix.  It might be good
>> to break such changes in two or three separate categories, although
>> sometimes one needs the other, and it's simpler to just apply one
>> patch that does all of them.
> 
> I will recast my characterizations in the commit messages.  I used to
> know the above categories, but they bit-rotted in my brain due to my
> feverish rush to get groff 1.23 ready.  Context switches are expensive
> in meatspace, too...
> 
> Do you continue to practice Michael's indifference to Git's first-line
> "limit" to commit messages?

Yes.  While I try to make subjects short, as anyone else, I don't have any 
strict rules about it.  If the number of files being modified is a bit large, 
it's easy to go past the 80-col, and I'm fine with that.

However, Michael and I used some abbreviations, such as "Many pages: ...", or 
"Various pages: ...", and similar, when there were a large amount of pages but 
the change was a global fix and the page names were completely irrelevant.  We 
used "various" for a smallish number of pages over 10 or so.  "Many" was more 
for things like 500 pages.

>  I have some pending patches that look like
> this.
> 
> commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5
> Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> Date:   Wed Jan 4 02:31:37 2023 -0600
> 
>      adjtimex.2, eventfd.2, mmap2.2, perf_event_open.2, quotactl.2, shmget.2, times.2, drand48.3, ldexp.3, random.3, tgamma.3, proc.5, mount_namespaces.7, random.7, sched.7, tcp.7, udplite.7, units.7, unix.7, utf-8.7: srcfix

You could use "Various pages: srcfix" here.

BTW, another thing I noticed you practice is writing a trailing '.' in the 
subject line.
I don't have any strong preference there, but followed the practice of not 
writing it, as Michael did.  It has the advantage of having one more byte for 
the subject.

I guess you prefer language consistency.

> 
>      Use correct *roff special character for hat/caret/circumflex accent.
> 
>      Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> 
> Regards,
> Branden

Cheers,

Alex

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

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

Re: [PATCH v2 0/9] intro.3, libc.7, ldconfig.8: Revise

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-04T20:03:08+0100, Alejandro Colomar wrote:
> > There is more elaborate ASCII art in sched(7).  That can be made
> > relatively pretty with Unicode arrow characters; the four orthogonal
> > single-stemmed arrows even happen to have portable special character
> > identifiers going back to 1976 AT&T troff.
> > 
> > But I'm not sure about chewing that one off.  Using special
> > character escape sequences would make the source looked weirder and
> > misaligned.  There's a way around that (the `tr` request) but that's
> > a fairly chunky breach of the "no *roff requests in man page
> > sources) rule that Ingo Schwarze and I try to hold to.
> > 
> > Still, it's worth thinking about whether you'd like to have pic(1)
> > diagrams in the Linux man-pages, with ASCII/Unicode-art fallbacks
> > for terminal devices.
> 
> I don't know.  Can you show source code and formatted output of some
> examples, so I can compare?

Sure.

groff's soelim(1) man page is an example.

https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/soelim/soelim.1.man

Here's the output of the first diagram in ASCII:

                 input        sourced
                 file          file
                   |             |
                   v             v
               preprocessor --> troff --> postprocessor
                                             |
                                             v
                                          output
                                           file

...and UTF-8:

                 input        sourced
                 file          file
                   ⎪             ⎪
                   ↓             ↓
               preprocessor ⎯→ troff ⎯→ postprocessor
                                             ⎪
                                             ↓
                                          output
                                           file

...and I'm attaching a screenshot from groff-man-pages.pdf.

> >  I have some pending patches that look like
> > this.
> > 
> > commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5
> > Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> > Date:   Wed Jan 4 02:31:37 2023 -0600
> > 
> >      adjtimex.2, eventfd.2, mmap2.2, perf_event_open.2, quotactl.2, shmget.2, times.2, drand48.3, ldexp.3, random.3, tgamma.3, proc.5, mount_namespaces.7, random.7, sched.7, tcp.7, udplite.7, units.7, unix.7, utf-8.7: srcfix
> 
> You could use "Various pages: srcfix" here.

Cool, I'll do that, then.

> BTW, another thing I noticed you practice is writing a trailing '.' in
> the subject line.  I don't have any strong preference there, but
> followed the practice of not writing it, as Michael did.  It has the
> advantage of having one more byte for the subject.
> 
> I guess you prefer language consistency.

Yes, it's a practice I advocate to remind the commit writer that they
should be writing a declarative _sentence_ in the imperative mood that
characterizes the _intent_ of their change.  Programmers, especially
inexperienced, overwhelmed, or devious ones, tend to resort to passive
description of their changes.  This makes it harder to tell what their
intentions were.  (The final group views this as a feature, not a bug.)

And anyone with a bit of salt knows--all too often, the effect and the
intention of code all too often diverge.

Then of course there are the rock stars who describe neither the intent
or the actuality of their code at all--they just hand you demoware that
"works", get a swift high-five from the manager, and hastily move on to
another department.  Leave documentation and validation to scullions,
with the same manager marveling at the poor productivity of the rest of
the team in contrast to the cowboy they just talked up for a promotion.

Anyway, I belatedly remembered that Linux man-pages prefers to omit the
trailing period, so my more recent proposed patches lack it.

Regards,
Branden

[-- Attachment #1.2: soelim-diagram.png --]
[-- Type: image/png, Size: 27388 bytes --]

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