Rendering output with a particular layout

Specificer et output layout
Author

Søren O’Neill & Steen Harsted

Published

December 30, 2024

Remind yourself of the way manuscripts are built using R code and MarkDown:

Figure 1: To Render output from a Quarto document, includes several separate processes.

Basically:

  • the knitr packages is used to
    • extract the R code from the .qmd Quarto document
    • execute that R code, and
    • replace the R code with the resulting output of it
  • this results in a clean MarkDown (‘md’ in the figure above1) file which contains no R code
  • an external program (Pandoc) will:
    • handle layout design of the Title, Author names, headings, etc
    • handle and convert literature citations and internal cross references
    • convert the entire document to the specified output format

The final layout of a published manuscript is complex and specific to the journal in question:

It is possible, but not straightforward to create such complex layout using Quarto markdown, assuming the publishing house provide a LaTeX template (as most of them do), but we do not recommend bothering with that, as a general rule.

It is better to aim for as simple a layout design as possible and there are good reasons for that:

When your submitted manuscript is accepted for publication, the editorial office will transfer the manuscript to the Design and Layout department of the publishing house. The first thing they will do, is extract the content and throw away the amateurish layout of your submitted Word document. They will substitute the layout with their own professional template, fonts, etc.

The employees of the publishers Design and Layout department are probably not bothered whether you use Times New Roman or Helvetica, in size 10pt or 12pt. That all gets thrown away, anyway.

They are however, interested in knowing which parts of the content is supposed to be a heading level 2 and which are a figure caption. Markdown is very well suited for this, as it defines the categories of the text, as opposed to its layout.

Alas, many journal editors insist that you submit your paper in agreement with a number of layout specifications listed in the Instructions for Authors. For instance, the following was stipulated by a journal we recently submitted to:

Manuscripts should be submitted in the Microsoft Word or RTF format of any word processor programs. Manuscripts should be typed on A4 size paper or standard US paper size (width 8.5 inch; length 11 inch) with double spacing, and a font size of 10 or larger with margins of 2 cm (1 inch) on each side, and 3 cm (2 inch) for top and bottom. Manuscripts should be submitted with line numbers to facilitate the review process.

In the Quarto YAML, we can specify the output format as Word or RTF: format: docx or format: RTF. See this page for details about the meny possible Pandoc formats.

That takes care of the ouput file format, but does not help us with the remaining layout requirements (double spacing, line numbers, etc).

To solve this we need to make use of an output template in the same output file format.

The procedure is relatively straight forward:

  • Specify the template in the YAML along with the output format
  • Create a template in the specific output format (e.g. docx)
  • Edit that template to reflect the requirements of the Instructions for Authors

You can read more about in on this website.

Note, that some journals provide a docx template for submission, which can be used in place of one you create yourself.

En påmindelse om den måde hvorpå manuskripter bygget af R-kode og MarkDown, bliver konverteret (render) til et output:

Figure 2: At render et output fra et Quarto-dokument beror i sidste led på programmet “Pandoc”.

Grundlæggende:

  • knitr pakken bruges til
    • isolere R-koden fra .qmd Quarto-dokumentet
    • udføre den R-kode, og
    • erstatte R-koden med det resulterende output af koden
  • det resulterer i en clean MarkDown (‘md’ i figuren ovenfor2)-fil, som ikke indeholder nogen R-kode
  • et eksternt program (Pandoc) vil:
    • håndtere layout design af titlen, forfatternavne, overskrifter osv
    • håndtere og konvertere litteraturhenvisninger og interne krydsreferencer
    • konverter hele dokumentet til det angivne outputformat

Det endelige layout af et publiceret manuskript er komplekst og specifikt for det pågældende tidsskrift:

Det er faktisk muligt, at render til et så komplekst layout ved hjælp af Quarto markdown, men det forudsætter at forlaget har offenligtgjort en LaTeX-skabelon, hvilket de fleste af dem har.

Vi anbefaler istedet at sigte efter et så enkelt layoutdesign som muligt, og det er der gode grunde til:

Når dit indsendte manuskript er accepteret til udgivelse, overfører redaktionen manuskriptet til forlagets Design- og Layoutafdeling. Det første de vil gøre, er at udtrække indholdet og droppe det amatøragtige layout af dit indsendte Word-dokument. De vil så erstatte layoutet med deres egen professionelle skabelon, skrifttyper osv.

Medarbejderne i forlagets Design- og Layoutafdeling er formentligt ligeglade med, om du bruger Times New Roman eller Helvetica, i størrelse 10pt eller 12pt. Hele layoutet bliver alligevel smidt væk.

Men de er interesserede i at vide, hvilke dele af indholdet der skal være en overskriftsniveau 2 og hvilke der er en figuroverskrift. Markdown (og LaTeX) er meget velegnet til det, da det definerer tekstens kategorier i modsætning til dens layout.

Men ak, mange tidsskriftsredaktører insisterer på, at du indsender dit manuskript i overensstemmelse med en række layoutspecifikationer, der er angivet i Instructions for Authors. For eksempel blev følgende fastsat af et tidsskrift, vi for nylig indsendte til:

Manuskripter skal indsendes i Microsoft Word- eller RTF-formatet for alle tekstbehandlingsprogrammer. Manuskripter skal skrives på papir i A4-størrelse eller standard amerikansk papirstørrelse (bredde 8,5 tommer; længde 11 tommer) med dobbelt mellemrum og en skriftstørrelse på 10 eller større med marginer på 2 cm (1 tomme) på hver side og 3 cm (2 tommer) til top og bund. Manuskripter skal indsendes med linjenumre for at lette gennemgangsprocessen.

I Quarto dokumentets YAML kan vi angive outputformatet som Word eller RTF: format: docx eller format: RTF. Se denne side for detaljer om de mange mulige Pandoc-formater.

Det løser opgaven med output-filformatet, men hjælper os ikke med de resterende layoutkrav (dobbelt mellemrum, linjenumre osv.).

For at løse dette skal vi gøre brug af en outputskabelon (som skal være samme output-filformat, f.eks .docx).

Fremgangsmåden er forholdsvis ligetil:

  • Angiv skabelonen i YAML sammen med outputformatet
  • Opret en skabelon i det specifikke outputformat (f.eks. docx)
  • Rediger denne skabelon, så den afspejler kravene i instruktionerne til forfattere

Du kan læse mere om det på denne hjemmeside.

Bemærk, at nogle tidsskrifter har en docx-skabelon på deres hjemmeside, som kan bruges i stedet for en, du selv opretter.

Footnotes

  1. If you want to see what this markdown looks like, add keep-md: true to your YAML, and instead of being deleted during the rendering process, it will remain in your project folder for inspection.↩︎

  2. Hvis du vil se, hvordan denne markdown ser ud, skal du tilføje keep-md: true til din YAML, og i stedet for at blive slettet under render-processen, vil markdown filen forblive i din projektmappe til inspektion.↩︎