Saltar al contingut principal
Recepta número 48

Receptari · Capítol 6 · Requadres i notes

Llistats de codi i tecles

Guia del terminal amb els blocs de codi compostos en requadres foscos de llistat, acolorit per elements, i les tecles com a xips.

En aquesta pàgina

pp. 50–51 · 2–3 de 3

  • Mostra en castellà: encara no hi ha edició en català
  • Format 178 × 229 mm
  • Columna i mitja, espai entre columnes de 6 mm
  • Charis SIL 10/14,5
  • JetBrains Mono
  • Sora
  • 3 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 89 ms
  • 147 línies de codi

En poques paraules

Tres pàgines d'una guia per començar amb la línia d'ordres de l'ordinador. Ensenya a compondre els exemples de codi en requadres foscos de colors i a dibuixar tecles com Ctrl com a botonets dins del text.

Què compondràs

Tres pàgines del capítol 4 de La terminal, con calma, una guia de butxaca inventada sobre la línia d'ordres, en format de 178 × 229 mm. El text va justificat en Charis SIL, en una columna de 100 mm, amb una columna lateral exterior per a les notes. Cada llistat és un requadre gairebé negre en JetBrains Mono que entra en aquesta columna, sota una pestanya amb el nom del fitxer o de la sessió. Les paraules clau i les ordres que tecleges surten en ambre, les cadenes en verd i els comentaris en gris. Ctrl, Tab i les altres tecles es dibuixen com a tecletes amb contorn dins de les línies justificades, i una xuleta de dreceres amb Ctrl, a dues columnes, ocupa el peu de la pàgina 50. El Markdown conserva els blocs de codi de sempre, i el motor els compon tal com són.

Aquesta recepta respon a

  • Com mostro llistats de codi?
  • Com faig xips en línia: tecles, etiquetes, bancs de paraules per a exercicis?
  • Com escric guions de diàleg, anys a l'inici de paràgraf, preus i símbols literals sense que el Markdown els interpreti malament?

La resposta curta

script.js · línies 26–41al codi complet
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
  fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
  background: col('night'), span: 'page', // across the text and the margin
  padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
  marginTop: mm(6), marginBottom: mm(2.5),
  label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
    background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
    position: 'top-left' },
  tokens: tokens(), // the colours, below
  inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};

Ingredients

També fa servir
Matemàtiques
Tipografia
Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Dona una caixa a les tanques

El codi d'aquest pas és la resposta curta de més amunt. Cada bloc ``` del Markdown és un bloc de codi: Postext en compon les línies tal com estan escrites, una línia de codi per línia de text, i conserva els sagnats, les línies en blanc del guió i les dues columnes de la sortida de du. codeStyle dissenya tots els llistats alhora (llistats de codi): la lletra i el seu interlineat, l'emplenament gairebé negre, el marge interior i l'espai de damunt i de sota. El que segueix el llenguatge a la línia d'obertura (Terminal, copia.sh) és el títol del llistat, i com que codeStyle.label està fixat, s'imprimeix en una pestanya d'etiqueta sobre la vora superior de la caixa i no en una fila de títol. codeStyle.inline compon el codi en línia del text corrent, ls o grep -c, en la mateixa lletra a 0,88 em (codi en línia). El paràgraf que segueix un llistat va en :::paragraphs{style="resume"}, de manera que comença sense sagnat, com després d'un títol.

#2 · Deixa el text estret i que el codi travessi el marge

script.js · línies 124–127al codi complet
  page: { sizePreset: 'custom', width: mm(178), height: mm(229), margins: {
    top: mm(22), bottom: mm(21), left: mm(20), right: mm(OUTER), mirror: true } },
  layout: { layoutType: 'oneAndHalf', sideColumnPercent: 26, gutterWidth: mm(6),
    sideColumnRole: 'floats', sideColumnSide: 'outer' },

A 10 pt, Charis SIL compon uns 62 caràcters per línia a la columna de 100 mm. La columna lateral d'aquesta disposició a columna i mitja només admet flotants i notes, així que el text no hi entra mai. span: 'page' a codeStyle estén cada llistat per les dues columnes, 143 mm. Dins del seu marge interior, un requadre admet 73 caràcters de JetBrains Mono a 8,6 pt; la línia més llarga d'aquestes pàgines, el comentari que obre copia.sh, en té 68.

#3 · Acoloreix el codi per elements

script.js · línies 45–54al codi complet
function tokens() {
  const plain = { color: col('code') }; // every other kind in the listing's own colour
  return {
    keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },
    string: { color: col('phosphor'), italic: true },
    comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
    prompt: { color: col('amber'), bold: true }, output: plain, // what you type, the answer
    number: plain, type: plain, variable: plain, meta: plain, operator: plain, punctuation: plain,
  };
}

El llenguatge de la línia d'obertura (console, bash) tria l'analitzador integrat, i codeStyle.tokens dona a cada tipus d'element el seu color, el seu gruix i la seva inclinació (colors de sintaxi). A copia.sh, les paraules clau com for i done i les ordres internes com set i echo surten en negreta ambre, les cadenes en cursiva verda i els comentaris en gris; els programes, com mkdir o rsync, queden en rodona. L'estil per defecte posa els comentaris en cursiva, així que italic: false els manté drets. En un bloc console, una línia que comença amb un indicador és un element prompt i totes les altres són output, de manera que les ordres que tecleges surten en negreta ambre i la resposta de l'intèrpret es queda en el gris clar del llistat. Els tipus que la recepta no vol acolorir, entre ells els números, les variables i les opcions, prenen també aquest gris.

#4 · Compon les tecles com a xips

script.js · línies 58–65al codi complet
// Chips never break or stretch, so a line with keys puts all its slack in its word spaces;
// the breaker tries other breaks before a space passes 140 % (default 200 %).
const spacing = { maxWordSpacing: 1.4 }; // spread into bodyText
const chipStyles = [
  { id: 'key', fontFamily: MONO, fontSize: pt(7.8), bold: true, color: col('ink'),
    background: col('code'), borderColor: col('slate'), borderWidth: pt(0.6),
    borderRadius: pt(1.6), paddingX: em(0.45), paddingY: em(0.14), gap: em(0.3) },
];

Les tecles són xips key, amb un emplenament clar i un contorn de 0,6 pt. El seu cos va en punts, de manera que fan 7,8 pt al text de 10 pt, a la nota del marge de 8,6 pt i a la xuleta de 8,4 pt; amb em(0.78), les de la xuleta baixarien a 6,6 pt. Un xip no es parteix mai entre línies ni s'estira (xips en línia), així que en una línia amb tecles tot el buit sobrant va als espais entre paraules. Amb spacing, l'algorisme de partició de línies cerca altres talls abans de deixar que un espai passi del 140 % de la seva amplada normal. Amb el valor per defecte, 200 %, sis línies d'aquestes pàgines el superen; amb l'ajust, la més oberta arriba al 132 %.

#5 · Numera els passos sobre la retícula

script.js · línies 91–94al codi complet
const orderedLists = { fontFamily: DISPLAY, fontWeight: 800, color: col('ember'),
  gap: em(0.7), separator: '›', separatorGap: em(0.25), separatorFontFamily: MONO,
  separatorFontWeight: 700, separatorColor: col('muted'),
  marginTop: ZERO, marginBottom: ZERO }; // the default 1.5 em opens 5.3 mm above and below

Els números van en Sora 800 amb el color d'accent, i el separador és un › monoespaiat en gris. Com que la seva lletra i el seu color no són els del número, el separador es dibuixa com un fragment propi (llistes numerades). Els marges de la llista són zero, així que els passos continuen a la retícula de base de 14,5 pt del text que els envolta. Els 1,5 em per defecte obririen 5,3 mm sobre els passos i durien la xuleta a la pàgina 51.

#6 · Porta la xuleta al peu de la pàgina

script.js · línies 69–76al codi complet
const sheet = { id: 'sheet', background: col('night'), span: 'page', placement: 'bottom',
  marginTop: mm(6), marginBottom: mm(2.5),
  columnGap: mm(8), padding: { top: mm(5), right: mm(6), bottom: mm(5.5), left: mm(6) },
  titleStyle: { fontFamily: MONO, fontSize: pt(7.5), fontWeight: 700, gap: mm(3.5),
    color: col('phosphor'), textTransform: 'uppercase', letterSpacing: pt(1.5) },
  body: { fontFamily: DISPLAY, fontSize: pt(8.4), lineHeight: pt(13), textAlign: 'left',
    color: col('code'), boldColor: col('amber'), italicColor: col('phosphor'),
    paragraphSpacing: false, firstLineIndent: ZERO } };

La xuleta és un estil de requadre amb l'emplenament dels llistats, Sora per a les accions i placement: 'bottom', que la fa flotar fins al peu de la pàgina 50 (requadres flotants). Dins del flux, un requadre que travessa la pàgina necessita lloc per a si mateix i per a dues línies de text a sota. Aquí saltaria a la pàgina 51 amb 58 mm buits sota els passos, i el capítol passaria a quatre pàgines. Al Markdown, :::columns{count=2 breaks="8"} obre la columna dreta al vuitè bloc, el seu títol. L'equilibratge tot sol talla per alçada, i quan una acció ocupa dues línies deixa Órdenes e historial al peu de la columna esquerra. Cada entrada comença pels mateixos dos xips, Ctrl i una lletra, tots dos en la monoespaiada, així que les accions arrenquen a la mateixa distància de la vora esquerra de la seva columna.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 048 · Code listings and keycaps ═══
// https://postext.dev/en/cookbook/code-listings-and-keycaps
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocument, prepareFonts, withLoadedFonts, renderPageToCanvas,
} from 'https://esm.sh/postext';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'code-listings-and-keycaps';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1b1f24', muted: '#5c636b', ember: '#9a5410', // text, heads, accent
  night: '#0e1116', code: '#d3d9df', amber: '#f2b134', phosphor: '#3ddc84', // the listings
  slate: '#8a939d' }; // comments in a listing, the outline of a key (code is its face)
// Every colour is linked to its palette entry by id.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.ember })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Charis SIL', 'Sora', 'JetBrains Mono'];
const LEAD = 14.5; // pt: the body leading, the page's baseline grid
const ZERO = pt(0);

// #region answer: a fence is a code listing; codeStyle gives it a dark box
// A ``` fence is a listing set line by line as written: indents, blank lines and the output
// columns of a session are kept. The rest of the fence line (Terminal, backup.sh) is its
// title; with a label set, it goes on the tab.
// The text after a listing goes in :::paragraphs{style="resume"}: flush, as after a heading.
const resume = { id: 'resume', firstLineIndent: ZERO };
const codeStyle = {
  fontFamily: MONO, fontSize: pt(8.6), lineHeight: pt(12.4), color: col('code'),
  background: col('night'), span: 'page', // across the text and the margin
  padding: { top: mm(4), right: mm(5), bottom: mm(4), left: mm(5) },
  marginTop: mm(6), marginBottom: mm(2.5),
  label: { fontFamily: MONO, fontSize: pt(7), fontWeight: 700, color: col('phosphor'),
    background: col('night'), height: mm(5), offset: mm(5), paddingX: mm(3), // the tab
    position: 'top-left' },
  tokens: tokens(), // the colours, below
  inline: { fontSize: em(0.88) }, // `grep` in running text: the code face, no box
};
// #endregion

// #region paint: keywords amber, strings green, comments slate; a session's typed lines amber
function tokens() {
  const plain = { color: col('code') }; // every other kind in the listing's own colour
  return {
    keyword: { color: col('amber'), bold: true }, function: { color: col('amber'), bold: true },

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Penja la pestanya a la dreta

La pestanya passa a la cantonada superior dreta del requadre, que en una pàgina senar queda sobre la columna lateral.

-    position: 'top-left' },
+    position: 'top-right' },

#Numera les línies

Cada llistat porta números de línia en gris en un marge dins de la caixa. Aquest marge ocupa uns quatre dels 73 caràcters, i en queden 69: el comentari que obre copia.sh, de 68, encara hi cap, però un sol caràcter més el faria partir, i la resta continuaria a sota darrere d'un ». La revisió del Receptari ho indica amb un avís codeOverflow; escurça la línia per mantenir el guió en les seves 13 línies. Un sol llistat rep números amb {lineNumbers} a la línia d'obertura.

+  lineNumbers: true, lineNumberColor: col('slate'),
   tokens: tokens(), // the colours, below

#Dona als comentaris el color de les cadenes

Els comentaris prenen el verd de les cadenes, en cursiva.

-    comment: { color: col('slate'), italic: false }, // upright: the default comment is italic
+    comment: { color: col('phosphor'), italic: true }, // the strings' green italic

Errors freqüents

Error freqüent

Un requadre lateral comença a l'altura del bloc que segueix la seva tanca

A postext 1.4.1, un requadre amb span: 'side' es col·loca a la columna lateral a l'altura on ha arribat el text a la seva tanca, a la línia següent de la retícula i sota els requadres que ja hi hagi. Posa la tanca d'una glossa just abans del paràgraf que explica: si va després, la glossa comença al costat del paràgraf següent. Un requadre que passaria del peu de la columna puja fins que el seu peu coincideix amb el de la columna, si el requadre de sobre li deixa lloc; si tot i així no hi cap, espera la columna lateral de la pàgina següent. Notes al marge →

  • No passis de 73 caràcters en cap línia de codi. Una línia més llarga es parteix després de l'últim espai o signe de puntuació que hi cap i continua a sota darrere d'un », i el motor genera un avís codeOverflow; overflow: 'shrink' compon tot el llistat més petit, i 'clip' talla la línia a la vora de la caixa.
  • Un tabulador d'un llistat avança fins al múltiple següent de quatre columnes (codeStyle.tabSize). Un guió sagnat amb tabuladors que el teu editor mostra amb vuit columnes d'amplada aquí surt més estret.
  • Amb codeStyle.inline fixat, el codi en línia no es parteix mai entre línies, igual que un xip. Una ruta llarga dins del text, com ~/Imatges/2025/IMG_0977.MOV, passa sencera a la línia següent i pot deixar enrere una línia massa oberta.

Crèdits

Text
Text original, CC BY 4.0
Fonts
Charis SIL (SIL OFL 1.1) · Sora (SIL OFL 1.1) · JetBrains Mono (SIL OFL 1.1)
Sandbox