Appendix B — Keys, Symbols and Terminal Habits

Keywords

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

Table B.1: Keys whose effect depends on the program you are in. Mac keys from Apple’s “Mac keyboard shortcuts” page (checked 2026-11-16).
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.

Table B.2: The symbols the book types most, and where each one appears.
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)
WarningCommon pitfall

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).

Table B.3: Terminal keys worth knowing: running, completing, recalling, stopping, copying and pasting.
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
WarningCommon pitfall

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:

Table B.4: Terminal keys for editing the line, clearing the screen and searching earlier commands.
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
ImportantTry it

Open a second tab (Ctrl+Shift+D in Windows Terminal, Command-T on a Mac), type ls ~/quarto-w and press Tab, then Enter. Press Ctrl+L, then Ctrl+R and type ls; then Ctrl+A, Ctrl+E and Ctrl+U.

You’re done when Ctrl+R found your ls command and Ctrl+U cleared it.

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.

Table B.5: The short forms of paths that this book’s commands use.
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 pwd before 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 preview in 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 sudo or rm.
  • 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.md opens a file in a simple editor: Ctrl+O, then Enter, saves it, and Ctrl+X leaves. On a Mac, nano opens Pico, which uses the same keys (checked on macOS 26, 2026-11-12); both list their keys along the bottom of the screen.