{{ message }}
Repository navigation
Commit 0c66dcf
committed
Add AsciiDoc versions of our manual pages
Our current manual pages use ronn or ronn-ng, which converts pages from
a superset of Markdown into manual pages or HTML. This mostly works,
but it has some limitations:
* ronn-ng requires several dependencies, some of which are C based,
which means we must build those on older version of RHEL-compatible
OSes. This adds a substantial amount of porting hassle and time to
the build.
* The superset of Markdown that ronn-ng uses is not rendered correctly
on GitHub, leading to difficulties when people view manual pages in
the web interface.
* Markdown, and the superset ronn-ng uses, don't contain description
lists, which are useful for both command options and items in the FAQ,
which we'd like to ship in the package.
Instead of using Markdown, let's switch to AsciiDoc as the format for
manual pages. Asciidoctor, the Ruby version of the command, is written
in pure Ruby and is self-contained, and supports HTML 5, XHTML 5, man,
and DocBook 5 all in a single program. In addition, it is the library
used for rendering AsciiDoc on GitHub, which means that whatever syntax
we use is fully supported and should render properly.
This commit introduces a simple conversion as the first step, which
we'll fix up in several subsequent commits. The Markdown pages remain
for now and will be removed in a later commit.
This conversion was done using Debian's pandoc 2.9.2.1-3+b2 using the
following command:
(for i in *.ronn; do pandoc -f commonmark -t asciidoc -o $(basename $(basename $i .1.ronn) .5.ronn).adoc $i; done)
Note that during our conversion we remove the number in the manual page
name, since Asciidoctor will emit this automatically and we don't want a
trailing ".1.1" or ".5.5".1 parent 5521dc1 commit 0c66dcf
34 files changed
Lines changed: 2321 additions & 0 deletions
File tree
- docs/man
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |

0 commit comments