Hello all,
I'd like to propose something radical, but that will greatly help us in
terms of documentation. (And documentation is very important when it
comes to people choosing whether to use a piece of software, as I am
sure you agree!)
First, the problem: Our documentation at
https://github.com/haproxy/haproxy/blob/master/doc/configuration.txt is
written using a sort of home-grown syntax that uses various conventions
for indicating sections, keywords, etc.
However, parsing this home-grown documentation is difficult. For
example, I contribute to the HAProxy Syntax Support for Atom project
(https://github.com/abulimov/atom-language-haproxy). This is a python
program that must parse the HAProxy configuration.txt file and find the
keywords by first finding specific section titles, then looking for
lines that don't have spaces in front of them. That's how we find the
keywords in each section. It must be updated when new versions of
HAProxy are released because new sections are added and the section
numbers may change, and some sections are not reliably using the
home-grown syntax. In short, parsing configuration.txt is difficult,
error-prone and requires regular maintenance because its syntax is:
* Not a standard
* Not used consistently throughout the document
* Not easily parsed by existing tools (home-grown tools must be created
and maintained)
You may wonder, why do we need to parse configuration.txt? The reasons
are:
* A text file without any styling is difficult to read, so we want to
add styling (e.g. convert it to HTML with CSS or offer a PDF download)
* We want search functionality of the document and an auto-generated
table of contents
* We want to write haproxy.cfg files and have them displayed in
syntax-highlighted color when using Github Gist or any modern text
editor (Atom, VS Code, Sublime Text, etc.). For that, we must currently
parse configuration.txt to learn the keywords (as in the
atom-language-haproxy project mentioned). For example, we use Github
Gist, with the atom-language-haproxy project, to display HAProxy
configuration snippets in color on the haproxy.com/blog. It would be
easier to maintain this if we could parse configuration.text more
easily.
The solution I am proposing:
Rather than using a home-grown, difficult to parse,
not-consistently-used grammar. We should use a standard. We should use
reStructuredText: http://docutils.sourceforge.net/rst.html
<http://>
The reStructuredText syntax gives us the following benefits:
* It is well documented
* Tools exist to parse this and convert it to other formats (such as
HTML)
* Tools exist that will "error check" the document to ensure that the
correct syntax is used throughout configuration.txt (which would become
configuration.rst)
* Tools such as Jekyll can easily parse reStructuredText and build
sophisticated, beautiful webpages that feature search functionality,
table-of-contents, images, graphs, links, etc. We could really start to
make the documentation shine!
* We won't have to worry about updating special tools because
reStructuredText syntax will allow us to reliably parse it forever
* reStructuredText is still easily human-readable using a terminal,
plain-text editor, etc.
I and others are fully willing to make the conversion to
reStructuredText, too. What do you all think?
Thanks,
Nick Ramirez
