File:  [NetBSD Developer Wiki] / wikisrc / projects / project / convert-docs-to-asciidoc.mdwn
Revision 1.1: download - view: text, annotated - select for diffs
Fri Jul 16 09:36:16 2021 UTC (2 years, 4 months ago) by wiki
Branches: MAIN
CVS tags: HEAD

[[!template id=project

title="Convert NetBSD documentation from DocBook to asciidoc"



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.

- [[]]
- [[]]
- [[]]

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

- [[]]
- [[]]

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.



CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb