Appendix B — Keys, Symbols and Terminal Habits
Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering
If you mostly type prose, four things in this book may be new: keys that each program treats differently, the symbols that code is full of, the paths that name files and folders, and the keys and habits that make a terminal predictable, including how to read an error. Skip what you already know. Chapter 5 is the place to practise all of it: almost everything in it is typed by hand.
The keyboard
| Keys | What to know |
|---|---|
| Shift, Caps Lock | hold Shift for one capital letter, or for the upper symbol on a key; Caps Lock stays on until you press it again |
| Backspace, Delete | Backspace deletes to the left of the cursor, Delete to the right; on a Mac the key labelled Delete is Backspace, and Fn-Delete deletes to the right |
| Enter (Return) | starts a new line in a document, sends a message in a chat, and runs the command in a terminal |
| Tab | moves to the next field in a form and indents in an editor; in a terminal it completes names (below) |
| Ctrl, Command | a shortcut means holding the first key while you press the second: Ctrl+Z undoes on Windows and Linux, Command-Z on a Mac |
Symbols this book uses
Code uses punctuation that prose rarely needs, and one wrong symbol stops a command. Each symbol below appears in the book’s prompts, commands or files.
| Symbol | Name | Where you meet it |
|---|---|---|
` |
backtick (grave accent) | around code in Markdown; three of them open a code block (Section 6.9) |
~ |
tilde | your home folder in a path: ~/quarto-workshop |
_ |
underscore (Shift and the minus key) | file and column names: _quarto.yml, water_coverage_total |
- |
hyphen, also called dash or minus | options to a command: quarto --version; type the key itself, not a longer dash |
: |
colon | YAML settings, with a space after it: title: "Visit London" (Section 7.2) |
', " |
single and double quotes | keep words with spaces together: cd "My Documents"; text in Python and YAML |
&& |
double ampersand | runs a second command only if the first worked: mkdir -p london-guide && cd london-guide |
; |
semicolon | runs two commands on one terminal line, one after the other; rare in this book |
{ } |
braces, or curly brackets | executable cells such as {python}, and attributes such as {.unnumbered} |
( ) |
parentheses, or round brackets | Python calls such as len(df), and a Markdown link’s address: [text](url) |
[ ] |
square brackets | a Markdown link’s text, and Python lists: ["html", "pdf"] |
/ |
forward slash | between folders on a Mac, Linux and WSL, and in web addresses: data/visits.csv |
\ |
backslash | between folders in Windows (C:\Users); at the end of a terminal line it continues the command on the next |
# |
hash | a Markdown heading, and a comment in Python, YAML and Bash scripts (not at a zsh prompt on a Mac, where it is passed to the command) |
Two traps change a symbol without telling you. Word processors and notes apps turn straight quotes into curly ones (“ ”) and two hyphens into a dash (—). A terminal and Python read those as different characters, so a quoted name or an option such as --version stops working: copy prompts and commands from the book or a plain-text editor. And some keyboard layouts make symbols dead keys, which wait for the next key to accent it: Windows’ United States-International layout does this to `, ', ", ~ and ^ (Microsoft’s layout page, checked 2026-11-16), and Spanish layouts to ` and ^. Press Space after a dead key to get the symbol itself.
Terminal keys
A handful of keys make the terminal much faster and less error-prone. They are defaults in Bash, Ubuntu’s shell, and zsh, the Mac’s, and in Windows Terminal and the Mac’s Terminal app (GNU Bash and zsh line-editor manuals; Microsoft and Apple keyboard documentation; all checked 2026-10-31).
| Keys | Does |
|---|---|
| Enter | runs the command you typed; press it once the whole command is there |
| Space | separates a command’s parts, so put quotes round a name that contains one: cd "My Documents" |
| Tab | completes a file or command name; lists the choices when several match |
| Up arrow, Down arrow | step back and forward through earlier commands; edit one, then press Enter to run it |
| Ctrl+C | stops the running command (in Windows Terminal, copies instead when text is selected) |
| Ctrl+Shift+C, Ctrl+Shift+V | copy and paste in Windows Terminal and Ubuntu (Mac: Command-C, Command-V) |
| right-click | in Windows Terminal: copies a selection, or pastes when nothing is selected |
Ctrl+C in the agent’s tab interrupts the agent, not a command. In Windows Terminal it copies only when text is selected; with nothing selected it stops what is running.
Other keys edit the line you are typing, clear the screen or find a command you typed before:
| Keys | Does |
|---|---|
| Ctrl+A, Ctrl+E | jump to the start and the end of the line |
| Ctrl+U | delete to the start of the line (the whole line in zsh); Ctrl+K deletes to the end |
| Ctrl+L | clear the screen |
| Ctrl+R | search earlier commands as you type; Ctrl+R again for older matches, Enter runs it, Ctrl+G gives up |
Paths
A path names a file or folder by the folders that lead to it, separated by /. An absolute path starts at the top of the computer’s folders, /, and means the same wherever you are: /home/ana/first-report on Linux and WSL, /Users/ana/first-report on a Mac. A relative path starts from the folder you are in: in ~/first-report, data/visits.csv is the file visits.csv in its data folder, and from your home folder the same path finds nothing.
| Path | Means |
|---|---|
~ |
your home folder: ~/first-report is the folder first-report inside it, from anywhere |
. |
the folder you are in: open . opens it on a Mac |
.. |
the folder above: cd .. goes up one, and ../quarto-workshop is a folder beside this one |
data/visits.csv |
relative: visits.csv in the data folder of the folder you are in |
A “no such file” error often means a relative path read from the wrong folder: pwd says where you are, and ls what is there.
A space separates a command’s parts, so a name with a space reads as two names. Each shell says so in its own words:
$ mkdir "my reports"
$ cd my reports
bash: cd: too many arguments
That is Bash on Ubuntu (5.2); zsh on a Mac answers cd: string not in pwd: my. Either way, keep the name in one piece: put it in quotes, cd "my reports", or put a backslash before the space, cd my\ reports. Easiest of all, type cd my and press Tab: the shell completes the name and types the backslash for you. Names you choose yourself are simpler without spaces: my-reports.
Reading an error
A failed command often prints more than you need. Read it in this order.
The first line. It says what went wrong, usually after ERROR: or error:. Run uv run quarto render report.qmd in the wrong folder and the line is:
ERROR: No valid input files passed to render
Stack trace:
at _Command.actionHandler (file:///Applications/quarto/bin/quarto.js:142967:11)
...
Quarto found no report.qmd here: you are in the wrong folder, or the name is misspelt.
Not the stack trace. The lines after Stack trace:, each starting at, show where inside Quarto the error surfaced. They are for Quarto’s developers, not for you: skip them.
The caret. A mistake in a file’s YAML ends with the lines around it, numbered, and a caret, ^, under the place where YAML gave up. Here format: html lost the space after its colon:
ERROR: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key (4:1)
1 |
2 | title: "Five London Sights"
3 | format:html
4 |
-----^
The numbers count lines from the opening ---, which is line 1, and (4:1) means line 4, character 1. YAML often notices a mistake one line after it, so look at the line the caret points to and the line above: here the culprit is line 3.
When you ask for help, copy the whole thing all the same: the command and every line it printed, stack trace included. The person or web chat helping you may need the part you skipped. Section 5.6 makes three common mistakes on purpose, and Appendix D lists the messages seen in practice, with their fixes.
Habits
- Know where you are. Run
pwdbefore starting an agent: its answer is the agent’s root folder (Section 2.4). - Two tabs. Keep the agent in one tab and commands such as
quarto previewin another, both in the project folder. - New tab after installing. A terminal learns where programs are when it starts, so a program installed a moment ago is “not found” until you open a new tab.
- Read before you run. Whether a command comes from the book, a web chat or the agent, read it before you press Enter or approve it, especially anything with
sudoorrm. - Copy errors whole. When something fails, copy the command and the entire error text; the useful line is rarely the last one.
- Edit small files in the terminal.
nano AGENTS.mdopens a file in a simple editor: Ctrl+O, then Enter, saves it, and Ctrl+X leaves. On a Mac,nanoopens Pico, which uses the same keys (checked on macOS 26, 2026-11-12); both list their keys along the bottom of the screen.