On Wed, 2017-04-12 at 11:00:20 -0400, G. Branden Robinson wrote: > At 2017-04-09T03:57:01+0200, Guillem Jover wrote: > > On Sat, 2017-03-25 at 19:27:55 -0400, G. Branden Robinson wrote: > > > 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<
Well, within the perl world, I'd go as far as considering missing documentation as malpractice. :) > > 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). Indeed, missed that one. > 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 /* */ Right, although given that the current markup is already mixed, and that I'm planning anyway to switch all man pages to use POD as source, because the unreadability of troff also affects translators, among other issues, this does not matter much, and in fact makes the conversion easier, so I've left it as is. :) <https://lists.debian.org/debian-dpkg/2016/09/msg00008.html> > 3. Vim and Emacs should be capitalized when referred to in prose as > editing systems, rather than by their command-line invocation names. Fixed, thanks. > 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). Right, I tend to use «RCS keyword», but I guess the «CVS comment» thing messed my brain too much. :) > I know that's a lot of nitpicking. :-O Nah, adequate; IMO, there's never enough nitpicking! ;) Attached a revised patch. Thanks, Guillem
From 0f5e42f465aab72dd3e4a5c3c21d732a9d0556bf Mon Sep 17 00:00:00 2001 From: Guillem Jover <[email protected]> Date: Sun, 9 Apr 2017 03:51:03 +0200 Subject: [PATCH] man: Document currently accepted syntax for changelogs The current implementation supports several comment lines, VCS and editor variable settings which get ignored. In addition, to be able to handle ancient changelog entries, the parser will detect those and ignore while preserving them for output. Closes: #858579 Reviewed-by: G. Branden Robinson <[email protected]> --- man/deb-changelog.man | 10 +++++++++- man/dpkg-mergechangelogs.man | 4 ++-- scripts/Dpkg/Changelog/Debian.pm | 8 ++++---- 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/man/deb-changelog.man b/man/deb-changelog.man index 2a424a4bb..a5dc78113 100644 --- a/man/deb-changelog.man +++ b/man/deb-changelog.man @@ -7,7 +7,7 @@ .\" Copyright © 2008, 2010 Russ Allbery <[email protected]> .\" Copyright © 2010 Charles Plessy <[email protected]> .\" Copyright © 2014 Bill Allombert <[email protected]> -.\" Copyright © 2015 Guillem Jover <[email protected]> +.\" Copyright © 2015-2017 Guillem Jover <[email protected]> .\" .\" This is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by @@ -141,6 +141,14 @@ preceded by exactly one space. The maintainer details and the date must be separated by exactly two spaces. .PP +Any line that consists entirely (i.e., no leading whitespace) of \fB#\fP +or \fB/* */\fP style comments, RCS keywords, Vim modelines or Emacs local +variables should be ignored. +.PP +Ancient changelog entries with other formats at the end of the file should +be accepted and preserved on output, but their contents might be otherwise +ignored and parsing stopped at that point. +.PP The entire changelog must be encoded in UTF-8. .SH FILES .TP diff --git a/man/dpkg-mergechangelogs.man b/man/dpkg-mergechangelogs.man index 47e15d89e..786dad281 100644 --- a/man/dpkg-mergechangelogs.man +++ b/man/dpkg-mergechangelogs.man @@ -63,8 +63,8 @@ Show the version and exit. .SH LIMITATIONS .P Anything that is not parsed by Dpkg::Changelog is lost during the merge. -This might include stuff like vim modelines, comments which were not -supposed to be there, etc. +This might include stuff like Vim modelines, Emacs variables, comments +which were not supposed to be there, etc. . .SH INTEGRATION WITH GIT .P diff --git a/scripts/Dpkg/Changelog/Debian.pm b/scripts/Dpkg/Changelog/Debian.pm index 4ed04a943..a44ac666c 100644 --- a/scripts/Dpkg/Changelog/Debian.pm +++ b/scripts/Dpkg/Changelog/Debian.pm @@ -1,7 +1,7 @@ # Copyright © 1996 Ian Jackson # Copyright © 2005 Frank Lichtenheld <[email protected]> # Copyright © 2009 Raphaël Hertzog <[email protected]> -# Copyright © 2012-2015 Guillem Jover <[email protected]> +# Copyright © 2012-2017 Guillem Jover <[email protected]> # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -28,7 +28,7 @@ Dpkg::Changelog::Debian parses Debian changelogs as described in deb-changelog(5). The parser tries to ignore most cruft like # or /* */ style comments, -CVS comments, vim variables, emacs local variables and stuff from +RCS keywords, Vim modelines, Emacs local variables and stuff from older changelogs with other formats at the end of the file. NOTE: most of these are ignored silently currently, there is no parser error issued for them. This should become configurable in the @@ -164,9 +164,9 @@ sub parse { } elsif (m/^(?:;;\s*)?Local variables:/io) { last; # skip Emacs variables at end of file } elsif (m/^vim:/io) { - last; # skip vim variables at end of file + last; # skip Vim modelines at end of file } elsif (m/^\$\w+:.*\$/o) { - next; # skip stuff that look like a CVS keyword + next; # skip stuff that look like a RCS keyword } elsif (m/^\# /o) { next; # skip comments, even that's not supported } elsif (m{^/\*.*\*/}o) { -- 2.12.2.762.g0e3151a226
