Debian Bug report logs - #175064
Debian policy documents should use DocBook XML in UTF-8

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Colin Walters <walters@debian.org>

To: submit@bugs.debian.org

Subject: Debian policy documents should be UTF-8 encoded

Date: 02 Jan 2003 12:19:39 -0500

Package: debian-policy

On Thu, 2003-01-02 at 11:48, Clint Adams wrote:
> > This proposal is a fairly important yet easy to take first step along
> > the way of transitioning all of Debian to UTF-8.
> > 
> > Attached is a patch against the latest version of policy.
> 
> Seconded.  The policy documents should probably be converted to UTF-8
> too.

I agree.  I can't actually figure out how they got to be ISO-8859-1
encoded as they are now; whatever, I do, I just seem to get ASCII; i.e.
(C) instead of the © character.  I'll file this as a separate bug,
though.

Message #10 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@gkvk.hr>

To: Colin Walters <walters@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Thu, 2 Jan 2003 19:24:48 +0100

On Thu, Jan 02, 2003 at 12:19:39PM -0500, Colin Walters wrote:
> Package: debian-policy
> 
> On Thu, 2003-01-02 at 11:48, Clint Adams wrote:
> > > This proposal is a fairly important yet easy to take first step along
> > > the way of transitioning all of Debian to UTF-8.
> > > 
> > > Attached is a patch against the latest version of policy.
> > 
> > Seconded.  The policy documents should probably be converted to UTF-8
> > too.
> 
> I agree.  I can't actually figure out how they got to be ISO-8859-1
> encoded as they are now; whatever, I do, I just seem to get ASCII; i.e.
> (C) instead of the ?? character.  I'll file this as a separate bug,
> though.

Umm, maybe because we use ©?

[joy@pork:~/cvs/policy]% recode latin1..utf8 policy.sgml
[joy@pork:~/cvs/policy]% cvs diff policy.sgml
[joy@pork:~/cvs/policy]%

Where is the bug, again?

-- 
     2. That which causes joy or happiness.

Message #15 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Colin Walters <walters@debian.org>

To: 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: 02 Jan 2003 14:01:03 -0500

On Thu, 2003-01-02 at 13:24, Josip Rodin wrote:

> Umm, maybe because we use ©?

Right, but the output documents seem to be ISO-8859-1 encoded.  For
example:

walters@space-ghost> zcat /usr/share/doc/debian-policy/policy.txt.gz | iconv --from-code=UTF-8 --to-code=UTF-8 1>/dev/null
iconv: illegal input sequence at position 689
walters@space-ghost> 

Message #20 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@gkvk.hr>

To: Colin Walters <walters@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Thu, 2 Jan 2003 22:28:31 +0100

On Thu, Jan 02, 2003 at 02:01:03PM -0500, Colin Walters wrote:
> > Umm, maybe because we use ©?
> 
> Right, but the output documents seem to be ISO-8859-1 encoded.  For
> example:
> 
> walters@space-ghost> zcat /usr/share/doc/debian-policy/policy.txt.gz | iconv --from-code=UTF-8 --to-code=UTF-8 1>/dev/null
> iconv: illegal input sequence at position 689
> walters@space-ghost> 

I'm not seeing that with the copy of policy.txt.gz which I generated myself.
Looks like debiandoc2text on Manoj's system used a different, Latin1 locale
and replaced Š for © on my Latin2 system it did no such (foolish) thing.
For the record, Š is a large latin letter S with a hacek/caron. :)

We should probably restrict the build process with LANG=C or something like
that.

-- 
     2. That which causes joy or happiness.

Message #25 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Colin Walters <walters@debian.org>

To: 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: 02 Jan 2003 17:20:26 -0500

On Thu, 2003-01-02 at 16:28, Josip Rodin wrote:

> I'm not seeing that with the copy of policy.txt.gz which I generated myself.
> Looks like debiandoc2text on Manoj's system used a different, Latin1 locale
> and replaced Š for © on my Latin2 system it did no such (foolish) thing.
> For the record, Š is a large latin letter S with a hacek/caron. :)
> 
> We should probably restrict the build process with LANG=C or something like
> that.

Right.  I think it should be sufficient to just add LANG=C before the
debiandoc2X invocations.

Message #30 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Colin Walters <walters@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Tue, 7 Jan 2003 10:49:03 -0800

Hi,

<disclaimer>I prefer to migrate to UTF-8.</disclaimer> 

But simply changing source file to UTF-8 has some issues which you may
want to consider in advance. (debian-policy being English only manual,
risks are small.)

I think it may be best if this encoding changes are done at the same
time when this documentation is moved to docbook-xml format.  A
functional conversion script already exists.  See below for the detail.

On Thu, Jan 02, 2003 at 05:20:26PM -0500, Colin Walters wrote:
> On Thu, 2003-01-02 at 16:28, Josip Rodin wrote:
> 
> > I'm not seeing that with the copy of policy.txt.gz which I generated myself.
> > Looks like debiandoc2text on Manoj's system used a different, Latin1 locale
> > and replaced ?? for &copy; on my Latin2 system it did no such (foolish) thing.
> > For the record, ?? is a large latin letter S with a hacek/caron. :)
> > 
> > We should probably restrict the build process with LANG=C or something like
> > that.
> 
> Right.  I think it should be sufficient to just add LANG=C before the
> debiandoc2X invocations.

Debiandoc2X basically assumes legacy codings in the source file as it
designed now.  Just add LANG=C before the debiandoc2X invocations does
not do much since it is required to be LANG=C and the script sets locale
by command line option with "-l" and invoke back-end processing commands
with that local as I understand.  (I may be wrong here.)

As I understand, you can use UTF-8 source file for creating plain text
and html files in UTF-8 (I guess html generation needs slightly modified
to indicate generated codes are UTF-8 in its header).  But It will break
PS and PDF generation pretty badly.  (I have been there with my Italian
translator committing UTF-8 file to the document I manage.)

I think Ardo used Latin-1 as code system for back-end at this moment.
Changing this will break many documentation building processes.

In debian-doc project, we have created debiandoc-sgml to docbook-xml
converter.  It is now very usable shape.  If someone makes nice build
script and environment for docbook-xml and spend sometime to hand tune
converted files (including converting it to UTF-8), it should be
smoother transition.  After all SGML used to use legacy encoding system
as the default for the source files while XML's default source encoding
is UTF-8.

URL for conversion script (by Phillipe):
 http://cvs.debian.org/ddp/utils/debiandoc-to-docbook/?cvsroot=debian-doc

Just my thoughts.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
        Osamu Aoki <osamu@debian.org>   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  "Our Priorities are Our Users and Free Software" --- Social Contract

Message #35 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Colin Walters <walters@debian.org>

To: Osamu Aoki <osamu@debian.org>

Cc: 175064@bugs.debian.org

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: 07 Jan 2003 14:44:28 -0500

On Tue, 2003-01-07 at 13:49, Osamu Aoki wrote:

> I think it may be best if this encoding changes are done at the same
> time when this documentation is moved to docbook-xml format.

That's perfectly fine by me.

Message #40 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@gkvk.hr>

To: Osamu Aoki <osamu@debian.org>, 175064@bugs.debian.org

Cc: Colin Walters <walters@debian.org>

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Tue, 7 Jan 2003 23:42:30 +0100

On Tue, Jan 07, 2003 at 10:49:03AM -0800, Osamu Aoki wrote:
> I think it may be best if this encoding changes are done at the same
> time when this documentation is moved to docbook-xml format.

I'm entirely not convinced that we should go beyond ASCII because a program
can't be taught to convert © into (C). It's just that, nothing else.

-- 
     2. That which causes joy or happiness.

Message #45 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Josip Rodin <joy@gkvk.hr>

Cc: 175064@bugs.debian.org, Colin Walters <walters@debian.org>

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Tue, 7 Jan 2003 15:38:43 -0800

On Tue, Jan 07, 2003 at 11:42:30PM +0100, Josip Rodin wrote:
> On Tue, Jan 07, 2003 at 10:49:03AM -0800, Osamu Aoki wrote:
> > I think it may be best if this encoding changes are done at the same
> > time when this documentation is moved to docbook-xml format.
> 
> I'm entirely not convinced that we should go beyond ASCII because a program
> can't be taught to convert © into (C). It's just that, nothing else.

I think we may be discussing slightly different things.  I do not
understand what you ment by the above message.  They are taught to do
so, I think.

Current debiasndoc-sgml creates copyright section starting with

  HTML:       Latain-1 code for ©  (1 character)
  PDF:        Latain-1 code for ©  (1 character)
  Plain text: ASCII 3 characters (C)

That was today's build of my documment results.  The source are like:

  <copyrightsummary>
  Copyright &copy; 2001&ndash;2002 by Osamu Aoki &lt;&osamu;&gt;.
  </copyrightsummary>

The plain text does not go beyond ASCII.  Neither UTF-8 nor ISO-8859-1.

Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
        Osamu Aoki <osamu@debian.org>   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  "Our Priorities are Our Users and Free Software" --- Social Contract

Message #50 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@gkvk.hr>

To: Osamu Aoki <osamu@debian.org>

Cc: 175064@bugs.debian.org, Colin Walters <walters@debian.org>

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Wed, 8 Jan 2003 00:55:01 +0100

On Tue, Jan 07, 2003 at 03:38:43PM -0800, Osamu Aoki wrote:
> > > I think it may be best if this encoding changes are done at the same
> > > time when this documentation is moved to docbook-xml format.
> > 
> > I'm entirely not convinced that we should go beyond ASCII because a program
> > can't be taught to convert © into (C). It's just that, nothing else.
> 
> I think we may be discussing slightly different things.  I do not
> understand what you ment by the above message.  They are taught to do
> so, I think.
> 
> Current debiasndoc-sgml creates copyright section starting with
> 
>   HTML:       Latain-1 code for ©  (1 character)
>   PDF:        Latain-1 code for ©  (1 character)
>   Plain text: ASCII 3 characters (C)
> 
> That was today's build of my documment results.  The source are like:
> 
>   <copyrightsummary>
>   Copyright &copy; 2001&ndash;2002 by Osamu Aoki &lt;&osamu;&gt;.
>   </copyrightsummary>
> 
> The plain text does not go beyond ASCII.  Neither UTF-8 nor ISO-8859-1.

% zgrep Š /usr/share/doc/debian-policy/policy.txt.gz
     Copyright Š 1996,1997,1998 Ian Jackson and Christian Schwarz.

How do you explain that? Honest question :)

-- 
     2. That which causes joy or happiness.

Message #55 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Josip Rodin <joy@gkvk.hr>

Cc: 175064@bugs.debian.org, Colin Walters <walters@debian.org>

Subject: Re: Bug#175064: Debian policy documents should be UTF-8 encoded

Date: Tue, 7 Jan 2003 16:35:25 -0800

On Wed, Jan 08, 2003 at 12:55:01AM +0100, Josip Rodin wrote:
> > The plain text does not go beyond ASCII.  Neither UTF-8 nor ISO-8859-1.
> 
> % zgrep ?? /usr/share/doc/debian-policy/policy.txt.gz
>      Copyright ?? 1996,1997,1998 Ian Jackson and Christian Schwarz.
> 
> How do you explain that? Honest question :)

Honestly, I can not explain.  I see © in the source and single
character copyright mark in installed text too.  Maintainer may have had
different conversion catalog or Ardo changed conversion table since then.

I had testing environment and I just upgrading to unstable for
debiandoc-sgml.  Still I get (C) even for policy source.  (Well, current
policy was FTBFS in my system when I did a very quick check to rebuild.)

I have not checked with chroot condition for woody or potato.  But this
situation seems really build environment issue.

(ISO-8859-1 is my mailer)     txt.gz
debian-policy_3.1.1.1.deb     (C)
debian-policy_3.5.6.1_all.deb  ©
debian-policy_3.5.8.0_all.deb  ©    15 Nov 2002

Osamu

-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
        Osamu Aoki <osamu@debian.org>   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  "Our Priorities are Our Users and Free Software" --- Social Contract

Message #62 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: 175064@bugs.debian.org, 175064-submitter@bugs.debian.org

Cc: control@bugs.debian.org

Subject: UTF-8 and DocBook XML transtion status

Date: Sat, 8 Jan 2011 12:30:56 +0900

retitle 175064 Debian policy documents should use DocBook XML in UTF-8
thanks

Even with the current SGML source, UTF-8 transition is possible.  But we
are in deep freeze and I am reluctant to push even a simple makefile
change and iconv conversion.  The recent debiandoc-sgml package support
UTF-8 even under lenny.

If you are uploading new version for squeeze and would like to know the
diff, I may be able to make it.

But .... why just UTF-8.  XML is the way :-)

I totally forgot about this bug and I was surprised to see this is still
using SGML.

I have tested with maint-guide that debiandoc2xml can be used to convert
SGML to XML with minimal manual intervention if I use the bug fix
version in git repo. (#430575: http://bugs.debian.org/430575 needs to be
fixed.)

I will be testing conversion on local branch ....  just FYI.

Osamu

Message #72 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: 175064@bugs.debian.org

Subject: Patch for UTF-8 build

Date: Sat, 8 Jan 2011 18:42:43 +0900

[Message part 1 (text/plain, inline)]

tags 175064 patch
thanks

Hi,

Current build use LANG=C which should work since LaTeX is forced to use
C locale.

I think older debiandoc2* used to use character conversion to high
bit latin-1 character for © using latin-1 if locale is not
specified as -l option.  

Under non latin-1, it shows up in
funny character.  HEX 1A or Decimal 169 is  
 © = (C) under latin-1,7,8,9,13,14,15 and 
 Š = S with v on top under latin-2,4 .
So Josip's reply makes sense.

Also (C) encoded values are
 UTF-8: 0xC2 0xA9
So it can A9 only does not work under UTF-8

So attached patch should work to build proper UTF-8 (Instead of ASCII
only) pages.

I am not pushing this hard for squeeze since we are deep freeze but if
someone wants it, please test it and use it.

Osamu

[utf-8.diff (text/x-diff, attachment)]

Message #81 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: 175064@bugs.debian.org

Subject: DocBook XML conversion is read with this script

Date: Sun, 17 Apr 2011 11:38:10 +0900

[Message part 1 (text/plain, inline)]

Hi,

By extracting attached file into source and running "make", it will do
the magic of converting to DocBok XML and then to PDF etc.
(Need the sid version of the latest debiandoc-sgml)

Technically, conversion is ready whenever you want to do so.

Osamu

[docbook-conversion.tar.gz (application/octet-stream, attachment)]

Message #86 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Jonathan Nieder <jrnieder@gmail.com>

To: Osamu Aoki <osamu@debian.org>

Cc: 175064@bugs.debian.org

Subject: Re: DocBook XML conversion is read with this script

Date: Mon, 25 Apr 2011 05:25:31 -0500

Hi Osamu,

Osamu Aoki wrote:

> By extracting attached file into source and running "make", it will do
> the magic of converting to DocBok XML and then to PDF etc.
> (Need the sid version of the latest debiandoc-sgml)

Very neat.  I also had to install dblatex.  I like the separation
between automated conversion and patches to fix it up.  Some quick
reactions:

. The generated HTML refers to some missing files like
  "images/prev.gif".  I assume "make publish" would have taken care of
  that; maybe it would be possible for a similar target to take care
  of putting a symlink or copy of the images/ dir in the source tree
  for easy previewing.

. The lack of indentation in the source is nice.  Less fussy.

. That said, if there were a way to preserve the whitespace of the
  original and just substitute tags (so diff-ing between the before
  and after would be possible), that would be even better.  I
  understand that's probably impossible.  I fell back to using "git
  diff --no-index --word-diff=color" to find meaningful differences.

. Sometimes the spacing around closing tags looks unidiomatic, as in

	... The detailed
	procedure for gracefully orphaning a package can be found in the Debian
	Developer's Reference (see <xref linkend="related"/> ).  </para> </footnote>

  The extra space carries over to the rendered HTML, too.  Is that
  intentional?

. Quotation marks were lost, for example in “Originally called "Debian
  GNU/Linux Policy Manual", ...” at the start of the policy manual.

. Aside from the quotation marks and spaces, I couldn't find any
  artifacts.  Seems like a good conversion.

Thanks much; nicely done.
Jonathan

Message #91 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Jonathan Nieder <jrnieder@gmail.com>

Cc: 175064@bugs.debian.org

Subject: Re: DocBook XML conversion is read with this script

Date: Mon, 25 Apr 2011 23:14:47 +0900

Hi,

On Mon, Apr 25, 2011 at 05:25:31AM -0500, Jonathan Nieder wrote:
> Hi Osamu,
> 
> Osamu Aoki wrote:
> 
> > By extracting attached file into source and running "make", it will do
> > the magic of converting to DocBok XML and then to PDF etc.
> > (Need the sid version of the latest debiandoc-sgml)
> 
> Very neat.  I also had to install dblatex.  I like the separation
> between automated conversion and patches to fix it up.  Some quick
> reactions:
> 
> . The generated HTML refers to some missing files like
>   "images/prev.gif".  I assume "make publish" would have taken care of
>   that; maybe it would be possible for a similar target to take care
>   of putting a symlink or copy of the images/ dir in the source tree
>   for easy previewing.

I was lazy to copy that kind of script to the makefile.  You can find it
in maint-guide subversion.  This bug report was a reminder and promting
for me to cordinate this conversion with people in charge of publishing
policy.  This is to show this conversion is possible with minimal
transtion work.
 
> . The lack of indentation in the source is nice.  Less fussy.

That is not my intention.  XML makes no distinction.  I think it may be
good idea to run some kind of lint program on XML source.

> . That said, if there were a way to preserve the whitespace of the
>   original and just substitute tags (so diff-ing between the before
>   and after would be possible), that would be even better.  I
>   understand that's probably impossible.  I fell back to using "git
>   diff --no-index --word-diff=color" to find meaningful differences.

If you want to do this, conversion needs to be done differently with
much more manual works.

> . Sometimes the spacing around closing tags looks unidiomatic, as in
> 
> 	... The detailed
> 	procedure for gracefully orphaning a package can be found in the Debian
> 	Developer's Reference (see <xref linkend="related"/> ).  </para> </footnote>

I noticed this while working on maint-guide conversion.  Bug filed.

>   The extra space carries over to the rendered HTML, too.  Is that
>   intentional?

No.

> . Quotation marks were lost, for example in “Originally called "Debian
>   GNU/Linux Policy Manual", ...” at the start of the policy manual.

I was wondering on the same problem on maint-guide conversion.  Bug
filed.

> . Aside from the quotation marks and spaces, I couldn't find any
>   artifacts.  Seems like a good conversion.

I am busy fixing maint-guide now.   Please let me know how I get changes
commited.  Access to git branch will be nice.

Osamu
 
> Thanks much; nicely done.
> Jonathan

Message #96 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Jonathan Nieder <jrnieder@gmail.com>

To: Osamu Aoki <osamu@debian.org>

Cc: 175064@bugs.debian.org

Subject: Re: DocBook XML conversion is read with this script

Date: Mon, 25 Apr 2011 12:26:52 -0500

Hi again,

Osamu Aoki wrote:

> I was lazy to copy that kind of script to the makefile.  You can find it
> in maint-guide subversion.

Okay, will take a look.

> On Mon, Apr 25, 2011 at 05:25:31AM -0500, Jonathan Nieder wrote:

>> . The lack of indentation in the source is nice.  Less fussy.
>
> That is not my intention.  XML makes no distinction.  I think it may be
> good idea to run some kind of lint program on XML source.
>
>> . That said, if there were a way to preserve the whitespace of the
>>   original and just substitute tags
[...]
> If you want to do this, conversion needs to be done differently with
> much more manual works.

Yes, I understand.  What I meant was, given that the whitespace is not
preserved, a non-fussy automatic set of whitespace seems like a nice
default to me.

Alternatives would be to teach debiandoc2dbk some heuristics to save
whitespace in the DOM or to teach it a set of rules that happens to
give the same whitespace as the original.  I am not convinced either
would work well.

>> . Sometimes the spacing around closing tags looks unidiomatic, as in
>> 
>> 	... The detailed
>> 	procedure for gracefully orphaning a package can be found in the Debian
>> 	Developer's Reference (see <xref linkend="related"/> ).  </para> </footnote>
>
> I noticed this while working on maint-guide conversion.  Bug filed.

Thanks (and likewise for the quotation-mark bug).

> I am busy fixing maint-guide now.   Please let me know how I get changes
> commited.  Access to git branch will be nice.

I think the usual way is for a policy delegate to commit patches or
pull from your repository.  I'd encourage doing the following on
alioth to set up a new repository:

	mkdir -p ~/public_git
	chmod a+xr ~/public_git
	git init --bare ~/public_git/policy.git
	: >~/public_git/policy.git/git-daemon-export-ok
	mv ~/public_git/policy.git/hooks/post-update{.sample,}

and then on your local machine, pushing to it:

	echo '[url "osamu@alioth.debian.org:/git"]
		pushinsteadof = git://git.debian.org' >>~/.gitconfig
	echo '[url "osamu@alioth.debian.org/public_git"]
		pushinsteadof = git://git.debian.org/~osamu' >>~/.gitconfig

	git clone git://git.debian.org/dbnpolicy/policy.git
	git remote add alioth git://git.debian.org/~osamu/policy.git
	... hack hack hack ...
	gitk;	# everything looks good?
	git push alioth master;	# yes; publish it.

	... hack hack hack ...
	gitk --branches;	# everything looks good?
	# yes; update all branches that already exist remotely.
	git push alioth;

Others can browse your history at
http://git.debian.org/?p=users/osamu/policy.git
See http://wiki.debian.org/Alioth/Git#Personal_Git_repository_-_the_morph_way
for details.

To get your work incorporated into the dbnpolicy repository, if it is a
complicated branch you might send an email like

	Hi,

	Please pull

	  git://git.debian.org/~osamu master

	to get the following changes:

	[nice summary comes here]

and the receiving person might run

	git pull git://git.debian.org/~osamu master

copying and pasting the URL and branch you specified on the command line.
If it is a simple branch sometimes people instead opt to do

	git format-patch origin/master..HEAD

so the patches can be reviewed within an email client and applied with
"git am".

Probably some of the above is already familiar, but I am spelling it
out for reference.

Thanks and hope that helps,
Jonathan

Message #101 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Jonathan Nieder <jrnieder@gmail.com>

Cc: 175064@bugs.debian.org

Subject: Re: DocBook XML conversion is read with this script

Date: Mon, 2 May 2011 22:19:18 +0900

Hi,

Thanks for your help.

On Mon, Apr 25, 2011 at 05:25:31AM -0500, Jonathan Nieder wrote:
... 
> . Sometimes the spacing around closing tags looks unidiomatic, as in
> 
> 	... The detailed
> 	procedure for gracefully orphaning a package can be found in the Debian
> 	Developer's Reference (see <xref linkend="related"/> ).  </para> </footnote>
> 
>   The extra space carries over to the rendered HTML, too.  Is that
>   intentional?
> 
> . Quotation marks were lost, for example in “Originally called "Debian
>   GNU/Linux Policy Manual", ...” at the start of the policy manual.
> 
> . Aside from the quotation marks and spaces, I couldn't find any
>   artifacts.  Seems like a good conversion.

I found the root causes of these and fixed them and uploaded debiandoc-sgml
1.2.24 .

I am busy with maint-guide at this moment but wil consider making
conversion available later.

Osamu

Message #108 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Osamu Aoki <osamu@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Wed, 11 Jan 2017 02:56:36 +0100

Hi!

On Sun, 2011-04-17 at 11:38:10 +0900, Osamu Aoki wrote:
> By extracting attached file into source and running "make", it will do
> the magic of converting to DocBok XML and then to PDF etc.
> (Need the sid version of the latest debiandoc-sgml)
> 
> Technically, conversion is ready whenever you want to do so.

I've prepared a renewal of the conversion. And scripted it so that
it can be performed at any point in time regardless of most changes
in the sources.

This also includes several fixes to the current SGML source to ease
the future conversion, I think these are fine to merge now already.

There are still some things to polish and review I'm afraid. I think
there is a problem with spacing which get mangled on conversion, but
I'd need to recheck. The comments are currently lost. The PS and PDF
generation might also need some work. I think all IDs are preserved,
but this also needs checking.

The current state can be tracked in the pu/markup-singularity branch
at <https://git.hadrons.org/cgit/debian/policy.git/>, which I might
rebase at any point in time.

Thanks,
Guillem

Message #113 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: Osamu Aoki <osamu@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sat, 14 Jan 2017 10:59:45 -0800

Guillem Jover <guillem@debian.org> writes:

> I've prepared a renewal of the conversion. And scripted it so that it
> can be performed at any point in time regardless of most changes in the
> sources.

> This also includes several fixes to the current SGML source to ease the
> future conversion, I think these are fine to merge now already.

> There are still some things to polish and review I'm afraid. I think
> there is a problem with spacing which get mangled on conversion, but I'd
> need to recheck. The comments are currently lost. The PS and PDF
> generation might also need some work. I think all IDs are preserved, but
> this also needs checking.

> The current state can be tracked in the pu/markup-singularity branch at
> <https://git.hadrons.org/cgit/debian/policy.git/>, which I might rebase
> at any point in time.

Awesome, thank you so much!

Are any of the sub-policies ready to convert to DocBook right now?  We
could convert them for the next release and worry about the main Policy
document, which presumably would be harder, in a later release.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #118 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Bill Allombert <ballombe@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Guillem Jover <guillem@debian.org>, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sat, 14 Jan 2017 20:13:45 +0100

On Sat, Jan 14, 2017 at 10:59:45AM -0800, Russ Allbery wrote:
> Guillem Jover <guillem@debian.org> writes:
> 
> > I've prepared a renewal of the conversion. And scripted it so that it
> > can be performed at any point in time regardless of most changes in the
> > sources.
> 
> > This also includes several fixes to the current SGML source to ease the
> > future conversion, I think these are fine to merge now already.
> 
> > There are still some things to polish and review I'm afraid. I think
> > there is a problem with spacing which get mangled on conversion, but I'd
> > need to recheck. The comments are currently lost. The PS and PDF
> > generation might also need some work. I think all IDs are preserved, but
> > this also needs checking.
> 
> > The current state can be tracked in the pu/markup-singularity branch at
> > <https://git.hadrons.org/cgit/debian/policy.git/>, which I might rebase
> > at any point in time.
> 
> Awesome, thank you so much!
> 
> Are any of the sub-policies ready to convert to DocBook right now?  We
> could convert them for the next release and worry about the main Policy
> document, which presumably would be harder, in a later release.

I am concerned that DocBook is much too complex to be used for Debian policy.
We need to people to write patches without trouble and we do not have
many editors available for fixing the XML. Debiandoc-SGML virtue is that
it is simple.

Cheers,
-- 
Bill. <ballombe@debian.org>

Imagine a large red swirl here. 

Message #123 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Bill Allombert <ballombe@debian.org>

Cc: 175064@bugs.debian.org, Guillem Jover <guillem@debian.org>, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sat, 14 Jan 2017 11:32:09 -0800

Bill Allombert <ballombe@debian.org> writes:

> I am concerned that DocBook is much too complex to be used for Debian
> policy.  We need to people to write patches without trouble and we do
> not have many editors available for fixing the XML. Debiandoc-SGML
> virtue is that it is simple.

They seem essentially identical to me?  We've had copyright-format in the
Policy distribution for a while, and it's never seemed any different to me
(as someone not horribly familiar with XML markup) from editing Policy.

The alternative, I guess, would be to use Markdown for the whole thing,
but I think it's worthwhile to have sections and internal links and a bit
more formatting than Markdown gives us.

Anyway, my understanding (see earlier messages in this bug) is that the
maintainer of DebianDoc-SGML is actively trying to transition people away
from it, so I think it's not viable to stay on it even if it's better
along some axes.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #128 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Simon McVittie <smcv@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Bill Allombert <ballombe@debian.org>, Guillem Jover <guillem@debian.org>, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sat, 14 Jan 2017 21:30:14 +0000

On Sat, 14 Jan 2017 at 11:32:09 -0800, Russ Allbery wrote:
> Bill Allombert <ballombe@debian.org> writes:
> 
> > I am concerned that DocBook is much too complex to be used for Debian
> > policy.  We need to people to write patches without trouble and we do
> > not have many editors available for fixing the XML. Debiandoc-SGML
> > virtue is that it is simple.
[...]
> The alternative, I guess, would be to use Markdown for the whole thing,
> but I think it's worthwhile to have sections and internal links and a bit
> more formatting than Markdown gives us.

asciidoc, then? Or Markdown with pandoc extensions?

asciidoc is another wiki-like language, but has semantics defined in
terms of Docbook rather than HTML.

Pandoc's Markdown dialect includes footnotes and explicit or implicit
anchors in headings.

    S

Message #133 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org, Simon McVittie <smcv@debian.org>

Cc: Bill Allombert <ballombe@debian.org>, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sun, 15 Jan 2017 16:54:32 +0100

Hi!

On Sat, 2017-01-14 at 21:30:14 +0000, Simon McVittie wrote:
> On Sat, 14 Jan 2017 at 11:32:09 -0800, Russ Allbery wrote:
> > Bill Allombert <ballombe@debian.org> writes:
> > > I am concerned that DocBook is much too complex to be used for Debian
> > > policy.  We need to people to write patches without trouble and we do
> > > not have many editors available for fixing the XML. Debiandoc-SGML
> > > virtue is that it is simple.

> > They seem essentially identical to me?  We've had copyright-format in the
> > Policy distribution for a while, and it's never seemed any different to me
> > (as someone not horribly familiar with XML markup) from editing Policy.

Yeah, pretty much. And there are way more tools to handle DocBook than
DebianDoc-SGML; linters, editors, converters, etc. more documentation
and people that will know DocBook too.

> > The alternative, I guess, would be to use Markdown for the whole thing,
> > but I think it's worthwhile to have sections and internal links and a bit
> > more formatting than Markdown gives us.

While I like Markdown very much, I've found in many situations that it
is very limiting when you want to start doing more interesting markup
and formatting. :(

> asciidoc, then? Or Markdown with pandoc extensions?
> 
> asciidoc is another wiki-like language, but has semantics defined in
> terms of Docbook rather than HTML.
> 
> Pandoc's Markdown dialect includes footnotes and explicit or implicit
> anchors in headings.

I'd also like to detangle this potential reformatting from this
initial conversion, because once it's in DocBook we can use other
tools (such as pandoc) to convert to other formats, but not from
DebianDoc-SGML.

I think both options, asciidoc or some kind of extended Markdown might
be suitable for policy, but that would also need someone to go over
the current markup and see if it would be enough. Or try a conversion
and see what gets lost.

> > Anyway, my understanding (see earlier messages in this bug) is that the
> > maintainer of DebianDoc-SGML is actively trying to transition people away
> > from it, so I think it's not viable to stay on it even if it's better
> > along some axes.

I don't think it's better TBH, it's Debian-centric, and it also has
beenknown at least for its encoding issues. The reason I restarted this
conversion was precisely due to one of those bugs, for which I didn't
feel like trying to track down the problem in this specific toolchain
that is already considered deprecated and being phased out.

I know that Osamu has been slowly switching other projects to DocBook,
and I've also converted the APT docs, and might do the same for other
projects I've to interact with, because this bothers me a bit, which
means less and less projects will be using this format and toolchain.

Thanks,
Guillem

Message #138 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: 175064@bugs.debian.org, Simon McVittie <smcv@debian.org>, Bill Allombert <ballombe@debian.org>, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sun, 15 Jan 2017 11:22:29 -0800

Guillem Jover <guillem@debian.org> writes:

> I'd also like to detangle this potential reformatting from this initial
> conversion, because once it's in DocBook we can use other tools (such as
> pandoc) to convert to other formats, but not from DebianDoc-SGML.

> I think both options, asciidoc or some kind of extended Markdown might
> be suitable for policy, but that would also need someone to go over the
> current markup and see if it would be enough. Or try a conversion and
> see what gets lost.

Yeah, my preference is to just go ahead with the DocBook conversion, since
nearly all of the work has already been done, it gets us off a fairly
deprecated toolchain, and it doesn't make the situation for moving to
something like Markdown or asciidoc any worse than it is today.  And it
gets us down to only two markup languages used when maintaining Policy.

That doesn't necessarily mean we need to use DocBook forever, but since
most of the work is done, it seems like a reasonable next step?

If anyone wants to pursue moving the other, smaller Policy documents to
MultiMarkdown, I certainly wouldn't object (for the Perl policy, please
check with the Perl maintainers on their preference), since I don't think
the full power of XML is doing much for us there.  The only drawback to
doing that would be if we eventually want to settle on a single markup
language for everything and have that be XML, and for me at least I don't
mind having some MultiMarkdown in there at all and don't think we need to
standardize on XML.

If folks want to work on asciidoc instead, my only request is that we not
increase the number of markup formats, so please convert the stuff in
MultiMarkdown to asciidoc while you're doing that (and of course provide
some evidence for why it's better than MultiMarkdown; I know very little
about the relative merits of the two).

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #143 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sun, 15 Jan 2017 20:51:07 +0100

[Message part 1 (text/plain, inline)]

Hi!

On Sat, 2017-01-14 at 10:59:45 -0800, Russ Allbery wrote:
> Guillem Jover <guillem@debian.org> writes:
> > I've prepared a renewal of the conversion. And scripted it so that it
> > can be performed at any point in time regardless of most changes in the
> > sources.
> 
> > This also includes several fixes to the current SGML source to ease the
> > future conversion, I think these are fine to merge now already.
> 
> > There are still some things to polish and review I'm afraid. I think
> > there is a problem with spacing which get mangled on conversion, but I'd
> > need to recheck. The comments are currently lost. The PS and PDF
> > generation might also need some work. I think all IDs are preserved, but
> > this also needs checking.
> 
> > The current state can be tracked in the pu/markup-singularity branch at
> > <https://git.hadrons.org/cgit/debian/policy.git/>, which I might rebase
> > at any point in time.
> 
> Awesome, thank you so much!

No problem!

> Are any of the sub-policies ready to convert to DocBook right now?  We
> could convert them for the next release and worry about the main Policy
> document, which presumably would be harder, in a later release.

I've found the problem with the wrong spacing, which was due to
tidy(1), I've played now with xmllint(1) and pandoc(1), but disabled
the initial cleanup for now (branch updated). So the converted XML is
not indented, but I'm not sure if you are fine with that.

I'm including a patchset which fixes several things that will make the
conversion easier, and I think they are correct independently of the
conversion.

The remaining possible output issues/differences are:

  * The Abstract and Copyright Notice end up w/o any heading, so it's
    a bit hard to distinguish.
  * The authors are listed at the top of the documents instead of at
    the bottom.
  * The policy version and date are not output.
  * The upgrading-checklist.xml output generates a TOC, the new
    html-notoc.dsl needs to be hooked into the build machinery to
    avoid that.
  * The PDF/PS output for policy.xml probably needs some tuning.
  * The build dependencies might need checking for additions or
    removals.
  * The XML is not shipped for some of the converted documents, I'm
    not sure why the SGML was being shipped before?
  * … (Probably some other stuff I might be forgetting now.)

OTOH, the output seems less cluttered which looks like an improvement
to me.

Thanks,
Guillem

[0001-Use-entities-instead-of-literal-and.patch (text/x-diff, attachment)]

[0002-Use-var-instead-of-angle-bracket-entities.patch (text/x-diff, attachment)]

[0003-Use-var-instead-of-em.patch (text/x-diff, attachment)]

[0004-Do-not-use-slashes-in-section-ID-attributes.patch (text/x-diff, attachment)]

[0005-Turn-an-SGML-comment-in-menu-policy-into-an-actual-p.patch (text/x-diff, attachment)]

[0006-Replace-SGML-comment-with-an-actual-reference-to-the.patch (text/x-diff, attachment)]

[0007-Remove-outdated-SGML-comments.patch (text/x-diff, attachment)]

Message #148 received at 175064@bugs.debian.org (full text, mbox, reply):

From: gregor herrmann <gregoa@debian.org>

To: Guillem Jover <guillem@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Mon, 16 Jan 2017 00:53:43 +0100

[Message part 1 (text/plain, inline)]

On Sun, 15 Jan 2017 20:51:07 +0100, Guillem Jover wrote:

> Subject: [PATCH 1/7] Use entities instead of literal <, > and &

It seems you've converted some '>' to '&gt;' but not all?
 
> -if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
> +if [ "$1" = start ] &amp;&amp; which initctl >/dev/null &amp;&amp; initctl version | grep -q upstart
                                                ^

> -  if dpkg-statoverride --list $i >/dev/null 2>&1
> +  if dpkg-statoverride --list $i >/dev/null 2&gt;&amp;1
                                    ^

Cheers,
gregor

-- 
 .''`.  https://info.comodo.priv.at/ - Debian Developer https://www.debian.org
 : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D  85FA BB3A 6801 8649 AA06
 `. `'  Member of VIBE!AT & SPI, fellow of the Free Software Foundation Europe
   `-   NP: Beatles

[signature.asc (application/pgp-signature, inline)]

Message #153 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: gregor herrmann <gregoa@debian.org>, 175064@bugs.debian.org

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Mon, 16 Jan 2017 01:46:28 +0100

[Message part 1 (text/plain, inline)]

On Mon, 2017-01-16 at 00:53:43 +0100, gregor herrmann wrote:
> On Sun, 15 Jan 2017 20:51:07 +0100, Guillem Jover wrote:
> 
> > Subject: [PATCH 1/7] Use entities instead of literal <, > and &
> 
> It seems you've converted some '>' to '&gt;' but not all?

Indeed, nice catch! The following two I think were part of a botched
patch split during a rebase. But there are several other I had missed
and for which the tools I've used did not complain. In any case, I've
now switching all of them, I think. Updated patch attached.

> > -if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
> > +if [ "$1" = start ] &amp;&amp; which initctl >/dev/null &amp;&amp; initctl version | grep -q upstart
>                                                 ^
> 
> > -  if dpkg-statoverride --list $i >/dev/null 2>&1
> > +  if dpkg-statoverride --list $i >/dev/null 2&gt;&amp;1

Thanks,
Guillem

[v2-0001-Use-entities-instead-of-literal-and.patch (text/x-diff, attachment)]

Message #158 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Osamu Aoki <osamu@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org, Simon McVittie <smcv@debian.org>, Bill Allombert <ballombe@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Tue, 17 Jan 2017 02:23:41 +0900

Hi,

Thanks for moving my 6 year old patch snippets/idea into real action.

On Sun, Jan 15, 2017 at 04:54:32PM +0100, Guillem Jover wrote:
...
> 
> On Sat, 2017-01-14 at 21:30:14 +0000, Simon McVittie wrote:
> > On Sat, 14 Jan 2017 at 11:32:09 -0800, Russ Allbery wrote:
> > > Bill Allombert <ballombe@debian.org> writes:
> > > > I am concerned that DocBook is much too complex to be used for Debian
> > > > policy.  We need to people to write patches without trouble and we do
> > > > not have many editors available for fixing the XML. Debiandoc-SGML
> > > > virtue is that it is simple.
> 
> > > They seem essentially identical to me?  We've had copyright-format in the
> > > Policy distribution for a while, and it's never seemed any different to me
> > > (as someone not horribly familiar with XML markup) from editing Policy.

DocBook can be complex if you use some rarely used tags.  But you don't
need to do that.

The DocBook XML files generated by Guillem's script only use very
limited subset of tags.  I know this since I wrote core of the
conversion engine.   For policy, it is wise not to use fancy new tags
unless it is absolutely needed and the future edits should limit the use
of new XML tags.

Subversion's documentation is insightful.  DocBook lite is what they
use.

 http://svn.apache.org/repos/asf/subversion/branches/1.6.x-r1138375/doc/tools/readme-dblite.html

> Yeah, pretty much. And there are way more tools to handle DocBook than
> DebianDoc-SGML; linters, editors, converters, etc. more documentation
> and people that will know DocBook too.

Also, DocBook format is very stable.  ASCIIDOC and other markup
languages are convenient if you use it once or for a short document.
But it will bite you when they change implementation details.  I have
been bitten by ASCIIDOC changes.

(I use ASCIIDOC for documentation as a way to easily create legal XML
data)

> > > The alternative, I guess, would be to use Markdown for the whole thing,
> > > but I think it's worthwhile to have sections and internal links and a bit
> > > more formatting than Markdown gives us.
> 
> While I like Markdown very much, I've found in many situations that it
> is very limiting when you want to start doing more interesting markup
> and formatting. :(
> 
> > asciidoc, then? Or Markdown with pandoc extensions?
> > 
> > asciidoc is another wiki-like language, but has semantics defined in
> > terms of Docbook rather than HTML.
> > 
> > Pandoc's Markdown dialect includes footnotes and explicit or implicit
> > anchors in headings.

Pandoc should be able to convert DocBook XML into Markdown or anything,
in theory.

But Markdown has too many dialects depending on which processing
infrastructure you use, results vary.

So DocBook is a neutral ground.  Exim documentation experience tells me
that these non-XML markup saves typing but its not a good idea for long
term solution if many people are involved.
...
 
> > > Anyway, my understanding (see earlier messages in this bug) is that the
> > > maintainer of DebianDoc-SGML is actively trying to transition people away

YES I do.  Once Policy is converted, I will probably orphan/RFA this package.

(Maybe FAQ is the remaining one to be converted but with this updated
script combination, that conversion is coming soon.)

...

Osamu

Message #163 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: 175064@bugs.debian.org, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Mon, 20 Feb 2017 13:16:25 -0800

Guillem Jover <guillem@debian.org> writes:

> I've found the problem with the wrong spacing, which was due to tidy(1),
> I've played now with xmllint(1) and pandoc(1), but disabled the initial
> cleanup for now (branch updated). So the converted XML is not indented,
> but I'm not sure if you are fine with that.

I'm totally fine with that.  I honestly don't care whether the generated
XML is particularly readable.  It would be minorly nice, but meh, it's an
output format, and very few people are ever going to look at it.  If it
makes maintenance easier, let's not worry about it.

> I'm including a patchset which fixes several things that will make the
> conversion easier, and I think they are correct independently of the
> conversion.

Thanks!  These have all been applied.

> The remaining possible output issues/differences are:

>   * The Abstract and Copyright Notice end up w/o any heading, so it's
>     a bit hard to distinguish.
>   * The authors are listed at the top of the documents instead of at
>     the bottom.
>   * The policy version and date are not output.
>   * The upgrading-checklist.xml output generates a TOC, the new
>     html-notoc.dsl needs to be hooked into the build machinery to
>     avoid that.
>   * The PDF/PS output for policy.xml probably needs some tuning.
>   * The build dependencies might need checking for additions or
>     removals.
>   * The XML is not shipped for some of the converted documents, I'm
>     not sure why the SGML was being shipped before?

I don't think there's any need to ship the SGML in the installed package.

Honestly, all of this sounds minor enough that I would be very tempted to
just pull the trigger and do the conversion.

> OTOH, the output seems less cluttered which looks like an improvement
> to me.

Yeah, that's been one of the things that's made me unhappy about the text
output for some time.

Thank you for working on this!

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #168 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sun, 26 Mar 2017 06:06:16 +0200

On Mon, 2017-02-20 at 13:16:25 -0800, Russ Allbery wrote:
> Guillem Jover <guillem@debian.org> writes:
> > I've found the problem with the wrong spacing, which was due to tidy(1),
> > I've played now with xmllint(1) and pandoc(1), but disabled the initial
> > cleanup for now (branch updated). So the converted XML is not indented,
> > but I'm not sure if you are fine with that.
> 
> I'm totally fine with that.  I honestly don't care whether the generated
> XML is particularly readable.  It would be minorly nice, but meh, it's an
> output format, and very few people are ever going to look at it.  If it
> makes maintenance easier, let's not worry about it.

Oh, I guess I was not clear, I was referring to the XML converted from
the SGML, which will become the new source from where all output
formats will be generated, so it would definitely be looked at (I'd
hope! :).

If you run the script, you'll see the resulting converted output, if
that looks fine, then, good. :)

> > I'm including a patchset which fixes several things that will make the
> > conversion easier, and I think they are correct independently of the
> > conversion.
> 
> Thanks!  These have all been applied.

Perfect, thanks!

> > The remaining possible output issues/differences are:
> 
> >   * The Abstract and Copyright Notice end up w/o any heading, so it's
> >     a bit hard to distinguish.
> >   * The authors are listed at the top of the documents instead of at
> >     the bottom.
> >   * The policy version and date are not output.
> >   * The upgrading-checklist.xml output generates a TOC, the new
> >     html-notoc.dsl needs to be hooked into the build machinery to
> >     avoid that.
> >   * The PDF/PS output for policy.xml probably needs some tuning.
> >   * The build dependencies might need checking for additions or
> >     removals.
> >   * The XML is not shipped for some of the converted documents, I'm
> >     not sure why the SGML was being shipped before?
> 
> I don't think there's any need to ship the SGML in the installed package.
> 
> Honestly, all of this sounds minor enough that I would be very tempted to
> just pull the trigger and do the conversion.

Sounds good to me. I can probably check several of those over time
once this is merged in.

In which case I can rebase, check that everything is fine, and resend
the scripts to run the conversion to the bug.

> > OTOH, the output seems less cluttered which looks like an improvement
> > to me.
> 
> Yeah, that's been one of the things that's made me unhappy about the text
> output for some time.
> 
> Thank you for working on this!

No problem!

Thanks,
Guillem

Message #173 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: 175064@bugs.debian.org, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sat, 25 Mar 2017 21:25:14 -0700

Guillem Jover <guillem@debian.org> writes:

> Oh, I guess I was not clear, I was referring to the XML converted from
> the SGML, which will become the new source from where all output formats
> will be generated, so it would definitely be looked at (I'd hope! :).

> If you run the script, you'll see the resulting converted output, if
> that looks fine, then, good. :)

Oh, I see.  I think we can live with this.

> Sounds good to me. I can probably check several of those over time
> once this is merged in.

> In which case I can rebase, check that everything is fine, and resend
> the scripts to run the conversion to the bug.

Thanks, that sounds great!

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #178 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Mon, 27 Mar 2017 04:47:33 +0200

[Message part 1 (text/plain, inline)]

Hi!

On Sat, 2017-03-25 at 21:25:14 -0700, Russ Allbery wrote:
> Guillem Jover <guillem@debian.org> writes:
> > Sounds good to me. I can probably check several of those over time
> > once this is merged in.
> 
> > In which case I can rebase, check that everything is fine, and resend
> > the scripts to run the conversion to the bug.
> 
> Thanks, that sounds great!

Ok, here they are. Some comments:

From the list of issues I mentioned previously, the possibly most
visually significant one still remaining is that the chunked HTML
output for the upgrading-checklist contains a TOC, but I've at least
removed it from the single-file HTML output now.

I've updated the Build-Depends, and removed the recently introduced
ghostscript, so the new changelog entry might need to to be removed.

I've included the conversion scripts as an actual commit for
historical purposes, but perhaps you might want to skip committing
that, or commit its removal afterwards. I've also not included the
actual conversion commit, because it might trip over list/BTS limits
(sized ar around 1.1 MiB). And you might perhaps want to squash that
with the one updating the build system? I can provide a branch instead
if you want, with the commits in whatever shape you'd prefer.

I think that to be able to fix some of the other minor issues I've
mentioned before, we'd need to switch to use XSLT toolchain for the
HTML generation. And also because openjade seems a bit stagnant
upstream. I've not done that here because other parts of the build
already use openjade, and went with the existing setup for now.

I've got also another patch on top of the converted files, to make
upgrading-checklist a proper appendix, but it has some issues, so
I'll probably post it later on, after a possible switch to XSLT.

Thanks,
Guillem

[0001-Make-tidy-not-convert-character-entities-to-their-UT.patch (text/x-diff, attachment)]

[0002-Do-not-ship-redundant-SGML-and-XML-sources.patch (text/x-diff, attachment)]

[0003-Add-new-DebianDoc-SGML-to-DocBook-conversion-script.patch (text/x-diff, attachment)]

[0004-Update-build-system-for-DocBook-conversion.patch (text/x-diff, attachment)]

Message #183 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Tue, 28 Mar 2017 05:50:35 +0200

On Mon, 2017-03-27 at 04:47:33 +0200, Guillem Jover wrote:
> I've updated the Build-Depends, and removed the recently introduced
> ghostscript, so the new changelog entry might need to to be removed.

It seems I missed also bsdmainutils.

> I think that to be able to fix some of the other minor issues I've
> mentioned before, we'd need to switch to use XSLT toolchain for the
> HTML generation. And also because openjade seems a bit stagnant
> upstream. I've not done that here because other parts of the build
> already use openjade, and went with the existing setup for now.

So, I just did this now on top, but it would seem better to do it
before the conversion, so I'll rebase and reorder the changes and
send an updated series tomorrow.

> I've got also another patch on top of the converted files, to make
> upgrading-checklist a proper appendix, but it has some issues, so
> I'll probably post it later on, after a possible switch to XSLT.

This should be fine now. :)

I've also now added a run for xmllint. Took also a look at replacing
dblatex with xmlroff, but it fails hard, and upstream also seems
stagnant, so abandoned that route.

Thanks,
Guillem

Message #188 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: Russ Allbery <rra@debian.org>, 175064@bugs.debian.org

Cc: Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Wed, 29 Mar 2017 05:28:23 +0200

[Message part 1 (text/plain, inline)]

Hi!

Ok, here's the updated patch series for the conversion omitting the
actual conversion commit. Attached and in the pu/markup-singularity
branch at <https://git.hadrons.org/cgit/debian/policy.git/>.

A summary of the current status:

* Switched from OpenJade to xsltproc, and added xmllint.
* The Abstract now has a heading again (!).
* The License and Copyright information although w/o heading are
  more distinguishible now (in all output formats).
* Turned the upgrading-checklist into a proper appendix.
* The standalone upgrading-checklist outputs have no TOC anymore, to
  preserve compatibility and avoid clutter, but perhaps we want them?
* Removed the tidy(1) usage, see the commit message, but left the
  first fix in, because I'm not sure if you agree with this or not,
  otherwise the first commit could be removed.
* Reordered the commits so that the conversion script makes more
  sense now on its own.
* Do not forget to remove the recent ghostscript entry from the
  changelog, as it's now gone!
* Commit 6/8 can be found in the git repo, but it should be
  reproducible by running the conversion script.

So, the HTML and txt outputs look pretty good to me (I think even
better than before). The PDF/PS output looks in general way better
than the current ones, but they have some issues mostly with the
heading/preface/etc that need to be addressed, and that will need
LaTeX tunning I think:

* The release information is not present in the PDF/PS output (the
  current version). This only gets displayed with draft.mode=yes,
  and in the wrong place anyway. :/
* The authors information is (IMO) attrociously presented (this at
  least includes the release date). This can be very easily disabled
  for now though with doc.collab.show=0. At least this information is
  somewhat present already in §1.3.

Thanks,
Guillem

[0001-Make-tidy-not-convert-character-entities-to-their-UT.patch (text/x-diff, attachment)]

[0002-Do-not-ship-redundant-SGML-and-XML-sources.patch (text/x-diff, attachment)]

[0003-Remove-unused-Build-Depends.patch (text/x-diff, attachment)]

[0004-Switch-from-OpenJade-to-xsltproc-for-DocBook-process.patch (text/x-diff, attachment)]

[0005-Add-new-DebianDoc-SGML-to-DocBook-conversion-script.patch (text/x-diff, attachment)]

[0007-Update-build-system-for-DocBook-conversion.patch (text/x-diff, attachment)]

[0008-Make-the-upgrading-checklist-a-proper-appendix-of-th.patch (text/x-diff, attachment)]

Message #195 received at 175064@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: Guillem Jover <guillem@debian.org>

Cc: 175064@bugs.debian.org, Osamu Aoki <osamu@debian.org>

Subject: Re: Bug#175064: DocBook XML conversion is read with this script

Date: Sun, 30 Apr 2017 16:59:45 -0700

Guillem Jover <guillem@debian.org> writes:

> Ok, here's the updated patch series for the conversion omitting the
> actual conversion commit. Attached and in the pu/markup-singularity
> branch at <https://git.hadrons.org/cgit/debian/policy.git/>.

This has now been applied including the conversion generated by the
script.  Thank you both for all your work on this!  This is a huge
milestone.

I have also gone through and reformatted and rewrapped the resulting
DocBook source to make it a bit more human-maintainable.  Not saying that
it's the best possible format (unfortunately, DocBook has fairly long tag
names), but it's a bit better than no indentation whatsoever, and is at
least relatively consistent.  And it's the formatting that I like and I'm
doing most of the patch merging right now, so....  :P

There's almost certainly going to be a bunch of remaining minor issues and
formatting bugs introduced by this conversion.  One thing I noticed
already is that the heavy use of footnotes gets more awkward for most of
the output formats, and I think I may go looking for a better way of
representing some of that data and moving it out of footnotes.  But we can
start tweaking things more easily now, and investigate better markup
language usage using the broader power of DocBook.

The next step is an upload.  More on that in another message.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Message #200 received at 175064-close@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: 175064-close@bugs.debian.org

Subject: Bug#175064: fixed in debian-policy 4.0.0.0

Date: Sun, 28 May 2017 21:03:39 +0000

Source: debian-policy
Source-Version: 4.0.0.0

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 175064@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Russ Allbery <rra@debian.org> (supplier of updated debian-policy package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Format: 1.8
Date: Sun, 28 May 2017 12:27:07 -0700
Source: debian-policy
Binary: debian-policy
Architecture: source
Version: 4.0.0.0
Distribution: experimental
Urgency: low
Maintainer: Debian Policy List <debian-policy@lists.debian.org>
Changed-By: Russ Allbery <rra@debian.org>
Description:
 debian-policy - Debian Policy Manual and related documents
Closes: 175064 181123 568374 688220 698012 700532 734662 746514 759186 759492 768117 768292 781654 792853 793493 793999 794902 798309 809382 816249 816515 819660 820197 821365 821859 822059 823348 823910 824922 829367 830989 833177 835490 835876 841877 849483 850646 852314
Changes:
 debian-policy (4.0.0.0) experimental; urgency=low
 .
   [ Andreas Barth ]
   * Policy: Add the MPLs to /usr/share/common-licenses
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Closes: #768292
   * Policy: [5.6.12] forbid colons in package version numbers
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Seconded: Sam Hartman <hartmans@debian.org>
     Thanks: Jakub Wilk <jwilk@debian.org>
     Closes: #792853
   * Policy: [4.3] Update config.guess and config.sub during the build
     Wording:  Bill Allombert <ballombe@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Seconded: Andreas Barth <aba@ayous.org>
     Closes: #746514
   * Spelling fixes, thanks to Martin A. Brown. Closes: #820197
 .
   [ Russ Allbery ]
   * Policy: [10.9] Don't contact base-passwd maintainer for dynamic users
     Wording: Colin Watson <cjwatson@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Seconded: gregor herrmann <gregoa@debian.org>
     Closes: #841877
   * Policy: Document Build-Depends-Arch and Build-Conflicts-Arch
     Wording: Johannes Schauer <josch@debian.org>
     Seconded: Stuart Prescott <stuart@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #823910
   * Policy: Add nodoc tag to DEB_BUILD_OPTIONS
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Johannes Schauer <j.schauer@email.de>
     Seconded: Charles Plessy <plessy@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Closes: #759186
   * Policy: Prohibit file conflicts between /bin and /usr/bin
     Wording: Ansgar Burchardt <ansgar@debian.org>
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Seconded: Felipe Sateler <fsateler@debian.org>
     Closes: #759492
   * Policy: Debug packages don't need a debian/control paragraph
     Wording: Tanguy Ortolo <tanguy+debian@ortolo.eu>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #819660
   * Policy: New dpkg-architecture flags
     Wording: Guillem Jover <guillem@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #793493
   * Policy: Remove even the fallback to calling /etc/init.d directly
     Wording: Ondřej Nový <onovy@debian.org>
     Seconded: Michael Stapelberg <stapelberg@debian.org>
     Seconded: Andreas Henriksson <andreas@fatal.se>
     Closes: #833177
   * Policy: Limit strength of dependencies on -doc packages
     Wording: Josh Triplett <josh@joshtriplett.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Closes: #823348
   * Policy: Explicitly allow https form of copyright-format URL
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Seconded: gregor herrmann <gregoa@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Closes: #850646
   * 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
   * Policy: Add optional try-restart init status, make status recommended
     Wording: Andreas Henriksson <andreas@fatal.se>
     Seconded: Simon McVittie <smcv@debian.org>
     Seconded: Felipe Sateler <fsateler@debian.org>
     Seconded: Ondřej Nový <novy@ondrej.org>
     Closes: #181123
   * 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
   * Policy: Update policy on /dev and device file management
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Andreas Henriksson <andreas@fatal.se>
     Seconded: Simon McVittie <smcv@debian.org>
     Closes: #698012
   * 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
   * Perl: Update module search path for multiarch support
     Wording: Dominic Hargreaves <dom@earth.li>
     Seconded: Niko Tyni <ntyni@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #798309
   * virtual-package-names-list: Add adventure
     Wording: Ben Finney <ben+debian@benfinney.id.au>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Closes: #821859
   * virtual-package-names-list: Add httpd-wsgi3
     Wording: Bill Allombert <ballombe@debian.org>
     Seconded: Brian May <bam@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #768117
   * virtual-package-names-list: Add virtual-mysql-* packages
     Wording: Otto Kekäläinen <otto@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #829367
   * Convert all remaining DebianDoc-SGML source files in the package to
     DocBook XML.  Many thanks to Osamu Aoki and Guillem Jover for lots of
     hard work on the conversion.  This was a huge conversion, so there
     will probably be some lingering formatting issues, incorrect markup,
     and less-than-ideal output.  Please report any problems as bugs.
     (Closes: #175064, #700532, #809382)
   * Additional fixes from Guillem Jover as part of the DocBook conversion:
     - Stop distributing the source SGML files as part of the installed
       package.  There doesn't seem to be any point in doing this.
     - Switch to xsltproc and dblatex instead of OpenJade.
     - Stop using tidy on the generated files since it generates larger
       files and the output from xsltproc is already compliant and fairly
       clean.
     - Remove unused Build-Depends.
     - Use entities instead of literal <, >, and & characters.
     - Use <var> instead of escaped angle brackets for metavariables.
     - Use <var> instead of <em> inside <tt>.
     - Avoid slashes in section IDs.
     - Convert a comment about maintenance policy in the Menu Policy
       document to a regular paragraph in the document.
     - Replace a comment reference to the policy maintenance process with
       an actual link to Process.md.
     - Remove obsolete SGML comments.
   * Move the description of < and > relations to a footnote to make
     abundantly clear that they're no longer valid relation operators in
     dependencies.  (Closes: #816515)
   * Clarify informative mentions of debian/tmp in the appendices to
     document the now-common use of debian/<pkg> instead as the temporary
     staging area.  Document that convention, instead of
     debian/tmp-something, for multi-binary packages.  Thanks, Niels
     Thykier.  (Closes: #816249)
   * Remove lingering wording that implied that build-arch and build-indep
     targets are optional.  Thanks, Ferenc Wagner, Jakub Wilk, and Charles
     Plessy.  (Closes: #793999)
   * Rather than giving the paths to the installed shlibs and symbols files
     and then saying those paths shouldn't be used, just say to use
     dpkg-query --control-show.  Recommend --control-show instead of
     --control-path, since the latter is deprecated.  Patch from Salvatore
     Bonaccorso.  (Closes: #688220)
   * Explicitly give Unicode code points in the definition of the syntax of
     Debian control files and, where appropriate, show the character.
     Patch from Ben Finney.  (Closes: #821365)
   * Remove obsolete footnote about a versioned dependency on a
     liblockfile1 release from 1999.  Thanks, Jakub Wilk.  (Closes: #794902)
   * Fix the long name of the Common Public License in the copyright-format
     policy.  It is just Common Public License, with no leading "IBM".
     Thanks, Stefano Zacchiroli.  (Closes: #781654)
   * Fix the copyright-format examples to not have duplicate License
     paragraphs.  Thanks, Stefan <bd@bc-bd.org>.  (Closes: #824922)
   * Replace reference to dbus-launch in the autopkgtest documentation with
     dbus-run-session.  Patch from Simon McVittie.  (Closes: #835876)
   * Add an example of an architecture restriction in a dependency with
     multiple architectures separated by spaces.  (Closes: #734662)
   * Replace use of markdown with MultiMarkdown for the autopkgtest
     documentation and convert README and Process to MultiMarkdown, thus
     dropping the last org-mode files and the build dependency on Emacs.
     Patch from Guillem Jover.  (Closes: #849483)
   * Add some additional information to the upgrading-checklist entry for
     the 3.9.8.0 release.
   * Fix debian/changelog and upgrading-checklist dates for the 3.9.8.0
     release to match the actual upload.  (Closes: #822059)
   * Fix duplicated "the" words in 4.4 and 8.6.3.2.  Patch from Valentin
     Samir.  (Closes: #830989)
   * 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 version headings 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.
   * Compress all files with gzip -n to avoid embedding timestamps,
     enabling reproducible builds.
   * 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.
   * Switch to https URLs for Vcs-Git and Vcs-Browser.
   * Use the same URL for both Vcs-Git and Vcs-Browser, which now works
     fine and has some advantages over the gitweb version for Vcs-Browser.
     Thanks, Mattia Rizzolo.
   * Run wrap-and-sort -ast.
   * Tag as Multi-Arch: foreign (mostly to silence the hinter).
 .
   [ Sean Whitton ]
   * Remove references to DebianDoc-SGML from README.md.
   * Fix typo & comma splice in Process.md.
Checksums-Sha1:
 67549dd71ee43fecadc298baadedb53d66140acd 1586 debian-policy_4.0.0.0.dsc
 94c933d5c4b474500185adab753affe6962562df 659440 debian-policy_4.0.0.0.tar.xz
Checksums-Sha256:
 5e2ec94dbf584b2889b309ad45fb12d1fd03bc953d90273d8ea0fee402e62ecc 1586 debian-policy_4.0.0.0.dsc
 539fe5c192532eb53fb7d5ffe05a241a0a1ead3cc9f39d88f4656f27110ee877 659440 debian-policy_4.0.0.0.tar.xz
Files:
 f759af808fe56dbb1b3c0469c755fa48 1586 doc optional debian-policy_4.0.0.0.dsc
 9fe33a84526b82d4544e30f604e6523f 659440 doc optional debian-policy_4.0.0.0.tar.xz

-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEE1zk0tJZ0z1zNmsJ4fYAxXFc23nUFAlkrM1UACgkQfYAxXFc2
3nWPrgf/X6/Hn4HFhSQk4uX2Rz7SMU9Mo+dVkSNrzPCVhVjR0EfHu5UbBmwGnXTO
3yshmDFJhz2YKcyjHKB63kmC4rYhoJdCWHDDqjCzCPtmaKRqEHUBJ3pPyOkPz3ZB
h637OyUtQEuxXnp1+a6l6aPxBhz/r1mfa/efDNoJAgmXhTREnwOiAi6BXkK6pG81
fqzW9+cyKK0okJdUKNmAu/mgCtKF1iSIWd86oQUzxs9lNXUVEwbUSqLH9hfe0XvJ
4OmO62NCeoQUFuSFSke97ugadrt8LXezgNNSKr+OXRcz5pSRCBQXpBaFFpYHg7OV
IsLauUljsVlA60IDzAV6kamuBqmMJw==
=5fyI
-----END PGP SIGNATURE-----

Message #209 received at 175064-close@bugs.debian.org (full text, mbox, reply):

From: Russ Allbery <rra@debian.org>

To: 175064-close@bugs.debian.org

Subject: Bug#175064: fixed in debian-policy 4.0.0.1

Date: Mon, 19 Jun 2017 02:49:11 +0000

Source: debian-policy
Source-Version: 4.0.0.1

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 175064@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Russ Allbery <rra@debian.org> (supplier of updated debian-policy package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Format: 1.8
Date: Sun, 18 Jun 2017 19:27:48 -0700
Source: debian-policy
Binary: debian-policy
Architecture: source all
Version: 4.0.0.1
Distribution: unstable
Urgency: low
Maintainer: Debian Policy List <debian-policy@lists.debian.org>
Changed-By: Russ Allbery <rra@debian.org>
Description:
 debian-policy - Debian Policy Manual and related documents
Closes: 175064 181123 568374 688220 698012 700532 734662 746514 759186 759492 768117 768292 781654 792853 793493 793999 794902 798309 809382 816249 816515 819660 820197 821365 821859 822059 823348 823910 824922 829367 830989 833177 835490 835876 841877 849483 850646 852314
Changes:
 debian-policy (4.0.0.1) unstable; urgency=low
 .
   * Upload to unstable.
   * Clarify the conflict policy between /path and /usr/path by adding the
     leading slash in front of the first path.  Thanks, Ferenc Wágner.
   * Change http URLs to https for every resource available over https.
   * Replace broken CPAN URL in the Perl policy with the current URL, and
     turn this into an in-line link rather than a footnote with the full
     URL.  This hides the URL in the text output, but it's not horribly
     important for the text version and easy to find with a search.
   * Fix formatting of the list of shlibs and symbol file locations.  These
     were mistakenly converted to itemized lists instead of variable lists
     during the DocBook conversion, which produced inferior output.
   * Use UTF-8 instead of ISO-8859-1 as the character set for the text
     versions of policy documents.
   * Further standardize author and copyright notices.
     - Add the notice from the main document that the copyright notices are
       incomplete to the other documents with copyright notices.
     - Add the Debian Policy Mailing List as an author of the debconf
       specification.
     - Replace (incorrect) Software in the Public Interest copyrights with
       copyright notices for the original authors.
     - Standardize capitalization of Debian Policy Mailing List in notices.
     - Update copyright notices in debian/copyright.
   * Add a full copy of the BSD license without advertising clause to the
     <legalinfo> section of the debconf specification, instead of just a
     reference to it.
   * Update the GPL license statements to the current recommended form,
     which doesn't include a street address for the FSF.  Use all-caps for
     the warranty disclaimer just in case it matters.  Link to the general
     FSF license page to make it easier to find the GPLv2, which is
     technically the license under which these documents are distributed,
     even if the GPLv3 may be used if desired.
   * Completely rewrite the build system to use debhelper.
     - Remove all hand-rolled package build rules and let debhelper do the
       package construction.
     - Remove gzip compression from the main build and let debhelper handle
       compression of text files.  This allows debhelper to control the
       gzip flags and do whatever is correct for reproducible builds.
     - The top-level Makefile now has conventional all and install targets
       that build all documents and would install them (not that anyone is
       likely to use the install target other than the packaging).
     - Get the document publication dates from debian/changelog instead of
       the current date for more reproducible builds.
     - Do xmllint validation of the copyright-format and debconf
       specification documents as well.
     - Remove a bunch of old leftovers from the clean and distclean targets
       and make distclean identical to clean.  Stop cleaning editor
       autosave files and patch droppings (this can be destructive).
     - Move all doc-base files into the debian packaging directory.
   * Restructure the command list in the debconf specification document to
     pass xmllint, which didn't like including the body of an itemizedlist
     as an XML entity.
   * Add missing release date to the 4.0.0 upgrading-checklist entry.
   * Fix tools/policy-bug-report to not fail when bug lists are empty and
     to ignore closed bugs.
   * Don't delete virtual-package-names-list.txt during make distclean.
   * Make distclean depend on clean to remove stamp-* files.
   * Update Standards-Version of the debian-policy package itself.
 .
 debian-policy (4.0.0.0) experimental; urgency=low
 .
   [ Andreas Barth ]
   * Policy: Add the MPLs to /usr/share/common-licenses
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Closes: #768292
   * Policy: [5.6.12] forbid colons in package version numbers
     Wording: Charles Plessy <plessy@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Seconded: Sam Hartman <hartmans@debian.org>
     Thanks: Jakub Wilk <jwilk@debian.org>
     Closes: #792853
   * Policy: [4.3] Update config.guess and config.sub during the build
     Wording:  Bill Allombert <ballombe@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Seconded: Andreas Barth <aba@ayous.org>
     Closes: #746514
   * Spelling fixes, thanks to Martin A. Brown. Closes: #820197
 .
   [ Russ Allbery ]
   * Policy: [10.9] Don't contact base-passwd maintainer for dynamic users
     Wording: Colin Watson <cjwatson@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Seconded: gregor herrmann <gregoa@debian.org>
     Closes: #841877
   * Policy: Document Build-Depends-Arch and Build-Conflicts-Arch
     Wording: Johannes Schauer <josch@debian.org>
     Seconded: Stuart Prescott <stuart@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #823910
   * Policy: Add nodoc tag to DEB_BUILD_OPTIONS
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Johannes Schauer <j.schauer@email.de>
     Seconded: Charles Plessy <plessy@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Closes: #759186
   * Policy: Prohibit file conflicts between /bin and /usr/bin
     Wording: Ansgar Burchardt <ansgar@debian.org>
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Seconded: Felipe Sateler <fsateler@debian.org>
     Closes: #759492
   * Policy: Debug packages don't need a debian/control paragraph
     Wording: Tanguy Ortolo <tanguy+debian@ortolo.eu>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #819660
   * Policy: New dpkg-architecture flags
     Wording: Guillem Jover <guillem@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #793493
   * Policy: Remove even the fallback to calling /etc/init.d directly
     Wording: Ondřej Nový <onovy@debian.org>
     Seconded: Michael Stapelberg <stapelberg@debian.org>
     Seconded: Andreas Henriksson <andreas@fatal.se>
     Closes: #833177
   * Policy: Limit strength of dependencies on -doc packages
     Wording: Josh Triplett <josh@joshtriplett.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Closes: #823348
   * Policy: Explicitly allow https form of copyright-format URL
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Seconded: gregor herrmann <gregoa@debian.org>
     Seconded: Didier 'OdyX' Raboud <odyx@debian.org>
     Closes: #850646
   * 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
   * Policy: Add optional try-restart init status, make status recommended
     Wording: Andreas Henriksson <andreas@fatal.se>
     Seconded: Simon McVittie <smcv@debian.org>
     Seconded: Felipe Sateler <fsateler@debian.org>
     Seconded: Ondřej Nový <novy@ondrej.org>
     Closes: #181123
   * 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
   * Policy: Update policy on /dev and device file management
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Andreas Henriksson <andreas@fatal.se>
     Seconded: Simon McVittie <smcv@debian.org>
     Closes: #698012
   * 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
   * Perl: Update module search path for multiarch support
     Wording: Dominic Hargreaves <dom@earth.li>
     Seconded: Niko Tyni <ntyni@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #798309
   * virtual-package-names-list: Add adventure
     Wording: Ben Finney <ben+debian@benfinney.id.au>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Closes: #821859
   * virtual-package-names-list: Add httpd-wsgi3
     Wording: Bill Allombert <ballombe@debian.org>
     Seconded: Brian May <bam@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #768117
   * virtual-package-names-list: Add virtual-mysql-* packages
     Wording: Otto Kekäläinen <otto@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: Raphael Hertzog <hertzog@debian.org>
     Closes: #829367
   * Convert all remaining DebianDoc-SGML source files in the package to
     DocBook XML.  Many thanks to Osamu Aoki and Guillem Jover for lots of
     hard work on the conversion.  This was a huge conversion, so there
     will probably be some lingering formatting issues, incorrect markup,
     and less-than-ideal output.  Please report any problems as bugs.
     (Closes: #175064, #700532, #809382)
   * Additional fixes from Guillem Jover as part of the DocBook conversion:
     - Stop distributing the source SGML files as part of the installed
       package.  There doesn't seem to be any point in doing this.
     - Switch to xsltproc and dblatex instead of OpenJade.
     - Stop using tidy on the generated files since it generates larger
       files and the output from xsltproc is already compliant and fairly
       clean.
     - Remove unused Build-Depends.
     - Use entities instead of literal <, >, and & characters.
     - Use <var> instead of escaped angle brackets for metavariables.
     - Use <var> instead of <em> inside <tt>.
     - Avoid slashes in section IDs.
     - Convert a comment about maintenance policy in the Menu Policy
       document to a regular paragraph in the document.
     - Replace a comment reference to the policy maintenance process with
       an actual link to Process.md.
     - Remove obsolete SGML comments.
   * Move the description of < and > relations to a footnote to make
     abundantly clear that they're no longer valid relation operators in
     dependencies.  (Closes: #816515)
   * Clarify informative mentions of debian/tmp in the appendices to
     document the now-common use of debian/<pkg> instead as the temporary
     staging area.  Document that convention, instead of
     debian/tmp-something, for multi-binary packages.  Thanks, Niels
     Thykier.  (Closes: #816249)
   * Remove lingering wording that implied that build-arch and build-indep
     targets are optional.  Thanks, Ferenc Wagner, Jakub Wilk, and Charles
     Plessy.  (Closes: #793999)
   * Rather than giving the paths to the installed shlibs and symbols files
     and then saying those paths shouldn't be used, just say to use
     dpkg-query --control-show.  Recommend --control-show instead of
     --control-path, since the latter is deprecated.  Patch from Salvatore
     Bonaccorso.  (Closes: #688220)
   * Explicitly give Unicode code points in the definition of the syntax of
     Debian control files and, where appropriate, show the character.
     Patch from Ben Finney.  (Closes: #821365)
   * Remove obsolete footnote about a versioned dependency on a
     liblockfile1 release from 1999.  Thanks, Jakub Wilk.  (Closes: #794902)
   * Fix the long name of the Common Public License in the copyright-format
     policy.  It is just Common Public License, with no leading "IBM".
     Thanks, Stefano Zacchiroli.  (Closes: #781654)
   * Fix the copyright-format examples to not have duplicate License
     paragraphs.  Thanks, Stefan <bd@bc-bd.org>.  (Closes: #824922)
   * Replace reference to dbus-launch in the autopkgtest documentation with
     dbus-run-session.  Patch from Simon McVittie.  (Closes: #835876)
   * Add an example of an architecture restriction in a dependency with
     multiple architectures separated by spaces.  (Closes: #734662)
   * Replace use of markdown with MultiMarkdown for the autopkgtest
     documentation and convert README and Process to MultiMarkdown, thus
     dropping the last org-mode files and the build dependency on Emacs.
     Patch from Guillem Jover.  (Closes: #849483)
   * Add some additional information to the upgrading-checklist entry for
     the 3.9.8.0 release.
   * Fix debian/changelog and upgrading-checklist dates for the 3.9.8.0
     release to match the actual upload.  (Closes: #822059)
   * Fix duplicated "the" words in 4.4 and 8.6.3.2.  Patch from Valentin
     Samir.  (Closes: #830989)
   * 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 version headings 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.
   * Compress all files with gzip -n to avoid embedding timestamps,
     enabling reproducible builds.
   * 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.
   * Switch to https URLs for Vcs-Git and Vcs-Browser.
   * Use the same URL for both Vcs-Git and Vcs-Browser, which now works
     fine and has some advantages over the gitweb version for Vcs-Browser.
     Thanks, Mattia Rizzolo.
   * Run wrap-and-sort -ast.
   * Tag as Multi-Arch: foreign (mostly to silence the hinter).
 .
   [ Sean Whitton ]
   * Remove references to DebianDoc-SGML from README.md.
   * Fix typo & comma splice in Process.md.
Checksums-Sha1:
 9e1cad4696845236e2ce1f6772442bcc5906f7d2 1605 debian-policy_4.0.0.1.dsc
 52a670be0884d887eaf965850f1c421997f172fc 660052 debian-policy_4.0.0.1.tar.xz
 699ee1b7376a1e4d5e9aa4574b6934c117de50ec 1970776 debian-policy_4.0.0.1_all.deb
 191c7682c754b6c35ff3bf0832ae55a5dfb1d50c 12027 debian-policy_4.0.0.1_amd64.buildinfo
Checksums-Sha256:
 eb9fe99e837ee45eb95dc1a98710d34693b8e1f34978d990022c5d236cbecaa6 1605 debian-policy_4.0.0.1.dsc
 496b558807a745c7c7fb02a46c8961026bc00dbe9af64392f8a8f33f76878fca 660052 debian-policy_4.0.0.1.tar.xz
 fad279e45151ee7a63a543aa12038e753ecaf17fa8006fc72b86531ac87409c6 1970776 debian-policy_4.0.0.1_all.deb
 5a863fce928d54787b5680bf2d97e1ba67bb5291bf00a449487be0493ef196f6 12027 debian-policy_4.0.0.1_amd64.buildinfo
Files:
 80756bbbba7f7da85237f191e023c183 1605 doc optional debian-policy_4.0.0.1.dsc
 05fc9941e68ae5856eca0c9155c0788b 660052 doc optional debian-policy_4.0.0.1.tar.xz
 d9f2164fe42ce300c0176544926605c5 1970776 doc optional debian-policy_4.0.0.1_all.deb
 5dfa139855afd65f93ced79fc25d9984 12027 doc optional debian-policy_4.0.0.1_amd64.buildinfo

-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEE1zk0tJZ0z1zNmsJ4fYAxXFc23nUFAllHOXgACgkQfYAxXFc2
3nW5Ogf9G9A5sabx7PPLXI8K0NrCXOwLQMQP/hECU1ylp1fXryfcPFq9jkNojTFV
jx8i00/OTNZUecCx1B3IQHxYb7EOOkcEYv2Qd6L2niAySUI+yj3Blpo+1bDJyV/t
BDG7edRZUyKOWas33wqhE+wCl/pZohuionefPUJRqEkX9Wd9PE84douIy3xAeGxT
dklUHY9oVxRjso4mlJ5GSYGPOiz6ra40pWO/AazPgk7JzoB2Chu7Td0EwpYeV06a
C4vo3fFTNanmj59iV7DXt3yACCO95FxVPLONsW9J5RM+zPISNplvRUydXiOf8u4r
T/goX8yy4dIT8nwWZYVNGyYOJ77RSA==
=FdSB
-----END PGP SIGNATURE-----

Send a report that this bug log contains spam.