Re: `Cd' and non-pairwise-breaking in SYNOPSIS.

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps and Joel,

Kristaps Dzonsons wrote on Tue, Mar 27, 2012 at 03:54:59PM +0200:

> Joel (CC'd) had asked off-list about manuals in .4 that have the
> following syntax:
> 
> SYNOPSIS
>      options BLAH
> 
>      #include <sys/blah.h>
>      #include <sys/foo.h>
> 
>      int
>      foo(int bar);
> 
> In the mdoc(7) manpage, we specify
> 
>        Some macros are displayed differently in the SYNOPSIS
>        section, particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft.
>        All of these macros are output on their own line.  If two
>        such dissimilar macros are pairwise invoked (except for Ft
>        before Fo or Fn), they are separated by a vertical space,
>        unless in the case of Fo, Fn, and Ft, which are always
>        separated by vertical space.
> 
> But this is a lie for `Cd', which does not emit a newline as would
> `In' or the others.  OpenBSD's manuals, for example, use a `Pp'
> separating the elements.  Examples:
> 
> http://www.openbsd.org/cgi-bin/man.cgi?query=multicast
> http://www.openbsd.org/cgi-bin/man.cgi?query=pim
> 
> groff(1) requires the `Pp'.
> 
> Basically, I think this breaks the consistency of other SYNOPSIS
> macros, which do not require `Pp'.  In the following patch,
> mandoc(1) puts in the necessary space automatically.  This has no
> effect on manuals that already use `Pp' but for a warning.  I tried
> to patch groff's doc.tmac for the same effect, but failed.
> 
> Thoughts?

I agree that the semantic change you propose would improve the
mdoc(7) language.  However, i still regard compatibility, in
particular with groff, as more important than minor improvements.
We should only break compatibility when we have really strong
reasons to do so.

I suspect that Werner Lemberg would accept a patch, unless it
would be too complicated or intrusive, and in that case, i would
be happy with the change.  But without staying in line with groff,
i'd be opposed to the change and think we should rather adjust
the manual to reflect reality.

Right now, i don't feel like diving into groff mdoc, in particular
since it's probably very complicated, or you wouldn't have failed.
There is a sufficient number of bugs in mandoc we could fix, so
i don't think i should give priority to this suggestion.

Yours,
  Ingo


> Index: mdoc_html.c
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_html.c,v
> retrieving revision 1.182
> diff -u -p -r1.182 mdoc_html.c
> --- mdoc_html.c	3 Nov 2011 20:37:00 -0000	1.182
> +++ mdoc_html.c	27 Mar 2012 13:53:49 -0000
> @@ -303,6 +303,8 @@ synopsis_pre(struct html *h, const struc
>  	}
>  
>  	switch (n->prev->tok) {
> +	case (MDOC_Cd):
> +		/* FALLTHROUGH */
>  	case (MDOC_Fd):
>  		/* FALLTHROUGH */
>  	case (MDOC_Fn):
> Index: mdoc_term.c
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc_term.c,v
> retrieving revision 1.238
> diff -u -p -r1.238 mdoc_term.c
> --- mdoc_term.c	13 Nov 2011 13:15:14 -0000	1.238
> +++ mdoc_term.c	27 Mar 2012 13:53:50 -0000
> @@ -1345,6 +1345,8 @@ synopsis_pre(struct termp *p, const stru
>  	 * vertical space, else only newline and move on.
>  	 */
>  	switch (n->prev->tok) {
> +	case (MDOC_Cd):
> +		/* FALLTHROUGH */
>  	case (MDOC_Fd):
>  		/* FALLTHROUGH */
>  	case (MDOC_Fn):
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv