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

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

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 1317 bytes --]

Hi,

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?

Kristaps

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 1025 bytes --]

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

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

[Kristaps Dzonsons]

> maybe it's best not to think of Cd as an exclusively SYNOPSIS macro. why
> go to the trouble of altering current (and groff) behaviour, just to
> match the doc? it only says that because, presumably, you wrote it.
>
> i've no idea if there's a good reason for it or not. but groff does
> explicitly document how it behaves.
>
> i see no good reason for the change. but having said that, i don;t
> overly object to it.

Hi jmc,

I don't understand -- the patch makes `Cd' behave like the other special 
SYNOPSIS macros instead of having it be a special case that requires 
`Pp' when followed by other macros.

I suppose the existing behaviour is cause `Cd' traditionally occured in 
SYNOPSIS sections on its own.  But the existence of pim(4) and friends 
shows this is no longer the case.

Also, where do you see groff explicitly documenting the zany SYNOPSIS 
line-breaking behaviour?  I can only find notes in the doc.tmac source 
itself.

Thanks,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

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

[Ingo Schwarze]

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