Re: [PATCH] mdoc.7 tweaks.

[Kristaps Dzonsons <kristaps@bsd.lv>]

>>>> Jason, thanks for your feedback.  Enclosed is a corrected patch with the
>>>> exception of the following:
>>>>
>>>>>> -This expands upon the brief, one line description in
>>>>>> -.Em NAME .
>>>>>> -It usually contains a breakdown of the options (if documenting a
>>>>>> +This begins with an expansion of the brief, one line description in
>>>>>> +.Em NAME :
>>>>>
>>>>> you should use Sx to refer to other section names.
>>>>
>>>> We don't have section documentation `Ss'd, so I can't refer back to them
>>>> as such.  The reason being that we stipulate (in both `Ss' and `Sh'
>>>> documentation) that names should be unique, so I can't `Ss NAME'.
>>>>
>>>> On the other hand, I agree that `Em' is not a good choice.  Do you have
>>>> another suggestion?  (Note that using `It Em NAME' to document and refer
>>>> to per-section documentation has long since irritated me.)
>>>>
>>>
>>> hmm. we really only have Em and Sy to play around with in cases like
>>> this. i guess it's just a matter of preference. i have none in
>>> particular...
>>
>> How about `Ss NAME Section' or something similar?  Anything but
>> standalone NAME.  In fact, I'd far prefer something like this than an
>> opaque `Sy NAME' or whatnot.  Thoughts?
>
> i think that would just look messy. you could try, but i'm not
> convinced. many things don;t fit specific macros very well - i don;t see
> the point of worrying about it.

Jason (note re-posting to tech@),

Enclosed is a patch (the prior has been committed) that does just this 
and makes the `Em's used for table headers be `Sy'.  It also notes the 
difference between a "manual section" and a "section" (in my opinion, we 
should really change the term "manual section" to "category" or something).

This uses the schema of "XXXX section" for section documentation, and 
allows the manual to refer directly to this documentation.  Quite handy.

Thoughts?  If you're ambivalent, I note that this makes linked output 
(-T[x]html and -Tpdf/-Tps, which I'd like to implement) much more 
reference-friendly.

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