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 <nrami...@haproxy.com> 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" <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 > > >
