Preserve the historic section anchors in older versions of the
upgrading-checklist by including all four version numbers, although
stop this practice with 4.0.0.

Fix a typo in one of the month names noticed by Guillem Jover.

* Clean up the upgrading checklist a bit:
  - Rewrite the introduction to read a bit more smoothly and mention
    that the Standards-Version value omits the minor patch number.
  - Remove the minor patch number from all the versions except for the
    anomalies that contain normative changes, and note those
    explicitly.
  - Remove some unhelpful section headings and trailing colons in very
    old upgrading checklist entries.
  - Standardize the release date format.

Also bump the package version to 4.0.0.0.

Declare a dependency on the upgrading checklist from policy.xml since
it includes it (although this doesn't seem to work in the build system
properly yet).  Suppress the table of contents in the text version as
well.  Add the upgrading-checklist conversion to the dependencies for
the stamp-build target.

Manually reformat the converted DocBook files using Emacs and a lot
of elbow grease.

This was a tool for a one-time conversion, so should no longer be
needed.

Guillem Jover authored Mar 26, 2017 and Russ Allbery committed Apr 30, 2017

This integrates the upgrading checklist properly into the policy
manual, so that there are now navigation references and it appears
in the TOC.

As a side effect we get rid of the split HTML output because it would
contain just a single index.html file anyway, but keep compatibility
files for the one-page HTML and text outputs.

Guillem Jover authored Jan 09, 2017 and Russ Allbery committed Apr 30, 2017

Switch to use xsltproc and dblatex for the converted sources. Stop
using tidy(1) because it produces bigger files, and the output
generated by xsltproc is pretty clean and compliant already. Remove
all build dependencies not used at all or not used directly by our
build system, even if they end up being pulled anyway by our direct
dependencies.

Done by running tools/sgml2docbook.

Guillem Jover authored Jan 10, 2017 and Russ Allbery committed Apr 30, 2017

This is a conversion script, that should automate the whole process
so that it can hopefully be repeated at any later point and is able
handle modifications to the documents sources.

Guillem Jover authored Mar 28, 2017 and Russ Allbery committed Apr 30, 2017

OpenJade seems to have stagnated upstream, and xsltproc is considered
one of the fastest XML processors out there, and more importantly it
is maintained, and used more widely.

Guillem Jover authored Mar 28, 2017 and Russ Allbery committed Apr 30, 2017

These are ancient dependencies that never got cleaned up.

Guillem Jover authored Jan 09, 2017 and Russ Allbery committed Apr 30, 2017

We already ship the sources in the source package, and there's nothing
requiring us to duplicate these files.

Guillem Jover authored Mar 26, 2017 and Russ Allbery committed Apr 30, 2017

The output documents do not have any encoding specified, so programs
handling them will assume ASCII, and when finding UTF-8 characters will
recode those, producing garbage on output.

* Policy: Remove integration instructions for upstart
  Wording: Ansgar Burchardt <ansgar@debian.org>
  Seconded: Michael Biebl <biebl@debian.org>
  Seconded: Andrey Rahmatullin <wrar@debian.org>
  Seconded: Simon McVittie <smcv@debian.org>
  Closes: #835490

This wasn't previously optional; rather, previously we didn't mention
it at all.  Just say that it's recommended.

Remove the requirement to call MAKEDEV and prohibit attempting to
create or remove device files if a dynamic management facility is in
place.  Packages should assume device files in /dev are dynamically
managed.  Point people towards dynamic creation of named pipes and
document that creation in postinst is not the usual approach.  Extend
that discussion to device files outside of /dev, which are required
for some chroot or file system namespace approaches.

Remove the reference to old serial devices, which are now so old that
it's highly unlikely anyone will care.

* Policy: No special dependency now required for /run
  Wording: Marc Haber <mh+debian-packages@zugschlus.de>
  Seconded: Andreas Henriksson <andreas@fatal.se>
  Seconded: Russ Allbery <rra@debian.org>
  Closes: #852314

In the init script section, avoid a comma splice by creating
separate sentences for recommended and optional arguments to
init scripts.

* Redo some of the Makefile and debian/rules dependencies to avoid
  ambiguous pattern rules and to ensure that make at the top level
  rebuilds output files if input files change.

Andreas Henriksson authored Jan 02, 2017 and Russ Allbery committed Feb 20, 2017

In LSB the status action is among the 'shall be supported' actions.
In Debian there are still many init scripts which does not support
the status action still to this day (see lintian catches for
init.d-script-does-not-implement-optional-option status).

Given we avoid creating a big number of RC bugs (under anyones
interpretation), we don't want to implement status as non-optional.
At the same time as it's not optional in LSB, we don't want to
add it to optional either.

Solve this by creating a new middle ground for 'recommended' actions
and put status there. Hopefully one day status can move up to the
rest of the 'non-optional' actions.

LSB also documents the specific return codes for the status action
which might be useful to have in policy as well, but at the same
time do we really want to duplicate all of LSB?
For now lets leave that as a potential future enhancement.
(See also discussion about this in merged/duplicate bug report.)

Fwiw, systemctl also supports status and trivial testing seems to
indicate it also uses the LSB specified return codes.

https://lintian.debian.org/tags/init.d-script-does-not-implement-optional-option.html

Andreas Henriksson authored Jan 02, 2017 and Russ Allbery committed Feb 20, 2017

Add the try-restart action similar to how LSB describes it.
Many init scripts in Debian still does not support this action
but fortunately even LSB just documents it as optional.

Fwiw, systemctl also supports try-restart action in the same fashion.

Guillem Jover authored Feb 20, 2017 and Russ Allbery committed Feb 20, 2017

This is required in DocBook, otherwise it makes XML toolchains trip over.

Guillem Jover authored Jan 15, 2017 and Russ Allbery committed Feb 20, 2017

These have not been true for a long time, just get rid of these
comments. Also making easier to conversion to DocBook.

Guillem Jover authored Jan 15, 2017 and Russ Allbery committed Feb 20, 2017

This gets rid of a comment, so we do not have to bother with restoring
it when converting to DocBook.

Guillem Jover authored Jan 15, 2017 and Russ Allbery committed Feb 20, 2017

This comment describes how the document is supposed to be maintained. So
it seems relevant in the About chapter.

This also makes it easier to convert to DocBook, as otherwise the comment
gets lost, and it cannot be mangled as it is located in a place where a
<para> is not valid.

Guillem Jover authored Jan 10, 2017 and Russ Allbery committed Feb 20, 2017

These are not valid in DocBook, and we should avoid using an ID that
will need to be changed later on, so that the ID can be preserved.

Guillem Jover authored Jan 10, 2017 and Russ Allbery committed Feb 20, 2017

<emphasis> is not allowed within <literal> in DocBook, which is what
this gets converted to. Instead use <var> which is allowed, and is also
a more correct markup anyway.

Guillem Jover authored Jan 10, 2017 and Russ Allbery committed Feb 20, 2017

This gets rid of these entities, which otherwise get lost in the DocBook
conversion, and also switches to use the more correct markup anyway.

Guillem Jover authored Jan 10, 2017 and Russ Allbery committed Feb 20, 2017

This is required in DocBook, otherwise it makes XML toolchains trip over.

* Policy: Recommend libraryname-dev or librarynameAPIVERSION-dev
  Wording: Ansgar Burchardt <ansgar@debian.org>
  Seconded: Julien Cristau <jcristau@debian.org>
  Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
  Closes: #568374