From: Ingo Schwarze <schwarze@usta.de>
To: jmc@openbsd.org
Cc: tech@mdocml.bsd.lv
Subject: minor mdoc.7 improvements
Date: Sat, 27 Nov 2010 23:27:09 +0100 [thread overview]
Message-ID: <20101127222709.GE27534@iris.usta.de> (raw)
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
next reply other threads:[~2010-11-27 22:27 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-11-27 22:27 Ingo Schwarze [this message]
[not found] ` <20101127224144.GB27550@kerhand.co.uk>
2010-11-28 0:22 ` Ingo Schwarze
[not found] ` <20101128080507.GA4033@kerhand.co.uk>
2010-11-28 17:43 ` Ingo Schwarze
[not found] ` <20101129162316.GB4071@kerhand.co.uk>
2010-11-30 20:51 ` Ingo Schwarze
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20101127222709.GE27534@iris.usta.de \
--to=schwarze@usta.de \
--cc=jmc@openbsd.org \
--cc=tech@mdocml.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).