Re: Vt vs. Ft/Fn

[Ingo Schwarze <schwarze@usta.de>]

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