discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Feature request for -Tlint
@ 2014-10-09 22:46 Anthony J. Bentley
  2014-10-11 21:25 ` Ingo Schwarze
  0 siblings, 1 reply; 4+ messages in thread
From: Anthony J. Bentley @ 2014-10-09 22:46 UTC (permalink / raw)
  To: discuss; +Cc: wblock

When converting old manual pages to mdoc(7), it's easy to accidentally
leave the trailing parentheses in the first argument to a Fn macro.
A warning when this happens would be nice.

.\" oops, wrong!
.Fn client_cert_cb()

.\" right
.Fn client_cert_cb

Not sure if this is the domain of mandoc -Tlint or if it would be better
implemented in a helper tool like igor(1).

Of course, parentheses are allowed in arguments besides the first argument,
but I can't think of any case where they're needed in the first one.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Feature request for -Tlint
  2014-10-09 22:46 Feature request for -Tlint Anthony J. Bentley
@ 2014-10-11 21:25 ` Ingo Schwarze
  2014-10-12  8:44   ` Anthony J. Bentley
  0 siblings, 1 reply; 4+ messages in thread
From: Ingo Schwarze @ 2014-10-11 21:25 UTC (permalink / raw)
  To: discuss; +Cc: wblock

Hi Anthony,

Anthony J. Bentley wrote on Thu, Oct 09, 2014 at 04:46:07PM -0600:

> When converting old manual pages to mdoc(7), it's easy to accidentally
> leave the trailing parentheses in the first argument to a Fn macro.
> A warning when this happens would be nice.
> 
> .\" oops, wrong!
> .Fn client_cert_cb()
> 
> .\" right
> .Fn client_cert_cb
> 
> Not sure if this is the domain of mandoc -Tlint

My opinion is that it is well in scope for mandoc.

> or if it would be better
> implemented in a helper tool like igor(1).

Igor's main strength is catching spelling errors, typos, and bad
phrases.  It's doing some syntactic checking, too, but not as
thoroughly as mandoc.

> Of course, parentheses are allowed in arguments besides the first
> argument, but I can't think of any case where they're needed in
> the first one.

Me neither, so i have committed the following patch.

Thanks for the suggestion,
  Ingo


Log Message:
-----------
warn about parentheses in function names after .Fn and .Fo;
particularly useful when converting from other languages to mdoc(7);
feature suggested by bentley@

Modified Files:
--------------
    mdocml:
        mandoc.1
        mandoc.h
        mdoc_validate.c
        read.c

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.1,v
retrieving revision 1.116
retrieving revision 1.117
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.116 -r1.117
--- mandoc.1
+++ mandoc.1
@@ -1120,6 +1120,14 @@ An argument of an
 or
 .Ic \&Fn
 macro contains a comma; it should probably be split into two arguments.
+.It Sy "parenthesis in function name"
+.Pq mdoc
+The first argument of an
+.Ic \&Fc
+or
+.Ic \&Fn
+macro contains an opening or closing parenthesis; that's probably wrong,
+parentheses are added automatically.
 .It Sy "invalid content in Rs block"
 .Pq mdoc
 An
Index: mdoc_validate.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_validate.c,v
retrieving revision 1.249
retrieving revision 1.250
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.249 -r1.250
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -101,6 +101,8 @@ static	int	 post_es(POST_ARGS);
 static	int	 post_eoln(POST_ARGS);
 static	int	 post_ex(POST_ARGS);
 static	int	 post_fa(POST_ARGS);
+static	int	 post_fn(POST_ARGS);
+static	int	 post_fname(POST_ARGS);
 static	int	 post_fo(POST_ARGS);
 static	int	 post_hyph(POST_ARGS);
 static	int	 post_hyphtext(POST_ARGS);
@@ -161,7 +163,7 @@ static	const struct valids mdoc_valids[M
 	{ NULL, post_fa },			/* Fa */
 	{ NULL, ewarn_ge1 },			/* Fd */
 	{ NULL, NULL },				/* Fl */
-	{ NULL, post_fa },			/* Fn */
+	{ NULL, post_fn },			/* Fn */
 	{ NULL, NULL },				/* Ft */
 	{ NULL, NULL },				/* Ic */
 	{ NULL, ewarn_eq1 },			/* In */
@@ -1000,11 +1002,36 @@ post_eoln(POST_ARGS)
 }
 
 static int
+post_fname(POST_ARGS)
+{
+	const struct mdoc_node *n;
+	size_t pos;
+
+	n = mdoc->last->child;
+	pos = strcspn(n->string, "()");
+	if (n->string[pos] != '\0')
+		mandoc_msg(MANDOCERR_FN_PAREN, mdoc->parse,
+		    n->line, n->pos + pos, n->string);
+	return(1);
+}
+
+static int
+post_fn(POST_ARGS)
+{
+
+	post_fname(mdoc);
+	post_fa(mdoc);
+	return(1);
+}
+
+static int
 post_fo(POST_ARGS)
 {
 
 	hwarn_eq1(mdoc);
 	bwarn_ge1(mdoc);
+	if (mdoc->last->type == MDOC_HEAD)
+		post_fname(mdoc);
 	return(1);
 }
 
Index: mandoc.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc.h,v
retrieving revision 1.160
retrieving revision 1.161
diff -Lmandoc.h -Lmandoc.h -u -p -r1.160 -r1.161
--- mandoc.h
+++ mandoc.h
@@ -114,6 +114,7 @@ enum	mandocerr {
 	MANDOCERR_BL_SKIPW, /* skipping -width argument: Bl -type */
 	MANDOCERR_AT_BAD, /* unknown AT&T UNIX version: At version */
 	MANDOCERR_FA_COMMA, /* comma in function argument: arg */
+	MANDOCERR_FN_PAREN, /* parenthesis in function name: arg */
 	MANDOCERR_RS_BAD, /* invalid content in Rs block: macro */
 	MANDOCERR_SM_BAD, /* invalid Boolean argument: macro arg */
 	MANDOCERR_FT_BAD, /* unknown font, skipping request: ft font */
Index: read.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/read.c,v
retrieving revision 1.88
retrieving revision 1.89
diff -Lread.c -Lread.c -u -p -r1.88 -r1.89
--- read.c
+++ read.c
@@ -159,6 +159,7 @@ static	const char * const	mandocerrs[MAN
 	"skipping -width argument",
 	"unknown AT&T UNIX version",
 	"comma in function argument",
+	"parenthesis in function name",
 	"invalid content in Rs block",
 	"invalid Boolean argument",
 	"unknown font, skipping request",
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Feature request for -Tlint
  2014-10-11 21:25 ` Ingo Schwarze
@ 2014-10-12  8:44   ` Anthony J. Bentley
  2014-10-13 13:27     ` Ingo Schwarze
  0 siblings, 1 reply; 4+ messages in thread
From: Anthony J. Bentley @ 2014-10-12  8:44 UTC (permalink / raw)
  To: discuss; +Cc: wblock

Hi Ingo,

Ingo Schwarze writes:
> > Of course, parentheses are allowed in arguments besides the first
> > argument, but I can't think of any case where they're needed in
> > the first one.
> 
> Me neither, so i have committed the following patch.

Thanks for implementing this. There are some cases (common in the
LibreSSL manuals) that are false positives:

SSL_CTX_set_info_callback(3):
.Fn "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"

SSL_CTX_set_client_cert_cb(3):
.Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"

Based on this I would suggest the warning only pick up trailing (), not
just any parentheses in the first argument. Of course, if there's a
better way to mark these up, I'd like to know...

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Feature request for -Tlint
  2014-10-12  8:44   ` Anthony J. Bentley
@ 2014-10-13 13:27     ` Ingo Schwarze
  0 siblings, 0 replies; 4+ messages in thread
From: Ingo Schwarze @ 2014-10-13 13:27 UTC (permalink / raw)
  To: discuss

Hi Anthony,

Anthony J. Bentley wrote on Sun, Oct 12, 2014 at 02:44:40AM -0600:
> Ingo Schwarze writes:
>> Anthony J. Bentley wrote:

>>> Of course, parentheses are allowed in arguments besides the first
>>> argument, but I can't think of any case where they're needed in
>>> the first one.

>> Me neither, so i have committed the following patch.

> Thanks for implementing this. There are some cases (common in the
> LibreSSL manuals) that are false positives:
> 
> SSL_CTX_set_info_callback(3):
> .Fn "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))"
> 
> SSL_CTX_set_client_cert_cb(3):
> .Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"

Gah, functions returning function pointers.
Another terrible example is signal(3).

> Based on this I would suggest the warning only pick up trailing (),
> not just any parentheses in the first argument.

Another idea:  If the first parenthesis is '(' and if it's followed
by '*', it looks like a callback and is probably OK.  I guess i'll
implement that.

> Of course, if there's a better way to mark these up, I'd like
> to know...

There is no really good way.  To insert the initial "(*",
prefexing .Fo or .Fn doesn't help because that would end up before
the line break, and there is no way to semantically prefix an
argument.  Likewise for the end:  Putting something after .Fc or .Fn
ends up after the trailing semicolon, and there is no way to
semantically postfix an .Fa macro or an .Fn argument.

So some physical trickery is required.  The best i managed to come
up with, in the sense of getting correct output, putting all
alphanumeric parts below the correct macros, and minimizing physical
formatting, looks like this:

  .Ft void
  .Fn \fR(*\fPSSL_CTX_get_info_callback "const SSL_CTX *ctx\fR))(\fP"

Sure, the "\fR(*\fP" and "\fR))(\fP" don't really belong inside
the .Fn arguments, but i see no other place to put them.

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-10-13 13:28 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-10-09 22:46 Feature request for -Tlint Anthony J. Bentley
2014-10-11 21:25 ` Ingo Schwarze
2014-10-12  8:44   ` Anthony J. Bentley
2014-10-13 13:27     ` Ingo Schwarze

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).