-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
AsciiDoc (or alternatives) instead of Markdown? #38
Comments
How about restructured text? Standard for sphinx and much more versatile than markdown. |
Could also be considered, indeed. |
Also for me reStructuredText is better suited for the kind of documents that you plan to manage |
Could you elaborate a bit on the reasons to make us understand why it might be a better choice over AsciiDoc? 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. |
Yes, as you saythe To clarify, I was meaning that reStructuredText is better suited than markdown in this case. ReStructuredText, especially with Sphinx extension, is very powerful and supports very well complicit documents structure and cross-referencing. |
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.) |
Same as Antonio, very happy user of RST/Sphinx, don't know AsciiDoc. |
I have no big experience in generating docx document for rst/sphinx. Just for my information, does asciidoc have better capabilities to convert to docx? |
Not sure, that's something we need to evaluate, but Pandoc worked quite well to convert from Markdown to Word. |
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. |
from Siri Jodha Khalsa (via email):
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. |
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 #28 (comment)
The text was updated successfully, but these errors were encountered: