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

[Kristaps Dzonsons <kristaps@bsd.lv>]

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