Re: Review incorrect man-pages commit

[G. Branden Robinson]

Hi Ingo,

At 2022-03-20T12:41:28+0100, Ingo Schwarze wrote:
> 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.

You have to be prepared for the characters to be dropped in any case,
since they might get rendered on an output device that is limited to
ASCII, or (I suppose less likely?) using KOI8-R...or ISO Latin-2, which
lacks code points for any letters combined with a grave accent.

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

It might be wise for the page to include a disclaimer that some of its
glyphs might not render.

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

We get used to delimiters being paired.  :)

I regret Ossanna's choice of a parenthesis here.

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

I would attribute that more to my haste in trying to get the email done
to watch a movie, as well as my reliably and severely attenuated
proofreading powers _before_ something I've written becomes irrevocably
public.  Nothing humbles me more than my first draft.  Or first six...

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

Thanks!

Regards,
Branden

signature.asc
Description: PGP signature