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 <nrami...@haproxy.com
> <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" <li...@ltri.eu <mailto:li...@ltri.eu>>
>     To: "Nick Ramirez" <nrami...@haproxy.com <mailto:nrami...@haproxy.com>>
>     Cc: "haproxy@formilux.org <mailto:haproxy@formilux.org>"
>     <haproxy@formilux.org <mailto:haproxy@formilux.org>>; "Cyril"
>     <cyril.bo...@free.fr <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 <nrami...@haproxy.com
>>     <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
>>>     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 <http://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
> 


Reply via email to