[dpkg] 46/192: man: Document currently accepted syntax for changelogs

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch pu/reproducible_builds
in repository dpkg.

commit 2378fb62a7b0985aef451beb9ff856a4df5dd715
Author: Guillem Jover <guillem at debian.org>
Date:   Sun Apr 9 03:51:03 2017 +0200

    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.robinson at gmail.com>
---
 debian/changelog                 |  3 +++
 man/deb-changelog.man            | 10 +++++++++-
 man/dpkg-mergechangelogs.man     |  4 ++--
 scripts/Dpkg/Changelog/Debian.pm |  8 ++++----
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 3833216..2401ea8 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,9 @@ dpkg (1.19.0) UNRELEASED; urgency=medium
   * Perl modules:
     - Switch from Dpkg::Util to List::Util, now that the module in the
       new required Perl contains the needed functions.
+  * Documentation:
+    - Document currently accepted syntax for changelogs in deb-changelog(5).
+      Closes: #858579
   * Build system:
     - Require Perl 5.20.2, the version in Debian oldstable (jessie).
     - Use new gcc-7 -Wrestrict and -Wshift-negative-value warnings if
diff --git a/man/deb-changelog.man b/man/deb-changelog.man
index 2a424a4..a5dc781 100644
--- a/man/deb-changelog.man
+++ b/man/deb-changelog.man
@@ -7,7 +7,7 @@
 .\" Copyright © 2008, 2010 Russ Allbery <rra at debian.org>
 .\" Copyright © 2010 Charles Plessy <plessy at debian.org>
 .\" Copyright © 2014 Bill Allombert <ballombe at debian.org>
-.\" Copyright © 2015 Guillem Jover <guillem at debian.org>
+.\" Copyright © 2015-2017 Guillem Jover <guillem at 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 47e15d8..786dad2 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 4ed04a9..a44ac66 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 <frank at lichtenheld.de>
 # Copyright © 2009 Raphaël Hertzog <hertzog at debian.org>
-# Copyright © 2012-2015 Guillem Jover <guillem at debian.org>
+# Copyright © 2012-2017 Guillem Jover <guillem at 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) {

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/dpkg.git