Bug#175064: DocBook XML conversion is read with this script
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
Reply to: