Línia d'ordres: postext en un terminal, un script o un agent

postext compon el teu llibre des d'un terminal, un script o un agent.

Al Sandbox escrius i dissenyes un llibre veient-lo. La línia d'ordres pren el mateix llibre i en produeix els fitxers sense navegador: un PDF a punt per a impremta, les pàgines en HTML, un EPUB, la imatge d'una pàgina o de totes, un document de Word. També empaqueta i desempaqueta paquets .postext, importa documents de Word, descriu un llibre i el revisa per trobar-hi problemes.

És un sol executable autònom per sistema. A dins hi ha el motor de postext, els generadors de PDF, EPUB, HTML i Word, el pintor de pàgines (Skia), HarfBuzz per a l'àrab i altres escriptures complexes, els perfils ICC d'impremta i les fonts per defecte (EB Garamond i Open Sans). No cal instal·lar cap entorn d'execució, paquet ni biblioteca, i la maquetació és la del Sandbox: el mateix llibre es parteix en les mateixes pàgines.

#Com obtenir-lo

Cada versió de Postext publica els executables a la seva GitHub Release, amb les seves sumes de verificació (SHA256SUMS) i un readme.txt:

Cada fitxer pesa entre 115 i 140 MB. L'enllaç https://github.com/drnachio/postext/releases/latest/download/<file> sempre dona el més recent.

A Linux o macOS:

curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
chmod +x postext
./postext

Mou-lo a una carpeta del teu PATH (/usr/local/bin, ~/.local/bin) per executar-lo com a postext des de qualsevol lloc. macOS posa en quarantena els fitxers baixats amb un navegador; treu-li la marca una vegada:

xattr -d com.apple.quarantine postext-macos-arm64

A Windows, al PowerShell:

Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exe

Si tens Node.js instal·lat, npx postext-cli baixa d'npm l'executable del teu sistema i l'executa, i npm install -g postext-cli el deixa instal·lat com a ordre postext.

Sense arguments, postext mostra l'ajuda; postext help <command> llista les opcions d'una ordre.

#Un primer llibre

Tres fitxers Markdown en una carpeta ja són un llibre, un capítol per fitxer, per ordre de nom:

postext pdf chapters/ --name "Field notes" -o field-notes.pdf

El frontmatter del primer capítol dona al llibre el títol i l'autor, i els valors per defecte del motor fan la resta: dues columnes, una retícula de línies de base, text justificat i amb partició de mots, capçaleres. Afegeix-hi una configuració i imatges quan les necessitis:

postext pdf chapters/ --config design.json --resources pictures/ -o field-notes.pdf

Un llibre fet al Sandbox (Llibres → Baixar (.postext)) funciona tal com és:

postext pdf my-book.postext -o my-book.pdf
postext image my-book.postext --page 1 -o cover.png

#Què pot ser un llibre

Totes les ordres que llegeixen un llibre accepten qualsevol d'aquestes formes:

• Un fitxer .postext: el paquet que el Sandbox exporta i obre (vegeu Paquets).
• Una carpeta de llibre: un paquet desempaquetat, amb el seu preset.json, els capítols, els recursos i les fonts. És el que lliura la skill per a agents, i postext unpack n'escriu una.
• Markdown solt: un o més fitxers .md, un capítol per fitxer en l'ordre en què els dones, o una carpeta els fitxers .md de la qual es prenen per nom (01-intro.md, 02-method.md…). Amb aquests fitxers:
  • --config design.json: la configuració, sigui un objecte de configuració sol o un preset.json sencer;
  • --resources pictures/: les imatges, cadascuna una figura amb el nom del fitxer sense l'extensió (map.png és ::resource{id="map"}); si a la carpeta hi ha un resources.json, les descriu aquest fitxer (ids, tipus, peus, text alternatiu), amb la mateixa forma que els resources d'un preset.json;
  • --fonts fonts/: fitxers de fonts que porta el llibre (TTF, OTF, WOFF2), amb el nom de la família que indiquen les seves taules;
  • --name "Title": el nom del llibre.

--config també funciona amb un paquet o una carpeta: es combina per sobre de la configuració pròpia del llibre. Un paquet en diverses llengües es llegeix en la seva llengua tret que --locale en demani una altra (--locale en).

#Ordres

Cada ordre escriu a la carpeta des d'on l'executes, amb el nom de l'entrada, tret que -o en doni la ruta. -o - escriu una única sortida a la sortida estàndard.

#pdf

postext pdf book.postext -o book.pdf
postext pdf book/ --pdfx x4 --profile fogra51 -o book-print.pdf
postext pdf book/ --color-space grayscale --no-outlines

El PDF segueix els ajustos del mateix llibre (vegeu Generació de PDF i Producció per a impremta); aquestes opcions els canvien per a una execució:

• --pdfx none|x1a|x4: l'estàndard PDF/X per a una impremta.
• --profile NAME|FILE: el perfil ICC de sortida, pel nom (fogra39, fogra51, fogra52, swop5, gracol2006, snap2007, ifra26 i els altres perfils dels ajustos d'impremta) o un fitxer .icc.
• --color-space rgb|cmyk|grayscale.
• --accessible / --no-accessible: l'estructura etiquetada per als lectors de pantalla.
• --no-outlines: deixa fora els marcadors.
• --page-negative: pàgines en negatiu, per a alguns fluxos d'impremta.

#html

postext html book.postext -o book.html
postext html book.postext -o site/ --mode single

Una ruta acabada en .html dona un sol fitxer amb les imatges i les fonts a dins, fàcil d'enviar. Qualsevol altra ruta és una carpeta: index.html al costat d'assets/, que conté les imatges, les fonts i els vídeos allotjats al llibre. --assets embed|folder tria una de les dues formes per a qualsevol ruta. Les pàgines són la maquetació impresa, mostrada a mida de pantalla: l'una al costat de l'altra (--mode multi, per defecte) o l'una sota l'altra (--mode single). Les fonts marcades redistributable: false s'anomenen però no es copien.

#epub

postext epub book.postext -o book.epub
postext epub book.postext --layout reflowable --cover cover.jpg

--layout fixed (per defecte) conserva cada pàgina com la impresa, amb text seleccionable; --layout reflowable deixa que el sistema de lectura torni a compondre el text per a la seva pantalla (vegeu Llibres EPUB). La coberta és la miniatura del llibre tret que --cover en doni una imatge. Les metadades del paquet (títol, autors, llengua, identificador) surten del frontmatter del primer capítol, com al Sandbox.

#image i images

postext image book.postext --page 12 -o page-12.png
postext image book.postext --page "#1" --dpi 300 -f jpeg -o cover.jpg
postext images book.postext -o pages/ --dpi 100
postext images book.postext --pages 1-10,iv -f webp --pattern "{chapter}-{label}"

Les pàgines s'anomenen com estan impreses (12, iv, un interval 7-9) o per la seva posició al llibre amb # (#1 és la primera pàgina, imprimeixi el que imprimeixi, #10-#20, #30- fins al final). --pages accepta una llista separada per comes. El pintor és el de la pestanya Canvas del Sandbox, així que una imatge mostra la pàgina exactament com s'ha compost, sense passar per un PDF.

• --format png|jpeg|webp (o l'extensió de -o), --quality 1-100 per a JPEG i WebP.
• --dpi: la resolució, 150 per defecte; amb 72–100 n'hi ha prou per llegir una pàgina, 300 per a impremta.
• --pattern: els noms de fitxer d'images, a partir de {n} (la posició; {n:03} l'emplena fins a tres xifres), {label} (el número imprès) i {chapter}; per defecte, page-{n:03}.
• --print-preview: la pàgina com la reproduirà la impremta, passada pel perfil de sortida, amb el tall i la sang dibuixats.
• --jobs N: quantes imatges es codifiquen alhora.

#docx i import-docx

postext docx book.postext -o book.docx
postext import-docx manuscript.docx -o manuscript/ --locale es --report
postext import-docx manuscript.docx -o manuscript.postext

docx escriu els capítols amb estils de Word per als títols, els paràgrafs, els requadres, les cites, les llistes i les notes. El que el Word no pot expressar es conserva tal com està escrit amb els estils Postext Markup, i la plantilla d'importació viatja dins del fitxer, de manera que el document es torna a importar sense canvis després que un editor hi hagi treballat. import-docx converteix un document de Word en un llibre: un capítol a cada títol de nivell 1 (--no-split en deixa un de sol), les imatges i les taules com a recursos, i --report imprimeix l'informe de qualitat que mostra el Sandbox (estils en ús, format directe, numeració escrita a mà…). --template pren una plantilla d'importació (un .json desat des del Sandbox o un .docx que en porti una).

#pack i unpack

postext pack my-book/ -o my-book.postext
postext pack 01.md 02.md --name "Notes" --config design.json --resources img/ -o notes.postext
postext unpack my-book.postext -o my-book/

pack comprimeix en zip una carpeta de llibre tal com és, o construeix un paquet a partir de Markdown solt. La mateixa entrada dona sempre els mateixos bytes, així que un paquet es pot comparar o se'n pot calcular el hash. unpack es nega a escriure en una carpeta que no sigui buida tret que es doni --force.

#info i check

postext info book.postext --pages
postext check book.postext
postext check chapters/ --strict --json

info llista els capítols (títol, paraules, fitxer i, amb --pages, les seves pàgines), els recursos i cada família tipogràfica amb la seva procedència (el llibre, una carpeta, l'executable, la memòria cau de baixades o la font de reserva). Si el llibre diu on comença (start a preset.json: un extracte que obre a la pàgina 58, al capítol 4), també ho mostra, i totes les ordres componen el llibre des d'aquí.

check compon el llibre i informa del mateix que mostra el Tauler de revisió del Sandbox: Markdown que no es tanca, recursos, directives i estils desconeguts, requadres que la maquetació ha hagut de forçar, fonts que falten, ajustos que el motor ha hagut de substituir i, en un llibre preparat per a impremta (o amb --preflight), el preflight: imatges de baixa resolució, filets fins, text petit en diverses tintes, tinta per sobre del límit, text a prop del tall. Cada problema indica el fitxer del capítol, la línia i la pàgina. El codi de sortida és 3 quan troba un error, o qualsevol avís amb --strict.

#build i --watch

postext build book/ --pdf out/book.pdf --html out/book.html --images out/pages --pages 1-4
postext build chapters/ --pdf book.pdf --watch

build compon el llibre una vegada i escriu totes les sortides que indiquis (--pdf, --html, --epub, --images, --docx), amb les opcions de cada ordre. --watch es queda en marxa: quan canvia un capítol, la configuració o una imatge, torna a compondre el llibre amb les fonts i el motor encara carregats, normalment en una fracció de segon per capítol, i torna a escriure les sortides. Un desament que trenca el llibre imprimeix l'error i conserva els últims fitxers bons.

#Opcions per a qualsevol llibre

I per a qualsevol ordre: --json, --quiet (-q, només errors), --verbose (el progrés i tots els avisos), --no-color, --help.

#Fonts

Un llibre que porta les seves fonts (un paquet, o --fonts amb Markdown solt) es compon amb aquestes fonts i cap altra. Per a cada família que anomena la configuració i que el llibre no porta, postext busca, per aquest ordre:

1. a les carpetes indicades amb --font-dir;
2. entre les fonts compilades dins de l'executable: EB Garamond i Open Sans, les del motor per defecte;
3. a la memòria cau de baixades;
4. a Google Fonts, que dona fitxers TrueType estàtics complets, o a Fontsource si Google Fonts no té la família (Commit Mono, FiraGO); es guarden a la memòria cau, així que cada família es baixa una sola vegada.

Un pes o una inclinació que la família no porta es compon amb la seva font més propera tal com és, a les imatges de pàgina igual que al PDF: una família de retolació amb un sol pes conserva les seves lletres a la negreta, i una família sense cursiva, les rodones.

La memòria cau és ~/.cache/postext (%LOCALAPPDATA%\postext\cache a Windows); POSTEXT_CACHE_DIR o --cache-dir la canvien de lloc. --offline s'estalvia la baixada. Una família que no es troba enlloc es compon en EB Garamond amb el seu propi nom, de manera que la maquetació i el PDF continuen coincidint, i un avís missingFont l'anomena. postext info mostra d'on ha sortit cada família.

#Per a scripts i agents

La línia d'ordres està pensada perquè la facin servir altres programes, també els agents de programació.

• --json imprimeix un objecte JSON a la sortida estàndard quan l'ordre acaba; tots els missatges van a la sortida d'error estàndard. L'informe llista el que s'ha escrit, les pàgines, cada avís amb el seu origen i quant ha durat cada pas (en mil·lisegons):

{
  "ok": true,
  "command": "pdf",
  "version": "1.22.1",
  "book": { "name": "notes", "id": "notes", "locale": "en", "chapters": 2 },
  "pages": 3,
  "outputs": [{ "kind": "pdf", "path": "notes.pdf", "bytes": 29746, "pages": 3 }],
  "warnings": [
    {
      "kind": "unknownResourceId",
      "severity": "warning",
      "message": "Unknown resource id \"map\" in ::resource — nothing is embedded (offset 26)",
      "at": "notes/02-more.md:5"
    }
  ],
  "timings": { "read": 13, "fonts": 8.4, "math": 28.2, "layout": 51.6, "pdf": 132.1, "total": 1638 },
  "exitCode": 0
}

• Codis de sortida: 0 fet, 1 error, 2 ús incorrecte (una opció desconeguda, una entrada que falta), 3 check ha trobat errors (o avisos amb --strict).
• Cap pregunta. No espera mai cap entrada; una carpeta que no és buida es rebutja en lloc de preguntar què cal fer.
• Sortida estàndard: -o - hi escriu un PDF, una imatge o un paquet, per passar-lo per una canonada a una altra ordre.
• Velocitat. L'executable arrenca en unes quantes centèsimes de segon. Un llibre curt es converteix en un PDF o en la imatge d'una pàgina en molt menys d'un segon; un de llarg triga el que trigui la seva maquetació (una novel·la il·lustrada de 140 pàgines, uns deu segons). Per mirar unes quantes pàgines d'un llibre llarg, combina --chapters amb image o images --pages. Per treballar en un llibre al llarg de molts canvis, deixa en marxa postext build --watch i llegeix-ne les sortides.

La skill per a agents fa servir la línia d'ordres per pintar les pàgines en què treballa i per revisar un port.

#Com està fet

La línia d'ordres és el paquet postext-cli del repositori. Bun el compila, amb el motor i els seus generadors, en un executable per sistema, i Skia (a través de @napi-rs/canvas) mesura i pinta el text, com ho fa el canvas del navegador al Sandbox. A cada versió, els executables es construeixen, s'executen a Linux, Alpine, macOS i Windows i s'adjunten a la GitHub Release; npm rep postext-cli i un paquet postext-cli-<system> per executable.

Per executar-lo des d'una còpia del repositori:

pnpm install
pnpm --filter postext-cli start pdf book.postext
pnpm --filter postext-cli build:bin --current

start l'executa des del codi font; build:bin escriu l'executable d'aquest ordinador a packages/postext-cli/bin/.

#Diferències amb el Sandbox

• L'HTML és la maquetació impresa mostrada a mida de pantalla. La pestanya HTML del Sandbox torna a compondre el text per a la finestra.
• --chapters compon els capítols per separat: la numeració de les seves pàgines torna a començar, mentre que el Sandbox continua la numeració del llibre.
• Les fonts surten del llibre, de les teves carpetes, de l'executable o de Google Fonts, mai de les fonts instal·lades a l'ordinador, així que un llibre surt igual a qualsevol màquina.