And for comparison's sake, here's Asciidoc renders on github:

Other features of the asciidoc/asciidoctor ecosystem are:
- Asciidoc is also standardized
- allows you to build 1 documentation website, from
multiple documentation repositories.
- asciidoctor is extendable, either by writing an extension in Javascript (
or in Ruby (
and it supports custom backends

Though I have no skin in the game. ReStructuredText is great, I'm merely
presenting other options.

On Tue, Jul 2, 2019 at 9:05 AM Nick Ramirez <> wrote:

> 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" <>
> To: "Nick Ramirez" <>
> Cc: "" <>; "Cyril" <
> 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 <> 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
> 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 (
> 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 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.
> cheers,
> lukas

Reply via email to