From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p36DFleD013891 for ; Wed, 6 Apr 2011 09:15:48 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 8EB6914D7E0; Wed, 6 Apr 2011 15:15:41 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([130.237.32.160]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id nnt9UhyqjsnK; Wed, 6 Apr 2011 15:15:40 +0200 (CEST) X-KTH-Auth: kristaps [193.10.49.5] X-KTH-mail-from: kristaps@bsd.lv Received: from [172.16.18.84] (unknown [193.10.49.5]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 53FA614D7D5; Wed, 6 Apr 2011 15:15:39 +0200 (CEST) Message-ID: <4D9C677B.2010804@bsd.lv> Date: Wed, 06 Apr 2011 15:15:39 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.16) Gecko/20110303 Icedove/3.0.11 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: Jason McIntyre CC: tech@mdocml.bsd.lv Subject: Re: [PATCH] mdoc.7 tweaks. References: <4D9C3699.7080802@bsd.lv> <20110406104809.GD7870@harkle.bramka> <4D9C4B1C.9060206@bsd.lv> <20110406112651.GE7870@harkle.bramka> <4D9C4E84.7080809@bsd.lv> <20110406124016.GF7870@harkle.bramka> In-Reply-To: <20110406124016.GF7870@harkle.bramka> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit >>>> 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