Date: Sun, 1 Aug 1999 10:44:53 +0930 From: Greg Lehey <grog@lemis.com> To: Bruce Evans <bde@zeta.org.au> 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> In-Reply-To: <199908010038.KAA16506@godzilla.zeta.org.au>; from Bruce Evans on Sun, Aug 01, 1999 at 10:38:22AM %2B1000 References: <199908010038.KAA16506@godzilla.zeta.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990801104452.P64532>