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" <pavlos.paris...@gmail.com>
To: "Nick Ramirez" <nrami...@haproxy.com>
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
<http://>
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
