From: schwarze@mdocml.bsd.lv
To: source@mdocml.bsd.lv
Subject: mdocml: Make the second, section number argument of .Xr mandatory.
Date: Wed, 28 Dec 2016 12:34:48 -0500 (EST) [thread overview]
Message-ID: <10523102442202852389.enqueue@fantadrom.bsd.lv> (raw)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=utf-8, Size: 4843 bytes --]
Log Message:
-----------
Make the second, section number argument of .Xr mandatory.
In fact, we have been requiring it for many years.
The only reason to not warn when it was missing
was excessive traditionalism - it was optional in 4.4BSD.
Modified Files:
--------------
mdocml:
mandoc.1
mandoc.h
mdoc.7
mdoc_validate.c
read.c
Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.1,v
retrieving revision 1.164
retrieving revision 1.165
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.164 -r1.165
--- mandoc.1
+++ mandoc.1
@@ -1147,6 +1147,13 @@ macro is immediately followed by an
.Ic \&Re
macro on the next input line.
Such an empty block does not produce any output.
+.It Sy "missing section argument"
+.Pq mdoc
+An
+.Ic \&Xr
+macro lacks its second, section number argument.
+The first argument, i.e. the name, is printed, but without subsequent
+parantheses.
.It Sy "missing -std argument, adding it"
.Pq mdoc
An
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mdoc.7,v
retrieving revision 1.258
retrieving revision 1.259
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.258 -r1.259
--- mdoc.7
+++ mdoc.7
@@ -2714,14 +2714,13 @@ Link to another manual
.Pq Qq cross-reference .
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Xr Ar name Op section
+.D1 Pf \. Sx \&Xr Ar name section
.Pp
Cross reference the
.Ar name
and
.Ar section
-number of another man page;
-omitting the section number is rarely useful.
+number of another man page.
.Pp
Examples:
.Dl \&.Xr mandoc 1
@@ -3033,7 +3032,7 @@ then the macro accepts an arbitrary numb
.It Sx \&Ux Ta Yes Ta Yes Ta n
.It Sx \&Va Ta Yes Ta Yes Ta n
.It Sx \&Vt Ta Yes Ta Yes Ta >0
-.It Sx \&Xr Ta Yes Ta Yes Ta >0
+.It Sx \&Xr Ta Yes Ta Yes Ta 2
.It Sx \&br Ta \&No Ta \&No Ta 0
.It Sx \&sp Ta \&No Ta \&No Ta 1
.El
Index: mdoc_validate.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mdoc_validate.c,v
retrieving revision 1.309
retrieving revision 1.310
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.309 -r1.310
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -103,6 +103,7 @@ static void post_sh_authors(POST_ARGS);
static void post_sm(POST_ARGS);
static void post_st(POST_ARGS);
static void post_std(POST_ARGS);
+static void post_xr(POST_ARGS);
static v_post mdoc_valids[MDOC_MAX] = {
NULL, /* Ap */
@@ -145,7 +146,7 @@ static v_post mdoc_valids[MDOC_MAX] = {
post_st, /* St */
NULL, /* Va */
NULL, /* Vt */
- NULL, /* Xr */
+ post_xr, /* Xr */
NULL, /* %A */
post_hyph, /* %B */ /* FIXME: can be used outside Rs/Re. */
NULL, /* %D */
@@ -1807,6 +1808,21 @@ post_sh_head(POST_ARGS)
}
static void
+post_xr(POST_ARGS)
+{
+ struct roff_node *n, *nch;
+
+ n = mdoc->last;
+ nch = n->child;
+ if (nch->next == NULL) {
+ mandoc_vmsg(MANDOCERR_XR_NOSEC, mdoc->parse,
+ n->line, n->pos, "Xr %s", nch->string);
+ return;
+ }
+ assert(nch->next == n->last);
+}
+
+static void
post_ignpar(POST_ARGS)
{
struct roff_node *np;
@@ -2002,7 +2018,7 @@ post_dt(POST_ARGS)
}
}
- /* Mandatory second argument: section. */
+ /* Mandatory second argument: section. */
if (nn != NULL)
nn = nn->next;
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.h,v
retrieving revision 1.210
retrieving revision 1.211
diff -Lmandoc.h -Lmandoc.h -u -p -r1.210 -r1.211
--- mandoc.h
+++ mandoc.h
@@ -107,6 +107,7 @@ enum mandocerr {
MANDOCERR_BF_BADFONT, /* unknown font type, using \fR: Bf font */
MANDOCERR_PF_SKIP, /* nothing follows prefix: Pf arg */
MANDOCERR_RS_EMPTY, /* empty reference block: Rs */
+ MANDOCERR_XR_NOSEC, /* missing section argument: Xr arg */
MANDOCERR_ARG_STD, /* missing -std argument, adding it: macro */
MANDOCERR_OP_EMPTY, /* missing option string, using "": OP */
MANDOCERR_UR_NOHEAD, /* missing resource identifier, using "": UR */
Index: read.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/read.c,v
retrieving revision 1.154
retrieving revision 1.155
diff -Lread.c -Lread.c -u -p -r1.154 -r1.155
--- read.c
+++ read.c
@@ -150,6 +150,7 @@ static const char * const mandocerrs[MAN
"unknown font type, using \\fR",
"nothing follows prefix",
"empty reference block",
+ "missing section argument",
"missing -std argument, adding it",
"missing option string, using \"\"",
"missing resource identifier, using \"\"",
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
reply other threads:[~2016-12-28 17:34 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
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=10523102442202852389.enqueue@fantadrom.bsd.lv \
--to=schwarze@mdocml.bsd.lv \
--cc=source@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).