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" <al-hapr...@none.at>
To: "Nick Ramirez" <nrami...@haproxy.com>; "haproxy@formilux.org" <haproxy@formilux.org>
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


Reply via email to