challenge: convert debian-policy doc from docbook to Sphinx

proposal: move forward to modern environment

Hideki Yamane <henrich@debian.org>

Why move away from docbook?

● Adding i18n support to docbook xml is so complicated○ couldn’t do that with old debiandoc-sgml, at least○ I want to merge Japanese translation to upstream

● It’s harder to edit/read than other markup language (such as Markdown, Asciidoc, reStructuredText)○ Less effort, more profit○ Lower barrier for newcomers

Why Sphinx?

● Linux Kernel documents have already moved from docbook to Sphinx○ They’ve already checked markdown and asciidoc,

but finally choosed reStructuredText and Sphinx ○ see https://youtu.be/jY_C-Z0qMSo

● I know upstream maintainer, so I can ask him about its feature via twitter at any time :-)

Sphinx?Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

Debian Policy: output formatSphinx supports:

HTML, LaTeX (PDF), ePub,Plain Text, Texinfo, manual pages

convert docbook .xml to .rst via pandoc

● It’s fairly easy!○ $ sudo apt install pandoc○ $ pandoc -f docbook -t rst policy.xml -o policy.rst

Pandoc issue

● Generates footnote as static number, not autonumbered →sed

● docbook generated footnote for each section, but pandoc puts only one huge footnote→manual edit

Pandoc issue

● Break Internal Hyperlink reference- `section\_title <#s-fhs>`__+ :ref:`s-fhs`

- ```Format`` <#s-f-Format>`__+ :ref:`Format <s-f-Format>`

-`Control files and their fields <#ch-controlfields>`__.+:doc:`Control files and their fields <ch-controlfields>`.

Pandoc issue

● Lose information○ <!ENTITY changesversion "1.8">

The format described in this document is <literal>&changesversion;</literal>.

○ The format described in this document is ````.

Pandoc issue

● Link tag is bit strange○ <https://www.example.com/>`__ ○ expected: <https://www.example.com/>`_

(last _ is single)

Demo: Pandoc issue

Sphinx: strong point

● i18n: established way to add new language support○ $ sudo apt install python-pip○ $ pip install sphinx-intl; export PATH=~/.local/bin:$PATH○ add locale setting to conf.py (edit)○ $ make gettext○ $ sphinx-intl update -p build/locale -l ja -l <lang2> ..○ translate source/locale/<lang>/LC_MESSAGES/<file>.po (edit)○ make html○ cd source && sphinx-build . ../build/html -D language='ja' -D

html_file_suffix=.ja.html

see http://www.sphinx-doc.org/en/stable/intl.html

Sphinx: modern look

Sphinx: “theme” feature

You can change HTML visual via“jinja2” template (I’m not sure…)

see http://www.sphinx-doc.org/en/stable/theming.html

Limitation in Sphinx compared to docbook

● No Appendix support● footnote number does not continue for whole

document→Upstream kindly create & proposed extension! :)

● Cannot use nested tag○ :ref:```Maintainer`` <s-f-Maintainer>`

Demo

$ sudo apt install python-sphinx python-pip$ pip install sphinx-intl; export PATH=~/.local/bin:$PATH$ git clone https://github.com/henrich/policydoc$ cd policydoc $ git checkout restructure$ make -f sphinx-makefile html

$ cd source; sphinx-build . ../build/html -D language='ja' -D html_file_suffix=.ja.html

Not yet

● PDF output check, compare to docbook one○ $ sudo apt install latexmk; make latexpdf

● ePub output check○ $ make epub

… Maybe need to discuss sphinx upstream to improve it.

Conclusion→Next step?

● It’s (almost) ready to use sphinx for debian-policy documentation○ But needs improvement for support multi language

output support● Give a propisal to -policy mailing list● ITP: sphinx-intl● make “debian doc” theme for sphinx (needs help)