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 <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" <li...@ltri.eu> > To: "Nick Ramirez" <nrami...@haproxy.com> > Cc: "haproxy@formilux.org" <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 <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 > 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 > >
