Pular para o conteúdo principal
Receita número 48

Receitas · Capítulo 6 · Boxes e notas

Listagens de código e teclas

Um guia do terminal cujos blocos de código delimitados saem como listagens em boxes escuros, coloridas por elemento, com as teclas como chips.

p. 50–51 · 2–3 de 3

  • Amostra em inglês: ainda sem edição em português
  • Refile 178 × 229 mm
  • Coluna e meia, medianiz de 6 mm
  • Charis SIL 10/14,5
  • JetBrains Mono
  • Sora
  • 3 páginas
  • Nível
  • Postext 1.57.1
  • Diagramado em 89 ms
  • 147 linhas de código

Em poucas palavras

Três páginas de um guia para iniciantes na linha de comando do computador. Mostra como compor exemplos de código em caixas escuras coloridas e desenhar teclas como Ctrl como botõezinhos no texto.

O que você vai compor

Três páginas do capítulo 4 de The Shell, Gently, um guia de bolso inventado sobre a linha de comando, numa página de 178 × 229 mm. O texto vai justificado em Charis SIL, numa coluna de 100 mm, com uma coluna lateral do lado externo para as notas. Cada listagem é um boxe quase preto em JetBrains Mono que entra nessa coluna, sob uma aba com o nome do arquivo ou da sessão. Palavras-chave e comandos digitados saem em âmbar, strings em verde e comentários em cinza. Teclas como Ctrl e Tab são pequenas teclas contornadas dentro das linhas justificadas, e uma colinha de atalhos com Ctrl, em duas colunas, ocupa o pé da página 50. O Markdown mantém os blocos de código delimitados de sempre, e o motor os compõe como estão.

Esta receita responde a

  • Como mostro listagens de código?
  • Como faço chips em linha: teclas, etiquetas, bancos de palavras para exercícios?
  • Como escrevo travessões de diálogo, anos no início do parágrafo, preços e símbolos literais sem que o Markdown os interprete errado?

A resposta curta

script.js · linhas 26–41no código completo
// 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
};

Ingredientes

Também usa
Matemática
Tipografia
Charis SIL, Sora, JetBrains Mono (SIL OFL 1.1)
Materiais
Nenhum: todas as imagens são desenhadas em código

Preparo

#1 · Dar um boxe às cercas

O código deste passo é a resposta curta lá em cima. Cada bloco delimitado por ``` no Markdown é um bloco de código: o Postext compõe as linhas como foram digitadas, uma linha de código por linha composta, mantendo os recuos, as linhas em branco do script e as duas colunas da saída de du. codeStyle desenha todas as listagens de uma vez (listagens de código): a fonte e a entrelinha, o preenchimento quase preto, o espaçamento interno e o espaço acima e abaixo. O que vem depois da linguagem na linha de abertura (Terminal, backup.sh) é o título da listagem, e como codeStyle.label está definido ele é impresso numa aba de rótulo na borda superior do boxe, e não numa linha de título. codeStyle.inline compõe o código em linha do texto corrido, ls ou grep -c, na mesma fonte a 0,88 em (código em linha). O parágrafo depois de uma listagem vai em :::paragraphs{style="resume"}, por isso começa sem recuo, como depois de um título.

#2 · Manter o texto estreito e deixar o código atravessar a margem

script.js · linhas 124–127no código completo
  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, a Charis SIL compõe cerca de 62 caracteres na coluna de 100 mm. A coluna lateral deste layout de coluna e meia só recebe flutuantes e notas, de modo que o texto nunca entra nela. O span: 'page' de codeStyle estende cada listagem pelas duas colunas, 143 mm. Dentro do espaçamento interno, um boxe comporta 73 caracteres de JetBrains Mono a 8,6 pt; a linha mais longa destas páginas, o comentário que abre backup.sh, tem 71.

#3 · Colorir o código por elemento

script.js · linhas 45–54no código completo
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,
  };
}

A linguagem do bloco (console, bash) escolhe o tokenizador integrado, e codeStyle.tokens dá a cada tipo de elemento a cor, o peso e a inclinação (coloração de sintaxe). Em backup.sh, palavras-chave como for e done e comandos internos como set e echo saem em negrito âmbar, as strings em itálico verde e os comentários em cinza; programas como mkdir e rsync ficam sem destaque. O estilo padrão põe os comentários em itálico, por isso italic: false os mantém em redondo. Num bloco console, uma linha que abre com um prompt é um elemento prompt e todas as outras são output, por isso os comandos que você digita saem em negrito âmbar e a resposta do shell fica no cinza-claro da listagem. Os tipos que a receita não quer colorir, entre eles números, variáveis e opções, também recebem esse cinza.

#4 · Compor as teclas como chips

script.js · linhas 58–65no código completo
// 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) },
];

As teclas são chips key, com um preenchimento claro e um contorno de 0,6 pt. O tamanho delas é dado em pontos, de modo que uma tecla mede 7,8 pt no texto de 10 pt, na nota de margem de 8,6 pt e na colinha de 8,4 pt; em(0.78) encolheria as teclas da colinha para 6,6 pt. Um chip nunca se divide entre linhas nem se estica (chips em linha), por isso uma linha com teclas joga toda a folga nos espaços entre palavras. spacing faz o algoritmo de quebra de linhas tentar outras quebras antes de deixar um espaço passar de 140 % da largura normal. No padrão, 200 %, seis linhas destas páginas se esticam além disso; com o ajuste, a mais aberta chega a 132 %.

#5 · Numerar os passos na grade

script.js · linhas 91–94no código completo
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

Os números são Sora 800 na cor de destaque, e o separador é um › monoespaçado em cinza. O separador tem fonte e cor próprias, por isso é desenhado como um trecho separado (listas numeradas). As margens da lista são zero, de modo que os passos continuam na grade de 14,5 pt do texto ao redor. O 1,5 em padrão abriria 5,3 mm acima dos passos e empurraria a colinha para a página 51.

#6 · Levar a colinha flutuando até o pé da página

script.js · linhas 69–76no código completo
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 } };

A colinha é um estilo de boxe com o preenchimento das listagens, Sora para as ações e placement: 'bottom', que a faz flutuar até o pé da página 50 (boxes flutuantes). Deixado no fluxo, um boxe na largura da página precisa de espaço para si e para duas linhas de texto embaixo. Aqui o boxe passaria para a página 51, deixando 58 mm vazios sob os passos, e o capítulo iria para quatro páginas. No Markdown, :::columns{count=2 breaks="8"} abre a coluna da direita no oitavo bloco, o título. O equilíbrio sozinho corta pela altura, e quando uma ação ocupa uma segunda linha ele deixa Commands and history no pé da coluna da esquerda. Toda entrada começa com os mesmos dois chips, Ctrl e uma letra, ambos na monoespaçada, por isso cada ação começa à mesma distância da borda esquerda da coluna.

A receita 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 = 'en'; // @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 },

O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)

Variações

#Pendurar a aba à direita

A aba passa para o canto superior direito do boxe, que num recto fica sobre a coluna lateral.

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

#Numerar as linhas

Cada listagem ganha números de linha em cinza numa margem dentro do boxe. A margem ocupa uns quatro dos 73 caracteres, por isso o comentário que abre backup.sh deixa de caber: ele quebra depois de backup, e disk. continua abaixo, atrás de um ». A verificação das Receitas o aponta como um aviso codeOverflow; encurte o comentário para manter o script nas 13 linhas. Uma só listagem recebe números com {lineNumbers} na linha de abertura do bloco.

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

#Dar aos comentários a cor das strings

Os comentários recebem o verde das strings, em itálico.

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

Erros comuns

Erro comum

Um boxe lateral começa na altura do bloco que vem depois do seu delimitador

No postext 1.4.1, um boxe com span: 'side' fica na coluna lateral na altura a que o texto chegou no seu delimitador, na linha seguinte da grade e abaixo dos boxes que já estiverem ali. Abra o delimitador de uma glosa logo antes do parágrafo que ela explica: se vier depois, a glosa começa ao lado do parágrafo seguinte. Um boxe que passaria do pé da coluna sobe até seu pé coincidir com o da coluna, se o boxe de cima permitir; se mesmo assim não couber, espera pela coluna lateral da página seguinte. Notas na margem →

  • Mantenha toda linha de código em até 73 caracteres. Uma linha mais longa quebra no último espaço ou sinal de pontuação que cabe e continua abaixo, atrás de um », e o motor gera um aviso codeOverflow; overflow: 'shrink' compõe a listagem inteira menor, e 'clip' corta a linha na borda do boxe.
  • Uma tabulação numa listagem avança até o múltiplo seguinte de quatro colunas (codeStyle.tabSize). Um script recuado com tabulações que seu editor mostra com oito colunas de largura sai mais estreito aqui.
  • Com codeStyle.inline definido, o código em linha nunca se divide entre linhas, como um chip. Um caminho longo no texto corrido, como ~/Pictures/2025/IMG_0977.MOV, passa inteiro para a linha seguinte e pode deixar para trás uma linha frouxa.

Créditos

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