From owner-cvs-all Mon Aug 2 19: 8:39 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 E42C914D2B; Mon, 2 Aug 1999 19:08:28 -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 LAA27702; Tue, 3 Aug 1999 11:38:00 +0930 (CST) Received: (from grog@localhost) by freebie.lemis.com (8.9.3/8.9.0) id LAA63456; Tue, 3 Aug 1999 11:37:59 +0930 (CST) Date: Tue, 3 Aug 1999 11:37:59 +0930 From: Greg Lehey To: Mike Pritchard Cc: Bruce Evans , rnordier@nordier.com, cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org Subject: Re: cvs commit: src/sbin/disklabel disklabel.8 Message-ID: <19990803113759.J62948@freebie.lemis.com> References: <199908010038.KAA16506@godzilla.zeta.org.au> <199908011141.GAA02125@mpp.pro-ns.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <199908011141.GAA02125@mpp.pro-ns.net>; from Mike Pritchard on Sun, Aug 01, 1999 at 06:41:20AM -0500 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 6:41:20 -0500, Mike Pritchard wrote: >>>> 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. Why not? Because our forefathers did it that way? > 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. There's ample scope for fixing mdoc. There are some really weird bugs^H^H^H^Hdependencies; the one Brian reported is only one of them. I keep getting gratuitous empty lines in man pages, and I'm damned if I know where they're coming from. It's not raw troff directives, anyway. > 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've taken the .ifs out and replaced them with .Dq's. My own feeling is that ``'' looks silly in ASCII. I note that mdoc(7) includes explicit constructs such as \\*q to represent quotes, which is wrong in my book, since they stay that way ("") in troff output. > 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. My statement was that it was one of the most illegible macro packages. That doesn't change if you learn it, but learning does help. > I can write most mdoc man pages from scratch off the top of my head. But only by avoiding fancy constructs. Have you tried tables in mdoc? I did in one of the vinum man pages, and it made such a mess of them (and completely blew the pagination) that I removed them and did lists instead. > 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. Well, that danger exists in a lot of cases. > 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. Don't bother, I'm doing it myself. 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