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

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Wed, 4 Jan 2023 13:34:59 +0100

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:
OpenPGP_signature

Description: OpenPGP digital signature