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

[Guillem Jover <guillem@debian.org>]

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