Hi,
[email protected] wrote on Wed, Dec 25, 2019 at 08:48:36AM +0100:
> "Ingo Schwarze" <[email protected]> wrote:
>> The arguments of .Vt almost never need quoting, not even if there
>> are other macros before or after it on the same input line.
> *shrugs* To me, there is a real difference between "struct blaat" and
> "struct" "blaat" (the latter would imply two separate types), but
> obviously YMDV :)
If you want to get technically pedantic, there is a difference
between both on a macro line: the former constitutes one macro
argument, the latter two macro arguments. But traditionally, most
roff macros just treat every argument as a word, and traditionally,
a text processor like roff just prints consecutive words with a
space in between, no matter the output mode (ASCII, UTF-8, PostScript,
HTML, ...) or the font or markup. So there is no visible difference
in any output mode, except for macros doing something special, like
.Fa and .Fn inserting commas.
For many macros, the mandoc(1) parser even takes advantage of the
equivalence by joining arguments:
$ echo '.Em "two words"' | mandoc -mdoc -T tree -O noval
Em (elem) *1:2
two words (text) 1:5
$ echo '.Em two words' | mandoc -mdoc -T tree -O noval
Em (elem) *1:2
two words (text) 1:5
Since it doesn't make a significant difference, i didn't spend much
time to make sure this is always done where it could be, for example:
$ echo '.Vt "two words"' | mandoc -mdoc -T tree -O noval
Vt (elem) *1:2
two words (text) 1:5
$ echo '.Vt two words' | mandoc -mdoc -T tree -O noval
Vt (elem) *1:2
two (text) 1:5
words (text) 1:9
So for .Vt, the parser does not currently join arguments, even though
it wouldn't be wrong to do so (consider that two types in practice
cannot appear side by side, *something*, at least punctuation or a
conjunction, will always intervene in practice if it's really two
types and not a type with a qualifier or a keyword+tag type).
But authors are not expected to worry about such subtleties, the
language is supposed to just work. That .Fa and .Fn do care is a
historic accident that i probably wouldn't repeat when designing
the language from scratch, but fixing it now would cause serious
incompatibility, so we have to live with the quotes for these two.
> In fact, it's an old peeve of mine that even when quoting the arguments,
> the underlining in the output is not applied to the spaces.
Hmm. Groff implements both word-by-word underlining (.ul) - which
is more common - but also continuous underlining (.cu). Then again,
the nroff formatter prints "\fI " as just a space, not as an
underlined space, and the mdoc macros implement .Em and similar
macros in terms of \fI for nroff output mode, not in terms of .ul
or .cu. I don't think we can redefine the rules for groff to
underline spaces after \fI, that would change existing documents
too much, including those that are not manual pages. So the only
option would be to change the implementation of the mdoc macros to
underline in-word spaces but not spaces between words. That sounds
complicated and currently, i have no idea how to do that.
It doesn't sound important enough to justify a major rewrite of the
macro set...
>> The usual way to quote punctuation is by prepending a zero-width
>> space, so if you really wanted to talk about a command called ";",
>> you would write: .Ic \&;
> Me'll give that some thought, although me'll already argue that ";" is
> (to me) a little more readable.
You may find it nicer, but it doesn't work:
$ echo '.Fl x ";"' | mandoc -mdoc
[...]
-x;
$ echo '.Fl x \&;' | mandoc -mdoc
[...]
-x -;
Quoting punctuation with "" only affects argument parsing. The macro
still sees a bare semicolon and treats it as punctuation, not as text,
like it would when the semicolon were escaped with \&.
>> But such a command would be weirdly named indeed, and appending
>> an internal command to a variable name would make no sense either.
> Well, what do you suggest? Just include C syntax elements as plain text?
Fot syntax elements that are mere punctuation, yes. Usually,
punctuation is not marked up in mdoc(7), not even when it has a
syntactic meaning in the language being documented.
>> If "scaahp" is a global variable, the best way to mention it is
>> simply
>>
>> .Vt struct blaat scaahp ;
> Except that scaahp is not a type, not a syntax element, but a variable:
> we have Va for that.
>> as documented in the mdoc(7) manual:
>>
>> https://man.openbsd.org/mdoc.7#Vt_2
> Interesting. It would appear that both and Va and Vt have the capacity
> for conflating type and variable names.
Yes, by historic accident.
> Unless me's seriously mistaken: the whole point of mdoc(7) is to not do
> that kind of thing anymore.
Yes, mdoc(7) is supposed to do semantic markup.
>> Note that the trailing semicolon is just punctuation, so it is
>> actually important to *not* escape or quote it.
> You suggest depending on the overlap between C and roff to handle the
> semicolon properly? Or is memissing something?
I don't understand what you mean by "overlap" and by "handle",
so i can't answer this question.
>> The forms
>>
>> .Va struct blaat scaahp ;
>> .Vt struct blaat Va scaahp ;
>>
>> are also acceptable albeit less common.
>> No quoting or escaping either way...
> Strange, this would really seem to fly in the face of the idea behind
> mdoc(7).
It seems you have a point.
Right now, mdoc(7) is documenting existing practice.
But it appears there would likely be no downside in encouraging
authors to always write ".Vt struct blaat Va scaahp" in new pages
and fix the markup when they come across ".Va int i" or ".Vt int
i" in old pages.
Maybe i should suggest a stricter wording for .Vt and .Va in mdoc(7)
and groff_mdoc(7) and maybe we should improve existing manuals.
But it needs some thought because in the SYNOPSIS, .Vt is a block
macro, so ".Vt extern char * Ns Va optarg ;" puts the .Va inside
the .Vt block. I need to check that doesn't have detrimental side
effects.
For now, i have made a note in the mandoc
https://cvsweb.bsd.lv/mandoc/TODO :
- Can the distinction between .Vt and .Va be made stricter,
recommending .Vt extern char * Ns Va optarg ; ?
What about the block macro properties of .Vt in the SYNOPSIS?
zeurkous 25 Dec 2019 08:48:36 +0100
>> Quoting with "" *is* needed in cases where it matters that two words
>> are kept together in a single macro argument even though there is
>> a space character between them in the source:
>>
>> .Sh SYNOPSIS
>> .Ft double
>> .Fn sin "double x"
>>
>> But that certainly isn't needed for .Vt. Relatively few macros
>> care, most prominently .Fa and .Fn.
> Yet they might care one day. What if someone'd decide to make variable
> type names appear in a different way from the variable names themselves?
That is already possible with user-defined CSS in HTML output mode,
see https://cvsweb.bsd.lv/mandoc/mandoc.css for the defaults.
Yours,
Ingo
