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
