[[!template id=project

title="Convert NetBSD documentation from DocBook to asciidoc"

contact="""
[nia](mailto:nia@NetBSD.org)
[netbsd-docs](mailto:netbsd-docs@NetBSD.org)
"""

category="misc"
difficulty="medium"
description="""

NetBSD has large amounts of documentation in XML DocBook: the Guide, the pkgsrc Guide, large parts of the website.

asciidoc is a much nicer, friendlier format than XML. It preserves the same advantages as DocBook: easy conversion to PDF and other formats for book distribution, and rich semantics.

- [[https://en.wikipedia.org/wiki/AsciiDoc]]
- [[https://asciidoctor.org/docs/asciidoc-writers-guide/]]
- [[https://asciidoc.org/]]

There is a tool for converting DocBook to asciidoc, but it is likely not perfect, and output will require manual adjustment:

- [[https://github.com/asciidoctor/docbookrx]]
- [[https://pandoc.org/MANUAL.html]]

asciidoc itself can also output DocBook. We might leverage this so we can convert the website step-by-step, and keep the existing templates.

This project will require careful adjustment of build systems in the htdocs repository and those used by the pkgsrc guide.

A working proposal should demonstrate _one_ page (of the website, pkgsrc guide, or NetBSD guide), converted to asciidoc and hooked up to the build system, integrated, with reasonable looking output.

"""

]]