From owner-cvs-all  Sat Jul 31 17:38:30 1999
Delivered-To: cvs-all@freebsd.org
Received: from godzilla.zeta.org.au (godzilla.zeta.org.au [203.26.10.9])
	by hub.freebsd.org (Postfix) with ESMTP
	id 8F36014DB5; Sat, 31 Jul 1999 17:38:23 -0700 (PDT)
	(envelope-from bde@godzilla.zeta.org.au)
Received: (from bde@localhost)
	by godzilla.zeta.org.au (8.8.7/8.8.7) id KAA16506;
	Sun, 1 Aug 1999 10:38:22 +1000
Date: Sun, 1 Aug 1999 10:38:22 +1000
From: Bruce Evans <bde@zeta.org.au>
Message-Id: <199908010038.KAA16506@godzilla.zeta.org.au>
To: grog@FreeBSD.org, rnordier@nordier.com
Subject: Re: cvs commit: src/sbin/disklabel disklabel.8
Cc: cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org
Sender: owner-cvs-all@FreeBSD.ORG
Precedence: bulk

>> 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.

Dubious quoting: 'a' is a C character so it should probably be quoted using
C character quotes.

More dubious quoting: ``a'' looks better than "a" even in nroff output.
Why not use .Dq?

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.

Wrong style: nroff honors hard whitespace in some cases, so formatting
paragraphs in the source file limits flexibilty.

Bruce


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message