Skip to contents

Source: vignettes/for_chapter_author.qmd

Configuring your computer

See basic computer installation of R, etc

Then open RStudio and install the package saros

Work with Quarto documents (*.qmd){sec-work-qmd}

  1. File location:
  2. Make sure the files are not in a folder with long paths on a Sharepoint/Teams folder (over 260 characters). This will cause trouble when you have to return.
  3. Each chapter should be in its own folder. Do not use a folder with your name on it where you have several chapters. It just becomes a mess.
  4. Leave all files associated with the chapter in the same folder, also versions sent to quality assurance, etc. Everything in one place. Feel free to use sub folders to keep things tidy.
  5. All files/folders that you consider “archive” that others should ignore can be named with an underscore at the beginning of the file/folder name. E.g. the file “_biter_jeg_har_klipt_ut.qmd”
  6. First press Edit ➠ Folding ➠ Collapse all.
  7. Open one chunk at a time by tapping on it. Feel free to close them afterwards (arrow on the left side of the chunk).
  8. Preview figures, graphs, etc by pressing the green button to the right of the chunk, or press Ctrl + Shift + Enter to run the entire chunk that the cursor is on.
  9. Tap Show in new window above the preview for shapes that are larger than the preview. If necessary, adjust the window to see everything.
  10. Write text for the results.
  11. Do you want to see how everything looks in the end? Press the Render button and an HTML page will eventually open. If you get error messages, read them carefully and check with this list.
  12. By pressing the gear to the right of the Render button, you can set the output to the Viewer window in RStudio (applies to HTML output). Some people prefer this.
  13. To save time in the long run, you should consider switching on caching, which means that figures and tables are temporarily stored and reused. It takes an extra long time (5x usual) to run the first time, but then these cached versions can be used later if there are no changes. It will be very useful if you only work with one figure at a time, or only with text. If you make small changes to many figures at the same time, in several rounds, it will not pay off in terms of time.
execute:
cache: true # Placed under execute which you already have.
  1. The keyboard shortcut to render the entire document is (think K for compile).
  2. Figures that are so compressed that you cannot read the text (or vice versa, too large), adjust the height:
#| fig-height: 4
  1. Beyond the height of the figure, colors in the figures and the like, don’t overthink the layout. Much that happens automatically will change globally when the entire website/report is compiled. However, figures must look good both in the HTML version (quite easy) and Word (a bit more difficult).

Glossary

Note

Chunk / code cell
A bit of R code, defined as anything between ``{r} and ```. It may have special settings, indicated by #| (called hash pipe), at the top. If you do not want to run the code temporarily (for example, if you are unsure whether it should be included), you can comment out the code itself (then keep the settings), or delete it completely, and rather retrieve it from the original if desired.
Render/compile
Runs all the chunks and assembles the document for e.g. an HTML page, PDF or DOCX. Can also be called compile in Norwegian.
YAML header
YAML is a way of writing settings for a document (potentially also for an entire project) that is both human and computer readable. Will never appear after compilation.
Quarto/QMD
Quarto is the technology that assembles R code, plain text, with YAML settings, etc. QMD is the file name for such a document.