At 2017-04-09T03:57:01+0200, Guillem Jover wrote: > Hi! > > On Sat, 2017-03-25 at 19:27:55 -0400, G. Branden Robinson wrote: > > On Sat, Mar 25, 2017 at 03:07:32PM +0100, Guillem Jover wrote: > > > The implementation in dpkg-dev already supports all of this > > > (see man Dpkg::Changelog::Debian), including: > > > > Section 3 manpages for Perl modules? Will wonders never cease? ;-) > > I'm not sure if the wonder is becuse there's documentation at all for > those, or because secion is 3 instead of say 3perl. In any case, this > prompted me to check and fix the latter, so I've queued a patch for > 1.19.x. :)
The former. You'll never see a C library interface manpage with
double-colons in the name, and C++ programmers never write manpages
because their programming language is completely intuitive. >cough<
> Ok, what about the attached patch, which I've queued for 1.19.x? I'm
> not documenting the ancient formats, because I feel that might induce
> people to use them, while this should be IMO pretty much just an
> implementation detail.
It looks good to me. I see no actual problems; I will make a few
observations that boil down to style, preference, and/or judgement.
1. The abbreviation "i.e." should always be followed by a comma. See,
e.g., man-pages(7).
2. I prefer to use "an" (man) macros for font changes, as they
integrate better with lexical highlighters and spell checkers, and
hide some grotty[1] syntax from those reading or writing the manpage
source. Most such people do not bother to learn what *roff syntax
really is, and I can't blame them. This does mean adding linebreaks
in the manpage sources, but filled paragraphs in *roff sources are
usually a bug, not a feature.[2] *roff is not Markdown, and
definitely not plaintext. There's only one place that you can't
escape using font escapes, and that's if you need three different
fonts in the tag of a tagged paragraph (.TP)[3].
So instead of \fB#\fP, you can have
.B #
and similarly
.B /* */
3. Vim and Emacs should be capitalized when referred to in prose as
editing systems, rather than by their command-line invocation names.
4. "CVS keywords" are more properly referred to as "RCS keywords", or
maybe even "ident(1) strings". RCS is the system that introduced
them[4]. CVS and Subversion followed the syntax. ident(1) is also
somewhat likely to be installed on the user's system, so a broader
audience will have ready access to the manpage to learn more about
what they are. See the rcs package description (last paragraph).
I know that's a lot of nitpicking. :-O
Regards,
Branden
[1] pun intended
[2] See man-pages(7), "Conventions for source file layout" and groff(7),
"Control Characters", ".".
[3] This annoys me so much that I'm trying to learn enough *roff to
write a fix or a replacement macro that people can use instead, that
we may banish the use of font escapes in manpages forever. :-|
[4] SCCS had keywords, but they were more primitive than RCS's and
infeasible to pattern-match once expanded; see <
https://docs.oracle.com/cd/E19504-01/802-5880/6i9k05dht/index.html#sccs-15316
>.
signature.asc
Description: PGP signature
