From owner-cvs-all Sat Jul 31 18:15:26 1999 Delivered-To: cvs-all@freebsd.org Received: from allegro.lemis.com (allegro.lemis.com [192.109.197.134]) by hub.freebsd.org (Postfix) with ESMTP id EC0E114A13; Sat, 31 Jul 1999 18:15:17 -0700 (PDT) (envelope-from grog@freebie.lemis.com) Received: from freebie.lemis.com (freebie.lemis.com [192.109.197.137]) by allegro.lemis.com (8.9.1/8.9.0) with ESMTP id KAA17561; Sun, 1 Aug 1999 10:44:55 +0930 (CST) Received: (from grog@localhost) by freebie.lemis.com (8.9.3/8.9.0) id KAA68744; Sun, 1 Aug 1999 10:44:54 +0930 (CST) Date: Sun, 1 Aug 1999 10:44:53 +0930 From: Greg Lehey To: Bruce Evans Cc: rnordier@nordier.com, cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org Subject: Re: cvs commit: src/sbin/disklabel disklabel.8 Message-ID: <19990801104452.P64532@freebie.lemis.com> References: <199908010038.KAA16506@godzilla.zeta.org.au> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <199908010038.KAA16506@godzilla.zeta.org.au>; from Bruce Evans on Sun, Aug 01, 1999 at 10:38:22AM +1000 WWW-Home-Page: http://www.lemis.com/~grog X-PGP-Fingerprint: 6B 7B C3 8C 61 CD 54 AF 13 24 52 F8 6D A4 95 EF Organization: LEMIS, PO Box 460, Echunga SA 5153, Australia Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-41-739-7062 Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk On Sunday, 1 August 1999 at 10:38:22 +1000, Bruce Evans wrote: >>> grog 1999/07/31 01:11:59 PDT >>> >>> Modified files: >>> sbin/disklabel disklabel.8 >>> Log: >>> Make intelligible: >>> Describe the command formats in English. >>> Add references to other programs (boot0cfg, fdisk). >>> Remove some old cruft, including FUD about single-level bootstraps. >>> Add example of output format. >>> >>> Not-objected-to-by: msmith >>> rnordier >> >> Actually, I do object: 24 hours (particularly Friday afternoon through >> Saturday morning) is probably too short a period after which to assume >> "qui tacet consentire" in the case of a volunteer project. > > I object too. Apart from the points mentioned by Robert, it adds > hundreds of (mdoc) style bugs. E.g.: > > *************** > *** 333,340 **** > Some device drivers create a label containing only a single large partition > ! if a disk is unlabeled; thus, the label must be written to the ``a'' > ! partition of the disk while it is open. > ! This sometimes requires the desired label to be set in two steps, > ! the first one creating at least one other partition, > ! and the second setting the label on the new partition > ! while shrinking the ``a'' partition. > .Pp > --- 529,540 ---- > Some device drivers create a label containing only a single large partition > ! if a disk is unlabeled; thus, the label must be written to the > ! .if t ``a'' > ! .if n "a" > ! partition of the disk while it is open. This sometimes requires the desired > ! label to be set in two steps, the first one creating at least one other > ! partition, and the second setting the label on the new partition while shrinking > ! the > ! .if t ``a'' > ! .if n "a" > ! partition. > .Pp > > Here you take a paragraph written in normal mdoc style and change dubious > quoting to even more dubious quoting, and then reformat the paragraph to > abnormal/wrong style. > > Normal mdoc style: most lines are very short, even without markup; > sentences and even clauses begin in column 1. Is this a feature or a bug? I haven't seen anything written about it being a feature, especially when the lines are usually of markedly uneven length. It doesn't correspond to any other style I know. What's the reasoning? Counterargument: mdoc must be the most illegible *roff macro format I know. It's an order of magnitude more difficult to write man pages in it than in, say, mm. Anything which makes the source more legible is a good idea IMO. > Dubious quoting: 'a' is a C character so it should probably be quoted using > C character quotes. 'a' is a C character, but the partition identifier "a" is not. > More dubious quoting: ``a'' looks better than "a" even in nroff > output. This is an opinion which few share. Again, we need to decide what this stuff should look like. The vast majority of man pages use "" in nroff, so I thought it would be better to stick to the unwritten convention. > Why not use .Dq? Because it produces ``'' :-) That was my first attempt. > Abnormal style: most lines are formatted to 80 characters, as if by > fmt(1). Changes ripple through entire paragraphs (limited by > markup) and give large diffs. These diffs would be large anyway. There's not much similarity between the text and what went before. Where there was, I had left the format as it was. > Wrong style: nroff honors hard whitespace in some cases, so formatting > paragraphs in the source file limits flexibilty. I don't see any example of that here. Can you show me one? And in those cases where the hard white space is significant, you can always format accordingly, so I don't see any limit in flexibilty. Greg -- See complete headers for address, home page and phone numbers finger grog@lemis.com for PGP public key To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message