Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[G. Branden Robinson]

At 2017-04-20T09:39:42+0200, Guillem Jover wrote:
> On Wed, 2017-04-12 at 11:00:20 -0400, G. Branden Robinson wrote:
> > 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. :)

Yes.  Unfortunately, POD is too, at least the last time I looked at it.

> 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,

D'oh!

> 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. :)

There is a subset of troff with the an macros that should be as easy for
translators as POD is.

>   

The list of reservations you have with pod2man here seems pretty
serious.

> Nah, adequate; IMO, there's never enough nitpicking! ;)

:-D

> Attached a revised patch.

Thanks!

> +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.

I'll reiterate that that the an macro B would be better here, if I
persuade you to block out the siren song of POD. :P

One felicity that I just learned about today is that the only
actively-maintained alternative troff implementation, "Heirloom Troff",
has been extended to support a lot of groff's own extensions.  Of
particular interest:

Most groff extensions, like long names for requests, strings, and
number registers, are supported. A special groff compatibility mode
is also provided.[1]

An essential part of that long-name support is the vastly superior
syntax for character escapes, even for traditional short escape names.

So if you need "shaped" quotation marks, you can say:

 \[oq], \[cq], \[lq], \[rq]

instead of

 \(oq, \(cq, \(lq, \(rq.

This is far easier on the eye--especially so with lexical highlighting
that puts a nice bright color on closing brackets, and perhaps more
importantly, it makes the words immediately abutting these symbols
recognizable by spell checkers.  Vim's spell checker, for instance,
flags "lqprotected" in "\(lqprotected\(rq" as an unrecognized word.
(The spell checker still griefs you on the names of the escapes
themselves, of course, but there are relatively few of those that one
would want to use in a man page, and they can be disregarded, or put
onto an internal or external word list much more easily.)

What sort of help do you need to lower the *roff manpage burden enough
that you'll keep it?  I'm here for you. :)

Regards,
Branden

[1] http://heirloom.sourceforge.net/doctools.html


signature.asc
Description: PGP signature

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[Guillem Jover]

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. :)

  

> 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 
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 
---
 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 
 .\" Copyright © 2010 Charles Plessy 
 .\" Copyright © 2014 Bill Allombert 
-.\" Copyright © 2015 Guillem Jover 
+.\" Copyright © 2015-2017 Guillem Jover 
 .\"
 .\" 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

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[G. Branden Robinson]

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

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[Guillem Jover]

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. :)

> Thanks--I was utterly unaware of this.

No problem!

> > So I guess your request would be to officialize (at least the proper
> > comment markers ‘#’) as supported, in the spec. I'll probably mention
> > this on the debian-policy mailing list, but I guess I should just do
> > it (perhaps all the currently accepted syntax) because if someone wants
> > to code an alternative implementation, they will have to replicate the
> > logic, or it will be unable to parse existing changelogs.
> > 
> > Also because dpkg can always be more lax than policy, and this is the
> > case right here.
> 
> Yes, that's precisely what I'm shooting for.
> 
> I urge you to go ahead and do it; it's obviously not a breaking change.

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.

Thanks,
Guillem
From a77397811e30e74500b79ea4eee4aa8d93a6e5ac Mon Sep 17 00:00:00 2001
From: Guillem Jover 
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
---
 man/deb-changelog.man| 10 +-
 scripts/Dpkg/Changelog/Debian.pm |  4 ++--
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/man/deb-changelog.man b/man/deb-changelog.man
index 2a424a4bb..4a058b1bd 100644
--- a/man/deb-changelog.man
+++ b/man/deb-changelog.man
@@ -7,7 +7,7 @@
 .\" Copyright © 2008, 2010 Russ Allbery 
 .\" Copyright © 2010 Charles Plessy 
 .\" Copyright © 2014 Bill Allombert 
-.\" Copyright © 2015 Guillem Jover 
+.\" Copyright © 2015-2017 Guillem Jover 
 .\"
 .\" 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, CVS keywords, vim variables 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/scripts/Dpkg/Changelog/Debian.pm b/scripts/Dpkg/Changelog/Debian.pm
index 4ed04a943..a63e6eb19 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 
 # Copyright © 2009 Raphaël Hertzog 
-# Copyright © 2012-2015 Guillem Jover 
+# Copyright © 2012-2017 Guillem Jover 
 #
 # 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
+CVS keywords, vim variables, 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
-- 
2.12.2.715.g7642488e1d

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[G. Branden Robinson]

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?  ;-)

Thanks--I was utterly unaware of this.

> So I guess your request would be to officialize (at least the proper
> comment markers ‘#’) as supported, in the spec. I'll probably mention
> this on the debian-policy mailing list, but I guess I should just do
> it (perhaps all the currently accepted syntax) because if someone wants
> to code an alternative implementation, they will have to replicate the
> logic, or it will be unable to parse existing changelogs.
> 
> Also because dpkg can always be more lax than policy, and this is the
> case right here.

Yes, that's precisely what I'm shooting for.

I urge you to go ahead and do it; it's obviously not a breaking change.

My longer-term objective here is to write (or persuade someone to write)
a Vim syntax highlighter for Debian copyright files, and for that it
would be helpful to have an implementation-independent spec for the file
format.  I was looking to the existing highlighting for deb-control and
deb-changelog files, when I noticed that Vim was highlighting my
existing comment line in xtrs's debian/changelog with ugly white-on-red.

It'll be easier to get that fixed if I can point to it being part of the
sepc, though in the meantime I'm happy to appeal to your authority.  ;-)

-- 
Regards,
Branden

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[Guillem Jover]

Hi!

On Thu, 2017-03-23 at 20:30:54 -0400, Branden Robinson wrote:
> Package: dpkg-dev
> Version: 1.18.23
> Severity: wishlist
> File: /usr/share/man/man5/deb-changelog.5.gz

> I believe that, as a general rule, all human-readable, human-editable,
> machine-parseable file formats should support a comment syntax.
> 
> Debian changelogs meet these criteria.  My use case is simply this, at
> the end of the file:
> 
> # vim:set ai et sw=2 ts=2 tw=78:
> 
> Fans of other editors can do similarly (and probably already do, outside
> the spec just like me).

The implementation in dpkg-dev already supports all of this
(see man Dpkg::Changelog::Debian), including:

,--- debian/changelog ---
# whatever
source (1.0) release; urgency=normal

# stuff
  * Entry.
# comment

 -- Name   Sat, 25 Mar 2017 15:01:01 +0100

vim:set ai et sw=2 ts=2 tw=78:

Anything after the vim modeline will be ignored.
`---

So I guess your request would be to officialize (at least the proper
comment markers ‘#’) as supported, in the spec. I'll probably mention
this on the debian-policy mailing list, but I guess I should just do
it (perhaps all the currently accepted syntax) because if someone wants
to code an alternative implementation, they will have to replicate the
logic, or it will be unable to parse existing changelogs.

Also because dpkg can always be more lax than policy, and this is the
case right here.

Thanks,
Guillem

Bug#858579: /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files

[Branden Robinson]

Package: dpkg-dev
Version: 1.18.23
Severity: wishlist
File: /usr/share/man/man5/deb-changelog.5.gz

I believe that, as a general rule, all human-readable, human-editable,
machine-parseable file formats should support a comment syntax.

Debian changelogs meet these criteria.  My use case is simply this, at
the end of the file:

# vim:set ai et sw=2 ts=2 tw=78:

Fans of other editors can do similarly (and probably already do, outside
the spec just like me).

-- System Information:
Debian Release: 9.0
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 4.9.0-2-amd64 (SMP w/4 CPU cores)
Locale: LANG=C, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages dpkg-dev depends on:
ii  binutils  2.27.90.20170124-2
ii  bzip2 1.0.6-8.1
ii  libdpkg-perl  1.18.23
ii  make  4.1-9.1
ii  patch 2.7.5-1+b2
pn  perl:any  
ii  tar   1.29b-1.1
ii  xz-utils  5.2.2-1.2+b1

Versions of packages dpkg-dev recommends:
ii  build-essential  12.3
ii  fakeroot 1.21-3.1
ii  gcc [c-compiler] 4:6.3.0-1
ii  gcc-6 [c-compiler]   6.3.0-6
ii  gnupg2.1.18-6
ii  gpgv 2.1.18-6
ii  libalgorithm-merge-perl  0.08-3

Versions of packages dpkg-dev suggests:
ii  debian-keyring  2017.01.20

-- no debconf information