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

[Kristaps Dzonsons <kristaps@bsd.lv>]

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