minor mdoc.7 improvements

minor mdoc.7 improvements

[Ingo Schwarze]

Hi,

at some point in the past, i started checking whether the stuff
explained in mdoc.samples(7) is also made clear in our own manuals.
I didn't get very far at that time, but wrote up a few improvements
to mdoc.7 and then forgot about them.

Now i ran into them by chance, and even though i'm currently working
in a different corner and not planning to return to mdoc.samples(7)
right now, i could as well put in what i have, which is:

 - Use a more rigorous wording when explaining the "callable"
   and "parsed" properties of mdoc macros.
 - Instead of the cold and fuzzy statement that .Xo is deprecated,
   explain in more detail what it can be used for and what can be
   done instead.
 - Be more specific about the time of the doc.tmac rewrite.
 - Explicitly list the limition of the number of arguments
   in historic groff as a COMPATIBILITY issue.

OK?

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.55
diff -u -r1.55 mdoc.7
--- mdoc.7	29 Oct 2010 10:36:08 -0000	1.55
+++ mdoc.7	27 Nov 2010 22:18:45 -0000
@@ -604,20 +604,21 @@
 .Pp
 The
 .Em Callable
-column indicates that the macro may be called subsequent to the initial
-line-macro.
-If a macro is not callable, then its invocation after the initial line
-macro is interpreted as opaque text, such that
+column indicates that the macro may also be called by passing its name
+as an argument to another macro.
+If a macro is not callable but its name appears as an argument
+to another macro, it is interpreted as opaque text.
+For example,
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed
-column indicates whether the macro may be followed by further
-(ostensibly callable) macros.
-If a macro is not parsed, subsequent macro invocations on the line
-will be interpreted as opaque text.
+column indicates whether the macro may call other macros by receiving
+their names as arguments.
+If a macro is not parsed but the name of another macro appears
+as an argument, it is interpreted as opaque text.
 .Pp
 The
 .Em Scope
@@ -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.
+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.
+This macro can also be used to extend the scope of a partial-implicit
+block macro beyond the end of its line, but it is almost always
+preferable to use the corresponding partial-explicit block macro
+instead.
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
@@ -2714,10 +2722,10 @@
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
+refers to groff versions before 1.17,
+which featured a significant update of the
 .Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+file.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
@@ -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.
 .It
 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: minor mdoc.7 improvements

[Ingo Schwarze]

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

Re: minor mdoc.7 improvements

[Ingo Schwarze]

Hi Jason,

> my point is that your description of Xo talks only in terms of using
> it for the It macro, but it can be used with many others.

OK, so lets try again.
Explaining it the other way round needs a bit more verbosity,
but i think it is worth spending the space because .Xo is
notoriously a source of confusion.

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.56
diff -u -r1.56 mdoc.7
--- mdoc.7	28 Nov 2010 15:45:26 -0000	1.56
+++ mdoc.7	28 Nov 2010 17:31:52 -0000
@@ -2659,9 +2659,60 @@
 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 or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .
+.Pp
+Regarding partial-implicit block macros, this has never been very useful
+because it is almost always better to use the corresponding
+partial-explicit block macro when many, long or complex arguments
+are required.
+For example, rewrite awkward code like
+.Bd -literal -offset indent
+\&.Op Fl s Ar modifier Xo
+\&.Op Fl R Ar id
+\&.Xc
+.Ed
+.Pp
+to the clear and fully portable form
+.Bd -literal -offset indent
+\&.Oo
+\&.Fl s Ar modifier
+\&.Op Fl R Ar id
+\&.Oc
+.Ed
+.Pp
+Thus, the only sensible use for
+.Sx \&Xo
+has been in
+.Sx \&It
+lines, for example:
+.Bd -literal -offset indent
+\&.It Xo
+\&.No if Ar list ;
+\&.No then Ar list ;
+\&.Oo elif Ar list ;
+\&.No then Ar list ; Oc
+\&.No ...
+\&.Oo else Ar list ; Oc
+\&.No fi
+\&.Xc
+.Ed
+.Pp
+Since the 9-argument limit has been lifted, it is now possible to use 
+line continuation with a backslash at the end of the line instead;
+but remeber that such code is not portable to historic
+.Nm
+implementations:
+.Bd -literal -offset indent
+\&.It if Ar list ; No then Ar list ; \e
+    Oo elif Ar list ; No then Ar list ; Oc No ... \e
+    Oo else Ar list ; Oc No fi
+.Ed
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: minor mdoc.7 improvements

[Ingo Schwarze]

Hi Jason,

> i think this is overkill, to be honest. i think your changes up to the
> first Pp are sufficient.

OK, done.

Thanks,
  Ingo

>> Index: mdoc.7
>> ===================================================================
>> RCS file: /cvs/src/share/man/man7/mdoc.7,v
>> retrieving revision 1.56
>> diff -u -r1.56 mdoc.7
>> --- mdoc.7	28 Nov 2010 15:45:26 -0000	1.56
>> +++ mdoc.7	28 Nov 2010 17:31:52 -0000
>> @@ -2659,9 +2659,60 @@
>>  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 or the body of a partial-implicit block macro
>> +beyond the end of the input line.
>> +This macro originally existed to work around the 9-argument limit
>> +of historic
>> +.Xr roff 7 .
>> +.Pp
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv