Kapitel 18 · Teil III · In der Praxis
Kommandozeile: postext im Terminal, in einem Skript oder einem Agenten
Eine eigenständige ausführbare Datei für macOS, Linux und Windows. Sie wandelt ein .postext-Buch, einen Buchordner oder lose Markdown-Dateien in PDF, HTML, EPUB, Seitenbilder und Word um, packt Pakete, prüft Bücher und liefert JSON-Ausgabe für Skripte und Agenten
Kurz gesagt
Diese Seite richtet sich an alle, die Bücher mit Postext im Terminal statt auf der Website machen wollen. Sie laden eine einzige Datei für Ihren Computer herunter und führen sie aus, ohne etwas zu installieren. Sie geben ihr Ihr Buch oder ein paar Textdateien, und sie erzeugt ein PDF, eine Webseite, ein E-Book, Bilder der Seiten oder ein Word-Dokument. Sie kann ein Buch auch auf Probleme prüfen und seine Dateien zu einer einzigen packen. Auch Programme und KI-Assistenten können sie nutzen, denn sie kann in einem Format antworten, das diese leicht lesen.
postext setzt Ihr Buch aus einem Terminal, einem Skript oder einem Agenten heraus.
In der Sandbox schreiben und gestalten Sie ein Buch nach Augenmaß. Die
Kommandozeile nimmt dasselbe Buch und erzeugt seine Dateien ohne Browser:
ein druckfertiges PDF, die Seiten als HTML, ein EPUB, ein Bild einer Seite oder aller
Seiten, ein Word-Dokument. Außerdem packt und entpackt sie .postext-Pakete, importiert
Word-Dokumente, beschreibt ein Buch und prüft es auf Probleme.
Sie ist eine eigenständige ausführbare Datei pro System. Die Postext-Engine, die Schreiber für PDF, EPUB, HTML und Word, der Renderer für die Seiten (Skia), HarfBuzz für Arabisch und andere komplexe Schriftsysteme, die ICC-Druckprofile und die Standardschriften (EB Garamond und Open Sans) stecken alle darin. Es gibt keine Laufzeitumgebung, kein Paket und keine Bibliothek zu installieren, und das Layout ist das der Sandbox: Dasselbe Buch bricht in dieselben Seiten um.
#Herunterladen
Mit Homebrew unter macOS oder Linux:
brew install drnachio/postext/postextMit Scoop unter Windows:
scoop bucket add postext https://github.com/drnachio/scoop-postext
scoop install postextBeide installieren die ausführbare Datei des neuesten Release als Befehl
postext, geprüft anhand ihrer Prüfsumme, und brew upgrade postext bzw.
scoop update postext holt das nächste. Ohne Paketmanager laden Sie die
Datei selbst herunter.
Jedes Release von Postext veröffentlicht die ausführbaren Dateien in seinem
GitHub Release, zusammen mit
ihren Prüfsummen (SHA256SUMS) und einer readme.txt:
| Datei | System |
|---|---|
postext-macos-arm64 | macOS auf Apple Silicon (M1 und neuer) |
postext-macos-x64 | macOS auf Intel |
postext-linux-x64 | Linux x86-64 mit glibc (Debian, Ubuntu, Fedora …) |
postext-linux-arm64 | Linux ARM64 mit glibc (Raspberry Pi OS 64 Bit, ARM-Server in der Cloud) |
postext-linux-x64-musl | Linux x86-64 mit musl (Alpine; vorher apk add libstdc++ libgcc ausführen) |
postext-windows-x64.exe | Windows x64 |
Jede Datei ist zwischen 115 und 140 MB groß. Der Link
https://github.com/drnachio/postext/releases/latest/download/<file> liefert
immer die neueste.
Unter Linux oder macOS:
curl -fL -o postext https://github.com/drnachio/postext/releases/latest/download/postext-linux-x64
chmod +x postext
./postextVerschieben Sie sie in einen Ordner in Ihrem PATH (/usr/local/bin, ~/.local/bin), um sie
von überall als postext aufzurufen. macOS stellt eine mit einem Browser heruntergeladene
Datei unter Quarantäne; entfernen Sie die Markierung einmal:
xattr -d com.apple.quarantine postext-macos-arm64Unter Windows in PowerShell:
Invoke-WebRequest https://github.com/drnachio/postext/releases/latest/download/postext-windows-x64.exe -OutFile postext.exe
.\postext.exeIst Node.js installiert, lädt npx postext-cli die ausführbare Datei für Ihr
System von npm herunter und führt sie aus, und npm install -g postext-cli behält sie als
Befehl postext.
Ohne Argumente aufgerufen, gibt postext seine Hilfe aus; postext help <command>
listet die Optionen eines Befehls auf.
#Ein erstes Buch
Drei Markdown-Dateien in einem Ordner sind ein Buch, je ein Kapitel, in der Reihenfolge der Namen:
postext pdf chapters/ --name "Field notes" -o field-notes.pdfDas Frontmatter des ersten Kapitels gibt dem Buch Titel und Autor, und die Standardwerte der Engine erledigen den Rest: zwei Spalten, ein Grundlinienraster, Text im Blocksatz mit Silbentrennung, Kolumnentitel. Fügen Sie eine Konfiguration und Bilder hinzu, wenn Sie sie brauchen:
postext pdf chapters/ --config design.json --resources pictures/ -o field-notes.pdfEin in der Sandbox erstelltes Buch (Bücher → .postext exportieren) funktioniert so, wie es ist:
postext pdf my-book.postext -o my-book.pdf
postext image my-book.postext --page 1 -o cover.png#Was ein Buch sein kann
Jeder Befehl, der ein Buch liest, akzeptiert jede dieser Formen:
- Eine
.postext-Datei: das Paket, das die Sandbox exportiert und öffnet (siehe Pakete). - Ein Buchordner: ein entpacktes Paket mit seiner
preset.json, seinen Kapiteln, Ressourcen und Schriften. Der Agent-Skill liefert so etwas, undpostext unpackschreibt einen. - Lose Markdown-Dateien: eine oder mehrere
.md-Dateien, je ein Kapitel in der angegebenen Reihenfolge, oder ein Ordner, dessen.md-Dateien nach Namen sortiert genommen werden (01-intro.md,02-method.md…). Dazu:--config design.json: die Konfiguration, entweder ein bloßes Konfigurationsobjekt oder eine ganzepreset.json;--resources pictures/: die Bilder, jedes eine Abbildung, benannt nach seinem Dateinamen ohne Endung (map.pngist::resource{id="map"}); eineresources.jsonim Ordner beschreibt sie stattdessen (IDs, Typen, Legenden, Alternativtext), in derselben Form wie dieresourceseinerpreset.json;--fonts fonts/: Schriftdateien, die das Buch mitbringt (TTF, OTF, WOFF2), benannt nach der Familie, die ihre Tabellen angeben;--name "Title": der Name des Buchs.
--config funktioniert auch bei einem Paket oder einem Ordner: Es wird über die eigene
Konfiguration des Buchs gelegt. Ein mehrsprachiges Paket wird in seiner eigenen Sprache gelesen, es sei denn,
--locale verlangt eine andere (--locale en).
#Befehle
| Befehl | Was er tut |
|---|---|
pdf | Das PDF, mit Lesezeichen, Links, eingebetteten Schriften und standardmäßig für Barrierefreiheit getaggt (PDF/UA); PDF/X und CMYK für den Druck. |
html | Die Seiten als HTML mit echtem Text: eine eigenständige Datei oder ein Ordner mit index.html und assets/. |
epub | Ein EPUB-3-Buch, mit festen Seiten wie gedruckt oder umfließendem Text. |
image | Eine Seite als PNG-, JPEG- oder WebP-Bild. |
images | Alle Seiten oder einen Bereich als Bilder in einem Ordner. |
docx | Die Kapitel als Word-Dokument: semantisch (der Inhalt allein, in schlichten Word-Formatvorlagen), gesetzt (derselbe bearbeitbare Text im Design des Buchs) oder als Seitenfaksimile (jede Zeile in einem festen Textfeld). |
idml | Die Seiten als InDesign-Paket (IDML), zur Fertigstellung in InDesign. |
import-docx | Die Korrekturen aus einer exportierten Word-Datei zurück ins Buch; jedes andere Word-Dokument als neues Buch (ein Ordner oder eine .postext-Datei). |
import-idml | Ein als IDML gespeichertes InDesign-Dokument als neues Buch (ein Ordner oder eine .postext-Datei). |
pack | Einen Buchordner oder lose Markdown-Dateien als eine einzige .postext-Datei. |
unpack | Eine .postext-Datei als Ordner. |
info | Kapitel, Sprachen, Ressourcen und Schriften des Buchs, mit --pages auch seine Seitenzahl. |
check | Setzt das Buch und meldet jedes Problem; für den Druck auch den Preflight. |
build | Setzt das Buch einmal und schreibt mehrere der obigen Ausgabeformate; --watch läuft weiter und baut bei jedem Speichern neu. |
Jeder Befehl schreibt in das Verzeichnis, in dem Sie ihn aufrufen, benannt nach der Eingabe, es sei denn,
-o gibt den Pfad an (images schreibt in pages/). -o - schreibt eine einzelne Ausgabe auf die Standardausgabe.
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-outlinesDas PDF folgt den eigenen Einstellungen des Buchs (siehe PDF-Erzeugung und Druckvorstufe); diese Optionen ändern sie für einen Lauf:
--pdfx none|x1a|x4: der PDF/X-Standard für eine Druckerei.--profile NAME|FILE: das ICC-Ausgabeprofil, über seinen Namen (fogra39,fogra51,fogra52,swop5,gracol2006,snap2007,ifra26und die übrigen Profile der Druckeinstellungen) oder eine.icc-Datei.--color-space rgb|cmyk|grayscale.--accessible/--no-accessible: die getaggte Struktur für Screenreader.--no-outlines: die Lesezeichen weglassen.--page-negative: negative Seiten, für manche Druckabläufe.
#html
postext html book.postext -o book.html
postext html book.postext -o site/ --mode singleEin Pfad, der auf .html endet, ergibt eine einzige Datei mit den Bildern und Schriften darin,
leicht zu verschicken. Jeder andere Pfad ist ein Ordner: index.html neben assets/, das
die Bilder, die Schriften und selbst gehostete Videos enthält. --assets embed|folder
wählt für jeden Pfad die eine oder andere Variante. Die Seiten sind das Drucklayout, in
Bildschirmgröße gezeigt: nebeneinander (--mode multi, Standard) oder untereinander
(--mode single). Schriften mit der Markierung redistributable: false werden genannt, aber nicht
kopiert. Gibt die Familie einen fallback an, werden stattdessen die Schnitte dieser freien Familie unter dem Namen der Familie geschrieben (seit postext 1.43).
#epub
postext epub book.postext -o book.epub
postext epub book.postext --layout reflowable --cover cover.jpg--layout fixed (Standard) behält jede Seite wie gedruckt, mit markierbarem
Text; --layout reflowable lässt das Lesesystem den Text für seinen Bildschirm
neu setzen (siehe EPUB-Bücher). Das
Cover ist das Vorschaubild des Buchs, es sei denn, --cover gibt ein Bild an. Die
Metadaten des Pakets (Titel, Autoren, Sprache, Kennung) kommen aus dem Frontmatter
des ersten Kapitels, wie in der Sandbox. Schriften mit redistributable: false werden nicht kopiert; eine Familie, die einen fallback angibt, wird mit den Schnitten dieser freien Familie unter ihrem eigenen Namen eingebettet (seit postext 1.43).
#image und 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}"Seiten werden wie gedruckt benannt (12, iv, ein Bereich 7-9) oder nach ihrer Position
im Buch mit # (#1 ist die erste Seite, egal, welche Nummer sie trägt, #10-#20,
#30- bis zum Ende). --pages nimmt eine kommagetrennte Liste an. Gezeichnet wird wie in
der Canvas-Ansicht der Sandbox, ein Bild zeigt die Seite also genau so, wie sie gesetzt ist,
ohne den Umweg über ein PDF.
--format png|jpeg|webp(oder die Endung von-o),--quality 1-100für JPEG und WebP.--dpi: Auflösung, standardmäßig 150; 72–100 genügen, um eine Seite zu lesen, 300 für den Druck.--pattern: die Dateinamen vonimages, aus{n}(die Position,{n:03}auf drei Ziffern aufgefüllt),{label}(die gedruckte Nummer) und{chapter}; standardmäßigpage-{n:03}.--print-preview: die Seite so, wie die Druckerei sie wiedergeben wird, über das Ausgabeprofil, mit eingezeichnetem Endformat und Anschnitt.--jobs N: wie viele Bilder gleichzeitig kodiert werden (standardmäßig so viele, wie der Rechner Prozessoren hat).
#docx und 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 schreibt die Word-Dokumente, die die Sandbox exportiert (siehe
Sandbox › Word-Dokumente), und
ein drittes. --variant formatted, die Voreinstellung, baut aus dem Markdown
ein bearbeitbares Dokument mit Überschriften, Listen, Fußnoten, Tabellen,
Formeln und Abschnitten von Word selbst, im Design des Buchs, so weit Word es
zulässt, und mit den eingebetteten Schriften des Buchs (--no-embed-fonts nennt
sie nur); wofür Word keine Struktur hat, das reist als Quelltext in
Inhaltssteuerelementen Postext Source. --variant semantic schreibt denselben
Text als reinen Inhalt: ein schlichtes Dokument (A4, eine Spalte, Arial) in
Word-Formatvorlagen, die jeden Teil benennen, ohne Seitendesign und ohne
eingebettete Schriften. Keines von beiden braucht ein Layout; beide lassen sich
in Word und in Google Docs öffnen, und beide kommen über import-docx zurück.
--variant facsimile setzt das Buch wie pdf und schreibt jede Seite als
Word-Abschnitt, jede Zeile in einem festen Textfeld, mit eingebetteten
Schriften: eine Datei, um das Layout in Word auf dem Desktop anzusehen, nicht
zum Bearbeiten und nicht für Google Docs. Eine Familie, die das Buch nicht
weitergeben darf (redistributable: false in customFonts), bleibt draußen,
und ihr freier Ersatz kommt hinein, wie im EPUB; eine Schrift, deren Lizenz das
Einbetten verbietet, eine mit PostScript-Konturen und eine variable Schrift
werden gemeldet und nur genannt. In build schreibt --docx DATEI dieselbe
Datei, mit --docx-variant und --no-docx-fonts. Seit postext 1.68;
--template gilt nicht mehr für docx und build.
Mit einem Buch nach der Datei bringt import-docx die Korrekturen zurück, die
in einem von docx aus diesem Buch exportierten Dokument gemacht wurden. Es
liest die Karte, die die Datei mitführt, vergleicht den Text mit der beim
Export gemachten Kopie der Kapitel und führt jede Korrektur mit dem Buch
zusammen, wie es jetzt ist: die Kapiteldateien eines Ordners, einer
.postext-Datei oder loser Markdown-Dateien, und den Wortlaut der Ressourcen
(Legenden, Anmerkungen, Alternativtext, Tabellenzellen) in preset.json, bei
losem Markdown in der resources.json von --resources DIR. Bei einem Buch in
mehreren Sprachen nennt --locale die Ausgabe, aus der die Datei exportiert
wurde, und eine Korrektur am Wortlaut einer Ressource geht in den
localized-Block dieser Ausgabe. Jede Korrektur wird in einer eigenen Zeile
gemeldet:
applied, mit der Datei und Zeile, in die sie ging;conflict: Der Text hat sich seit dem Export auch im Buch geändert, das Kapitel oder die Ressource gibt es nicht mehr, oder zwei Korrekturen überschneiden sich;rejected: Text, den das Buch selbst erzeugt (Nummern, Legendenbezeichnungen), oder Formatierung, die über Postext-Markup hinwegläuft.
Nachverfolgte Änderungen gelten als angenommen, und Kommentare werden mit
Autor und Stelle aufgeführt, aber nicht geschrieben. Der Exit-Code ist 3, wenn
eine Korrektur nicht übernommen wurde. --dry-run (-n) gibt den Bericht und
ein Unified Diff jeder Datei aus, die sich ändern würde, und schreibt nichts.
Jede Datei wird neben ihr Ziel geschrieben und darüber umbenannt, sodass ein
abgebrochener Lauf nie ein halbes Kapitel hinterlässt; eine Kapiteldatei, die
sich während des Imports geändert hat, bleibt mit einer Warnung
docx.fileChanged unangetastet. -o passt nicht zu einem Buch. Mit --json
enthält die Antwort variant, exportId, edits (jeweils mit status,
reason, kind, before, after und at), comments, files und bei
einem Probelauf diff.
Auch eine Datei, die in Google Docs bearbeitet und als .docx heruntergeladen
wurde, kommt zurück. Docs lässt die Karte und die Kopie der Kapitel weg; der
Import schreibt die Karte aus dem Buch neu, und sagt das im Bericht. Weil diese
Datei keine Kopie des exportierten Texts mitführt, wird sie mit dem Buch
verglichen, wie es jetzt ist. Hat sich das Buch seit dem Export geändert, warnt
der Bericht davor, und eine inzwischen im Buch gemachte Änderung kann als
Bearbeitung erscheinen, die sie zurücknimmt. Importieren Sie eine Docs-Datei in
das Buch, aus dem sie exportiert wurde, bevor Sie dieses Buch ändern; eine von
Word gespeicherte Datei behält ihre Karte und wird mit späteren Änderungen am
Buch zusammengeführt. Docs entfernt außerdem das verborgene Lesezeichen eines
Texts, der ganz ersetzt wird (eine Überschrift, eine Tabellenzelle, eine
Legende, ein Kastentitel, eine Fußnote). Der Import findet einen solchen Text an
seinem Platz zwischen seinen Nachbarn; eine Überschrift bleibt also eine
Überschrift, und eine Legende geht an ihre Ressource. Lässt sich das nicht
entscheiden, etwa weil daneben auch ein Absatz getippt wurde und nichts die
beiden unterscheidet, zeigt der Bericht stattdessen eine Löschung und eine
Hinzufügung. Dieselbe Datei ein zweites Mal zu importieren, bringt nichts.
Ohne Buch macht import-docx aus jedem Word-Dokument ein neues Buch: ein
Kapitel an jeder Überschrift der Ebene 1 (--no-split behält eines), Bilder
und Tabellen als Ressourcen, und --report gibt den Qualitätsbericht aus, den
die Sandbox zeigt (verwendete Formatvorlagen, direkte Formatierung, getippte
Nummerierung …). --template nimmt eine Importvorlage an (eine aus der Sandbox
gespeicherte .json-Datei oder eine .docx-Datei, die eine enthält).
Der Zeichenabstand gehört zur Formatvorlage, nicht zum Text, und steht deshalb nicht im
Markdown. docx schreibt das letterSpacing der Absatzformate, der Überschriftenstile
und der Überschriftenebenen als Zeichenabstand der Word-Formatvorlage, und import-docx
liest ihn in em der Schriftgröße der Vorlage zurück: Er wird als letterSpacing bei den Formaten
des Buchs gesetzt, die keinen eigenen haben (den Absatzformaten und Überschriftenstilen der
--config-Datei, denen die Word-Formatvorlagen entsprechen, und den Überschriftenebenen);
einen Zeichenabstand, den das Buch schon festlegt, lässt er unverändert. Mit --json führt
styleTracking auf, was gesetzt wurde (applied) und was übrig blieb (skipped). Seit 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 setzt das Buch wie pdf und schreibt die Seiten als
InDesign-Markup-Paket, zur Fertigstellung in InDesign: die Seiten in
Druckbögen beiderseits des Rückens bei einem Buch mit Rändern für
gegenüberliegende Seiten (sonst eine Seite je Druckbogen), Linien, Kästen,
Pfade und Bilder als Seitenobjekte, Tabellen als InDesign-Tabellen, der Text
jedes Rahmens einer zusammengesetzten Seite als Textrahmen mit eigenem
Textabschnitt (mit next verkettete Rahmen teilen sich einen), Kastenstile
als Absatzformate und vom Autor angelegte CMYK-Farben als Farbfelder. Chips
mit einem Formularfeld werden zu InDesign-Formularfeldern. --lines keep
(Standard) beendet jede Zeile dort, wo Postext sie beendet hat, sodass
InDesign dieselben Zeilen zeigt wie das PDF; --lines reflow überlässt die
Absätze dem Setzer von InDesign, und die Zeilenumbrüche können abweichen.
--images link legt die Bilder neben der Datei in Links/ ab, statt sie in
die Datei zu packen. --fonts schreibt die Schriftdateien der verwendeten
Schnitte neben das Paket, nach Document fonts/, wo InDesign sie für dieses
Dokument findet; dafür muss -o eine Datei nennen, und eine Familie, die das
Buch nicht weitergeben darf, bleibt mit einer Warnung draußen. Was das Paket
nicht so tragen kann, wie es im Buch steht (senkrechter Text, der abgerundete
Rahmen einer Tabelle), wird als Warnung idml.* gemeldet. Der Export ist das
Paket postext-idml: siehe Programmatische Nutzung ›
InDesign-Pakete.
In build schreibt --idml DATEI dasselbe Paket, mit --idml-images, --idml-lines und --idml-fonts.
Seit postext 1.71; --lines und --fonts seit 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 liest ein InDesign-Markup-Paket und schreibt ein neues Buch, als Ordner oder als .postext-Datei: die Kapitel als Markdown, die Konfiguration, die sich aus den Formaten und Seiten des Dokuments ergibt, und seine Bilder und Tabellen als Ressourcen. Eine .indd-Datei wird nicht gelesen: Speichern Sie sie vorher in InDesign als InDesign Markup. --layout pages folgt dem Dokument Seite für Seite mit zusammengesetzten Seiten, jeder Rahmen dort, wo er stand; --layout flow schreibt ein Buch mit fließendem Text, in Lesereihenfolge und mit den Formaten des Dokuments, das Postext neu setzt; auto (Standard) wählt eines von beiden und nennt den Grund. Verknüpfte Bilder werden aus --links gelesen, sonst aus dem Ordner der Datei und dessen Links/, und die nicht gefundenen werden aufgelistet. Auch die Schriften, die das Dokument nennt, werden aufgelistet: Ein Paket enthält keine Schriftdateien, geben Sie sie also beim Erzeugen des Buchs mit --font-dir an.
Ein aus Postext exportiertes Buch kommt mit denselben Zeilen zurück. Ein in InDesign erstelltes Dokument wird mit Verlusten gelesen: Der Befehl gibt das Urteil (faithful, approximate oder lossy), die Zählungen und das Verlorene oder Angenäherte aus; --report ergänzt die Hinweise und wie jedes Absatzformat gelesen wurde, und --json trägt alles als Daten. --hidden, --pasteboard und --non-printing lesen auch ausgeblendete Ebenen und Objekte, die Montagefläche und nicht druckende Objekte; --conditions all liest den gesamten bedingten Text, --changes reject liest verfolgte Änderungen als abgelehnt, und --no-masters lässt die Objekte der Musterseiten weg. --name und --locale geben Titel und Sprache an. Der Import ist idmlToPostext aus dem Paket postext-idml: siehe Programmatische Nutzung › InDesign-Pakete.
#pack und 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 packt einen Buchordner so, wie er ist, als ZIP oder baut ein Paket aus losen Markdown-Dateien.
Dieselbe Eingabe ergibt immer dieselben Bytes, sodass sich ein Paket vergleichen oder
hashen lässt. Bei losen Markdown-Dateien setzen --id, --description und --thumbnail FILE
(ein Titelbild) die ID, die Beschreibung und das Vorschaubild des Pakets; die ID ist
standardmäßig ein Slug des Namens. Ein Ordner behält, was seine preset.json angibt. Ein Buch, das kein Titelbild angibt, erhält seine erste Seite als Titelbild (thumbnail.jpg, 1024 px an der langen Seite), das Bild, das ein Dateimanager für die Datei anzeigen kann; --no-auto-thumbnail lässt es weg. unpack weigert sich, in einen Ordner zu schreiben, der nicht leer ist, es sei denn,
--force ist angegeben.
#info und check
postext info book.postext --pages
postext check book.postext
postext check chapters/ --strict --jsoninfo listet die Kapitel auf (Titel, Wörter, Datei und mit --pages ihre
Seiten), die Ressourcen und jede Schriftfamilie mit ihrer Herkunft (Buch,
Ordner, ausführbare Datei, Download-Cache oder Ersatzschrift). Bei einem Buch, das angibt, wo es beginnt (start in preset.json: ein Auszug, der auf Seite 58 in Kapitel 4 einsetzt), gibt info auch das aus, und jeder Befehl setzt das Buch ab dort.
check setzt das Buch und meldet, was das Bedienfeld Prüfungen der Sandbox zeigt:
Markdown, das nicht geschlossen wird, unbekannte Ressourcen, Direktiven und Formate, Kästen,
die das Layout erzwingen musste, fehlende Schriften, Einstellungen, die die Engine
ersetzen musste, und bei einem für den Druck eingerichteten Buch (oder mit --preflight) den
Preflight: Bilder mit geringer Auflösung, Haarlinien, kleinen Text in mehreren Druckfarben, Farbauftrag
über dem Grenzwert, Text nahe am Endformat. Außerdem listet er den Text auf, der sich auf seinem
Grund nicht lesen lässt (contrast), einmal pro Farbpaar, mit dem Kontrastverhältnis auf dem Bildschirm
und für den Druck auf dem Papier des Ausgabeprofils. Jedes Problem nennt die
Kapiteldatei, die Zeile und die Seite. Der Exit-Code ist 3, wenn ein Fehler gefunden wird, oder mit --strict
bei jeder Warnung.
Außerdem meldet er Gestaltungstexte der Konfiguration, die den Text des
Buches statt Platzhaltern enthalten (contentInConfig), einmal je
Überschriftenstil, Kolumnentitel oder Teilgestaltung, mit dem Pfad jedes
Textes: Verschieben Sie diesen Text ins Markdown oder tragen Sie Titel oder
Verlagsnamen in checks.contentInConfig.allow ein.
Bei einem Buch mit Seitenvorlagen meldet check außerdem Text, der nicht in seinen Rahmen passt (frameOverflow, mit den Einpassstufen, die versucht wurden, und den Änderungen, die das Problem beheben würden), einen Artikel, der über die Seiten hinausläuft, die ein Rahmen anfügen darf (frameContinuationLimit), einen Sprung auf eine Seite, die nicht folgt (continueTargetMissing), Beschriftungen von Abbildungen, die sich nicht zeichnen lassen oder sich überschneiden (labelAnchorUnknown, anchorUnlabelled, labelOverflow, labelOverlap), Rahmen, die unter anderen Rahmen verborgen liegen oder über ihre Kante hinausragen (frameCovered, frameOutsideArea), mehr Karten, als ein Raster fasst (repeatOverflow), und Module, die eine Seite nicht setzen kann (moduleUnknown, moduleAsPage, moduleNested, moduleNameRejected). Nach den Warnungen gibt es pro zusammengesetzter Seite mit Ereignissen eine reflow-Zeile aus, und --json liefert die Schritte, die Vorschläge und das Umbruchprotokoll als Daten. Siehe Zusammengesetzte Seiten › Warnungen und Umbruchprotokoll.
#build und --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 setzt das Buch einmal und schreibt jedes Ausgabeformat, das Sie angeben (--pdf,
--html, --epub, --images, --docx, --idml), mit den Optionen des jeweiligen Befehls.
--watch bleibt aktiv: Wenn sich ein Kapitel, die Konfiguration oder ein Bild
ändert, wird das Buch neu gesetzt, wobei Schriften und Engine geladen bleiben,
für ein Kapitel typischerweise in einem Bruchteil einer Sekunde, und die Dateien werden
neu geschrieben. Führt eine gespeicherte Änderung zu einem Fehler, wird der Fehler ausgegeben,
und die zuletzt fehlerfreien Dateien bleiben erhalten.
#Optionen für jedes Buch
| Option | Was sie tut |
|---|---|
--locale TAG | Die Sprache, in der ein mehrsprachiges Buch gelesen wird (es, en, pt-BR …). |
--chapters LIST | Setzt nur einige Kapitel: 2, 1,3-5, 4-. Schneller bei einem langen Buch; ihre Seiten werden ab ihrer eigenen ersten Seite nummeriert. |
--set PATH=VALUE | Ändert eine Einstellung für diesen Lauf, als Pfad mit Punkten: --set page.dpi=150, --set bodyText., --set headings.. Der Wert wird als JSON gelesen, wenn das geht (Zahlen, true und false, Objekte), sonst als Text. Wiederholbar. |
--config FILE | Eine Konfiguration (oder eine preset.json) für lose Markdown-Dateien, oder über die eigene eines Buchs gelegt. |
--resources DIR, --fonts DIR, --name TEXT | Bilder, Schriften und Titel für lose Markdown-Dateien. |
--font-dir DIR | Ein Ordner, in dem nach Schriften gesucht wird, die das Buch nicht mitbringt. Wiederholbar. |
--offline | Nie Schriften herunterladen. |
--cache-dir DIR | Wo heruntergeladene Schriften aufbewahrt werden. |
Und für jeden Befehl: --json, --quiet (-q, nur Fehler), --verbose
(Fortschritt und jede Warnung), --no-color, --help (-h), --version (-v).
#Schriften
Ein Buch, das seine Schriften mitbringt (ein Paket oder --fonts bei losen Markdown-Dateien), wird
mit ihnen gesetzt und mit nichts anderem. Für jede Familie, die die Konfiguration nennt und
die das Buch nicht mitbringt, sucht postext der Reihe nach:
- in den mit
--font-dirangegebenen Ordnern; - unter den in die ausführbare Datei kompilierten Schriften: EB Garamond und Open Sans, die Standardschriften der Engine;
- im Download-Cache;
- bei Google Fonts, das ganze statische TrueType-Dateien liefert, oder bei Fontsource für eine Familie, die Google Fonts nicht hat (Commit Mono, FiraGO); sie werden im Cache aufbewahrt, sodass eine Familie nur einmal heruntergeladen wird.
Eine Schriftstärke, die eine Familie nicht mitliefert, wird in dem Schnitt gesetzt, den ein Browser dafür wählen würde (CSS-Font-Matching: über 500 zuerst die schwereren Schnitte, unter 400 zuerst die leichteren; bei einer Familie mit 400 und 700 wird eine 600 also zur 700, ebenso eine 550). Eine Neigung, die die Familie nicht mitliefert, wird in ihrem aufrechten Schnitt gesetzt. Beide Schnitte werden unverändert verwendet, in den Seitenbildern wie im PDF: Eine Displayschrift mit nur einer Schriftstärke behält auch für Fett ihre eigenen Buchstaben, und eine Familie ohne Kursive bleibt auch für Kursiv aufrecht.
Geladen werden die Schriftstärken, die die Konfiguration verlangt: für jede Familie normal und fett
samt ihren Kursiven, dazu jede andere Schriftstärke, die eine Einstellung angibt, auch die für Fett
(bodyText.boldFontWeight: 600 verlangt den Schnitt 600). Wenn sich eine
Schriftstärke, die die Familie mitliefert, nicht laden ließ (offline ohne Datei im Cache, ein
fehlgeschlagener Download, ein Schriftordner ohne die Datei), wird der Text in dem
Schnitt der Familie gesetzt, der nach derselben Regel dafür einspringt, und postext check
listet das als Warnung fontFallback auf: Die Zeilen dieses Textes können anders umbrechen als in der Sandbox.
Ein Zeichen, für das eine Schrift keine Glyphe hat, wird aus einer anderen Schrift gezeichnet. postext check liest die cmap-Tabelle jeder geladenen Schrift und meldet solche Zeichen einmal je Schrift für das ganze Buch als Warnung glyphFallback; mit --json enthält ihr data die Zeichen und ihre Anzahl.
Der Cache liegt in ~/.cache/postext (%LOCALAPPDATA%\postext\cache unter Windows);
POSTEXT_CACHE_DIR oder --cache-dir verlegt ihn. --offline überspringt den Download.
Eine nirgends gefundene Familie wird unter ihrem eigenen Namen in EB Garamond gesetzt, sodass Layout
und PDF weiterhin übereinstimmen, und eine Warnung missingFont nennt sie. postext info
zeigt, woher jede Familie stammt.
Ein Paket, das die Dateien einer lizenzierten Familie weglässt, kann dafür eine freie Familie ähnlicher Breite angeben (fallback in den fonts des Manifests, seit postext 1.42). postext sucht diese Familie dann nach den obigen Schritten und setzt die Schnitte, die das Buch nicht mitbringt, in deren Schnitten gleicher Stärke und Neigung unter dem Namen der lizenzierten Familie; das Layout kommt dem mit den Dateien nahe, und postext check meldet dafür kein missingFont. Eine Familie, die das Buch nur teilweise mitbringt, nimmt vom fallback nur die Neigung, von der sie keine Datei hat. Das PDF bettet die freie Schrift ein.
#Für Skripte und Agenten
Die Kommandozeile ist dafür gebaut, von anderen Programmen gesteuert zu werden, auch von Coding-Agenten.
--jsongibt am Ende des Befehls ein JSON-Objekt auf der Standardausgabe aus; jede Meldung geht auf die Standardfehlerausgabe. Der Bericht listet auf, was geschrieben wurde, die Seiten, jede Warnung mit ihrer Quelle und wie lange jeder Schritt gedauert hat (in Millisekunden):
{
"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
}- Exit-Codes:
0erledigt,1fehlgeschlagen,2falsche Verwendung (eine unbekannte Option, eine fehlende Eingabe),3checkhat Fehler gefunden (oder mit--strictWarnungen), oderimport-docxhat eine Word-Korrektur nicht übernommen. - Keine Rückfragen. Die Kommandozeile wartet nie auf eine Eingabe; ein Ordner, der nicht leer ist, wird abgelehnt, statt nachzufragen.
- Standardausgabe:
-o -schreibt ein PDF, ein Bild oder ein Paket dorthin, um es per Pipe weiterzureichen. - Geschwindigkeit. Die ausführbare Datei startet in wenigen Hundertstelsekunden. Ein kurzes
Buch wird in deutlich unter einer Sekunde zu einem PDF oder einem Seitenbild; ein langes braucht
so lange, wie sein Layout braucht (ein illustrierter Roman mit 140 Seiten etwa zehn Sekunden). Um
ein paar Seiten eines langen Buchs anzusehen, kombinieren Sie
--chaptersmitimageoderimages --pages. Um über viele Änderungen hinweg an einem Buch zu arbeiten, lassen Siepostext build --watchlaufen und lesen seine Ausgaben.
Der Agent-Skill verwendet die Kommandozeile, um die Seiten zu rendern, an denen er arbeitet, und um eine Portierung zu prüfen.
#Python
pip install postext macht die Kommandozeile zu einer Python-Bibliothek. Das
Paket ist reines Python ohne Abhängigkeiten, und seine Version ist die von
postext. Beim ersten Befehl lädt es die ausführbare Datei Ihres Systems aus dem
GitHub-Release dieser Version herunter, prüft sie gegen SHA256SUMS und legt
sie im oben beschriebenen Cache unter bin/<Version>/ ab. Zeigt POSTEXT_BIN
auf eine ausführbare Datei, die Sie schon haben (aus Homebrew, Scoop oder einem
eigenen Build), wird nichts heruntergeladen.
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())- Eine Funktion pro Befehl:
pdf,html,epub,image,images,docx,import_docx,pack,unpack,info,checkundbuild. Die Optionen behalten ihre Namen, mit Unterstrichen (color_space,font_dirs,dry_run).setnimmt ein Dictionary,configeine Datei oder ein Dictionary,chapterseine Zahl, eine Liste, einrangeoder"1,3-5". - Berichte als Objekte. Jede Funktion führt ihren Befehl mit
--jsonaus und gibt den Bericht zurück:outputs,pages,timingsundwarnings, jede Warnung einDiagnosticmitkind,severity,message,atundpage.infoergänztchapters,resourcesundfonts,checkergänztpassed,error_countundwarning_count. - Fehler als Ausnahmen. Ein Fehlschlag löst
PostextErroraus, eine falsche OptionUsageError. FindetcheckFehler, löst esProblemsFoundaus, dessenreportsie auflistet; mitraise_on_problems=Falsegibt es den Bericht zurück. - Bytes. Ein Buch kann als Bytes eines
.postext-Pakets übergeben werden. Mitout="-"kommt die Datei inreport.contentzurück;pdf_bytes,html_bytes,epub_bytes,image_bytes,docx_bytesundpack_bytesgeben sie direkt zurück. postext.Postext(binary, cwd=…, timeout=…)verwendet eine bestimmte ausführbare Datei, undpython -m postext …ist die Kommandozeile selbst.
Jeder Aufruf startet die ausführbare Datei neu. Das README des Pakets führt alle Optionen auf.
#Wie sie gebaut ist
Die Kommandozeile ist das Paket postext-cli im
Repository.
Bun kompiliert sie mit der Engine und ihren Schreibern zu einer
ausführbaren Datei pro System, und Skia (über @napi-rs/canvas)
misst und zeichnet den Text, so wie das Canvas des Browsers in der Sandbox. Ein SVG-Bild, das ein Rasterbild enthält (ein als Data-URI eingebettetes PNG oder JPEG, wie es pdftocairo -svg für aus einem PDF ausgeschnittene Grafiken schreibt), wird stattdessen von resvg gezeichnet, weil der SVG-Renderer von Skia solche Bilder weglässt. Bei
jedem Release werden die ausführbaren Dateien gebaut, unter Linux, Alpine, macOS und
Windows ausgeführt und an das GitHub Release angehängt; npm erhält postext-cli und
ein Paket postext-cli-<system> pro ausführbarer Datei.
So führen Sie sie aus einer Kopie des Repositorys aus:
pnpm install
pnpm --filter postext-cli start pdf book.postext
pnpm --filter postext-cli build:bin --currentDer erste Befehl führt sie aus ihren Quellen aus; der zweite schreibt die ausführbare Datei für diesen
Computer nach packages/postext-cli/bin/.
#Unterschiede zur Sandbox
- HTML ist das Drucklayout in Bildschirmgröße. Der Tab HTML der Sandbox setzt den Text für das Fenster neu.
--chapterssetzt die Kapitel einzeln: Ihre Seitenzahlen beginnen neu, während die Sandbox die Nummerierung des Buchs fortführt.- Schriften kommen aus dem Buch, Ihren Ordnern, der ausführbaren Datei, Google Fonts oder Fontsource (für eine Familie, die Google Fonts nicht hat), nie aus den auf dem Computer installierten Schriften, sodass ein Buch auf jedem Rechner gleich herauskommt.
- Die Sprache des Texts ist im Browser die des Dokuments
(
bodyText.shapingLanguage: 'document', der Standard seit postext 1.30). Das Canvas von Skia nimmt zwar eine Sprache entgegen, formt den Text aber ohne sie; die Kommandozeile misst daher die Formen der Standardsprache jeder Schrift und setzt ihre Bücher immer mitshapingLanguage: 'host', was auch immer die Konfiguration angibt; ihr PDF und ihre Bilder zeigen dieselben Formen. Ein Buch, dessen Schrift Formen für eine Sprache hat (ein katalanischesl·l, ein türkischesfi, die Ziffern einer chinesischen Schrift in einem englischen Buch), wird hier in den Standardformen gesetzt. Was'document'sonst misst (die an einem Zeilenende getrennten Teile eines Worts, ein Wort von rechts nach links, ein Gestaltungstext), wird hier so gemessen, wie'host'es misst, sodass eine Zeile an einem anderen Wort umbrechen kann als in der Sandbox.