Re: Review incorrect man-pages commit

[Ingo Schwarze <schwarze@usta.de>]

Hi Branden, hi Alex,

G. Branden Robinson wrote on Sun, Mar 20, 2022 at 09:52:37PM +1100:

> If you wanted to write this without using any aliases,
> you could adopt groff syntax.
> 
> +to "\fI[a\[a aa]\[a ga]\[a ad]\[a a^]\fP", that is,

While that is arguably neat, please be aware that it is significantly
less portable even when considering modern formatting software only.
For example, consider this:

   $ mandoc -Wall 
  ==\fI[a\[a aa]\[a ga]\[a ad]\[a a^]]\fP==  <enter> <Ctrl-D>
  mandoc: <stdin>:1:29: WARNING: invalid escape sequence: \[a a^]
  mandoc: <stdin>:1:22: WARNING: invalid escape sequence: \[a ad]
  mandoc: <stdin>:1:15: WARNING: invalid escape sequence: \[a ga]
  mandoc: <stdin>:1:8: WARNING: invalid escape sequence: \[a aa]
  [...]
  ==[a]==
  [...]

Arguably, not supporting the groff multi-argument form of \[]
character escape sequences might be a defect in mandoc, but for
now, that's how things are, so if you go that way, you have to
accept that some (even modern) formatters will drop the accented
characters from the output.

> I don't know if people regard that as more or less impenetrable.
> It is more _flexible_, and admits usage of diacritics/combining
> characters not envisioned by AT&T troff or ISO Latin-1.

That flexibility is precisely what makes the feature somewhat hard
to implement (though not impossible).  Admittedly, for typeset output,
any accent can be placed on any character, and for UTF-8 and HTML
output, zero-width combining Unicode codepoints can be used, but for
arbitrary output modes, the formatter would still have to contain
a complete table of all character-accent combinations to map them
to combined glyphs available in the output mode - and users would
probably have to accept that some combinations can't be rendered
in some output modes.  All that is less than ideal in manual pages,
where portability generally trumps typographic elegance.

> +.q !$%&\[aq]()*,/:;<=>?@[\[rs]]\[ha]\`{|}\[ti] .

I agree that nothing much is wrong with using the \[] variable
length character escape syntax in manual pages nowadays from
the point of view of portability.  Then again, i'm not convinced
that \[aq] is more readable than \(aq.  Why would it be?

Quite to the contrary, in the other example above, you wrote:

  ... \[a a^]\fP

forgetting the trailing square bracket; it should have been:

  ... \[a a^]]\fP

So my impression is the \[] syntax introduces additional opportunities
for markup bugs, if there is any difference to \( at all.

The rest of your message beautifully explains what is going on.

Yours,
  Ingo