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 <guil...@debian.org>
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 <g.branden.robin...@gmail.com>
---
 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 <r...@debian.org>
 .\" Copyright © 2010 Charles Plessy <ple...@debian.org>
 .\" Copyright © 2014 Bill Allombert <ballo...@debian.org>
-.\" Copyright © 2015 Guillem Jover <guil...@debian.org>
+.\" Copyright © 2015-2017 Guillem Jover <guil...@debian.org>
 .\"
 .\" 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 <fr...@lichtenheld.de>
 # Copyright © 2009 Raphaël Hertzog <hert...@debian.org>
-# Copyright © 2012-2015 Guillem Jover <guil...@debian.org>
+# Copyright © 2012-2017 Guillem Jover <guil...@debian.org>
 #
 # 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

Reply via email to