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