From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-1.sys.kth.se (smtp-1.sys.kth.se [130.237.32.175]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o857pH9j014121 for ; Sun, 5 Sep 2010 03:51:17 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-1.sys.kth.se (Postfix) with ESMTP id 77AFF1563C2 for ; Sun, 5 Sep 2010 09:51:11 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-1.sys.kth.se ([130.237.32.175]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id 1bpVy95lSGIX for ; Sun, 5 Sep 2010 09:51:09 +0200 (CEST) X-KTH-Auth: kristaps [85.8.60.165] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.bsd.lv Received: from lappy.cust.alltele.se (h85-8-60-165.dynamic.se.alltele.net [85.8.60.165]) by smtp-1.sys.kth.se (Postfix) with ESMTP id B4A451563B6 for ; Sun, 5 Sep 2010 09:51:08 +0200 (CEST) Message-ID: <4C834C17.9000502@bsd.lv> Date: Sun, 05 Sep 2010 09:51:51 +0200 From: Kristaps Dzonsons User-Agent: Thunderbird 2.0.0.23 (X11/20100318) X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: discuss@mdocml.bsd.lv Subject: Re: Cleanups to mdoc.7 section documentation. References: <4C8287F3.4000308@bsd.lv> <20100904211319.GA26112@bramka.kerhand.co.uk> In-Reply-To: <20100904211319.GA26112@bramka.kerhand.co.uk> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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