Re: minor mdoc.7 improvements

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

Jason McIntyre wrote on Sat, Nov 27, 2010 at 10:41:20PM +0000:
> On Sat, Nov 27, 2010 at 11:27:09PM +0100, Ingo Schwarze wrote:

[...]
>> @@ -2658,9 +2659,16 @@
>>  Close a scope opened by
>>  .Sx \&Xo .
>>  .Ss \&Xo
>> -Open an extension scope.
>> -This macro originally existed to extend the 9-argument limit of troff;
>> -since this limit has been lifted, the macro has been deprecated.
>> +Extend the header of an
>> +.Sx \&It
>> +macro beyond the end of the input line.
 
> i'm not sure that this always concerned the It macro. i know there's a
> fair bit of abuse of Xo/Xc, but i think there were examples where it was
> used outside It correctly.

Yes, there are examples where it can be used correctly outside It:
Specifically, to extend partial-explicit block macros.

I *did* check which kinds of macros can be extended by Xo.
Here is the complete list of all mdoc macro classes:

 1. full-explicit block macros (Bd, Bf, Bk, Bl)
    None of these is parsed, so It cannot be used.

 2. full-implicit block macros
    Nd, Sh and Ss are not parsed.
    Abusing Xo to extend SYNOPSIS Nm would be completely insane.
    So It is the only relevant one in this class,
    and if Xo extends It, it extends the It header.

 3. partial-explicit block macros (like Ac, Bc, ...)
    These can't be extended, they are already multi-line capable
    all by themselves.  Actually, Xo itself belongs to this class,
    and that's exactly why it can extend other macros.

 4. partial-implicit block macros (like Aq, Bq, ...)
    These can correctly be extended, as i say in the proposed text.
    But it makes very little sense because these replacements are
    always better:
      Aq  -> Ao
      Bq  -> Bo
      Brq -> Bro
      Dq  -> Do
      Op  -> Oo
      Pq  -> Po
      Qq  -> Qo
      Sq  -> So
    Only the following remain:
      - D1, Dl and Vt
        Extending these with Xo would be insane (not sure whether
        it even works).
      - Ql
        That's probably the only one where there is no alternative
        to using Xo to extend it.  But Ql is so obscure in the first
        place that discussing it explicitly is hardly warranted.

  5. in-line macros (like Ar, Em, Fl, ...)
     These don't form blocks at all, hence can't be extended with Xo.

And that's it.  So i really think the proposed wording is exact.

> anyway, since it can be used with other
> macros, maybe just clearer to say "extend the header of a macro".

No, that's wrong.
With Aq, Bq, Brq, Dq, Op, Pq, Ql, Qq and Sq, Xo extends the body
of the macro, not the header.  These macros don't even have headers,
hence Kristaps calls them "partial".  It is the only macro where
the header can be extended.

>> +This macro originally existed to work around the 9-argument limit of troff;
>> +since this limit has been lifted, it is now possible to use
>> +line continuation with a backslash at the end of the line instead.

> i wonder whether we should prefer this then in situations where it is
> easier to read if Xo/Xc is used? like we have lots of examples like:
> 
> 	.It Xo
> 	.Ar reallylongargumentname1 reallylongargumentname2
> 	.Ar reallylongargumentname3
> 	.Xc
> 
> maybe, as we come across them, we should prefer the backslash?

	.It reallylongargumentname1 reallylongargumentname2 \
	    reallylongargumentname3
	body starts here

Does that look better?
Maybe it's a matter of taste.

There are instances of really ugly Xo, but the .It Xo solution in its
standard form as shown above is quite readable.  Thus, i tend to
continue using it, it is also more portable - though the latter is
a weak argument, we prefer readability to portability when it
comes to other details, so our manuals aren't completely portable
to ancient troff, anyway.  Still, why reduce portability where
it provides little to no gain in readability?

That's why i only said "possible ... to use instead".
I certainly won't blame anybody writing readable code
involving backslashes to extend lines, but i don't dislike
clean use of It Xo either.

Should we express a clear preference?

[...]
>> @@ -2807,6 +2815,11 @@
>>  .It
>>  .Sx \&%C
>>  is not implemented.
>> +.It
>> +Historic groff only allows up to eight or nine arguments per macro input
>> +line, depending on the exact situation.
>> +Providing more arguments causes garbled output.
>> +The number of arguments one on input line is not limited with mandoc.

> i think "one on" -> "on one".

Thanks, i fixed that in my tree.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv