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