Date: Tue, 3 Aug 1999 11:37:59 +0930 From: Greg Lehey <grog@lemis.com> To: Mike Pritchard <mpp@mpp.pro-ns.net> Cc: Bruce Evans <bde@zeta.org.au>, 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> In-Reply-To: <199908011141.GAA02125@mpp.pro-ns.net>; from Mike Pritchard on Sun, Aug 01, 1999 at 06:41:20AM -0500 References: <199908010038.KAA16506@godzilla.zeta.org.au> <199908011141.GAA02125@mpp.pro-ns.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990803113759.J62948>