Apéndice B — Teclas, símbolos y hábitos de la terminal

Palabras clave

Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means

Si sobre todo escribes prosa, cuatro cosas de este libro pueden ser nuevas: teclas que cada programa trata de manera distinta, los símbolos de los que el código está lleno, las rutas que nombran archivos y carpetas, y las teclas y los hábitos que hacen predecible una terminal, incluido cómo leer un error. Sáltate lo que ya sabes. El Capítulo 5 es el lugar para practicarlo todo: casi todo lo que contiene se escribe a mano.

El teclado

Tabla B.1: Teclas cuyo efecto depende del programa en el que estás. Teclas de la Mac según la página “Mac keyboard shortcuts” de Apple (consultada el 2026-11-16).
Teclas Qué saber
Shift (Mayús), Bloq Mayús mantén Shift para una sola mayúscula, o para el símbolo de arriba de una tecla; Bloq Mayús queda activo hasta que lo vuelves a presionar
Retroceso, Supr Retroceso borra a la izquierda del cursor, Supr a la derecha; en una Mac la tecla que dice Delete es Retroceso, y Fn-Delete borra a la derecha
Enter (Intro, Return) empieza una línea nueva en un documento, envía un mensaje en un chat y ejecuta el comando en una terminal
Tab pasa al siguiente campo de un formulario y sangra en un editor; en una terminal completa nombres (más abajo)
Ctrl, Comando un atajo significa mantener la primera tecla mientras presionas la segunda: Ctrl+Z deshace en Windows y Linux, Comando-Z en una Mac

Símbolos que usa este libro

El código usa signos de puntuación que la prosa casi nunca necesita, y un solo símbolo equivocado detiene un comando. Cada símbolo de abajo aparece en los prompts, comandos o archivos del libro.

Tabla B.2: Los símbolos que el libro escribe más, y dónde aparece cada uno.
Símbolo Nombre Dónde lo encuentras
` acento grave (backtick) alrededor del código en Markdown; tres seguidos abren un bloque de código (Sección 6.9)
~ virgulilla (tilde) tu carpeta personal en una ruta: ~/quarto-workshop
_ guion bajo (Shift y la tecla del guion) nombres de archivos y columnas: _quarto.yml, water_coverage_total
- guion, también llamado signo menos opciones de un comando: quarto --version; escribe la tecla misma, no una raya más larga
: dos puntos ajustes YAML, con un espacio después: title: "Visit London" (Sección 7.2)
', " comillas simples y dobles mantienen juntas palabras con espacios: cd "My Documents"; texto en Python y YAML
&& doble ampersand ejecuta un segundo comando solo si el primero funcionó: mkdir -p london-guide && cd london-guide
; punto y coma ejecuta dos comandos en una línea de la terminal, uno tras otro; raro en este libro
{ } llaves celdas ejecutables como {python}, y atributos como {.unnumbered}
( ) paréntesis llamadas de Python como len(df), y la dirección de un enlace de Markdown: [text](url)
[ ] corchetes el texto de un enlace de Markdown, y las listas de Python: ["html", "pdf"]
/ barra entre carpetas en una Mac, Linux y WSL, y en direcciones web: data/visits.csv
\ barra invertida entre carpetas en Windows (C:\Users); al final de una línea de la terminal, continúa el comando en la siguiente
# numeral un encabezado de Markdown, y un comentario en Python, YAML y los scripts de Bash (no en la terminal zsh de una Mac, donde se le pasa al comando)
AdvertenciaError frecuente

Dos trampas cambian un símbolo sin avisarte. Los procesadores de texto y las aplicaciones de notas cambian las comillas rectas por curvas (“ ”) y dos guiones por una raya (—). Una terminal y Python los leen como caracteres distintos, así que un nombre entre comillas o una opción como --version deja de funcionar: copia los prompts y los comandos del libro o de un editor de texto plano. Y algunas distribuciones de teclado convierten símbolos en teclas muertas, que esperan la tecla siguiente para acentuarla: la distribución United States-International de Windows lo hace con `, ', ", ~ y ^ (página de esa distribución de Microsoft, consultada el 2026-11-16), y las distribuciones en español con ` y ^. Presiona Espacio después de una tecla muerta para obtener el símbolo solo.

Teclas de la terminal

Un puñado de teclas hace que la terminal sea mucho más rápida y menos propensa a errores. Son las que vienen por defecto en Bash, la shell de Ubuntu, y en zsh, la de la Mac, y en Windows Terminal y en la aplicación Terminal de la Mac (manuales del editor de línea de GNU Bash y de zsh; documentación de teclado de Microsoft y de Apple; todo consultado el 2026-10-31).

Tabla B.3: Teclas de la terminal que vale la pena conocer: ejecutar, completar, recuperar, detener, copiar y pegar.
Teclas Hace
Enter ejecuta el comando que escribiste; presiónalo cuando el comando esté completo
Espacio separa las partes de un comando, así que pon entre comillas un nombre que tenga uno: cd "My Documents"
Tab completa un nombre de archivo o de comando; muestra las opciones cuando coinciden varias
Flecha hacia arriba, flecha hacia abajo recorren hacia atrás y hacia adelante los comandos anteriores; edita uno y presiona Enter para ejecutarlo
Ctrl+C detiene el comando en ejecución (en Windows Terminal, copia si hay texto seleccionado)
Ctrl+Shift+C, Ctrl+Shift+V copiar y pegar en Windows Terminal y en Ubuntu (Mac: Comando-C, Comando-V)
clic derecho en Windows Terminal: copia una selección, o pega cuando no hay nada seleccionado
AdvertenciaError frecuente

Ctrl+C en la pestaña del agente interrumpe al agente, no a un comando. En Windows Terminal copia solo cuando hay texto seleccionado; sin nada seleccionado, detiene lo que esté corriendo.

Otras teclas editan la línea que estás escribiendo, limpian la pantalla o encuentran un comando que escribiste antes:

Tabla B.4: Teclas de la terminal para editar la línea, limpiar la pantalla y buscar comandos anteriores.
Teclas Hace
Ctrl+A, Ctrl+E saltan al principio y al final de la línea
Ctrl+U borra hasta el principio de la línea (la línea entera en zsh); Ctrl+K borra hasta el final
Ctrl+L limpia la pantalla
Ctrl+R busca comandos anteriores mientras escribes; Ctrl+R otra vez para coincidencias más viejas, Enter lo ejecuta, Ctrl+G abandona
ImportantePruébalo

Abre una segunda pestaña (Ctrl+Shift+D en Windows Terminal, Comando-T en una Mac), escribe ls ~/quarto-w y presiona Tab, y luego Enter. Presiona Ctrl+L, luego Ctrl+R y escribe ls; luego Ctrl+A, Ctrl+E y Ctrl+U.

Terminaste cuando Ctrl+R encontró tu comando ls y Ctrl+U lo borró.

Rutas

Una ruta nombra un archivo o una carpeta por las carpetas que llevan hasta él, separadas por /. Una ruta absoluta empieza en lo más alto de las carpetas de la computadora, /, y significa lo mismo estés donde estés: /home/ana/first-report en Linux y WSL, /Users/ana/first-report en una Mac. Una ruta relativa empieza en la carpeta en la que estás: en ~/first-report, data/visits.csv es el archivo visits.csv de su carpeta data, y desde tu carpeta personal la misma ruta no encuentra nada.

Tabla B.5: Las formas cortas de rutas que usan los comandos de este libro.
Ruta Significa
~ tu carpeta personal: ~/first-report es la carpeta first-report que está dentro, desde cualquier lugar
. la carpeta en la que estás: open . la abre en una Mac
.. la carpeta de arriba: cd .. sube un nivel, y ../quarto-workshop es una carpeta al lado de esta
data/visits.csv relativa: visits.csv en la carpeta data de la carpeta en la que estás

Un error “no such file” (no existe el archivo) suele significar una ruta relativa leída desde la carpeta equivocada: pwd dice dónde estás, y ls qué hay ahí.

Un espacio separa las partes de un comando, así que un nombre con un espacio se lee como dos nombres. Cada shell lo dice con sus propias palabras:

$ mkdir "my reports"
$ cd my reports
bash: cd: too many arguments

Eso es Bash en Ubuntu (5.2); zsh en una Mac responde cd: string not in pwd: my. En los dos casos, mantén el nombre de una pieza: ponlo entre comillas, cd "my reports", o pon una barra invertida antes del espacio, cd my\ reports. Lo más fácil es escribir cd my y presionar Tab: la shell completa el nombre y escribe la barra invertida por ti. Los nombres que eliges son más simples sin espacios: my-reports.

Leer un error

Un comando que falla suele imprimir más de lo que necesitas. Léelo en este orden.

La primera línea. Dice qué salió mal, por lo general después de ERROR: o error:. Ejecuta uv run quarto render report.qmd en la carpeta equivocada y la línea es:

ERROR: No valid input files passed to render

Stack trace:
    at _Command.actionHandler (file:///Applications/quarto/bin/quarto.js:142967:11)
    ...

Quarto no encontró ningún report.qmd aquí: estás en la carpeta equivocada, o el nombre está mal escrito.

No la traza de la pila. Las líneas después de Stack trace:, cada una empezando con at, muestran en qué lugar de Quarto apareció el error. Son para los desarrolladores de Quarto, no para ti: sáltalas.

El acento circunflejo. Un error en el YAML de un archivo termina con las líneas que lo rodean, numeradas, y un acento circunflejo, ^, debajo del lugar donde YAML se rindió. Aquí format: html perdió el espacio después de sus dos puntos:

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 |
-----^

Los números cuentan las líneas desde el --- de apertura, que es la línea 1, y (4:1) significa línea 4, carácter 1. YAML a menudo nota un error una línea después de él, así que mira la línea a la que apunta el acento circunflejo y la de arriba: aquí el culpable es la línea 3.

Cuando pidas ayuda, copia todo de todos modos: el comando y cada línea que imprimió, incluida la traza de la pila. La persona o el chat web que te ayuda puede necesitar la parte que te saltaste. La Sección 5.6 comete tres errores frecuentes a propósito, y el Apéndice D enumera los mensajes vistos en la práctica, con sus soluciones.

Hábitos

  • Sabe dónde estás. Ejecuta pwd antes de iniciar un agente: su respuesta es la carpeta raíz del agente (Sección 2.4).
  • Dos pestañas. Deja el agente en una pestaña y los comandos como quarto preview en otra, las dos en la carpeta del proyecto.
  • Una pestaña nueva después de instalar. Una terminal aprende dónde están los programas cuando arranca, así que un programa instalado hace un momento queda “not found” (no encontrado) hasta que abres una pestaña nueva.
  • Lee antes de ejecutar. Venga un comando del libro, de un chat web o del agente, léelo antes de presionar Enter o de aprobarlo, sobre todo cualquiera con sudo o rm.
  • Copia los errores completos. Cuando algo falla, copia el comando y todo el texto del error; la línea útil rara vez es la última.
  • Edita archivos pequeños en la terminal. nano AGENTS.md abre un archivo en un editor simple: Ctrl+O y luego Enter lo guardan, y Ctrl+X sale. En una Mac, nano abre Pico, que usa las mismas teclas (revisado en macOS 26, el 2026-11-12); los dos muestran sus teclas en la parte de abajo de la pantalla.