Yes, either reStructuredText or Markdown would be okay. They both have a
very intuitive syntax, so newcomers would pick it up and become
productive with it quickly. It is quite easy to learn either one.
------ Original Message ------
From: "Aleksandar Lazic" <[email protected]>
To: "Nick Ramirez" <[email protected]>; "[email protected]"
<[email protected]>
Sent: 7/1/2019 12:05:15 PM
Subject: Re: The case for changing the documentation syntax
Hi Nick.
Am 01.07.2019 um 17:01 schrieb Nick Ramirez:
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!)
Full Ack. This discussion comes up from time to time and I agree with you that a
more mainstream format would be nice.
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?
I would prefer Markdown with pandoc as I don't like the rst format, but I'm fine
with what the community and contributes decides.
Thanks,
Nick Ramirez
Regards
Aleks
