From 0f5e42f465aab72dd3e4a5c3c21d732a9d0556bf Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@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.robinson@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 <rra@debian.org>
 .\" Copyright © 2010 Charles Plessy <plessy@debian.org>
 .\" Copyright © 2014 Bill Allombert <ballombe@debian.org>
-.\" Copyright © 2015 Guillem Jover <guillem@debian.org>
+.\" Copyright © 2015-2017 Guillem Jover <guillem@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 <frank@lichtenheld.de>
 # Copyright © 2009 Raphaël Hertzog <hertzog@debian.org>
-# Copyright © 2012-2015 Guillem Jover <guillem@debian.org>
+# Copyright © 2012-2017 Guillem Jover <guillem@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

