From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailout.scc.kit.edu (mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id q3FLFEKT011101 for ; Sun, 15 Apr 2012 17:15:15 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1SJWmu-00029j-A0; Sun, 15 Apr 2012 23:15:12 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1SJWmu-0002Fr-9c; Sun, 15 Apr 2012 23:15:12 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1SJWmu-0002Gk-7L; Sun, 15 Apr 2012 23:15:12 +0200 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1SJWmt-0002tj-SX; Sun, 15 Apr 2012 23:15:11 +0200 Date: Sun, 15 Apr 2012 23:15:11 +0200 From: Ingo Schwarze To: tech@mdocml.bsd.lv Cc: Joel Dahl , Jason McIntyre Subject: Re: `Cd' and non-pairwise-breaking in SYNOPSIS. Message-ID: <20120415211511.GK28604@iris.usta.de> References: <4F71C6B3.9080302@bsd.lv> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4F71C6B3.9080302@bsd.lv> User-Agent: Mutt/1.5.21 (2010-09-15) 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 > #include > > 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