From owner-cvs-all  Sun Aug  1  4:42:26 1999
Delivered-To: cvs-all@freebsd.org
Received: from mpp.pro-ns.net (mpp.pro-ns.net [208.200.182.72])
	by hub.freebsd.org (Postfix) with ESMTP
	id C626914F40; Sun,  1 Aug 1999 04:42:21 -0700 (PDT)
	(envelope-from mpp@mpp.pro-ns.net)
Received: (from mpp@localhost)
	by mpp.pro-ns.net (8.9.3/8.9.3) id GAA02125;
	Sun, 1 Aug 1999 06:41:20 -0500 (CDT)
	(envelope-from mpp)
From: Mike Pritchard <mpp@mpp.pro-ns.net>
Message-Id: <199908011141.GAA02125@mpp.pro-ns.net>
Subject: Re: cvs commit: src/sbin/disklabel disklabel.8
In-Reply-To: <199908010038.KAA16506@godzilla.zeta.org.au> from Bruce Evans at "Aug 1, 1999 10:38:22 am"
To: bde@zeta.org.au (Bruce Evans)
Date: Sun, 1 Aug 1999 06:41:20 -0500 (CDT)
Cc: grog@FreeBSD.org, rnordier@nordier.com, cvs-all@FreeBSD.org,
	cvs-committers@FreeBSD.org
X-Mailer: ELM [version 2.4ME+ PL54 (25)]
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: owner-cvs-all@FreeBSD.ORG
Precedence: bulk

> >>     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.
> >
> I object too.  Apart from the points mentioned by Robert, it adds
> hundreds of (mdoc) style bugs.  E.g.:
> 
> ...[trimmed]
> ! .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?

Arghhhh!  Man pages should never use direct *roff command for formatting.
If for some reason you can't do it in mdoc, then either we should
fix the particular mdoc macro or define a new one to do it.
Adding direct *roff directives usually winds up messing something
else up in the end.  Using *roff commands directly can really
mess things up in some cases when using mdoc.  I think we should
be able to do what you want within the current mdoc package.

I would rather not have to add anything to mdoc, just so our man pages
are compatible with the other *BSDs, but if we really do need to
add something, we should.  Hopefully we can talk the other *BSDs
into adopting it.

I agree with Bruce here, just use .Dq, or .Ac, or .Aq (or one of
ther other quoting macros).  

As for a comment in a follow-up to Bruce's message, if you learn mdoc, 
it is not that illegible.  I can write most mdoc man pages from scratch 
off the top of my head.  I've converted  man pages from the old -man 
package to -mdoc by hand without ever having to refer to the man pages.
Yes, it is a little clumbsy at times.  But having the same text repeated
twice just for quoting make it twice as likely that someone
won't correct all of the text when making changes.

If no one objects, I'll fix disklabel.8 back into true mdoc
format, which I would probably do anyways now that I know it
is using *roff directives directly.

[...]
  
-Mike
--
Mike Pritchard
mpp@FreeBSD.ORG or mpp@mpp.pro-ns.net


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