Support AsciiDoc

[fniu]

We use asciidoc a lot for various documents. I haven't seen the support of asciidoc on your roadmap. Do you have any plan for this? Thanks!

[stanislaw]

Hi @fniu,

Thanks for asking! It is the first time that I hear someone bringing up AsciiDoc. I have not considered implementing it before, and the Markdown support is on the roadmap with a very low priority.

A similar question about Markdown was asked by @villanella here: https://github.com/strictdoc-project/strictdoc/issues/1321. In my answer there, I outline what has to be done to implement the Markdown support, and the instructions should be pretty similar to AsciiDoc.

Here are some additions to my Markdown answer, and I should probably include them to a general FAQ about implementing a "format X in StrictDoc".

• As you know, StrictDoc SDoc format partitions a document into sections and requirements, and their fields can have multiline texts of RST markup (for example, the requirement statement). Note that parsing of all these fragments to HTML is done by StrictDoc separately for each fragment: first the SDoc parser parses the SDoc file into sections/requirements with their fields, and then the docutils is used to parse and convert each of those multiline fields with RST text individually into HTML. In order to enable parsing of asciidoc fragments, there has to be a Python pip package that would allow StrictDoc to do the same but for AsciiDoc. Let's put aside the question of how performant such a library is (the performance of docutils for RST is known to be one of StrictDoc's performance bottlenecks).

• Each such library generates its format into HTML format by probably adding custom CSS classes and its own HTML markup, which has to be CSS-stylized. This work has been nicely completed for RST by @mettta, but her time is also limited. I would expect that a format X should require its own CSS support to make the exported info look nice.

• The roadmap of StrictDoc is quite packed given that it is a spare-time project, so it is unlikely that I would start implementing the AsciiDoc support myself for just one interested user. At the same time, I can provide more detailed instructions on top of my Markdown answer linked above, and you could spend some time contributing this support yourself.

• The statement above should be taken with a grain of salt. Even if there is an initial proof of concept for Markdown or AsciiDoc, the full integration of either feature will require non-trivial work. A complete coverage of all edge cases specific to these formats will take a good chunk of time for both the contributor and me as the long-term maintainer of this software. If you take a closer look at just how many integration and UI tests were needed to stabilize the RST markup, you could guess that someone would have to do something similar for any other "format X". For example, the errors from the markup parser and converter have to be handled by StrictDoc gracefully.

• I would definitely invite you to consider how strong is your commitment to use StrictDoc in combination with AsciiDoc (or any other format X for that matter). In my other answer, I estimate 1–2 months of open source work if someone wanted to make StrictDoc support Markdown. It is hard to say how long things should take, but it is certainly far more than a "couple of evenings".

To summarize the above, I don't say No to AsciiDoc, but a good Yes would need a strong commitment from whoever wants to have it implemented in StrictDoc.

[fniu]

Thanks for the thorough response! Much food for thought.

[stanislaw]

@fniu @villanella, in case you do not have resources for implementing AsciiDoc/Markdown yourself, I could think of an intermediate compromise solution which may work or not, depending on your use cases.

For both of these formats, StrictDoc could simply implement export functions so that the SDoc/RST content could be exported/converted to AsciiDoc/Markdown. One would still have to work inside StrictDoc files and use its default RST markup, but the SDoc/RST content could be exported as AsciiDoc/Markdown and be integrated to whatever target documentation environments you maintain. For this task, the good RST to Markdown and RST to AsciiDoc Python/Pip converters would have to be found.

[villanella]

@stanislaw I usually convert markdown <-> RST by Pandoc converter. It also works with AsciiDoc.

Export .sdoc to .md and to AsciiDос is good idea. Titles and statements/freetext I think could be converted easy.

If we have to convert grammar fields, we can use yaml frontmatter or xml in case of markdown. For example, Writerside (IntellijIdea new plugin) uses xml injections in markdown to define meta-information.

[stanislaw]

@fniu some follow-up thoughts on AsciiDoc. In the comment above, @villanella literally means replacing SDoc with AsciiDoc or Markdown completely.

One intermediate option would be: keep the SDoc files but inside the text blocks (i.e., FREETEXT or STATEMENT) write AsciiDoc instead of RST. Then a converter to AsciiDoc would generate all SDoc contents as AsciiDoc contents pretty much the same like the existing RSTWriter does it. The same could be arranged easier for Markdown if that was needed. Is this something that you asked for or you wanted a complete replacement of SDoc like the comment above by @villanella means it?

[fniu]

Both options are valuable to me. I am familiar with AsciiDoc syntax so being able to write that inside text blocks are certanly nice to me. In the meantime, we also want to covert the entire SDoc documents to AsciiDoc because we have our own compiler to produce PDF (still via pdflatex but with many customizations on format and style). Currently I am experimenting with the solution using pandoc: SDoc -> .rst --pandoc--> .adoc -> .pdf.