Quarto should incorporate Asciidoc rendering facilities

[aksigkvgithub]

Bug description

Quarto is a far bigger platform than R markdown. But, this is limited to only rendering markdown or its flavours with R or the like code sequences only.

Asciidoc is simpler and has only one flavour with distinct features for writings very good books, articles and what not?

Therefore, I request its developer's to incorporate rendering facilities for Asciidoc documents to be written in Asciidoc quarto.

First, I raised this issue at RStudio.com community forum. But, andresrcs (the Sustainer) suggested me to raise Quarto related issues at this forum.

So, I would like to clarify it further that Quarto does provide one format option of "Asciidoc". But, that feature, in fact converts the document written in Quarto Markdown (Pandoc Markdown) to Asciidoc format with asciidoc codes, which should be rendered elsewhere. And what I mean is that the input file of quarto document should contain asciidoc codes, which can be rendered by Quarto to an output file, not with asciidoc codes, but a file rendered into html, pdf or docx.

To be more clear, what I am expecting from Quarto is that we should be able to write the document, along with R scripts in RStudio in .asciidoc (or .adoc) codes, instead of Rmarkdown or Markdown, which could be rendered to html, pdf, docx or docbook.

Wishing all the best hopefully,

Dr. A.K Singh

Checklist

• [ ] Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• [ ] Please format your issue so it is easier for us to read the bug report.
• [ ] Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• [ ] Please document the operating system you're running. If on Linux, please provide the specific distribution.

[cscheid]

There are a number of features of Quarto that are designed very specifically to only work with Markdown, and that will not change in the foreseeable future. With that said, if you choose to your asciidoc as input, you could take advantage of pre-render scripts to convert from asciidoc to markdown (using, for example, quarto pandoc, which will run the version of pandoc that's bundled with quarto), and then run quarto on the resulting markdown.

[aksigkvgithub]

Thanks for answering. However, I am a beginner at quarto. Can you please tell me the commands/scripts for pre-rendering Asciidoc documents to markdown using Quarto pandoc.

Dr A. K. Singh

On Wed, 18 Jan, 2023, 8:53 pm Carlos Scheidegger, @.***> wrote:

There are a number of features of Quarto that are designed very specifically to only work with Markdown, and that will not change in the foreseeable future. With that said, if you choose to your asciidoc as input, you could take advantage of pre-render scripts to convert from asciidoc to markdown (using, for example, quarto pandoc, which will run the version of pandoc that's bundled with quarto), and then run quarto on the resulting markdown.

— Reply to this email directly, view it on GitHub https://github.com/quarto-dev/quarto-cli/issues/4003#issuecomment-1387247828, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIKTCDQQUY7ZF2P5XWUBUADWTADG3ANCNFSM6AAAAAAT7CH3ZM . You are receiving this because you authored the thread.Message ID: @.***>

[cderv]

However, I am a beginner at quarto. Can you please tell me the commands/scripts for pre-rendering Asciidoc documents to markdown using Quarto pandoc.

quarto pandoc is a command in the Quarto CLI to be able to use the pandoc binary used by Quarto directly.

Regarding how to use Pandoc itself, you can look at its documenation: https://pandoc.org/MANUAL.html

However, regarding previous answer, asciidoc is only available as a output format and unfortunately not as an input format in pandoc - Feature request is there: https://github.com/jgm/pandoc/issues/1456

So for now, you cannot use Quarto or Pandoc with Asciidoc as input.

[cscheid]

@cderv Thank you for correcting me, I hadn't realized pandoc didn't support asciidoc.

With that said, here's a page describing a pipeline to convert asciidoc to markdown: https://alvinalexander.com/bookmarks/how-convert-asciidoc-to-html-or-markdown/

[cderv]

Nice finding this blog post ! Thanks for sharing !

[jkcv]

Imagine purchasing a printer that only printed ascii text and you wanted to format your document with bold, italics and underline using LibreOffice. So you write to the manufacturer, who replies, "No problem, compose your document in LibreOffice, export it to ascii and voila! Now you can print it on our printer."

You scratch your head, thinking, "Ascii text does not include bold, italic and underline."

So, why is it a good suggestion to say "Just convert your asciidoc to markdown?" The reason to use asciidoc is because it can do a whole lot more formatting than markdown.

That said, what is this page about? https://quarto.org/docs/reference/formats/asciidoc.html

[jkcv]

Am I missing something?

[dragonstyle]

We have great rendering asciidoc facilities at this point, but we definitely currently see that as an output format rather than an input format. I did quite a bit of work on our asciidoc output support so am generally familiar with asciidoc, but I am not sure exactly what you mean when you say that asciidoc can do a whole lot more formatting that markdown (especially when comparing to Quarto markdown which supports a lot of additions to base markdown).

Can you share some example of what you're thinking of- even if we don't end up supporting asciidoc input, we may want to pursue supporting native Quarto support for those formatting features.

[jkcv]

Thanks for your quick reply.

First, I would like to say that I am very pleased to find your project because it looks to be a major upgrade to Rmarkdown. Congratulations on what I imagine is a lot of hard work that you and your colleagues put in.

Since I am new to Quarto, I am perhaps really reacting to Rmarkdown, which I have abandoned in favor of Rasciidoc. Unfortunately, the Rasciidoc project does not have a lot of support and the last time I upgraded R/Rstudio, I was warned that the upgrade was not compatible with Rasciidoc. I had to use a non-Cran method to reinstall Rasciidoc. So, when I heard about Quarto, my hope was that it had incorporated the advances of Rasciidoc, but with robust support. When I heard that Quarto supported asciidoc, I was excited, until I learned that it was only on the output side. I think the issue is that Quarto is based on pandoc, which has shunned Asciidoc on the input side.

Here is a link to a comparison between the two languages. This page expresses my preference for Asciidoc (asciidoctor) as an input language better than I can.

https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

In looking at this and other comparisons, I see that Markdown has matured. For example, I see now you can do footnotes in some flavors of Markdown. That was a major stumbling block for me. Yet still, the fragmentation between the flavors troubles me. I want to learn one language, not multiple variations of the same language, never knowing which one will work in each context. That is why years ago, I looked at all of these languages and settled on Asciidoc (Asciidoctor) as the most mature in terms of features, with active development and community and extensions built on the base. You don't have the Markdown problem of always keeping in mind that in this context (flavor of Markdown) you can do this and in another context, you can do that.

So, why don't I use both? Learning Asciidoctor and Markdown and its dialects is like learning Spanish and Italian. Unless you are really good at languages, you can get confused. Perhaps Markdown itself is like learning Bantu languages in Africa. There are lots of similarities, but lots of differences from one community to the next. In English, all that I have to remember is to "get on line" here but to "queue up" on the other side of the pond.

On a completely other issue, I had a serious problem with Quarto and had to uninstall it. There is a major memory leak. I normally use 10 - 12 Gi of my 62 Gi RAM + 19 Gi Swap. With Quarto installed, my computer crashed frequently. I discovered that all 81 Gi of memory were used. I uninstalled Quarto and my computer is fine now. I am using the Pop!_OS 22.04 LTS flavor of debian, which is closest to the Jammy version of Ubuntu. I am running on a System76 Gazelle model gaze16-3050. In case it matters, I was running in hybrid mode using the Intel-based video (TigerLake-H GT1) and the Nvidia (GeForce RTX 3050 Ti Mobile). I did not try it in pure Intel or Pure Nvidia modes.

I am sure you will resolve the memory issue and sincerely hope that you allow authors to write in asciidoc. I am not a programmer, but I imagine incorporating an open-source code base is doable. I have come across several projects, which allow multiple input languages, including asciidoc.

Cheers!

[aksigkvgithub]

Dear JCKV,

Thank you very much for understanding what I really wanted to say to Quarto team. I would like to add further.

1. They released Quarto with the intent to make it more robust and more inclusive compared to Rmarkdown.

2. If Rmarkdown deprecated Rasciidoc, then that is understandable because markdown was its base language and not asciidoc.

3. But, what about Quarto? Is it not duplicating the Rmarkdown itself in a more robust manner, based on the same markdown. Then, what is the greater advantage of shifting to Quarto???. What not to confine to Rmarkdown only because it is for those who have less requirement of features for documentation.

4. Quarto should note that there are many users out there, whose requirements are for really feature-rich documentation, which asciidoc has got immensly.

5. Moreover, Asciidoc (Asciidoctor) is very simple too, in its syntax, compared to markdown. And they produce very nice html, docbook, pdf format outputs too, one of which (docbook) markdown can not do.

6. However, I have one reservation with the Asciidoc, that it can not handle latex/asciimath based mathematical formulae well. They suggest a very cumbersome approach, which becomes near impossible for common users.

7. I started this thread only because I thought Quarto would be doing extraordinary in the sense that it will fulfill the discrepancies the Rmarkdown is suffering from.

8. However, Rmarkdown and Quarto both have a very good approach of rendering the output that the Asciidoctor is lacking completely. Rmarkdown and Quarto both process the documents through latex in between somewhere, which render mathematical formulae very nicely.

9. In rest of the matters, Asciidoc (Asciidoctor) is far ahead of the present Rmarkdown or Quarto.

10. One of my objectives to open this thread was to request the developers of Quarto to make it king of all document processors by including asciidoc as one of the input languages too. And this wish of mine is very well explained by JCKV.

11. Dear developers of Quarto, please recall any document processor other than latex, which is near perfect. But, latex is difficult to compose for common users. The other perfect one is Docbook, which is also very difficult to compose. Here, the Asciidoc(Asciidoctor) fits in very well, in the sense that (i) it has super rich features, which in areas beat latex too, (ii) it can produce docbook format too, which is very much in demand by publishers, (ii) it can produce epub format too, which is also in demand by publishers.

12. But, one thing where the Asciidoc(Asciidoctor) fares badly is in translating its latex based mathematical formulae. This is the place where Quarto can fit in very well, because its toolchain goes through latex processors.

13. If Quarto has to become feature rich too, then please incorporate Asciidoc(Asciidoctor) as one of the inpurt languages too, because your outputs are already great. And let the Rmarkdown excel well with markdown alone.

Thanks again to JCKV and to the Quarto team.

Dr. A.K. Singh Professor and Ex-Head (Agricultural Statistics) Department of Agricultural Statistics and Social Science (L) Indira Gandhi Krishi Vishwavidyalaya, Raipur-492 012, Chhattisgarh, India Mobile: +918770625795 Email: @.***

On Sun, Mar 19, 2023 at 12:15 AM jkcv @.***> wrote:

Imagine purchasing a printer that only printed ascii text and you wanted to format your document with bold, italics and underline using LibreOffice. So you write to the manufacturer, who replies, "No problem, compose your document in LibreOffice, export it to ascii and voila! Now you can print it on our printer."

You scratch your head, thinking, "Ascii text does not include bold, italic and underline."

So, why is it a good suggestion to say "Just convert your asciidoc to markdown?" The reason to use asciidoc is because it can do a whole lot more formatting than markdown.

That said, what is this page about? https://quarto.org/docs/reference/formats/asciidoc.html

— Reply to this email directly, view it on GitHub https://github.com/quarto-dev/quarto-cli/issues/4003#issuecomment-1474952473, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIKTCDUKLR2225BECPA65F3W4X7GFANCNFSM6AAAAAAT7CH3ZM . You are receiving this because you authored the thread.Message ID: @.***>

[aksigkvgithub]

Thank you Allen and Quarto Team for reopening and adding this feature as a future milestone.

Dr. A.K. Singh Professor and Ex-Head (Agricultural Statistics) Department of Agricultural Statistics and Social Science (L) Indira Gandhi Krishi Vishwavidyalaya, Raipur-492 012, Chhattisgarh, India Mobile: +918770625795 Email: @.***

On Mon, Mar 20, 2023 at 3:02 PM Allen Manning @.***> wrote:

Reopened #4003 https://github.com/quarto-dev/quarto-cli/issues/4003.

— Reply to this email directly, view it on GitHub https://github.com/quarto-dev/quarto-cli/issues/4003#event-8792171547, or unsubscribe https://github.com/notifications/unsubscribe-auth/AIKTCDRC3TO66AGT2FQTYULW5AP3JANCNFSM6AAAAAAT7CH3ZM . You are receiving this because you authored the thread.Message ID: @.***>

[rben01]

It would be interesting if ```{Asciidoctor} ... ``` blocks were a thing so that we could drop down into Asciidoctor just for a fragment here and there — for instance, I hate writing tables in markdown; Asciidoctor is much more natural. Then Quarto could render just those few blocks to html. The rest of the document would still be markdown.

[mcanouil]

@rben01 Use raw blocks

```{=LANGUAGE}
CODE

or `` `CODE`{=LANGUAGE} ``.

[cderv]

@rben01 can you clarify your idea? I am not sure if I got it right;

@mcanouil Using Raw block above is only if you are using format: asciidoc to target the output. It is not the same as Asciidoc rendering facilities.

My understanding, based on the context of this issue, is that you would like to be able to have some code cells be computed using asciidoctor rendering so that you can write a Table using asciidoc syntax. It would then be converted to HTML to be inserted into the document to render.

Example:

---
title: Test
format: html
---

```{asciidoctor}
#| echo: false
[width="15%"]
|=======
|1 |2 |A
|3 |4 |B
|5 |6 |C
|=======

Some content in bold using markdown syntax and other Quarto feature

Is that what you are suggesting? 

In addition to what has been discussed above, I think the best chance to have that working in the near feature would be to hack something around what Quarto can do and support. 

For example, there is **knitr** extension mechanism (with knitr's engine) and maybe some available feature/examples in R to render to asciidoc (like [**rasciidoc** package](https://cran.r-project.org/web/packages/rasciidoc/index.html) ). On Quarto side, there are extension mechanism and / or pre-render script with include that could also be an option maybe. 

Hope it helps

[mcanouil]

Oh I see. So the following could be of interest, i.e., there a Jupyter converter: https://github.com/neo4j-documentation/asciidoctor-jupyter. (I did not find a proper kernel though)

[rben01]

@rben01 can you clarify your idea? I am not sure if I got it right;

You got it exactly right.

[jmhimara]

I hate writing tables in markdown;

What editor are you using? Some editors have plugins that make writing markdown tables much much easier. I know emacs does.