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

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?

Nick Ramirez

Reply via email to