Re[2]: The case for changing the documentation syntax
It sounds like restructuredText and Asciidoc are the top choices. They both look capable: http://hyperpolyglot.org/lightweight-markup I can, as a next step, post this as an Issue on the Github project and it can be triaged and tracked. For something like this, it might even make sense to create a new branch so that multiple people can work on it. In that case, splitting the documentation into multiple files would be helpful too. If approved, an empty file for each section of the documentation could be created in order to have the skeleton of the project. Having the documentation split into multiple files may make maintaining the documentation easier in the future too (i.e. someone could change one section without conflicting with a person making a change in another section). How have collaborative efforts like this been done in the past? How would multiple people be able to commit changes to this branch? Other thoughts? -- Original Message -- From: "Pavlos Parissis" To: "Nick Ramirez" Sent: 7/3/2019 10:44:11 AM Subject: Re: The case for changing the documentation syntax On Δευτέρα, 1 Ιουλίου 2019 5:01:33 Μ.Μ. CEST Nick Ramirez wrote: Hello all, [...snip...] 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? +1 from me. asciidoctor is something you should have a look at and consider as well. I know that people don't like markdown, but it is very simple to use and that is, sometimes, more important than standards and etc. My cents, Pavlos
Re: The case for changing the documentation syntax
Hi. Am 02.07.2019 um 20:29 schrieb Hugues Alary: > And for comparison's sake, here's Asciidoc renders on github: > https://github.com/asciidoctor/asciidoctor/blob/master/README.adoc > > Other features of the asciidoc/asciidoctor ecosystem are: > - Asciidoc is also standardized > - https://antora.org/ allows you to build 1 documentation website, from > multiple > documentation repositories. > - asciidoctor is extendable, either by writing an extension in Javascript > (https://asciidoctor-docs.netlify.com/asciidoctor.js/extend/extensions/register/) > or > in Ruby (https://asciidoctor.org/docs/user-manual/#example-extensions) and it > supports custom backends > > Though I have no skin in the game. ReStructuredText is great, I'm merely > presenting other options. I have used asciidoctor for some projects, my reason to switch to pandoc markdown was hat the pdf output of asciidoctor isn't very good especially when you come to footmarks and bibliography. Even though I don't like reStructuredText I vote for them as I think it fits more into the haproxy workflows, AFAIK. Jm2c Regards Aleks > On Tue, Jul 2, 2019 at 9:05 AM Nick Ramirez <mailto:nrami...@haproxy.com>> 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. > > https://gist.github.com/ionelmc/e876b73e2001acd2140f > > > -- Original Message -- > From: "Lukas Tribus" mailto:li...@ltri.eu>> > To: "Nick Ramirez" mailto:nrami...@haproxy.com>> > Cc: "haproxy@formilux.org <mailto:haproxy@formilux.org>" > mailto:haproxy@formilux.org>>; "Cyril" > mailto:cyril.bo...@free.fr>> > 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 > <mailto:nrami...@haproxy.com>> 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 >>> 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 >>> configur
Re: Re[2]: The case for changing the documentation syntax
And for comparison's sake, here's Asciidoc renders on github: https://github.com/asciidoctor/asciidoctor/blob/master/README.adoc Other features of the asciidoc/asciidoctor ecosystem are: - Asciidoc is also standardized - https://antora.org/ allows you to build 1 documentation website, from multiple documentation repositories. - asciidoctor is extendable, either by writing an extension in Javascript ( https://asciidoctor-docs.netlify.com/asciidoctor.js/extend/extensions/register/) or in Ruby (https://asciidoctor.org/docs/user-manual/#example-extensions) 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. > > https://gist.github.com/ionelmc/e876b73e2001acd2140f > > > -- Original Message -- > From: "Lukas Tribus" > To: "Nick Ramirez" > Cc: "haproxy@formilux.org" ; "Cyril" < > cyril.bo...@free.fr> > 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 > 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. > > > > 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: > > https://www.mail-archive.com/haproxy@formilux.org/msg07040.html > https://github.com/cbonte/haproxy-dconv > https://cbonte.github.io/haproxy-dconv/ > > > 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 pur
Re[2]: The case for changing the documentation syntax
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. https://gist.github.com/ionelmc/e876b73e2001acd2140f -- Original Message -- From: "Lukas Tribus" To: "Nick Ramirez" Cc: "haproxy@formilux.org" ; "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 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. 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: https://www.mail-archive.com/haproxy@formilux.org/msg07040.html https://github.com/cbonte/haproxy-dconv https://cbonte.github.io/haproxy-dconv/ 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
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 > 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. 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: https://www.mail-archive.com/haproxy@formilux.org/msg07040.html https://github.com/cbonte/haproxy-dconv https://cbonte.github.io/haproxy-dconv/ 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
Re: Re[2]: The case for changing the documentation syntax
Adding my 2 cents here: I write documentation a lot and would like to mention the Asciidoc format, and more specifically asciidoctor ( https://asciidoctor.org/). Asciidoc is a _very_ powerful syntax yet extremely simple to use. Here's a link to their cheat sheet to give you a quick idea of the syntax: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ And a more in depth manual: https://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor On Mon, Jul 1, 2019 at 1:51 PM Nick Ramirez wrote: > 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" > To: "Nick Ramirez" ; "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 an
Re[2]: The case for changing the documentation syntax
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" To: "Nick Ramirez" ; "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
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
The case for changing the documentation syntax
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 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? Thanks, Nick Ramirez
