Re: [BUG] groff: inconsistent behavior of " to separate arguments

[Alejandro Colomar (man-pages)]

Hi Ingo,

On 3/20/22 10:48, Ingo Schwarze wrote:
> Hi Alex,
It seems your emails didn't reach me directly.
But the email from the mailing list arrived to my other mailbox.
Hummm.

After that, I checked again, and I found your email in the SPAM folder...
#$%* gmail!

> Alejandro Colomar (man-pages) wrote on Sun, Mar 20, 2022 at 01:29:32AM +0100:
> 
>> I've met some undocumented (or I couldn't find it) behavior
>> of double quotes ("),
> 
> I did not check the authoritative GNU troff documentation yet,
> but the roff(7) manual in the mandoc package says this:
> 
>   MACRO SYNTAX
>     Macros are provided by the mdoc(7) and man(7) languages and can be
>     defined by the de request.  When called, they follow the same syntax
>     as requests, except that macro arguments may optionally be quoted
>     by enclosing them in double quote characters (`"').  Quoted text,
>     even if it contains whitespace or would cause a macro invocation when
>     unquoted, is always considered literal text.  Inside quoted text,
>     pairs of double quote characters (`""') resolve to single double
>     quote characters.
> 
>     To be recognised as the beginning of a quoted argument, the opening
>     quote character must be preceded by a space character.  A quoted
>     argument extends to the next double quote character that is not part
>     of a pair, or to the end of the input line, whichever comes earlier.
>     Leaving out the terminating double quote character at the end of the
>     line is discouraged.  For clarity, if more arguments follow on the
>     same input line, it is recommended to follow the terminating double
>     quote character by a space character; in case the next character
>     after the terminating double quote character is anything else,
>     it is regarded as the beginning of the next, unquoted argument.
> 
> This text is also available here:
> 
>   https://man.openbsd.org/roff#MACRO_SYNTAX
> 
> While the mandoc roff(7) manual is neither authoritative with respect
> to groff (it merely describes the most important parts of mandoc(1)'s
> roff(7) implementation, but that is designed to be compatible with groff)
> nor complete, that manual is designed to explain those facts about the
> roff language that are most relevant for manual pages, in a form that
> is as compact as possible, so it might sometimes be helpful for your
> particular purposes.

That documentation is what I was looking for in groff(7).  Thanks.

> 
>> which might be a bug in groff(1):
> 
> Consequently, i agree with Ralph and doubt that this is a bug
> in groff.  I believe it works as intended.

It clearly isn't.  It's just a poorly documented feature, it seems :)

> 
>> .IR "foo"bar
>> .IR foo"bar"
>> .IR "foo"bar"baz"
> 
> The first and third lines are bad style and are better written as
> 
>   .IR "foo" bar
>   .IR "foo" bar"baz"

Yes, the original problem was some line in some Linux manual page,
which contained something like:

.IR "foo bar",

which I expected to be wrong, and be equivalent of

.I foo bar,

as I had sh(1) quotation in mind.
When I rendered the page and found that it was printing the same as if
there had been a space before the comma, I was quite surprised.


> 
> [...]
>>        foobar foo"bar" foobar"baz"
> 
> That output seems correct to me.  In any case, the mandoc(1) program 
> produces the same output.
> 
>> When a double-quoted word is not space-separated from an adjacent word,
>> it's not considered a different argument _except_ if if is the first
>> argument.
> 
> That description is inaccurate.  It has nothing to do with whether
> or not it is the first argument.
> 
>> Could you please improve the documentation regarding '"'?
>> I've also seen """ to mean \(dq in some manual pages.
> 
> That seems like bad style to me.  If you really want to use the
> quoted argument syntax to provide an argument containing nothing
> but a single quote, than that argument should better be written
> as four quotes (""""), not three.  Then again, i believe \(dq
> is more readable than """" to the average reader.

I also believe \(dq is better, but I also found those examples in
existing pages and was trying to understand the author intent, to update
it to a better source.


Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/