Date: Wed, 11 Jul 2001 10:06:21 +0300 From: Ruslan Ermilov <ru@FreeBSD.org> To: Greg Lehey <grog@FreeBSD.org> Cc: doc@FreeBSD.org Subject: Re: cvs commit: src/sbin/vinum vinum.8 Message-ID: <20010711100621.A24098@sunbay.com> In-Reply-To: <20010711082605.D64441@wantadilla.lemis.com>; from grog@FreeBSD.org on Wed, Jul 11, 2001 at 08:26:05AM %2B0930 References: <200107101800.f6AI0Jg09923@freefall.freebsd.org> <200107101004.f6AA49e06877@freefall.freebsd.org> <200107041418.f64EIXJ57365@freefall.freebsd.org> <20010704173757.A296@sydney.worldwide.lemis.com> <20010705084955.A92314@sunbay.com> <20010711082605.D64441@wantadilla.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[Cc: list trimmed to -doc as per imp@]
On Wed, Jul 11, 2001 at 08:26:05AM +0930, Greg Lehey wrote:
> On Thursday, 5 July 2001 at 8:49:55 +0300, Ruslan Ermilov wrote:
> > On Wed, Jul 04, 2001 at 05:37:57PM -0500, Greg Lehey wrote:
> >> On Wednesday, 4 July 2001 at 7:18:32 -0700, Ruslan Ermilov wrote:
> >>> ru 2001/07/04 07:18:32 PDT
> >>>
> >>> Modified files:
> >>> sbin/vinum vinum.8
> >>> Log:
> >>> mdoc(7) police:
> >>> Keep document title (.Dt) in CAPITALS, as required by the mdoc(7) manpage.
> >>
> >> This is WRONG. We discussed this requirement, and you came up with no
> >> valid reasons. As a result, I fixed the problem in the next update.
> >> It is really childish to have commit wars like this. Please back out
> >> immediately. We'll discuss in core whether it makes any sense to
> >> shout. I believe that the title of the document should be the name of
> >> the command.
> >
> > Nope, this was *you* who, with no valid reason, backed out my change
> > without explaining.
>
> I first asked you to back it out, and when you refused (without
> stating a valid reason), I did it myself. My valid reason is that the
> name of the program is vinum, not VINUM. Your reason for this change
> was bogus: you said that troff couldn't handle lower case in this
> position, which is just plain wrong. Even if it were right, it would
> be the wrong solution.
>
Don't I said that the actual limitation is that troff(1) can't convert
the document title to uppercase itself, not that it can't print it in
lowercase?
> > From about two thousand -mdoc manpages that could be found in src/
> > tree (including src/contrib/ ones), this manpage was the only one
> > with lowercased document title,
>
> After you had changed all the rest.
>
This is simply not true. Search 4.4BSD manpages, for example.
> > and this *is* a good reason to keep it in uppercase.
>
> No, it's not.
>
Yes, it is. ``VINUM'' in .Dt context is not the command name,
it's a document _TITLE_. This is also consistent with .Sh
being in uppercase.
> > The purpose of inventing the -mdoc package (ten years ago) was to
> > have a single style for all manpages, as opposed to the -man
> > package, where everyone is free to use whatever style he likes
> > (probably, you should convert to this format).
>
> > If you back this change out, please also coordinate the acceptance
> > of this with OpenBSD, NetBSD, and GNU Groff maintainer, Werner
> > Lemberg <wl@gnu.org>.
> >
> > Please also fix the rest of FreeBSD -mdoc manpages, the template
> > file in /usr/src/share/misc/mdoc.template, /usr/src/share/examples/mdoc/
> > examples, and a bunch of other places.
>
> I think this is going somewhat over the top.
>
-mdoc likes consistency, that's what it was invented for.
> > <PS>
> > The phrase "due to troff limitation" that could be found in the mdoc(7)
> > manpage on the .Dt subject means that troff(1) can't itself convert the
> > title to uppercase.
> > </PS>
>
> That is, to say the least, ambiguous.
>
The documented phrase "The document title is the subject of the man page
and must be in CAPITALS due to troff limitations." looks ambiguos?
> On Tuesday, 10 July 2001 at 3:04:09 -0700, Ruslan Ermilov wrote:
> > ru 2001/07/10 03:04:09 PDT
> >
> > Modified files:
> > bin/cp cp.1
> > (etc)
> > Log:
> > mdoc(7) police: removed HISTORY info from the .Os call.
>
> The HISTORY section is of interest; it seems that you have now decided
> to axe it in all man pages. If this is a requirement of mandoc, we
> should review whether we want to be that compliant.
>
Why don't you look at the actual changes before complaining? I didn't
remove the HISTORY section, I've fixed the .Os call so that all FreeBSD
manpages print the correct operating system information at the bottom
left (and in the nroff case, at the bottom right) corners of the manpage.
Most manpages had their .Os argument equivalent to the HISTORY section
contents, hence the commitlog.
> On Tuesday, 10 July 2001 at 11:00:19 -0700, Ruslan Ermilov wrote:
> > ru 2001/07/10 11:00:19 PDT
> >
> > Modified files:
> > lib/libcrypt crypt.3
> > share/man/man5 sysctl.conf.5
> > usr.sbin/diskpart diskpart.8
> > gnu/usr.bin/man/makewhatis makewhatis.local.8
> > lib/libc/sys setresuid.2
> > Log:
> > mdoc(7) police: removed punctuation after the last SEE ALSO xref.
>
> I find all of these changes objectionable. You shouldn't be required
> to change correct punctuation to incorrect punctuation, correct number
> to incorrect number (AUTHOR to AUTHORS), correct case to incorrect
> case, nor to remove relevant information. Please point to the
> document which mandates this, and the part of the document which makes
> this a requirement, not a recommendation. In addition, please stop
> changing these man pages until we've had a chance to discuss whether
> we really want to modify our man pages in this manner.
>
These changes were already discussed at various times in the -doc mailing
list and with people who were active on -mdoc issues. Are you subscribed?
The document in question is called mdoc(7).
Please look at the ``A MANUAL PAGE TEMPLATE'', ``Author Name'', and the
``Section Headers'' section to see why AUTHORS vs. AUTHOR, and how the
.An macro is treated differently while in the AUTHORS section.
Please take a look at the ``A MANUAL PAGE TEMPLATE'':
: .Dt DOCUMENT_TITLE [section number] [architecture/volume]
^^^^^^^^^^^^^^
[...]
: The first items in the template are the macros `.Dd', `.Os', and `.Dt';
: the document date, the operating system the man page or subject source is
: developed or modified for, and the man page title (in upper case) along
^^^^^^^^^^^^^
: with the section of the manual the page belongs in.
And then at the ``TITLE MACROS'' section, to see that DOCUMENT TITLE SHOULD
BE IN UPPER CASE.
Please see the ``Section Headers'' section, ``.Sh SEE ALSO'' part, to see
how cross references should be sorted. The last one does not mandate that
particular order, but "recommends" it, similar to how this is done by style(9),
and I don't see anything wrong if all manpages use a single style.
After all, this is the way most books have their INDEX built, i.e., sorted
alphabetically, ignoring case differences.
Cheers,
--
Ruslan Ermilov Oracle Developer/DBA,
ru@sunbay.com Sunbay Software AG,
ru@FreeBSD.org FreeBSD committer,
+380.652.512.251 Simferopol, Ukraine
http://www.FreeBSD.org The Power To Serve
http://www.oracle.com Enabling The Information Age
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010711100621.A24098>