Date: Sun, 1 Aug 1999 06:41:20 -0500 (CDT) From: Mike Pritchard <mpp@mpp.pro-ns.net> To: bde@zeta.org.au (Bruce Evans) Cc: grog@FreeBSD.org, rnordier@nordier.com, cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org Subject: Re: cvs commit: src/sbin/disklabel disklabel.8 Message-ID: <199908011141.GAA02125@mpp.pro-ns.net> In-Reply-To: <199908010038.KAA16506@godzilla.zeta.org.au> from Bruce Evans at "Aug 1, 1999 10:38:22 am"
next in thread | previous in thread | raw e-mail | index | archive | help
> >> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199908011141.GAA02125>