I found this page on Github. It uses reStructuredText and demonstrates how Github would render various elements out of the box. Of course, it can be made more visually appealing with other tools, but it's a free benefit that it renders on Github.


------ Original Message ------
From: "Lukas Tribus" <li...@ltri.eu>
To: "Nick Ramirez" <nrami...@haproxy.com>
Cc: "haproxy@formilux.org" <haproxy@formilux.org>; "Cyril" <cyril.bo...@free.fr>
Sent: 7/1/2019 6:49:50 PM
Subject: Re: The case for changing the documentation syntax

Hello Nick,

On Mon, 1 Jul 2019 at 17:02, Nick Ramirez <nrami...@haproxy.com> wrote:

 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 

 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 
 * 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.

Actually since 7 years we do 2 of the 3 things you mention here;
documentation.txt and others are parsed automatically (in python) and
generate a verify nice HTML site, searchable and indexed with table of
contents, etc:


We use this extensively and are able to point people to specific
sections or keywords of the documentation. When the documentation is
inconsistent and breaks the tool, we (or more specifically Cyril)
fixes it. I don't see any 2.0 specific changes in haproxy-dconv, and
I'm not sure if a structured text would fix all the issues you have
with the atom project.

I'm not saying we should maintain configuration.txt as it currently
is, but to me the status-quo does not feel as dire as you suggested.

haproxy-dconv also mentions:

 The purpose of this project is to ultimately convert the HAProxy documentation 
into a more generic format (example : ReStructuredText) that would allow for an 
easier spreading of various output files (.pdf, .html, .epub, etc).

So it seems like there is common ground. I'm CCing Cyril who has
invested a lot of time for this already.

I think I agree that we would benefit from moving towards a
standardized, structured text.

Regarding markdown vs reStructuredText vs asciidoc, I don't have a lot
of experience with either of those, but if we go down this road I feel
like we should pick a format that is here to stay and is standardized,
and for me, that is reStructuredText. Markdown is probably the worst
possible choice and I know first hand how the lack of standardization
negatively affects it's interoperability (specifically a site had a JS
based preview that looked different than when the server-side code
parsed it after the submission ... so I have a strong negative opinion
about Markdown).

Readthedocs supports reStructuredText (and discourages but supports
markdown), however asciidoc is not supported. Not that we need to use
readthedocs, but it's something to keep in mind.


Reply via email to