Giving up on emulating SYNOPSIS vspace.

Giving up on emulating SYNOPSIS vspace.

[Kristaps Dzonsons]

Hi,

As you may know from the commits, I've been trying to normal-form 
groff's SYNOPSIS behaviour regarding vertical spacing.  I have failed. 
Anything but using "normal" SYNOPSIS macros produces catshit.

If you really want to cover groff's behaviour, send me patches and I'll 
find behaviour that breaks them.  Instead I propose making consistent 
rules out of observed, normative behaviour, then going from there.

*Please give feedback on this*: the SYNOPSIS is very important.  I will 
hold off on implementing my suggestion until I have some oks.  It's a 
trivial implementation and will result in some nice cleanup, and is 
easily documented.

Note that I'll only discuss 'function' manual sections in this email, 
i.e., Fn/Ft/etc., not Nm/Op/etc, which is much easier.  You'll see what 
I mean.  Nm/Op is more straightforward (let's leave this discussion for 
later).

First, I propose that SYNOPSIS sections be grouped into the following 
macro sets,

  .In
  .Ft/Fn ("combo", i.e., one after the other)
  .Ft/Fo (same)
  .Fo
  .Fn
  .Fd

with rules as follows.  Any macro/combo of these sets will be preceded 
and proceeded by a newline.  It doesn't matter what the hell comes 
before or after or whether these are line macros or not.

Next, non-like pair-wise sets will be separated by a single vertical space.

Lastly, like pairwise Ft/Fn, Ft/Fo, Fo, and Fn are separated by a single 
vertical space.

That's it.  Simple, no?

Please let me know ASAP, as I want to tag version 1.10.1 and move on 
with PostScript and Ingo's block-breaking patches.

Thanks,

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

Re: Giving up on emulating SYNOPSIS vspace.

[Jason McIntyre]

On Mon, Jun 07, 2010 at 01:18:28AM +0200, Kristaps Dzonsons wrote:
> Hi,
> 
> As you may know from the commits, I've been trying to normal-form 
> groff's SYNOPSIS behaviour regarding vertical spacing.  I have failed. 
> Anything but using "normal" SYNOPSIS macros produces catshit.
> 
> If you really want to cover groff's behaviour, send me patches and I'll 
> find behaviour that breaks them.  Instead I propose making consistent 
> rules out of observed, normative behaviour, then going from there.
> 
> *Please give feedback on this*: the SYNOPSIS is very important.  I will 
> hold off on implementing my suggestion until I have some oks.  It's a 
> trivial implementation and will result in some nice cleanup, and is 
> easily documented.
> 
> Note that I'll only discuss 'function' manual sections in this email, 
> i.e., Fn/Ft/etc., not Nm/Op/etc, which is much easier.  You'll see what 
> I mean.  Nm/Op is more straightforward (let's leave this discussion for 
> later).
> 
> First, I propose that SYNOPSIS sections be grouped into the following 
> macro sets,
> 
>  .In
>  .Ft/Fn ("combo", i.e., one after the other)
>  .Ft/Fo (same)
>  .Fo
>  .Fn
>  .Fd
> 
> with rules as follows.  Any macro/combo of these sets will be preceded 
> and proceeded by a newline.  It doesn't matter what the hell comes 
> before or after or whether these are line macros or not.
> 
> Next, non-like pair-wise sets will be separated by a single vertical space.
> 
> Lastly, like pairwise Ft/Fn, Ft/Fo, Fo, and Fn are separated by a single 
> vertical space.
> 
> That's it.  Simple, no?
> 
> Please let me know ASAP, as I want to tag version 1.10.1 and move on 
> with PostScript and Ingo's block-breaking patches.
> 
> Thanks,
> 
> Kristaps

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

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.

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

Re: Giving up on emulating SYNOPSIS vspace.

[Ingo Schwarze]

Hi Kristaps,

> First, I propose that SYNOPSIS sections be grouped into the
> following macro sets,
> 
>  .In
>  .Ft/Fn ("combo", i.e., one after the other)
>  .Ft/Fo (same)
>  .Fo
>  .Fn
>  .Fd
> 
> with rules as follows.  Any macro/combo of these sets will be
> preceded and proceeded by a newline.  It doesn't matter what the
> hell comes before or after or whether these are line macros or not.
> 
> Next, non-like pair-wise sets will be separated by a single vertical space.
> 
> Lastly, like pairwise Ft/Fn, Ft/Fo, Fo, and Fn are separated by a
> single vertical space.

That definitely sounds sane, and it covers the most important use cases.

I'm not 100% sure this covers all sane use cases, even though i couldn't
name a real-world manual page that needs additional rules, off the top
of my head.

So, i think implementing this has good chances to be OK;
there is a small risk it turns out to not be better in practice
than what we have now, but in that case it will hopefully not be
too difficult to add the missing feature(s).

[...]
> move on with PostScript and Ingo's block-breaking patches.

Oh, you don't have the final version yet, what you have is
 1) known buggy
 2) not feature-complete

I need to check that the final version in my tree is really
complete and correct, extract it and post it.  I hope to get
round to that.  It's really the next thing i should do with
respect to mandoc, now that 1.10.1 is merged into OpenBSD.

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

Re: Giving up on emulating SYNOPSIS vspace.

[Kristaps Dzonsons]

> 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

Re: Giving up on emulating SYNOPSIS vspace.

[Ingo Schwarze]

Kristaps Dzonsons wrote on Mon, Jun 07, 2010 at 01:12:15PM +0200:

> It's much nicer now.

Right.  The code has definitely become more systematic, and i do not
see any serious fallout.

There a a two minor issues.

1) SYNOPSIS macros following non-SYNOPSIS-specific text
-------------------------------------------------------
Consider /usr/src/lib/libc/compat-43/sigvec.3:

  .Sh SYNOPSIS
  .Fd #include <signal.h>
  .Pp
  .Bd -literal
  struct sigvec {
  	void     (*sv_handler)();
  	int      sv_mask;
  	int      sv_flags;
  };
  .Ed
  .Ft int
  .Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec"

I think this is sane usage.

There is no more blank line between the .Ed and .Ft (missing term_vspace).
I guess this can be easily fixed by making .Ft and friends issue a
term_vspace after *any* preceding content, even regular text or
random macros.  Not because that would be closer to groff (not sure
whether it would), but because it looks better.

Besides, the .Pp after the .Fd causes *two* blank lines.
One would be sufficient.
But that is not important, lets just add it to the TODO list
and not worry about it right now.


2) global variables
-------------------
Consider /usr/src/lib/libc/rpc/svc.3:

  .Ft int
  .Fn svc_destroy "SVCXPRT *xprt"
  .Ft struct pollfd *
  .Fa svc_pollfd ;
  .Ft int
  .Fa svc_max_pollfd ;
  .Ft fd_set
  .Fa svc_fdset ;
  .Ft fd_set
  .Fa *__svc_fdset ;
  .Ft int
  .Fa __svc_fdsetsize ;
  .Ft int
  .Fa svc_fds ;
  .Ft int
  .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"

I think this is acceptable usage; probably using .Va instead of .Fa
would be a bit better, but apart from that, i wouldn't know how to
express this in a better way.  (NB, it wasn't RPC variable naming
conventions i was trying to praise here... ;-)

There is no more blank line between the .Ft/.Fa (or .Ft/.Va) pairs.
It think it might be good to treat .Ft/.Fa and .Ft/.Va exactly
like .Ft/.Fn.  Why not just *always* issue the blank line before
.Ft, whatever may be following?  Wouldn't that make the code even
simpler, all the while improving the results?  I really can't think
of any sane construct that might not want a blank line before .Ft
in the synopsis - and even less find one in real manuals.


That's all i found in libc.

Of course, large portions of man9 are still garbled for the lack
of .nr support, but that's another matter.

So, i'm going to commit this to OpenBSD, we can fix the two minor
issues presented above in tree, either now or later.

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

Re: Giving up on emulating SYNOPSIS vspace.

[Kristaps Dzonsons]

> 1) SYNOPSIS macros following non-SYNOPSIS-specific text
> -------------------------------------------------------
> Consider /usr/src/lib/libc/compat-43/sigvec.3:
> 
>   .Sh SYNOPSIS
>   .Fd #include <signal.h>
>   .Pp
>   .Bd -literal
>   struct sigvec {
>   	void     (*sv_handler)();
>   	int      sv_mask;
>   	int      sv_flags;
>   };
>   .Ed
>   .Ft int
>   .Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec"
> 
> I think this is sane usage.

I agree.  I'm yet to find a good way to document structs.  This is as 
good as any.  And I agree: if `Ft' (and/or all SYNOPSIS-set macros) 
assert prior vspace for /all/ non-like elements, we'll capture this 
usage fine.

> Besides, the .Pp after the .Fd causes *two* blank lines.
> One would be sufficient.
> But that is not important, lets just add it to the TODO list
> and not worry about it right now.

Agreed.  Pp should be a little smarter in general about when it's a noop 
(i.e., on a newline as it is).

> 2) global variables
> -------------------
> Consider /usr/src/lib/libc/rpc/svc.3:
> 
>   .Ft int
>   .Fn svc_destroy "SVCXPRT *xprt"
>   .Ft struct pollfd *
>   .Fa svc_pollfd ;
>   .Ft int
>   .Fa svc_max_pollfd ;
>   .Ft fd_set
>   .Fa svc_fdset ;
>   .Ft fd_set
>   .Fa *__svc_fdset ;
>   .Ft int
>   .Fa __svc_fdsetsize ;
>   .Ft int
>   .Fa svc_fds ;
>   .Ft int
>   .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
> 
> I think this is acceptable usage; probably using .Va instead of .Fa
> would be a bit better, but apart from that, i wouldn't know how to
> express this in a better way.  (NB, it wasn't RPC variable naming
> conventions i was trying to praise here... ;-)

`Vt' is documented for use in this case.

> 
> There is no more blank line between the .Ft/.Fa (or .Ft/.Va) pairs.
> It think it might be good to treat .Ft/.Fa and .Ft/.Va exactly
> like .Ft/.Fn.  Why not just *always* issue the blank line before
> .Ft, whatever may be following?  Wouldn't that make the code even
> simpler, all the while improving the results?  I really can't think
> of any sane construct that might not want a blank line before .Ft
> in the synopsis - and even less find one in real manuals.

I agree, although it should be Vt (there aren't any "F" in the Ft/Fa).

> That's all i found in libc.

Nice!

> Of course, large portions of man9 are still garbled for the lack
> of .nr support, but that's another matter.
> 
> So, i'm going to commit this to OpenBSD, we can fix the two minor
> issues presented above in tree, either now or later.

Can you commit fixes to BSD.lv as well?

Thanks,

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

Re: Giving up on emulating SYNOPSIS vspace.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Tue, Jun 08, 2010 at 01:42:25AM +0200:
> Ingo Schwarze wrote:

>> 2) global variables
>> -------------------
>> Consider /usr/src/lib/libc/rpc/svc.3:
>>
>>  .Ft int
>>  .Fn svc_destroy "SVCXPRT *xprt"
>>  .Ft struct pollfd *
>>  .Fa svc_pollfd ;
>>  .Ft int
>>  .Fa svc_max_pollfd ;
>>  .Ft fd_set
>>  .Fa svc_fdset ;
>>  .Ft fd_set
>>  .Fa *__svc_fdset ;
>>  .Ft int
>>  .Fa __svc_fdsetsize ;
>>  .Ft int
>>  .Fa svc_fds ;
>>  .Ft int
>>  .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
>>
>> I think this is acceptable usage; probably using .Va instead of .Fa
>> would be a bit better, but apart from that, i wouldn't know how to
>> express this in a better way.  (NB, it wasn't RPC variable naming
>> conventions i was trying to praise here... ;-)

> `Vt' is documented for use in this case.

Right, and i tried that, but being documented is not the same as
being in working order.  This is what both old and new grow spit out
when you switch to .Vt/.Va:

     struct pollfd *
     svc_pollfd;
     int
     svc_max_pollfd;
     fd_set
     svc_fdset;
     fd_set
     *__svc_fdset;
     int
     __svc_fdsetsize;
     int
     svc_fds;

Not quite what we want...  :-/

[...]
>> So, i'm going to commit this to OpenBSD, we can fix the two minor
>> issues presented above in tree, either now or later.

> Can you commit fixes to BSD.lv as well?

Er, frankly, no, i meant i'm going commit your reorg, i don't have
patches for the issues (1) and (2) yet.  But as this concerns a very
small number of pages and all that goes awry is a few missing
blank lines, we can add these patches whenever we have them.

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

OT: Vt vs. Ft/Fn (WAS: Giving up on emulating SYNOPSIS vspace.)

[Kristaps Dzonsons]

>>> 2) global variables
>>> -------------------
>>> Consider /usr/src/lib/libc/rpc/svc.3:
>>>
>>>  .Ft int
>>>  .Fn svc_destroy "SVCXPRT *xprt"
>>>  .Ft struct pollfd *
>>>  .Fa svc_pollfd ;
>>>  .Ft int
>>>  .Fa svc_max_pollfd ;
>>>  .Ft fd_set
>>>  .Fa svc_fdset ;
>>>  .Ft fd_set
>>>  .Fa *__svc_fdset ;
>>>  .Ft int
>>>  .Fa __svc_fdsetsize ;
>>>  .Ft int
>>>  .Fa svc_fds ;
>>>  .Ft int
>>>  .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
 > [...]
> Right, and i tried that, but being documented is not the same as
> being in working order.  This is what both old and new grow spit out
> when you switch to .Vt/.Va:

I'd meant just `Vt' instead of Vt/Va, forming

      int
      svc_destroy(SVCXPRT *xprt);

      struct pollfd * svc_pollfd;
      int svc_max_pollfd;
      fd_set svc_fdset;
      fd_set *__svc_fdset;
      int __svc_fdsetsize;
      int svc_fds;

      int
      svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

from, e.g.,

.Vt struct pollfd * svc_pollfd ;

mdoc.samples documents `Vt' as doing funny business in SYNOPSIS, not 
`Va' (wtf?).  From what I understand, Vt's the conventional way of 
putting variables in the SYNOPSIS.  `F' macros are certainly not the way.

jmc, wiz, any suggestions and/or observations?  I like Ingo's notation 
of `Vt/Va'.  I've never seen it before (mdocml's manuals use `Vt' 
standalone as suggested in mdoc.samples), but you know better.

I think we can take this opportunity, in mdoc.7, to specify how 
variables should get documented in the SYNOPSIS.  And what about the 
following:

  - CPP defines?
  - structs Vt's?  (the `Bd' was used in one of your examples)

We have `Dv' for defines, but that doesn't help me with wanting to print 
out `.Dv #define FOOBAR'.

>> Can you commit fixes to BSD.lv as well?
> 
> Er, frankly, no, i meant i'm going commit your reorg, i don't have
> patches for the issues (1) and (2) yet.  But as this concerns a very
> small number of pages and all that goes awry is a few missing
> blank lines, we can add these patches whenever we have them.

Ah, I see...  The above patches are easy enough to come by, so long as 
we settle on the Right Way of doing it.

Thanks again,

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

Re: OT: Vt vs. Ft/Fn (WAS: Giving up on emulating SYNOPSIS vspace.)

[Thomas Klausner]

On Tue, Jun 08, 2010 at 11:13:32AM +0200, Kristaps Dzonsons wrote:
> mdoc.samples documents `Vt' as doing funny business in SYNOPSIS, not
> `Va' (wtf?).  From what I understand, Vt's the conventional way of
> putting variables in the SYNOPSIS.  `F' macros are certainly not the
> way.
> 
> jmc, wiz, any suggestions and/or observations?  I like Ingo's
> notation of `Vt/Va'.  I've never seen it before (mdocml's manuals
> use `Vt' standalone as suggested in mdoc.samples), but you know
> better.

I found some examples in libelf manpages (from FreeBSD) and a few in
random places. More .Vt usage like groff's mdoc(7) describes.

> I think we can take this opportunity, in mdoc.7, to specify how
> variables should get documented in the SYNOPSIS.  And what about the
> following:
> 
>  - CPP defines?
>  - structs Vt's?  (the `Bd' was used in one of your examples)
> 
> We have `Dv' for defines, but that doesn't help me with wanting to
> print out `.Dv #define FOOBAR'.

rpcgen(1) actually uses Dv in that case, but it's the only occurrence.
For the name of the struct, using Vt is fine, but for the struct
definition including members, there currently is no better tag than
Bd, which at least keeps it readable. Do we want to extend mdoc?
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: OT: Vt vs. Ft/Fn (WAS: Giving up on emulating SYNOPSIS vspace.)

[Kristaps Dzonsons]

>> mdoc.samples documents `Vt' as doing funny business in SYNOPSIS, not
>> `Va' (wtf?).  From what I understand, Vt's the conventional way of
>> putting variables in the SYNOPSIS.  `F' macros are certainly not the
>> way.
>>
>> jmc, wiz, any suggestions and/or observations?  I like Ingo's
>> notation of `Vt/Va'.  I've never seen it before (mdocml's manuals
>> use `Vt' standalone as suggested in mdoc.samples), but you know
>> better.
> 
> I found some examples in libelf manpages (from FreeBSD) and a few in
> random places. More .Vt usage like groff's mdoc(7) describes.

I think the following makes sense.  Let `Vt' work as it does right now,
but let's adopt `Vt/Va' as being the conventional form for labelling
variables in the SYNOPSIS.

Pros: consistent with Ft/Fn et al.; much richer semantic annotation;
more intuitive (subjective, of course); backwards-compatible with
plain-old `Vt'.

How does this sound?  I'm really wary about changing convention, but
this seems like an area that really needs it.

>> I think we can take this opportunity, in mdoc.7, to specify how
>> variables should get documented in the SYNOPSIS.  And what about the
>> following:
>>
>>  - CPP defines?
>>  - structs Vt's?  (the `Bd' was used in one of your examples)
>>
>> We have `Dv' for defines, but that doesn't help me with wanting to
>> print out `.Dv #define FOOBAR'.
> 
> rpcgen(1) actually uses Dv in that case, but it's the only occurrence.
> For the name of the struct, using Vt is fine, but for the struct
> definition including members, there currently is no better tag than
> Bd, which at least keeps it readable. Do we want to extend mdoc?

I think extending mdoc for this is step down a maze of twisty passages.
 The SYNOPSIS should be short and sweet, I think, with a `Vt' for
structs that could be fully defined later in the manual.  I guess?

Still no idea about defines.  I see a few uses with `Fd', which makes
more sense than `Dv'.

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

Re: Vt vs. Ft/Fn

[Ingo Schwarze]

Hi Kristaps, hi Thomas,

Kristaps Dzonsons wrote on Tue, Jun 08, 2010 at 02:06:23PM +0200:

> I think the following makes sense.  Let `Vt' work as it does right now,
> but let's adopt `Vt/Va' as being the conventional form for labelling
> variables in the SYNOPSIS.
> 
> Pros: consistent with Ft/Fn et al.; much richer semantic annotation;
> more intuitive (subjective, of course); backwards-compatible with
> plain-old `Vt'.
> 
> How does this sound?  I'm really wary about changing convention, but
> this seems like an area that really needs it.

Sounds reasonable, though i might be missing some aspect of how .Vt
is traditionally used.

Currently, groff formats .Vt/.Va with a line break, just like .Ft/.Fa.
To implement your idea, that behaviour would need to be changed,
both in mandoc and in current upstream groff.

So we should postpone this and just stick with traditional .Vt for now.
But i have taken a note in my personal long-term TODO list (not to
be confused with the public short-term TODO file on bsd.lv).


> Thomas Klausner wrote:
>> Kristaps wrote:

>>> I think we can take this opportunity, in mdoc.7, to specify how
>>> variables should get documented in the SYNOPSIS.

For now, i think recommending traditional .Vt is fine.

>>> And what about the following:
>>>
>>>  - CPP defines?
>>>  - structs Vt's?  (the `Bd' was used in one of your examples)

I wouldn't worry about documenting that right now, at least not
before fixing mandoc to get the vertical spacing around .Bd
used for structs right, and even that is not terribly high
priority (as compared to .Nm/.Fn indenting and .Bk, for example).

>> Do we want to extend mdoc?

Certainly not right now!

Before it makes sense to suggest changing the rules,
we should first be able to play by them,
and we should also, after that, document them thoroughly.

Otherwise, we would only add to the chaos.


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