AsciiDoc (or alternatives) instead of Markdown?

[m-mohr]

I'm running into more and more issues with Markdown. The Markdown syntax is too simple or what we are trying to achieve here, especially with vasts amounts of tables.

We could consider using AsciiDoc or other similar alternatives instead. It would also support includes, which allows re-use of commonly used elements.

Generally, I wonder whether the tabular approach is good or whether an approach based on headings and normal paragraphs would be better for such a specification.

Originally posted by @m-mohr in https://github.com/ceos-org/ceos-ard/issues/28#issuecomment-2194242896

[johntruckenbrodt]

How about restructured text? Standard for sphinx and much more versatile than markdown.

[m-mohr]

Could also be considered, indeed.

[avalentino]

Also for me reStructuredText is better suited for the kind of documents that you plan to manage

[m-mohr]

Could you elaborate a bit on the reasons to make us understand why it might be a better choice over AsciiDoc? I don't have experience with any of them but they look very similar to me at first glance. So it would be good to collect some pros and cons here for an informed decision.

I find the file includes from AsciiDoc very appealing to avoid duplication, which seems to heavily appear on the files and as such would allow us to heavily decrease the maintanance work and move us closer to a biuilding block approach. Edit: It seems restructuredText can also do it... https://docutils.sourceforge.io/docs/ref/rst/directives.html#toc-entry-38

[avalentino]

Yes, as you saythe include directive is also available in reStructuredText.

To clarify, I was meaning that reStructuredText is better suited than markdown in this case. I do not know AsciiDoc, sorry.

ReStructuredText, especially with Sphinx extension, is very powerful and supports very well complicit documents structure and cross-referencing. Both the HTML output and the PDF are very good and can be highly customized (a large amount of HTML themes is available). The tooling, Sphinx mostly, is very powerful and several extensions are available for different purposes.

[m-mohr]

Thanks.

(Just a note here: I believe we also still need Word/docx files for users to fill unless we generate separate documents for self-assessment and specification.)

[johntruckenbrodt]

Same as Antonio, very happy user of RST/Sphinx, don't know AsciiDoc.

[avalentino]

I have no big experience in generating docx document for rst/sphinx. Searching with google the first hits are https://github.com/mherkazandjian/docxsphinx, https://github.com/amedama41/docxbuilder and a couple of indirect ways using rst2otd (docutils) and/or pandoc. I guess that there is also a possibility to make an indirect conversion via LaTeX but I never did it.

Just for my information, does asciidoc have better capabilities to convert to docx?

[m-mohr]

Not sure, that's something we need to evaluate, but Pandoc worked quite well to convert from Markdown to Word.

[johntruckenbrodt]

According to the pandoc website, pandoc is capable of conversion from and to reStructuredText and docx respectively. AsciiDoc can only be converted to but not from.

[m-mohr]

from Siri Jodha Khalsa (via email):

I just want to point out that some IEEE standards projects use metanorma to write their drafts, there being an IEEE-SA document model. Metanorma is based on AsciiDoc, which is similar to markdown (comparison), all of which are amenable to version control in github. CEOS could create a custom stylesheet for the PFSs. See https://www.metanorma.org/develop/topics/simple-adoption/

I know metanorma from OGC work and the ecosystem to be pretty complex to use in my experience. But also not much worse than pandoc, so I guess it's worth considering it. We had proposed AsciiDoc above anyway.

If we start with metanorma it may have the advantage that OGC is also using it and a switch to OGC/ISO later may be a little simpler.