Saltar al contingut principal

Capítol 18 · Part III · La pràctica

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

Un sol executable autònom, per a macOS, Linux i Windows, que converteix un llibre .postext, una carpeta de llibre o fitxers Markdown solts en PDF, HTML, EPUB, imatges de pàgina i Word. També crea paquets i revisa llibres, i pot respondre en JSON per a scripts i agents

Actualitzat 2026-11-0614 minenescadefritptzhjaar

En poques paraules

Aquesta pàgina és per a qui vol fer llibres amb Postext des d'un terminal en lloc del web. Baixes un sol fitxer per al teu ordinador i l'executes, sense instal·lar res més. Li dones el teu llibre, o uns quants fitxers de text, i en fa un PDF, una pàgina web, un llibre electrònic, imatges de les pàgines o un document de Word. També pot revisar un llibre per trobar-hi problemes i reunir tots els fitxers del llibre en un de sol. També el poden fer servir altres programes i els assistents d'intel·ligència artificial, perquè pot respondre en un format que llegeixen sense dificultat.

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

Al Sandbox escrius i dissenyes un llibre mentre el veus. La línia d'ordres agafa el mateix llibre i en genera 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é crea i desfà 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 mateixa del Sandbox: el mateix llibre es reparteix en les mateixes pàgines.

#Com obtenir-lo

Amb Homebrew, a macOS o Linux:

brew install drnachio/postext/postext

Amb Scoop, a Windows:

scoop bucket add postext https://github.com/drnachio/scoop-postext
scoop install postext

Tots dos instal·len l'executable de la darrera versió com a ordre postext, comprovat amb la seva suma de verificació, i brew upgrade postext o scoop update postext porten la següent. Sense gestor de paquets, baixa tu mateix el fitxer.

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

FitxerSistema
postext-macos-arm64macOS amb Apple silicon (M1 i posteriors)
postext-macos-x64macOS amb Intel
postext-linux-x64Linux x86-64 amb glibc (Debian, Ubuntu, Fedora…)
postext-linux-arm64Linux ARM64 amb glibc (Raspberry Pi OS de 64 bits, servidors ARM al núvol)
postext-linux-x64-muslLinux x86-64 amb musl (Alpine; executa abans apk add libstdc++ libgcc)
postext-windows-x64.exeWindows x64

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 de quarantena una sola 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 alfabètic del 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 està:

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 preset.json, els capítols, els recursos i les fonts. És el que lliura la skill per a agents, i postext unpack en crea una.
  • Markdown solt: un o més fitxers .md, un capítol per fitxer en l'ordre en què els dones, o una carpeta amb fitxers .md, que es prenen per ordre de 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 família que indiquen les taules de cada fitxer;
    • --name "Title": el nom del llibre.

--config també funciona amb un paquet o una carpeta: es combina amb la configuració pròpia del llibre i hi té prioritat. Un paquet en diverses llengües es llegeix en la llengua principal, tret que --locale en demani una altra (--locale en).

#Ordres

OrdreQuè fa
pdfEl PDF, amb marcadors, enllaços, fonts incrustades i, per defecte, etiquetat per a l'accessibilitat (PDF/UA); PDF/X i CMYK per a impremta.
htmlLes pàgines en HTML amb text real: un fitxer autònom, o una carpeta amb index.html i assets/.
epubUn llibre EPUB 3, amb pàgines fixes com les impreses o amb text adaptable.
imageUna pàgina com a imatge PNG, JPEG o WebP.
imagesTotes les pàgines, o un interval, com a imatges en una carpeta.
docxEls capítols com un document de Word: semàntic (només el contingut, en estils de Word senzills), maquetat (el mateix text editable amb el disseny del llibre) o facsímil de pàgines (cada línia en un quadre de text fix).
idmlLes pàgines com un paquet d'InDesign (IDML), per acabar-les a InDesign.
import-docxLes correccions fetes en un fitxer de Word exportat, de tornada al llibre; qualsevol altre document de Word, com a llibre nou (una carpeta o un .postext).
import-idmlUn document d'InDesign desat com a IDML, com a llibre nou (una carpeta o un .postext).
packUna carpeta de llibre o Markdown solt com un sol fitxer .postext.
unpackUn fitxer .postext com a carpeta.
infoEls capítols, les llengües, els recursos i les fonts del llibre, i amb --pages el nombre de pàgines.
checkCompon el llibre i informa de cada problema; per a impremta, el preflight.
buildCompon el llibre una vegada i escriu diverses de les sortides anteriors; amb --watch es queda en marxa i el torna a generar cada vegada que deses.

Cada ordre escriu a la carpeta des d'on l'executes, amb el nom de l'entrada, tret que indiquis una altra ruta amb -o (images escriu dins de pages/). -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 paràmetres del mateix llibre (vegeu Generació de PDF i Producció per a impremta); aquestes opcions els canvien només 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 paràmetres 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 imposa una de les dues formes sigui quina sigui la 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 es mencionen pel nom, però no es copien. Si la família indica un fallback, se n'escriuen en lloc seu les cares d'aquesta família oberta, amb el nom de la família original (des de postext 1.43).

#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 pantalla (vegeu Llibres EPUB). La coberta és la miniatura del llibre, tret que indiquis una imatge amb --cover. Les metadades del paquet (títol, autors, llengua, identificador) surten del frontmatter del primer capítol, com al Sandbox. Les fonts marcades redistributable: false no es copien; una família que indica un fallback s'incrusta amb les cares d'aquesta família oberta, però amb el nom original (des de postext 1.43).

#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'indiquen pel número imprès (12, iv, un interval 7-9) o per la posició al llibre, amb # (#1 és la primera pàgina, porti el número que porti; #10-#20; #30-, fins al final). --pages accepta una llista separada per comes. Les pàgines es pinten com a la pestanya Canvas del Sandbox, de manera 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 tal com la reproduirà la impremta, convertida amb el perfil de sortida i amb el tall i la sang dibuixats.
  • --jobs N: quantes imatges es codifiquen alhora (per defecte, tantes com processadors té l'ordinador).

#docx i import-docx

postext docx book.postext -o book.docx
postext docx book/ --variant semantic -o words.docx
postext docx book/ --variant facsimile -o pages.docx
postext import-docx book.docx book/ --dry-run
postext import-docx book.docx book/
postext import-docx manuscript.docx -o manuscript/ --locale es --report

docx escriu els documents de Word que exporta el Sandbox (vegeu Sandbox › Documents de Word) i un tercer. --variant formatted, el valor per defecte, construeix un document editable a partir del Markdown, amb els títols, les llistes, les notes al peu, les taules, les equacions i les seccions propis de Word, compost amb el disseny del llibre fins on Word ho permet i amb les fonts del llibre incrustades (--no-embed-fonts només les anomena); el que no té estructura a Word viatja com a font en controls de contingut Postext Source. --variant semantic escriu el mateix text com a contingut sol: un document senzill (A4, una columna, Arial) en estils de Word que diuen què és cada part, sense res del disseny de la pàgina i sense fonts incrustades. Cap dels dos no necessita compondre; tots dos s'obren a Word i a Google Docs, i tots dos tornen amb import-docx. --variant facsimile compon el llibre com ho fa pdf i escriu cada pàgina com una secció de Word, amb cada línia en un quadre de text fix i les fonts incrustades: un fitxer per mirar la composició al Word d'escriptori, no per editar ni per a Google Docs. Una família que el llibre no pot cedir (redistributable: false a customFonts) es deixa fora i hi entra l'alternativa oberta, com a l'EPUB; una font la llicència de la qual prohibeix incrustar-la, una amb contorns PostScript i una font variable es notifiquen i només s'anomenen. A build, --docx FITXER escriu el mateix fitxer, amb --docx-variant i --no-docx-fonts. Des de postext 1.68; --template ja no s'aplica a docx ni a build.

Amb un llibre després del fitxer, import-docx recupera les correccions fetes en un document que docx va exportar des d'aquest llibre. Llegeix el mapa que porta el fitxer, compara el text amb la còpia dels capítols feta a l'exportació i combina cada correcció amb el llibre tal com és ara: els fitxers de capítol d'una carpeta, d'un .postext o de Markdown solt, i el text dels recursos (peus, notes, text alternatiu, cel·les de taula) a preset.json, o al resources.json de --resources DIR si és Markdown solt. En un llibre amb diverses llengües, --locale indica l'edició des de la qual es va exportar el fitxer, i la correcció del text d'un recurs va al bloc localized d'aquella edició. Cada correcció es notifica en una línia pròpia:

  • applied, amb el fitxer i la línia on ha anat;
  • conflict: el text també ha canviat al llibre des de l'exportació, el capítol o el recurs ja no existeix, o dues correccions es superposen;
  • rejected: text que genera el mateix llibre (números, etiquetes de peu) o un format que travessa el marcatge de Postext.

Els canvis amb control de canvis es prenen com a acceptats, i els comentaris s'enumeren amb l'autor i el lloc, però no s'escriuen. El codi de sortida és 3 si una correcció no s'ha aplicat. --dry-run (-n) imprimeix l'informe i un diff unificat de cada fitxer que canviaria, i no escriu res. Cada fitxer s'escriu al costat del seu destí i es reanomena a sobre, de manera que una execució interrompuda no deixa mai mig capítol; un fitxer de capítol que ha canviat mentre s'executava la importació es deixa com està, amb un avís docx.fileChanged. -o no va amb un llibre. Amb --json, la resposta porta variant, exportId, edits (cadascuna amb status, reason, kind, before, after i at), comments, files i, en una prova en sec, diff.

Un fitxer editat a Google Docs i baixat com a .docx també torna. Docs no hi desa el mapa ni la còpia dels capítols; la importació torna a escriure el mapa a partir del llibre, i ho diu a l'informe. Com que aquest fitxer no porta cap còpia del text exportat, es compara amb el llibre tal com és ara. Si el llibre ha canviat des de l'exportació, l'informe n'avisa, i un canvi fet mentrestant al llibre pot aparèixer com una edició que el desfà. Importa un fitxer de Docs al llibre del qual es va exportar, abans de canviar aquest llibre; un fitxer desat per Word conserva el mapa i es combina amb els canvis posteriors del llibre. Docs també elimina el marcador ocult d'un text que se substitueix sencer (un títol, una cel·la de taula, un peu, el títol d'un requadre, una nota al peu). La importació troba aquest text pel lloc que ocupa entre els seus veïns, de manera que un títol continua sent un títol i un peu va al seu recurs. Quan això no es pot decidir, per exemple perquè també s'ha escrit un paràgraf al costat i res no els distingeix, l'informe mostra una supressió i una addició en lloc seu. Importar el mateix fitxer una segona vegada no porta res.

Sense cap llibre, import-docx converteix qualsevol document de Word en un llibre nou: crea un capítol a cada títol de nivell 1 (amb --no-split, un de sol), converteix les imatges i les taules en recursos, i amb --report imprimeix l'informe de qualitat que mostra el Sandbox (estils en ús, format directe, numeració escrita a mà…). --template indica una plantilla d'importació (un .json desat des del Sandbox o un .docx que en contingui una).

L'espaiat entre caràcters és una propietat de l'estil, no del text, i per això no apareix al Markdown. docx escriu el letterSpacing dels estils de paràgraf, dels estils de títol i dels nivells de títol com a espaiat entre caràcters de l'estil de Word, i import-docx el torna a llegir en em de la mida de l'estil: l'assigna com a letterSpacing als estils del llibre que encara no en tenen (els estils de paràgraf i de títol del fitxer de --config als quals corresponen els estils de Word, i els nivells de títol), i no toca els espaiats que el llibre ja defineix. Amb --json, styleTracking enumera el que s'ha aplicat (applied) i el que s'ha deixat (skipped). Des de postext 1.39.

#idml

postext idml book/ -o book.idml
postext idml book.postext -o book.idml --images link
postext idml book/ -o out/book.idml --lines reflow --fonts

idml compon el llibre com ho fa pdf i escriu les pàgines com un paquet d'InDesign Markup, per acabar-lo a InDesign: les pàgines en plecs a banda i banda del llom en un llibre amb marges de pàgines enfrontades (una pàgina per plec en qualsevol altre), filets, requadres, traçats i imatges com a elements de pàgina, les taules com a taules d'InDesign, el text de cada marc d'una pàgina composta com un marc de text amb la seva pròpia història (els marcs encadenats amb next en comparteixen una), els estils de requadre com a estils de paràgraf i els colors CMYK d'autor com a mostres. Els xips amb camp de formulari passen a ser camps de formulari d'InDesign. --lines keep (el valor per defecte) acaba cada línia on la va acabar Postext, de manera que InDesign mostra les mateixes línies que el PDF; --lines reflow deixa els paràgrafs al compositor d'InDesign, i els salts de línia poden variar. --images link deixa les imatges al costat del fitxer, a Links/, en lloc de dins. --fonts escriu els fitxers de font de les variants usades al costat del paquet, a Document fonts/, on InDesign els troba per a aquell document; necessita que -o anomeni un fitxer, i una família que el llibre no pot redistribuir es deixa fora amb un avís. El que el paquet no pot portar tal com és al llibre (el text vertical, el marc arrodonit d'una taula) es notifica com a avís idml.*. El generador és el paquet postext-idml: vegeu Ús programàtic › Paquets d'InDesign. A build, --idml FITXER escriu el mateix paquet, amb --idml-images, --idml-lines i --idml-fonts. Des de postext 1.71; --lines i --fonts, des de 1.76.

#import-idml

postext import-idml book.idml -o book/
postext import-idml book.idml -o book.postext --layout flow --links pictures/
postext import-idml book.idml --report --json

import-idml llegeix un paquet d'InDesign Markup i escriu un llibre nou, en una carpeta o en un .postext: els capítols en Markdown, la configuració que donen els estils i les pàgines del document, i les seves imatges i taules com a recursos. Un .indd no es llegeix: desa'l abans des d'InDesign com a InDesign Markup. --layout pages segueix el document pàgina a pàgina amb pàgines compostes, cada marc on era; --layout flow escriu un llibre de text seguit, en ordre de lectura i amb els estils del document, perquè Postext el torni a compondre; auto (el valor per defecte) en tria un i diu per què. Les imatges enllaçades es llegeixen de --links o, si no s'indica, de la carpeta del fitxer i del seu Links/, i les que no es troben s'enumeren. També s'enumeren les fonts que anomena el document: un paquet no porta fitxers de font, de manera que cal donar-los amb --font-dir en generar el llibre.

Un llibre exportat des de Postext torna amb les mateixes línies. Un document fet a InDesign es llegeix amb pèrdues: l'ordre imprimeix el veredicte (faithful, approximate o lossy), els recomptes i el que s'ha perdut o aproximat; --report hi afegeix les notes i com s'ha llegit cada estil de paràgraf, i --json ho porta tot com a dades. --hidden, --pasteboard i --non-printing llegeixen també les capes i els objectes ocults, la taula de muntatge i els objectes no imprimibles; --conditions all llegeix tot el text condicional, --changes reject llegeix els canvis registrats com si s'haguessin rebutjat i --no-masters deixa fora els elements de les pàgines mestres. --name i --locale donen el títol i la llengua. L'importador és idmlToPostext, del paquet postext-idml: vegeu Ús programàtic › Paquets d'InDesign.

#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 està, o construeix un paquet a partir de Markdown solt. La mateixa entrada dona sempre els mateixos bytes, de manera que es poden comparar paquets o calcular-ne el hash. Per al Markdown solt, --id, --description i --thumbnail FILE (una imatge de coberta) fixen l'id, la descripció i la miniatura del paquet; per defecte l'id és un slug del nom. Una carpeta conserva el que diu el seu preset.json. Un llibre que no indica coberta rep la primera pàgina com a coberta (thumbnail.jpg, 1024 px al costat llarg), la imatge que un gestor de fitxers pot mostrar per al fitxer; --no-auto-thumbnail l'omet. unpack es nega a escriure en una carpeta que no sigui buida, tret que hi afegeixis --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 pàgines), els recursos i cada família tipogràfica amb la procedència (el llibre, una carpeta, l'executable, la memòria cau de baixades o la font de reserva). Si el llibre indica on comença (start a preset.json: un extracte que s'obre a la pàgina 58, al capítol 4), també ho mostra, i totes les ordres componen el llibre a partir d'aquest punt.

check compon el llibre i informa del mateix que mostra el tauler 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, paràmetres 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. També llista el text que no es llegeix bé sobre el fons (contrast), un cop per parell de colors, amb la ràtio en pantalla i, per a impremta, sobre el paper del perfil de sortida. 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 si hi ha --strict.

També avisa quan els textos dels dissenys de la configuració contenen text del llibre en lloc de marcadors (contentInConfig), un cop per estil de títol, capçalera o disseny de part, amb el camí de cada text: passa aquest text al Markdown, o afegeix el títol o el nom de l'editorial a checks.contentInConfig.allow.

En un llibre amb plantilles de pàgina, check també informa del text que no cap al marc (frameOverflow, amb els passos que ha provat l'escala de reajustament i els canvis que ho arreglarien), d'una història que ocupa més pàgines de les que un marc pot afegir (frameContinuationLimit), d'un salt a una pàgina que no ve a continuació (continueTargetMissing), dels rètols de figura que no es poden dibuixar o que se superposen (labelAnchorUnknown, anchorUnlabelled, labelOverflow, labelOverlap), dels marcs que queden amagats sota uns altres marcs o que sobrepassen la seva vora (frameCovered, frameOutsideArea), de més targetes de les que cap en una retícula (repeatOverflow) i dels mòduls que una pàgina no pot compondre (moduleUnknown, moduleAsPage, moduleNested, moduleNameRejected). Després dels avisos imprimeix una línia reflow per cada pàgina composta amb esdeveniments, i --json inclou com a dades els passos, les propostes i el registre de reajustament. Vegeu Pàgines compostes › Avisos i Registre de reajustament.

#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, --idml), 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. Si en desar el llibre queda trencat, imprimeix l'error i conserva els últims fitxers bons.

#Opcions per a qualsevol llibre

OpcióQuè fa
--locale TAGLa llengua en què es llegeix un llibre en diverses llengües (es, en, pt-BR…).
--chapters LISTCompon només alguns capítols: 2, 1,3-5, 4-. És més ràpid en un llibre llarg; les pàgines es numeren a partir de la primera pàgina d'aquests capítols.
--set PATH=VALUECanvia un paràmetre per a aquesta execució, indicat com una ruta amb punts: --set page.dpi=150, --set bodyText.fontFamily=Lora, --set headings.levels.0.italic=true. El valor es llegeix com a JSON quan és possible (números, true i false, objectes) i, si no, com a text. Es pot repetir.
--config FILEUna configuració (o un preset.json) per a Markdown solt, o que es combina amb la del llibre i hi té prioritat.
--resources DIR, --fonts DIR, --name TEXTImatges, fonts i títol per a Markdown solt.
--font-dir DIRUna carpeta on buscar les fonts que el llibre no porta. Es pot repetir.
--offlineNo baixa mai fonts.
--cache-dir DIROn es desen les fonts baixades.

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

#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 esmenta 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 desen a la memòria cau, així que cada família es baixa una sola vegada.

Un pes que la família no té es compon amb la font que triaria un navegador (la selecció de fonts de CSS: per sobre de 500, primer les més pesants; per sota de 400, primer les més lleugeres; així, en una família amb 400 i 700, el 600 es compon amb el 700, i el 550 també). Una inclinació que la família no té es compon amb la rodona. En tots dos casos la font es fa servir tal com és, tant a les imatges de pàgina com al PDF: una família de retolació amb un sol pes fa servir les mateixes lletres per a la negreta, i una família sense cursiva, la rodona.

Es baixen els pesos que esmenta la configuració: rodona, negreta i les cursives corresponents per a cada família, i qualsevol altre pes que indiqui un paràmetre, inclòs el de la negreta (bodyText.boldFontWeight: 600 demana la font de pes 600). Si no s'ha pogut carregar un pes que la família sí que té (sense connexió i sense fitxer a la memòria cau, una baixada fallida, una carpeta de fonts sense el fitxer), el text es compon amb la font de la família que triaria la mateixa regla, i postext check en dona un avís fontFallback: les línies es poden tallar d'una altra manera que al Sandbox.

Un caràcter per al qual una font no té glif es dibuixa amb una altra font. postext check llegeix la taula cmap de cada font que carrega i mostra aquests caràcters un cop per font per a tot el llibre com a avís glyphFallback; amb --json, el seu data porta els caràcters i quants són.

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, però conserva el nom, de manera que la maquetació i el PDF continuen coincidint, i un avís missingFont en dona el nom. postext info mostra d'on ha sortit cada família.

Un paquet que no inclou els fitxers d'una família amb llicència pot indicar-ne una família oberta d'amplada semblant (fallback a les fonts del manifest, des de postext 1.42). Llavors postext busca aquesta família seguint els passos anteriors i compon les cares que el llibre no porta amb les variants del mateix pes i inclinació de la família oberta, però amb el nom de la família amb llicència. Així la maquetació s'assembla a la que s'obtindria amb els fitxers, i postext check no en dona cap avís missingFont. D'una família que el llibre porta només en part, del fallback només se'n pren la inclinació que hi falta. El PDF incrusta la cara oberta.

#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 l'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), o import-docx ha deixat fora una correcció de Word.
  • Cap pregunta. No espera mai que l'usuari escrigui res; si la carpeta no és buida, la rebutja en lloc de preguntar què cal fer.
  • Sortida estàndard: -o - hi escriu un PDF, una imatge o un paquet, per passar-lo a una altra ordre amb una canonada.
  • 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 en trigui la 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.

#Python

pip install postext converteix la línia d'ordres en una biblioteca de Python. El paquet és Python pur, sense dependències, i la seva versió és la de postext. La primera vegada que executa una ordre baixa l'executable del teu sistema de la GitHub Release d'aquesta versió, el comprova amb SHA256SUMS i el desa a la memòria cau de més amunt, a bin/<versió>/. Si POSTEXT_BIN apunta a un executable que ja tens (de Homebrew, d'Scoop o compilat per tu), no es baixa res.

import postext
 
report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300}, locale="es")
print(report.output.pages)
for warning in report.warnings:
    print(warning.kind, warning.at, warning.message)
 
pdf = postext.pdf_bytes(open("book.postext", "rb").read())
  • Una funció per ordre: pdf, html, epub, image, images, docx, import_docx, pack, unpack, info, check i build. Les opcions conserven el nom, amb guions baixos (color_space, font_dirs, dry_run). set rep un diccionari, config un fitxer o un diccionari, chapters un número, una llista, un range o "1,3-5".
  • Informes com a objectes. Cada funció executa la seva ordre amb --json i retorna l'informe: outputs, pages, timings i warnings, cada avís un Diagnostic amb kind, severity, message, at i page. info hi afegeix chapters, resources i fonts; check, passed, error_count i warning_count.
  • Errors com a excepcions. Una fallada llança PostextError; una opció equivocada, UsageError. Quan check troba errors llança ProblemsFound, el report del qual els enumera; amb raise_on_problems=False retorna l'informe.
  • Bytes. Un llibre es pot donar com els bytes d'un paquet .postext. Amb out="-" el fitxer torna a report.content; pdf_bytes, html_bytes, epub_bytes, image_bytes, docx_bytes i pack_bytes el retornen directament.
  • postext.Postext(binary, cwd=…, timeout=…) fa servir un executable concret, i python -m postext … és la mateixa línia d'ordres.

Cada crida torna a engegar l'executable. El README del paquet recull totes les opcions.

#Com està fet

La línia d'ordres és el paquet postext-cli del repositori. Bun el compila, juntament amb el motor i els generadors, en un executable per sistema, i Skia (a través de @napi-rs/canvas) mesura i pinta el text, com fa el canvas del navegador al Sandbox. Les il·lustracions SVG que contenen un mapa de bits (un PNG o un JPEG incrustat com a URI de dades, que és com pdftocairo -svg escriu les il·lustracions retallades d'un PDF) les dibuixa resvg, perquè el renderitzador d'SVG de Skia omet aquestes imatges. 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 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, de Google Fonts o de Fontsource (per a una família que Google Fonts no té), mai de les fonts instal·lades a l'ordinador, així que un llibre surt igual a qualsevol màquina.
  • La llengua del text és, en un navegador, la del mateix document (bodyText.shapingLanguage: 'document', el valor per defecte des de postext 1.30). El canvas de Skia accepta una llengua, però conforma el text sense tenir-la en compte, així que la línia d'ordres mesura les formes de la llengua per defecte de cada font i compon sempre els llibres amb shapingLanguage: 'host', digui el que digui la configuració; el PDF i les imatges de pàgina pinten aquestes mateixes formes. Si la font d'un llibre té formes pròpies per a una llengua (una l·l catalana, un fi turc, les xifres d'una font xinesa en un llibre anglès), aquí es compon amb les formes per defecte. El que 'document' mesura d'una altra manera (les parts d'una paraula partida a final de línia, una paraula de dreta a esquerra, un text de disseny) es mesura aquí com ho mesura 'host', així que una línia es pot partir per una altra paraula que al Sandbox.