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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

G. 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      <none>
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  gnupg                    2.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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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 <[hidden email]>  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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

0001-man-Document-currently-accepted-syntax-for-changelog.patch (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

  <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

0001-man-Document-currently-accepted-syntax-for-changelog.patch (4K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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.

>   <https://lists.debian.org/debian-dpkg/2016/09/msg00008.html>

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 (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Processed: Bug#858579 in package dpkg marked as pending

Debian Bug Tracking System
In reply to this post by G. Branden Robinson
Processing control commands:

> tag 858579 pending
Bug #858579 [dpkg-dev] /usr/share/man/man5/deb-changelog.5.gz: please support a comment syntax for Debian changelog files
Added tag(s) pending.

--
858579: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=858579
Debian Bug Tracking System
Contact [hidden email] with problems

Loading...