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
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/postextAmb Scoop, a Windows:
scoop bucket add postext https://github.com/drnachio/scoop-postext
scoop install postextTots 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:
| Fitxer | Sistema |
|---|---|
postext-macos-arm64 | macOS amb Apple silicon (M1 i posteriors) |
postext-macos-x64 | macOS amb Intel |
postext-linux-x64 | Linux x86-64 amb glibc (Debian, Ubuntu, Fedora…) |
postext-linux-arm64 | Linux ARM64 amb glibc (Raspberry Pi OS de 64 bits, servidors ARM al núvol) |
postext-linux-x64-musl | Linux x86-64 amb musl (Alpine; executa abans apk add libstdc++ libgcc) |
postext-windows-x64.exe | Windows 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
./postextMou-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-arm64A Windows, al PowerShell:
Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exeSi 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.pdfEl 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.pdfUn 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, ipostext unpacken 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 unpreset.jsonsencer;--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 unresources.json, les descriu aquest fitxer (ids, tipus, peus, text alternatiu), amb la mateixa forma que elsresourcesd'unpreset.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
| Ordre | Què fa |
|---|---|
pdf | El PDF, amb marcadors, enllaços, fonts incrustades i, per defecte, etiquetat per a l'accessibilitat (PDF/UA); PDF/X i CMYK per a impremta. |
html | Les pàgines en HTML amb text real: un fitxer autònom, o una carpeta amb index.html i assets/. |
epub | Un llibre EPUB 3, amb pàgines fixes com les impreses o amb text adaptable. |
image | Una pàgina com a imatge PNG, JPEG o WebP. |
images | Totes les pàgines, o un interval, com a imatges en una carpeta. |
docx | Els 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). |
idml | Les pàgines com un paquet d'InDesign (IDML), per acabar-les a InDesign. |
import-docx | Les 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-idml | Un document d'InDesign desat com a IDML, com a llibre nou (una carpeta o un .postext). |
pack | Una carpeta de llibre o Markdown solt com un sol fitxer .postext. |
unpack | Un fitxer .postext com a carpeta. |
info | Els capítols, les llengües, els recursos i les fonts del llibre, i amb --pages el nombre de pàgines. |
check | Compon el llibre i informa de cada problema; per a impremta, el preflight. |
build | Compon 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.
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-outlinesEl 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,ifra26i 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 singleUna 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-100per 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 --reportdocx 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 --fontsidml 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 --jsonimport-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 --jsoninfo 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 --watchbuild 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 TAG | La llengua en què es llegeix un llibre en diverses llengües (es, en, pt-BR…). |
--chapters LIST | Compon 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=VALUE | Canvia un paràmetre per a aquesta execució, indicat com una ruta amb punts: --set page.dpi=150, --set bodyText., --set headings.. 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 FILE | Una 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 TEXT | Imatges, fonts i títol per a Markdown solt. |
--font-dir DIR | Una carpeta on buscar les fonts que el llibre no porta. Es pot repetir. |
--offline | No baixa mai fonts. |
--cache-dir DIR | On 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:
- a les carpetes indicades amb
--font-dir; - entre les fonts compilades dins de l'executable: EB Garamond i Open Sans, les del motor per defecte;
- a la memòria cau de baixades;
- 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ó.
--jsonimprimeix 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:
0fet,1error,2ús incorrecte (una opció desconeguda, una entrada que falta),3checkha trobat errors (o avisos amb--strict), oimport-docxha 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
--chaptersambimageoimages --pages. Per treballar en un llibre al llarg de molts canvis, deixa en marxapostext build --watchi 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,checkibuild. Les opcions conserven el nom, amb guions baixos (color_space,font_dirs,dry_run).setrep un diccionari,configun fitxer o un diccionari,chaptersun número, una llista, unrangeo"1,3-5". - Informes com a objectes. Cada funció executa la seva ordre amb
--jsoni retorna l'informe:outputs,pages,timingsiwarnings, cada avís unDiagnosticambkind,severity,message,atipage.infohi afegeixchapters,resourcesifonts;check,passed,error_countiwarning_count. - Errors com a excepcions. Una fallada llança
PostextError; una opció equivocada,UsageError. Quanchecktroba errors llançaProblemsFound, elreportdel qual els enumera; ambraise_on_problems=Falseretorna l'informe. - Bytes. Un llibre es pot donar com els bytes d'un paquet
.postext. Ambout="-"el fitxer torna areport.content;pdf_bytes,html_bytes,epub_bytes,image_bytes,docx_bytesipack_bytesel retornen directament. postext.Postext(binary, cwd=…, timeout=…)fa servir un executable concret, ipython -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 --currentstart 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.
--chapterscompon 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 ambshapingLanguage: '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 (unal·lcatalana, unfiturc, 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.