Re: Giving up on emulating SYNOPSIS vspace.

[Kristaps Dzonsons <kristaps@bsd.lv>]

> i propose you do whatever you think makes sense: a simple synopsis with
> workable rules is preferable to a bug-compatible groff.

Done and committed.  Ingo, please let me know if you experience fall-out
and we can tweak as necessary.  If it's ok, I'll tag the version and we
can move on.

From mdoc.7 (note, by the way, mandoc(1) has a new output option
-Owidth=xxx that allows me to paste this into this mail so nicely):

       SYNOPSIS
       Documents the utility invocation syntax, function call
       syntax, or device configuration.

       For the first, utilities (sections 1, 6, and 8), this is
       generally structured as follows:

             .Nm foo
             .Op Fl v
             .Op Fl o Ar file
             .Op Ar
             .Nm bar
             .Op Fl v
             .Op Fl o Ar file
             .Op Ar

       For the second, function calls (sections 2, 3, 9):

             .Vt extern const char *global;
             .In header.h
             .Ft "char *"
             .Fn foo "const char *src"
             .Ft "char *"
             .Fn bar "const char *src"

       And for the third, configurations (section 4):

             .Cd "it* at isa? port 0x2e"
             .Cd "it* at isa? port 0x4e"

       Manuals not in these sections generally don't need a
       SYNOPSIS.

       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 pair-wise 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.


> i know you don;t want to talk about the simpler cases but i have to add:
> can we make synopsis nice please? Bk/Ek is broken, and we need a nice
> synopsis. are we far away? let's take this from openbsd's isakmpd.8:
> 
> 	isakmpd [-46adKLnSTv] [-c config-file] [-D class=level] [-f fifo] [-i
> 	pid-file] [-l packetlog-file] [-N udpencap-port] [-p listen-port] [-R
> 	report-file]
> 
> i'd like this, by default:
> 
> 	isakmpd [-46adKLnSTv] [-c config-file] [-D class=level] [-f fifo]
> 		[-i pid-file] [-l packetlog-file] [-N udpencap-port]
> 		[-p listen-port] [-R report-file]
> 
> ignore any crappy Bk/Ek stuff. just format nicely please. it's a real
> killer for mandoc right now, i feel. by the way, it's how groff
> currently formats it. i've no idea if it's coincidence or sth else.

One of the reasons of fixing vertical spacing was to pave the way for
this.  Before doing so, there was too much chaos between -T[x]html and
-Tascii in the various macro handlers.  It's much nicer now.

Thanks,

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