Our options should be in monospace since they're thing that people will
type at the command line. Convert all of our AsciiDoc files with the
following one-liner:
ruby -pi -e '$_.gsub!(/^(-[-A-Za-z][^:]*)::$/, "`\\1`::")' *.adoc
While Asciidoctor will accept inconsistent indentation for our
definition lists, this makes it hard to read in the plain text format.
Since the text we embed in the manual pages is the source, it would be
nice to have a consistent indentation for ease of reading by users.
Therefore, indent each of our definition lists such they are properly
indented to two spaces.
For some items which should have been definition lists, but, due to
syntactic anomalies, didn't get converted, convert those to definition
lists and properly indent them as well.
Because Markdown lacks description lists, ronn converts bulleted lists
with options in them into an appropriate entry in the manual page.
However, AsciiDoc has description lists, so let's convert the values we
got from the ronn source to actual description lists.
Do this with the following one-liner:
ruby -pi -e '$_.gsub!(/^\* `(-.*)`\s+`(-.*)`(.*):(.*)$/, "\\1::\n\\2\\3::\n \\4")' \
-e '$_.gsub!(/^\* `(-.*)`(.*):$/, "\\1\\2::")' \
-e '$_.gsub!(/^\* `(-.*)`(.*):\s+(.*)$/, "\\1\\2::\n \\3")' \
-e '$_.gsub!(/^\* (-.*):$/, "\\1\\2::")' \
-e '$_.gsub!(/^\* (-.*):\s+(.*)$/, "\\1::\n \\2")' *.adoc
When pandoc did our conversion to AsciiDoc, it was not aware that we
were working with manual pages. Automatic handling of manual pages with
Asciidoctor requires that the title of the manual page be a top-level,
not a second-level, title, and that the name section be explicitly
specified.
Let's fix our manual pages to meet that standard automatically with the
following shell command. This has the pleasant side effect of also
normalizing whether we use one or two dashes between the name and the
description to a single dash, which is what the Git manual pages use.
ruby -pi -e '$_.gsub!(/^(=+)=( \S)/, "\\1\\2")' \
-e '$_.gsub!(/^= (\S+)(\(\d\)) -+ (.*)$/, "= \\1\\2\n\n== NAME\n\n\\1 - \\3")' \
*.adoc
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".
