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:


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.


Reply via email to