search

ceos-org / ceos-ard

Repository for CEOS Analysis Ready Data (CEOS-ARD), including Product Family Specifications (PFSs)
9 stars 0 forks source link

AsciiDoc (or alternatives) instead of Markdown? #38

Open m-mohr opened 1 week ago

m-mohr commented 1 week ago

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 commented 1 week ago

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

m-mohr commented 1 week ago

Could also be considered, indeed.

avalentino commented 6 days ago

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

m-mohr commented 6 days ago

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 commented 6 days ago

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 commented 6 days ago

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 commented 6 days ago

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

avalentino commented 5 days ago

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 commented 5 days ago

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

johntruckenbrodt commented 4 days ago

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.