Em poucas palavras

Um capítulo de um livro de teoria musical sobre como as frases terminam. Os exemplos são escritos como linhas curtas de texto no capítulo, e o Postext os desenha como pautas e notas; o mais longo continua na página seguinte.

O que você vai compor

O capítulo 5 de um curso de harmonia ao teclado, em 180 × 250 mm e Libre Caslon, sobre as cinco cadências: perfeita e imperfeita, meia cadência, plagal e de engano. Cada cadência ganha dois parágrafos curtos e um exemplo a três vozes com os algarismos romanos sob a pauta, escrito em ABC no próprio Markdown. O capítulo termina com Greensleeves em lá menor, com um algarismo sobre cada compasso, e essa melodia é longa demais para o espaço que sobra na página 3: põe ali três sistemas e os dois últimos no alto da página 4, quebrada entre sistemas como um parágrafo se quebra entre linhas. O tamanho da pauta, a fonte musical e o espaçamento são definidos uma vez só na configuração, e assim os cinco exemplos e a melodia têm a mesma aparência.

Esta receita responde a

Como coloco exemplos musicais no texto de um livro didático, escritos como notação?

A resposta curta

script.js · linhas 36–51no código completo

// Each ```abc fence in the chapter is engraved at the width of the text column and cut
// into systems. The style is set once here; the Markdown only holds the notation.
const scoreStyle = {
  staffSize: mm(5.5), // a textbook's rastral: examples read at arm's length on a desk
  musicFont: 'Bravura', // the traditional engraved look, heavy enough beside Caslon
  textFont: 'Libre Caslon Text', // the Roman numerals of `w:` lines, in the text face
  spacing: 1.6, // air between the chords: an example reads as a progression, not a cluster
  barNumbers: 'system',
  systemGap: mm(4),
  marginTop: pt(LEAD / 2),
  marginBottom: pt(LEAD / 2),
  color: col('ink'),
  // A long example runs on into the next page between two systems, never leaving one
  // system alone at the foot of a page or at the head of the next.
  minSystemsAtBreak: 2,
};

Ingredientes

Funcionalidades: Notação musical Estilo de partitura Aberturas desenhadas Atributos de título Cabeços e fólios Margens espelhadas Cabeços por tipo de página Boxes Estilos de parágrafo Paleta de cores semântica Viúvas, órfãs e linhas curtas Exportação para PDF
Também usa: Listagens de código Fontes incorporadas ao PDF Sobrescritos e subscritos
Tipografia: Libre Caslon Text, Libre Caslon Display, Libre Franklin (SIL OFL 1.1)
Materiais: Nenhum: todas as imagens são desenhadas em código
API: buildDocumentWithFontsdecompressWoff2initMusicEnginerenderPageToCanvasrenderToPdf

Preparo

#1 · Escrever o exemplo onde o texto precisa dele

Um bloco marcado abc contém a notação, e o texto continua depois dele. L:1/2 faz de cada acorde sem duração uma mínima, [Bdg] empilha três notas numa só voz e uma linha w: põe uma palavra sob cada acorde, aqui os algarismos romanos. O atributo alt é o que um leitor de tela e o PDF etiquetado dizem no lugar da imagem.

```abc {alt="Cadência perfeita em sol maior: I, IV, V, I"}
X:1
M:4/4
L:1/2
K:G
[Bdg] [ceg] | [Adf] [Bdg] |]
w: I IV V I
```

#2 · Dar a cada partitura a aparência do livro

A resposta curta é todo o design da música: uma pauta de 5,5 mm, como os manuais de harmonia usam para exemplos lidos ao teclado, Bravura ao lado do texto em Caslon e os algarismos na fonte do texto em vez da Times do gravador. spacing: 1.6 espalha quatro acordes em mínimas por um terço da largura da coluna, para que a progressão se leia acorde por acorde. A mesma configuração decide quantos compassos de Greensleeves cabem num sistema: três, numa coluna de 125 mm.

#3 · Deixar um exemplo longo continuar

minSystemsAtBreak: 2 é o que mantém Greensleeves legível na virada da página. A melodia sai em cinco sistemas; três cabem no pé da página 3, então dois vão para a página 4, e nenhuma página fica com um sistema sozinho. Uma partitura com menos de quatro sistemas passa inteira para a página seguinte, como fariam os exemplos curtos de cadências.

#4 · Iniciar o gravador antes da composição

script.js · linhas 264–270no código completo

// The engraver (Verovio) loads only for books with music: start it before the build,
// or every score is laid out as a grey placeholder box.
await initMusicEngine();
const doc = await buildDocumentWithFonts({ markdown }, config, kitFonts(FONTS));
showPages(doc, { title: t({ en: 'Harmony textbook', es: 'Manual de armonía' }) });
// The PDF draws every system as vector paths, the numerals in the embedded text face.
offerPdf(() => renderToPdf(doc, { fontProvider: fontsourceProvider }), `${RECIPE}.pdf`);

O Verovio tem cerca de 3,7 MB de WebAssembly, por isso o motor só o carrega quando você pede. Sem initMusicEngine() a diagramação roda mesmo assim, e cada partitura é uma caixa cinza do tamanho certo. renderToPdf não precisa de mais nada: o PDF desenha cada sistema como traçados vetoriais e compõe os algarismos na Caslon embutida.

#5 · Abrir o capítulo com um título rebaixado

script.js · linhas 55–72no código completo

const opener = {
  enabled: true,
  minHeight: mm(48),
  slot: { elements: [
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', fontFamily: LABEL, fontSize: pt(8.5),
      fontWeight: 700, letterSpacing: pt(1.7), textTransform: 'uppercase', color: col('accent'),
      align: 'left', placement: { anchor: { to: 'container', edge: 'top-left' },
        offset: { x: mm(0), y: mm(12) } } },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: 'Libre Caslon Display',
      fontSize: pt(34), lineHeight: 1.05, color: col('ink'), align: 'left', overflow: 'wrap',
      placement: { anchor: { to: '#kicker', edge: 'below' }, offset: { x: mm(0), y: mm(3) },
        size: { width: mm(110), height: 'auto' } } },
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(1.5),
      color: col('accent'),
      placement: { anchor: { to: '#title', edge: 'below' }, offset: { x: mm(0), y: mm(5) },
        size: { width: mm(16) } } },
  ] },
};

A abertura tira o chapéu do atributo kicker do título e reserva 48 mm, o bastante para o título e o seu fio com o primeiro exemplo ainda na página 1.

A receita completa

Sandbox

// ═══ Postext Cookbook · Nº 163 · Harmony textbook with ABC examples ═════════════
// https://postext.dev/en/cookbook/harmony-textbook-abc-examples
// Code: MIT · Text: original (CC BY 4.0) · Music: Greensleeves (traditional, PD)
// Fonts: Libre Caslon Text & Display, Libre Franklin (SIL OFL 1.1) · Needs postext ≥ 1.54.0
import {
  buildDocumentWithFonts, renderPageToCanvas, initMusicEngine,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'harmony-textbook-abc-examples';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a conservatory green for the accents, warm ink for text and notes
const palette = {
  ink: '#1f1c19', // text and notation: a warm near-black
  accent: '#2f5d4f', // kickers, rules, Roman numerals in the table
  tint: '#edf2ef', // the box of key terms
  rule: '#c3cfc9', // hairlines
  muted: '#5c6863', // running heads, colophon
  paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to main-color: point it at the accent, never the default blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion
const TRIM = { width: 180, height: 250 };
const MARGIN = { top: 22, bottom: 24, inner: 22, outer: 33 }; // a 125 mm measure
const LEAD = 14.5; // body leading in pt: the baseline grid
const LABEL = 'Libre Franklin';

// #region answer: one score style for every example in the text
// Each ```abc fence in the chapter is engraved at the width of the text column and cut
// into systems. The style is set once here; the Markdown only holds the notation.
const scoreStyle = {
  staffSize: mm(5.5), // a textbook's rastral: examples read at arm's length on a desk
  musicFont: 'Bravura', // the traditional engraved look, heavy enough beside Caslon
  textFont: 'Libre Caslon Text', // the Roman numerals of `w:` lines, in the text face
  spacing: 1.6, // air between the chords: an example reads as a progression, not a cluster
  barNumbers: 'system',
  systemGap: mm(4),
  marginTop: pt(LEAD / 2),
  marginBottom: pt(LEAD / 2),
  color: col('ink'),
  // A long example runs on into the next page between two systems, never leaving one

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

#Usar Leland para uma página mais leve

Leland, a fonte do MuseScore, tem hastes mais finas e cabeças de nota menores que a Bravura; combina com um livro composto numa fonte de texto leve.

-  musicFont: 'Bravura',
+  musicFont: 'Leland',

#Escrever uma segunda voz em outro formato

O leitor de ABC aceita uma só voz. Para soprano e baixo em pautas separadas, escreva o exemplo em Humdrum ou MusicXML; o método de conservatório compõe assim corais a quatro vozes.

Erros comuns

Escreva a duração de um acorde dentro dos colchetes, [B2d2g2], ou ajuste L: ao valor do acorde: uma duração depois do colchete, [Bdg]2, é lida como a duração padrão.
O leitor de ABC do Verovio dá cada sílaba de uma linha w: à nota seguinte e ignora * e _, então uma linha w: não pode pular notas. Para marcar alguns compassos, escreva as marcas como cifras sobre a pauta, como faz o exemplo de Greensleeves.
Uma fonte de texto raramente tem os sinais ♯ e ♭: escreva “fá sustenido” no texto, ou o navegador põe o sinal com uma fonte do sistema.

Créditos

Receita: Ignacio Ferro
Texto: The chapter on cadences and its examples, written for this recipe · Ignacio Ferro · CC BY 4.0
Greensleeves, English tune of the sixteenth century, in its common modern form · Traditional · domínio público
Fontes: Libre Caslon Text (SIL OFL 1.1) · Libre Caslon Display (SIL OFL 1.1) · Libre Franklin (SIL OFL 1.1)
Código: MIT, como o Postext

Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)

Em poucas palavras

#O que você vai compor

#A resposta curta

#Ingredientes

#Preparo

#1 · Escrever o exemplo onde o texto precisa dele

#2 · Dar a cada partitura a aparência do livro

#3 · Deixar um exemplo longo continuar

#4 · Iniciar o gravador antes da composição

#5 · Abrir o capítulo com um título rebaixado

#A receita completa

#Variações

#Usar Leland para uma página mais leve

#Escrever uma segunda voz em outro formato

#Erros comuns

#Créditos

Mais das Receitas

Uma família de boxes de livro didático com código de cores

Livro didático com coluna na margem

Um livro de leitura escolar com furigana em cada kanji