Haai,
"Ingo Schwarze" <schwa...@usta.de> wrote:
> Hi,
>
>zeurk...@volny.cz wrote on Wed, Dec 25, 2019 at 08:48:36AM +0100:
>> "Ingo Schwarze" <schwa...@usta.de> 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,
The machine is, so why shouldn't we? ;)
> 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,
Surely you're not arguing that it's a burden to add a pair of
double-quotes now and then?
> 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.
On the contrary: the current behaviour of those two macros is nicely
consistent with sh(1), the other 'name [-fl...] [arg...]'-style
language of UNIX.
>> 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
> iunderline 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...
Can't Ft, Va, and Vt be fixed, though? So that each individual argument
is fully underlined, even when spaces appear in it... Mehas text flow
issues with the current behaviour:
If you like hypothetical examples: use
.Vt "struct blaat" ;
otherwise: just forget about the whole thing.
Is me the only one to trip over the non-underlined space, between
'struct' and 'blaat', in the middle of the keyword, in the resulting
output?
>>> 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 \&.
Thanks, that it useful.
>>> 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.
Weird, me's never thought of it as 'punctuation'... but mesupposes
you're not quite wrong w/ that classification. Again, mehas to give this
some thought.
>> 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.
Overlap in the sense that both in "natural language" and in C, the
semicolon has a similar meaning, so they can be treated ("handled"), by
roff and by us, the same way.
>>> 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.
Of course.
> 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.
And then please to quote "struct blaat" so that the underlining will be
unbroken (at least in the future, should the macros be fixed).
> 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.
Yes. Perhaps it was a mistake to make macros have different effects
depending on the section...
> 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
>
Very good, we'll let this percolate further.
>>> 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.
Mesees me point proven <g>.
> Yours,
> Ingo
Good holidays (assuming you celebrate),
--zeurkous.
--
Friggin' Machines!
