Re: Cleanups to mdoc.7 section documentation.

[Kristaps Dzonsons <kristaps@bsd.lv>]

Jason McIntyre wrote:
> On Sat, Sep 04, 2010 at 07:54:59PM +0200, Kristaps Dzonsons wrote:
>> Hi,
>>
>> I noticed that the section documentation entries redundantly noted
>> relevant sections.  Removing these led to some clarification, examples,
>> and so on.
>>
>> Yeas, nays?
>>
>> Kristaps
> 
> hmm. i'm not sure this is better. for one, it's handy not to have to
> back/forward scroll to see which sections headers pertain to which
> manual sections, and for another i think the place where you document
> the macros is the best place for examples, not in the bit where you've
> added. your diff just adds more text to the file and, if anything, we
> desperately need to cut down on verbiage in this file.
> 
> and note, for example, that the section on Ev already contains an
> exmaple; do we really need another?
> 
> so i'd nay say.

Ok, these make sense.  The thrust is just the examples giving the 
"conventional" section form (e.g., for errno): I'm unconcerned about 
whether the manual-section info is duplicated.

There are brief examples for both the SYNOPSIS and DESCRIPTION section. 
  Should these be off-loaded, say, to mdoc.template or something?

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