Scientific Publishing: Feedback from Using Quarto to Publish a Paper

[alping]

Hi!

I do medical/epidemiological research and I've been using markdown and Pandoc for a long time to write my manuscripts. I've been keeping an eye on RMarkdown, Sweave, Knitr, Pweave and similar projects, and was very excited to recently discover Quarto. It's a fantastic project and I'm happy to see that it's being actively developed (thank you!). I'm trying out Quarto for writing my current manuscript and want to contribute some feedback that I hope can make Quarto even better.

I've put together a sample project which demonstrates most of the things I discuss here:

• https://gitlab.com/alping/quarto-test
• https://alping.gitlab.io/quarto-test/

Enhancements

1. It would be great to be able to include tables from separate files (markdown or csv) in the same way we can do for figures. It almost works using the include lua filter, but the table is not recognized to be cross-referenced, see sample repo. (I usually output MD/CSV tables from scripts which allows me to not have to manually change them every time the numbers change).
2. Specify capitalization of Figure/figure and Table/table on a per reference basis, e.g. @Fig-main > Figure 1.1 and @fig-main > figure 1.1. Or @fig-main would give the default, @^fig-main > Figure 1.1, and @_fig-main > figure 1.1, or something similar.
3. A way to specify Supplementary Figures/Tables instead of a "hacky" solution involving chapters and crossref: chapters: true (see sample repo), so that we can get Supplementary Figure 1 (with it's own counter separate from the main figures/tables). (This is used a lot in my field).
4. Table/Figure headers separate from table/figure text, possibly in bold font. E.g:

   Figure 1: Survival Function
   Survival function for entire population using...

5. Variables in inline text. E.g. We identified {pop_size} patients... > "We identified 3026 patients...". To avoid manually having to change these every time the numbers change. Variables could be read from a YAML or JSON file.
6. Make some parts only visible for specific render formats:

   ::: {.docx}
   This only shows up in .docx renders.
   :::
   

7. Make HTML preview remember the scroll location on reload. Now every time the page is changed and updated it jumps to the top, which makes it difficult to work on a specific section.

Issues

1. Refs positioning not working for HTML, but for .docx. In HTML, references always show up at the end of the document.

   ::: {#refs}
   :::
   

2. No top margin for H1 in HTML render (weird spacing for chapters)
3. Printing HTML output causes cut text in page breaks in many cases, similar to what is shown here: https://stackoverflow.com/questions/55990473/htmlcss-page-breaks-cutting-text-characters-in-half-media-print

Again, fantastic project and thank you for your work.
- Peter

[jjallaire]

Thanks for all of this feedback! Wanted to let you know that we aren't leaving this unattended -- hope to reply w/ thoughts/feedback/workaround later on this week.

[alping]

Sounds great! Take your time.

[jjallaire]

Thanks for the feedback! I'll try to address each of these points below.

Enhancements:

#1 external tables we've discussed here and have a potential workaround based on using R or Python cells to read the table: #639

#2 capitalization per reference. As described here (https://quarto.org/docs/authoring/cross-references.html#references) this would work if you change the default capitalization to lower case and then use a capital letter in the reference (e.g. @Fig-foobar)

#3 Separate counters for e.g. supplemental tables we don't have right now. I've noted that LaTeX does have flexible resetting of counters so this is definitely something we could support. Issue filed here: #644

#4 Another good idea. Issue here: #645

#5 This is possible now using shortcodes/variables: https://quarto.org/docs/authoring/shortcodes-and-filters.html#shortcodes

#6 Issue here: #646

#7 HTML preview remembering its scroll position. This is definitely how it should work (and in all my testing it does work correctly). Perhaps something specific to your browser/os? LMK what you config is and I'll see if I can repro it not working. Also perhaps something related to the document itself so LMK what document(s) you see this behavior with.

Issues:

#1 By default we relocate the bibliography to an appendix with special formatting. You can specify appendix-style: none to prevent this (see https://quarto.org/docs/authoring/appendices.html#appendix-style)

#2 Fixed here: 6a8c5c6

#3: We unfortunately don't currently provide a print stylesheet that would address this and other print specific concerns. We will eventually do this but would certainly welcome a PR in the meantime!

[alping]

Thank you for the thorough reply! I guess I should have read the documentation more carefully, sorry about that.

• I'll start using your suggestions for #1.2, #1.5, and #2.1, and see if I can figure out what's wrong with my setup for #7 once I'm back at work. I'm especially excited for #1.5, I can't believe I missed that!
• Looking forward to future developments for #1.1, #1.3, #1.4, #1.6, and #2.3. Especially a way to reset the fig/table counters would be awesome!

I'm not too knowledgeable about CSS for printing, but if I get the time to look into it I'll see what I can do.
Otherwise I can keep giving feedback from my process of using Quarto to prepare my paper if that is useful.

Again, thank you for your work on this!

[jjallaire]

Thanks for all the feedback!

[mcanouil]

I believe this to be almost if not all completed.
If note, feel free to open a new feature request dedicated to the missing feature.