manual: Include raw wiki files as source code for DocBook output
Currently, we edit our manual on the Debian Wiki, and fetch it in DocBook format using the "Render as Docbook" link on each page. These are the .raw.xml
files that are stored in the repository. When we build the package, we convert them to html and pdf.
There were 2 concerns raised on the freedombox-pkg-team mailing list:
-
The DocBook functionality relies on security unsupported Python code from an ancient Debian release.(Resolved) - Shipping the DocBook output without the raw wiki files violates DFSG item 2 (inclusion of source code).
- Since the raw wiki files (on the wiki server) are the preferred form of modification, and the DocBook files are generated from them.
- Suggestions are to switch to Sphinx, or ship the raw wiki text and render to DocBook and other formats.
https://alioth-lists.debian.net/pipermail/freedombox-pkg-team/2019-November/000746.html
Also relates to freedombox.org#35.
Edited by James Valleroy