Skip to contentSkip to conversation

intro.3, libc.7, ldconfig.8: Revise

PATCH Superseded G. Branden Robinson 2 participants 5 messages Jan 4, 2023 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v2 cover intro.3, libc.7, ldconfig.8: Revise

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

#1 lore raw

Hi Branden,

Quoted 6 lines · G. Branden Robinson

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.

Quoted 6 lines

* 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.

Quoted 6 lines

+ 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).

Quoted 3 lines

+ Style changes are a broad category encompassing corrections to spelling

This more or less corresponds to what we call tfix.

Quoted 1 line

and grammar in natural language,

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

Quoted 2 lines

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.

Quoted 4 lines

+ 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.

Quoted 3 lines

Regards,
Branden

Cheers,

Alex

Signature · 1 line
<http://www.alejandro-colomar.es/>
#2 lore raw

Hi Alex,

Quoted 6 lines · Alejandro Colomar
Quoted 4 lines

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.

Quoted 2 lines

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

[...]

Quoted 1 line

This more or less corresponds to what we call tfix.

[...]

Quoted 2 lines

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

[...]

Quoted 4 lines

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 <[email protected]>
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.

Regards,
Branden

#3 lore raw

Hi Branden,

Quoted 23 lines · G. Branden Robinson

Hi Alex,

Quoted 6 lines · Alejandro Colomar
Quoted 4 lines

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.

Quoted 3 lines

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?

Quoted 14 lines
Quoted 3 lines

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

[...]

Quoted 1 line

This more or less corresponds to what we call tfix.

[...]

Quoted 2 lines

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

[...]

Quoted 4 lines

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.

Quoted 7 lines

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.

Quoted 8 lines

I have some pending patches that look like
this.

commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5

Author: G. Branden Robinson <[email protected]>
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.

Quoted 7 lines

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

Regards,
Branden

Cheers,

Alex

Signature · 1 line
<http://www.alejandro-colomar.es/>
#4 lore raw

Hi Alex,

Quoted 11 lines · Alejandro Colomar
Quoted 11 lines

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.

Quoted 6 lines
Quoted 3 lines

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.

Quoted 10 lines
Quoted 8 lines

I have some pending patches that look like
this.

commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5

Author: G. Branden Robinson <[email protected]>
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.

Quoted 6 lines

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