# Skill per agenti: portare una pubblicazione in Postext > Installa la skill postext-port in Claude Code, Codex o in qualunque agente e lasciale trasformare un sorgente PDF, Word, PowerPoint, EPUB, InDesign o HTML in un progetto Postext che segue l’impaginazione originale - Versione HTML: https://postext.dev/it/docs/skill - Ultimo aggiornamento: 2026-10-09 - Tempo di lettura: 8 min - Altre lingue: [en](https://postext.dev/en/docs/skill.md), [es](https://postext.dev/es/docs/skill.md), [ca](https://postext.dev/ca/docs/skill.md), [de](https://postext.dev/de/docs/skill.md), [fr](https://postext.dev/fr/docs/skill.md), [pt](https://postext.dev/pt/docs/skill.md), [zh](https://postext.dev/zh/docs/skill.md), [ja](https://postext.dev/ja/docs/skill.md), [ar](https://postext.dev/ar/docs/skill.md) ## In breve Questa pagina è per chi ha già un libro o un documento in un altro formato, come PDF, Word o InDesign, e vuole portarlo in Postext. Un assistente di intelligenza artificiale, chiamato agente, può fare gran parte del lavoro se gli dai un piccolo componente aggiuntivo chiamato skill. La skill insegna all’agente come copiare il testo e ricostruire la grafica dell’originale. La pagina spiega come installarla, che cosa chiedere e come controllare il risultato. Un video di circa cinque minuti mostra ogni passaggio. **Trasforma una pubblicazione esistente in un progetto Postext con un agente di programmazione.** Molti arrivano a Postext con un libro che esiste già: un manuale come PDF di stampa, una relazione in Word, un corso in PowerPoint, un catalogo in InDesign, un EPUB. Portarlo in Postext vuol dire fare due lavori: - **Contenuto**: il Markdown arricchito di ogni capitolo, con le sue direttive e i suoi microformati. - **Grafica**: un manifesto di configurazione che riproduce le regole di impaginazione dell’originale (geometria della pagina, griglia della linea di base, caratteri, aperture, testatine, riquadri, elementi flottanti, tabelle, parti). Un LLM può fare buona parte di questo lavoro, ma solo se sa come funziona Postext. Il Markdown di Postext non è CommonMark, e la configurazione ha trappole che si notano solo quando una pagina viene resa male. La skill **`postext-port`** raccoglie queste conoscenze insieme agli strumenti con cui abbiamo costruito ogni preset della Sandbox, così il tuo agente può fare il porting come si deve. Segue il formato aperto [Agent Skills](https://agentskills.io), quindi funziona con Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode e [molti altri agenti](https://skills.sh). ## Guarda il tutorial Cinque minuti, niente codice: prepara la cartella, porta gli originali vettoriali, aggiungi un PDF di riferimento, chiedi all’agente e controlla il risultato nella Sandbox. > *Converti la tua pubblicazione in Postext con un agente IA* · Guarda il tutorial · 5:12 **Trascrizione.** Tutto ciò che dice la voce narrante, con una descrizione di ciò che appare sullo schermo. - 0:00 · *Sullo schermo:* Scheda del titolo: il logo di Postext, l’occhiello «Tutorial · 5 steps» («Tutorial in 5 passi») e il titolo «Turn your publication into Postext with an AI agent. No code.» («Trasforma la tua pubblicazione in Postext con un agente di IA. Senza codice.») - 0:03 · *Sullo schermo:* «Your publication already exists.» («La tua pubblicazione esiste già.») Tre pagine composte da Postext, un libro, un manuale e una rivista, arrivano una dopo l’altra, etichettate InDesign (IDML), Word (DOCX) e PDF. Si raccolgono a sinistra, una freccia dorata tratteggiata attraversa un badge «AI agent» (agente di IA) e compare l’icona di un file chiamato my-book.postext, sotto «An agent turns it into Postext. Five steps. A few well-written requests.» («Un agente la trasforma in Postext. Cinque passi. Poche richieste scritte bene.») · *Narrazione:* Hai già una pubblicazione: un libro, un manuale, una rivista. Vive in InDesign, in Word o in un PDF. In questo tutorial un agente di IA la trasformerà in Postext per te. Senza codice: solo cinque passi e poche richieste scritte bene. - 0:23 · *Sullo schermo:* «The plan» («Il piano»): cinque schede numerate compaiono man mano che ogni passo viene nominato: 01 Prepare the folder, 02 Bring the vector originals, 03 Add a reference, 04 Ask the agent, 05 Check in the sandbox (prepara la cartella, porta gli originali vettoriali, aggiungi un riferimento, chiedi all’agente, verifica nella Sandbox). · *Narrazione:* Ecco il piano: prepara la cartella, porta le illustrazioni originali, aggiungi un riferimento, chiedi all’agente e verifica il risultato. - 0:33 · *Sullo schermo:* Passo 01, la cartella: «One project, one folder.» («Un progetto, una cartella.») Una grande cartella, my-book/, fluttua tra dieci file sparsi come MinionPro-Regular.otf, cover.jpg, fig-2-1.ai, chapter-01.docx, map.svg, book.idml e chart.pdf. Si apre una finestra sull’albero della cartella e ogni file vola nella sua sottocartella man mano che viene nominato: reference.pdf (l’aspetto da ottenere, passo 03), fonts/ (Minion Pro, Myriad…, .otf .ttf .woff2), images/ (foto, .jpg .png), artwork/ (originali vettoriali, .ai .svg .pdf) e text/ (Word, InDesign IDML…). · *Narrazione:* Primo passo: metti tutto in un’unica cartella sul tuo computer. Un progetto, una cartella. Dentro, dai a ogni tipo di materiale la sua sottocartella: i font, le immagini, le illustrazioni e i file di testo. - 0:50 · *Sullo schermo:* La riga fonts/ viene evidenziata e una scheda intitolata «Fonts» («Font») mostra una grande «Aa», gli stili Regular, Italic e Bold, i formati OTF, TTF e WOFF2, e la nota «Only the fonts you include can be used.» («Si possono usare solo i font che includi.») Poi «The tidier the folder, the less it guesses.» («Più la cartella è in ordine, meno deve indovinare.»), mentre ogni sottocartella dell’albero riceve un segno di spunta. · *Narrazione:* Non dimenticare i font. Danno voce al progetto grafico, e l’agente può usare solo quelli che includi. Più la cartella è in ordine, meno l’agente deve indovinare. - 1:03 · *Sullo schermo:* Passo 02, gli originali vettoriali: «Bring the originals.» («Porta gli originali.») Uno schema, un grafico e una mappa vengono disegnati al tratto, con i punti di ancoraggio in vista, e compaiono tre icone di file: .ai Illustrator, .svg SVG e .pdf PDF. · *Narrazione:* Secondo passo: se le tue illustrazioni sono grafica vettoriale, come schemi, grafici o mappe, recupera i file originali: Illustrator, SVG o PDF. - 1:14 · *Sullo schermo:* Due pannelli mostrano la stessa figura, uno schema in cui Manuscript e Template puntano entrambi a Pages, con la didascalia «Fig. 2.1 Content and design meet.» («Contenuto e progetto grafico si incontrano.») A sinistra, «Cut from the PDF: a photo of the drawing» («Ritagliata dal PDF: una foto del disegno») diventa sfocata e quadrettata man mano che la vista si ingrandisce; a destra, «The original: the drawing itself» («L’originale: il disegno stesso») resta nitida. Il pannello di sinistra svanisce, le etichette dell’originale vengono riscritte in spagnolo (Manuscrito, Plantilla, Páginas), i segni di taglio la incorniciano e tre segni di spunta indicano «Sharp at any size» (nitida a qualunque dimensione), «Labels are live text» (le etichette sono testo vero) e «Print master → press» (l’originale va in stampa). · *Narrazione:* Una figura ritagliata dal PDF finito è poco più di una foto del disegno. L’originale è il disegno stesso. Con l’originale, l’agente ricostruisce ogni figura: nitida a qualunque dimensione, con le etichette ancora come testo vero, pronte da tradurre. E per la stampa, l’originale va in macchina intatto. - 1:37 · *Sullo schermo:* Passo 03, il riferimento: «Show how it should look.» («Mostra come deve apparire.») Nell’albero della cartella, reference.pdf viene evidenziato ed etichettato «In the root» («Nella radice»); ne esce una pagina che diventa una grande pagina di libro a due colonne con la scritta reference.pdf. · *Narrazione:* Il terzo passo è essenziale: nella radice della cartella, includi un file che mostri chiaramente come deve apparire il prodotto finito. Un PDF è l’ideale. - 1:47 · *Sullo schermo:* Sulla pagina compaiono delle misure: i contorni delle colonne, un’intercolonna di 9 mm, un margine di 20 mm, le etichette del titolo (Fraunces 28 pt), del testo corrente (Lora 9,4/13,6 pt) e di un riquadro (con fondo colorato, 1 filetto), e le linee di base con un’interlinea di 13,6 pt. Un file, spec-sheet.md, si riempie: pagina di 210 × 280 mm; margini di 24 · 20 · 22 · 20 mm, speculari; 2 colonne, intercolonna di 9 mm; griglia della linea di base di 13,6 pt; testo corrente in Lora 9,4/13,6 pt, giustificato; titoli in Fraunces 28 pt · Geist; aperture con una fascia di colore di 101 mm; riquadri con fondo colorato e un filetto a sinistra. Poi la parola «Guess» («Indovinare») viene barrata e «Measure.» («Misurare.») si accende in oro. · *Narrazione:* L’agente legge il progetto grafico da quelle pagine. Misura margini, colonne, font e spaziature, e li annota come regole di impaginazione. Senza un riferimento dovrebbe indovinare. Con un riferimento, misura. - 2:03 · *Sullo schermo:* Passo 04, l’agente: «Ask for it in plain words.» («Chiedilo con parole semplici.») Si apre una finestra intitolata «Agent · ~/my-book» accanto ai badge Claude Code, Codex e «or any other agent» («o qualunque altro agente»). Un messaggio di YOU (tu) si scrive: «Install the Postext skill: `npx skills add drnachio/postext --skill postext-port`» («Installa la skill di Postext»), e l’agente risponde «✓ Skill installed: postext-port» (skill installata). Una scheda della skill postext-port elenca «A proven workflow» (un metodo collaudato), «Everything about Postext» (tutto su Postext) e «Tools to check its own work» (strumenti per verificare il proprio lavoro). · *Narrazione:* Quarto passo: apri il tuo agente, Claude Code, Codex o quello che usi, in quella cartella, e chiedigli di installare la skill di Postext. Una skill è un pacchetto di competenze da esperto. Questa insegna all’agente come portare una pubblicazione in Postext e gli dà gli strumenti per verificare il proprio lavoro. - 2:24 · *Sullo schermo:* Si scrive la richiesta successiva: «Use the postext-port skill to convert this book to Postext. The design is in reference.pdf, the fonts are in fonts/ and the original illustrations are in artwork/: use them instead of cutting figures out of the PDF. Start with chapter 1 only, and show me the spec sheet before you build it.» («Usa la skill postext-port per convertire questo libro in Postext. Il progetto grafico è in reference.pdf, i font sono in fonts/ e le illustrazioni originali sono in artwork/: usale invece di ritagliare le figure dal PDF. Comincia solo dal capitolo 1 e mostrami la scheda tecnica prima di costruirlo.») Accanto, reference.pdf, fonts/ e artwork/ si accendono nell’albero della cartella man mano che la richiesta li nomina, e spunta una scheda con la scritta «Ch. 1». · *Narrazione:* Poi chiedi quello che vuoi, con parole semplici. Digli dove sono il riferimento, i font e gli originali, e chiedigli di cominciare da un solo capitolo. - 2:37 · *Sullo schermo:* Una griglia di dodici pagine di libro attenuate; la prima è contornata d’oro. Una freccia circolare conta su di essa i giri di rifinitura finché compare un segno di spunta, poi si accendono le altre undici. Sotto: Sample chapter → Polish → Extend (capitolo di prova, rifinitura, estensione). · *Narrazione:* Se il contenuto è lungo, comincia da un capitolo di prova. Rifiniscilo finché non è perfetto, e solo allora estendilo al resto. - 2:46 · *Sullo schermo:* L’agente chiede «Faithful copy or redesign?» («Copia fedele o nuovo progetto grafico?»), «Which languages?» («Quali lingue?») e «Print, screen, or both?» («Stampa, schermo o entrambi?»). Una lista di controllo scorre Take inventory, Measure the design, Extract the text, Fonts and images, Compare page by page e Pack the file (fare l’inventario, misurare il progetto grafico, estrarre il testo, font e immagini, confrontare pagina per pagina, impacchettare il file), e compare il file my-book.postext. Si scrive una terza richiesta: «Chapter 1 is approved. Convert the remaining chapters with the same design, compare each one with reference.pdf, and pack everything into a single .postext file.» («Il capitolo 1 è approvato. Converti i capitoli rimanenti con lo stesso progetto grafico, confronta ciascuno con reference.pdf e raccogli tutto in un unico file .postext.») L’agente risponde «✓ 12 chapters · 0 warnings · my-book.postext» (12 capitoli, nessun avviso). · *Narrazione:* L’agente ti farà qualche domanda: copia fedele o nuovo progetto grafico, quali lingue, stampa o schermo. Poi misura, estrae, assembla e verifica. E ti consegna un file Postext. Quando il capitolo di prova è a posto, per estenderlo a tutto il libro basta una richiesta in più. - 3:14 · *Sullo schermo:* Passo 05, la Sandbox: «Check it, page by page.» («Verificalo, pagina per pagina.») Una finestra del browser digita l’indirizzo postext.dev/sandbox. Il puntatore fa clic su Books (Libri) nella barra laterale, poi su New (Nuovo), poi su «Open a .postext file…» («Apri un file .postext…»); il file arriva in volo, «My book, 12 chapters · 184 pages» compare in cima all’elenco e le sue prime pagine si aprono nella vista Canvas; le schede delle viste riportano Canvas, HTML, PDF, Folio ed EPUB 3. · *Narrazione:* Quinto passo: apri la Sandbox di Postext su postext.dev. In Libri, scegli Nuovo e apri il tuo file. - 3:24 · *Sullo schermo:* La pagina di riferimento e la pagina di Postext stanno una accanto all’altra, etichettate Reference e Postext, e una linea dorata le percorre dall’alto in basso. Il pannello Checks (Verifiche) si apre con un badge a 3 ed elenca Widow (p. 4), Loose line (p. 7) e Figure does not fit (p. 9), cioè una vedova, una riga lasca e una figura che non ci sta; dei riquadri rossi segnano ogni problema sulla pagina di Postext. · *Narrazione:* Scorrilo pagina per pagina, accanto al tuo riferimento. Il pannello Verifiche ti segnala i problemi: vedove, righe lasche, figure che non ci stanno. - 3:35 · *Sullo schermo:* Due file di pagine in wireframe, «Reference · PDF» e «Postext · reflowed» (ricomposto). Nella fila ricomposta, una figura passa dalla prima pagina alla cima della seconda, e una linea tratteggiata collega le sue due posizioni. Testo: «Same rules, not the same pages. The content flows: a figure or a page break may land elsewhere.» («Stesse regole, non le stesse pagine. Il contenuto scorre: una figura o un’interruzione di pagina possono cadere altrove.») Poi un segno di uguale unisce ogni coppia di pagine sotto «What must match» («Che cosa deve coincidere»): Margins and baseline grid, Typography, Figure and box styles, Clean pages: no widows, even columns (margini e griglia della linea di base, tipografia, stili di figure e riquadri, pagine pulite: niente vedove, colonne pari). Un pannello rosso con il segno ≠ dice «Hand-made craft decisions: not rules, so they can’t set changing content» («Decisioni artigianali prese a mano: non sono regole, quindi non possono comporre un contenuto che cambia»). · *Narrazione:* Una cosa da tenere a mente: le pagine non devono essere identiche al tuo PDF. Postext ha imparato le regole di impaginazione e ora il tuo contenuto scorre, così una figura o un’interruzione di pagina possono cadere altrove. Quello che deve coincidere è la qualità: la stessa cura di produzione. Quando impaginiamo a mano, prendiamo piccole decisioni artigianali che non sono regole. E solo le regole possono comporre un contenuto che continua a cambiare. - 4:03 · *Sullo schermo:* Torna la finestra dell’agente con una quarta richiesta: «In the sandbox, chapter 2, page 7: the “Remember” box is split across two columns, and the running head is missing. Checks shows 3 loose lines. Fix it and pack the file again.» («Nella Sandbox, capitolo 2, pagina 7: il riquadro “Remember” è diviso su due colonne e manca la testatina. Verifiche segnala 3 righe lasche. Correggilo e impacchetta di nuovo il file.») È allegato uno screenshot, screenshot-ch2-p7.png. Poi un ciclo tra Sandbox (check, verifica) e Agent (fix, correzione) percorre i giri da 1 a 3 mentre il numero di avvisi scende da 3 a 0, e termina con un segno di spunta e «Exactly right.» («Proprio come deve essere.») · *Narrazione:* Poi di’ all’agente quello che vedi, con la massima precisione: il capitolo, la pagina e che cosa non va. Uno screenshot aiuta. Apri la nuova versione, verifica di nuovo e ripeti. Ogni giro si avvicina, finché non è proprio come deve essere. - 4:23 · *Sullo schermo:* «Not just a Postext version.» («Non solo una versione in Postext.») Il file my-book.postext si divide in due lungo una linea dorata. A sinistra, «Content (what it says)», il contenuto (che cosa dice): chapters/en/02-the-cell.md, con il titolo «The cell», una frase che rimanda alla figura fig-cell e un riquadro «remember». A destra, «Form (how it looks)», la forma (come appare): un modello dedotto dal tuo originale, con pagina di 210 × 280 mm speculare, 2 colonne con un’intercolonna di 9 mm, testo corrente in Lora 9,4/13,6 giustificato, titoli in Fraunces numerati, riquadri «remember» con fondo colorato e filetto, e figure flottanti in cima alla colonna. · *Narrazione:* Ed ecco la parte migliore: non hai solo fatto una versione in Postext del tuo contenuto. Hai separato il contenuto dalla forma. Il testo vive in capitoli puliti. Il progetto grafico vive in un modello, con regole di impaginazione dedotte dal tuo originale. - 4:39 · *Sullo schermo:* Si accendono dei chip per Correct, Extend e Translate (correggere, estendere, tradurre) sopra una fila di pagine di libro: una riga viene evidenziata e un riflesso attraversa le pagine, scivolano dentro altre due pagine, e le pagine si girano sull’edizione spagnola. Si scrive una richiesta: «Add a Spanish edition: translate the chapters, captions and diagram labels, and keep the same design.» («Aggiungi un’edizione spagnola: traduci i capitoli, le didascalie e le etichette degli schemi, e mantieni lo stesso progetto grafico.») Didascalia: «Same rules. New content. Pages set themselves.» («Stesse regole. Nuovo contenuto. Le pagine si compongono da sole.») Poi «One file, the whole book.» («Un file, tutto il libro.»): un’icona .postext si dirama verso una pagina con i segni di taglio (Print-ready PDF, un PDF pronto per la stampa), un lettore di e-book con il testo ricomposto sul suo schermo (EPUB e-book, un libro digitale EPUB), una finestra del browser (Web reader, un lettore per il web) e una coppia di pagine (Every page, set: ogni pagina, composta). · *Narrazione:* Così, quando il tuo contenuto cambia, quando lo correggi, lo estendi o lo traduci, non devi pensare all’impaginazione. Postext lo ricompone seguendo le stesse regole. Un unico file per tutto il libro: un PDF pronto per la stampa, un libro digitale EPUB, un lettore per il web e pagine che si compongono da sole. - 5:03 · *Sullo schermo:* Scheda finale: il logo di Postext, lo slogan «The programmable typesetter for the web» («Il compositore programmabile per il web»), postext.dev, una pillola con la scritta «The prompts from this video are in the description ↓» («Le richieste di questo video sono nella descrizione») e il piede «Open source · MIT · github.com/drnachio/postext». · *Narrazione:* Postext. Open source, su postext.dev. Trovi le richieste di esempio nella descrizione. Anche su YouTube: [guardalo lì](https://www.youtube.com/watch?v=Hh-mWtZGWHw&list=PLXV_YSL9ROv0) o nella [playlist di Postext](https://www.youtube.com/playlist?list=PLXV_YSL9ROv0). ## Che cosa contiene la skill - **Un flusso di lavoro**: 1. concordare il brief; 2. fare l’inventario del sorgente; 3. misurare la grafica in una scheda tecnica; 4. creare lo scheletro del progetto; 5. estrarre il contenuto; 6. rifinirlo in Markdown di Postext; 7. preparare font e immagini; 8. verificare pagina per pagina; 9. impacchettarlo. - **Riferimenti**: - il formato del documento e il manifesto di configurazione, entrambi verificati sul motore; - il formato del progetto (pacchetto); - un manuale operativo per ogni formato sorgente; - un metodo di analisi della grafica; - un catalogo di casi di impaginazione risolti: parti con colori propri, aperture di capitolo, versi, glosse a margine, note a piè di pagina, indici analitici, riquadri flottanti, spezzati e annidati, master di stampa vettoriali, figure con testo vivo, immagini nelle celle delle tabelle, tabelle in orizzontale, edizioni bilingui e altro ancora; - i libri cinesi, composti in orizzontale o in verticale e rilegati a destra: che cosa chiedere nel brief (scrittura, regione, direzione, rilegatura), come misurare una griglia di caratteri, come leggere i PDF verticali, ruby e warichu di InDesign, il layout dell’Asia orientale di Word e gli EPUB da destra a sinistra, e come ritagliare i font CJK sul libro (vedi [Composizione cinese](https://postext.dev/it/docs/chinese-layout.md)); - i libri giapponesi, romanzi bunko e tankōbon verticali rilegati a destra o libri tecnici orizzontali: la lingua che attiva le regole giapponesi (`ja`, mai un tag cinese), che cosa chiedere (direzione, griglia, furigana, note, ortografia dell’edizione), come misurare la gabbia del testo in caratteri e righe, il markup di furigana e bōten, i testi di Aozora Bunko convertiti con `aozora.py`, le scansioni di edizioni di pubblico dominio della National Diet Library e i font giapponesi ritagliati con i loro kana e le loro forme verticali (vedi [Composizione giapponese](https://postext.dev/it/docs/japanese-layout.md)); - i libri arabi, moderni o classici e vocalizzati, composti da destra a sinistra e rilegati a destra: la lingua che gira il libro, che cosa chiedere (regione e cifre, vocalizzazione, versi, indice in fondo), come misurare una pagina speculare, come leggere l’arabo da PDF, Word e Wikisource, le poesie come `:::verse`, le note «(١)» per pagina e i font arabi ritagliati con le loro tabelle di legatura (vedi [Composizione araba](https://postext.dev/it/docs/arabic-layout.md)); - fumetti, manga e strisce dei giornali: la suddivisione che taglia una pagina in vignette, le immagini delle vignette con i loro ancoraggi dei personaggi e le zone sicure, un copione per lingua che il motore letterizza (nuvolette, didascalie, effetti sonori), i manga e le edizioni arabe da destra a sinistra, e come fare il porting partendo da disegni senza testo più le traduzioni, da scansioni già letterizzate o da un copione con disegni generati (vedi [Fumetti](https://postext.dev/it/docs/comics.md)); - l’oggetto stampato: come leggere carta, rilegatura, copertine e dorso del sorgente e impostarli come le impostazioni `folio` che il [visualizzatore Folio](https://postext.dev/it/docs/sandbox.md#scheda-folio) mostra, controllate dal linter. - **Script** (Python e Node), descritti nella sezione successiva. ## Script | Script | Che cosa fa | | --- | --- | | `inventory.py` | Primo sguardo a qualunque sorgente: geometria, font, stili in uso, media, pagine che richiedono OCR; per un PDF stampato come PDF/X, la sua condizione di output e l’abbondanza, con le impostazioni `print` che le riproducono. | | `measure_layout.py` | Margini, colonne, intercolonna e interlinea (la griglia della linea di base) di un PDF | | `pdf_extract.py` | PDF → bozze di capitoli per *ruolo tipografico* (font/corpo/colore): ordine di lettura, paragrafi, rimozione della sillabazione, grassetto/corsivo, apici/pedici, elenchi, didascalie | | `pdf_figures.py` | Ritaglia le figure da un PDF: foto alla risoluzione nativa, anteprime SVG, master di stampa in PDF vettoriale | | `extract_tables.py` | Tabelle PDF → `TableModel` di Postext | | `pandoc_to_postext.py` | DOCX, PPTX, ODT, EPUB, HTML, LaTeX, Markdown, JATS, DocBook → bozze di capitoli, con gli stili di Word mappati su riquadri e stili di paragrafo | | `idml_extract.py` | IDML di InDesign → bozze di capitoli per stile di paragrafo, tabelle e immagini ancorate; ruby, tate-chu-yoko, segni di enfasi e warichu diventano `:ruby`, `:tcy`, `:dots` e `:warichu`, e vengono segnalati i brani verticali e una rilegatura da destra a sinistra | | `aozora.py` | Testo di Aozora Bunko (uno zip CP932 o un `.txt`) → Markdown di Postext: furigana, bōten e linee laterali, titoli con i loro rientri, blocchi 字下げ e 地付き come stili di paragrafo, interruzioni di pagina, 外字 risolti tramite JIS X 0213, segni kanbun; restituisce il blocco dei crediti e un rapporto su ciò che non è riuscito a esprimere | | `index_marks.py` | Ricostruisce un indice analitico stampato come segni `:index`: legge le pagine dell’indice nel PDF, trova ogni voce nella sua pagina e segna le stesse parole nei capitoli | | `comic_panels.py` | Misura le pagine dei fumetti: trova le vignette dalla carta che le separa, scrive l’espressione `split` (da sinistra a destra o da destra a sinistra, compresi gli spazi inclinati), gli spazi tra le vignette e la cornice, ritaglia un’immagine per vignetta e stampa gli scheletri `:::page`; stende una griglia sulle immagini per leggere ancoraggi dei personaggi e zone sicure, e li ridisegna per controllarli | | `fonts.py`, `images.py`, `convert_assets.py` | Istanziano, ritagliano in sottoinsiemi, scalano e dividono i font (un carattere cinese o giapponese ritagliato sui caratteri del libro conserva le forme verticali e le metriche, uno arabo le forme di legatura e il tatweel); convertono le immagini in sRGB, le rifilano e le uniscono; trasformano le illustrazioni `.ai`/`.pdf` in SVG | | `preset_kit.py` | Crea lo scheletro del progetto e del suo script generatore, costruisce `preset.json`, impacchetta il file `.postext` | | `lint_project.py` | Intercetta tutto ciò che il parser e il caricatore sbagliano in silenzio e, per il testo cinese, giapponese e coreano, i caratteri che i font inclusi non possono comporre; per il testo giapponese, i kana sotto una lingua cinese, caratteri o impostazioni cinesi, notazione Aozora rimasta nei capitoli e voci d’indice in kanji senza lettura; per il testo arabo, una lingua araba mancante, caratteri solo latini o senza legature, spaziatura tra lettere, sillabazione forzata ed enfasi in corsivo; nei fumetti, espressioni di suddivisione che non si analizzano, vignette che non corrispondono alle celle, immagini e stili di nuvoletta o di vignetta sconosciuti, ancoraggi dei personaggi malformati, caratteri del lettering che il progetto non include ed edizioni con pagine diverse | | `render.mjs` | Impagina il progetto (una cartella o un file `.postext`) senza interfaccia con il motore vero, leggendone la configurazione come fa la Sandbox, e stampa gli avvisi. Con `--jpeg` dipinge le pagine che chiedi (`--pages 12-15`) come file JPEG con il renderer canvas del motore stesso, in un secondo o due, così l’agente guarda le sue pagine senza costruire un PDF; `--out` scrive il PDF. Un libro impostato per la stampa riceve righe PREFLIGHT (immagini a bassa risoluzione, filetti sottili, testo piccolo in più inchiostri, inchiostro oltre il limite, testo vicino al rifilo), e il suo PDF viene separato tramite il profilo ICC di output. | | `compare_pages.py` | Mette affiancate le pagine del sorgente e quelle di Postext, dal PDF del rendering o dalla sua cartella di JPEG | ## Installazione ### Qualunque agente (skills.sh) La CLI [`skills`](https://skills.sh) rileva i tuoi agenti e installa la skill per ciascuno: ```bash npx skills add drnachio/postext --skill postext-port ``` Scegli gli agenti in modo esplicito con `-a`, e installa a livello globale (in ogni progetto) con `-g`: ```bash npx skills add drnachio/postext --skill postext-port -a codex -a claude-code -g ``` La stessa skill è pubblicata dal sito, quindi funziona anche così: ```bash npx skills add https://postext.dev ``` ### Plugin per Claude Code Il repository di Postext è anche un marketplace di plugin per Claude Code. Dentro Claude Code: ```text /plugin marketplace add drnachio/postext /plugin install postext@postext ``` Oppure da una shell: ```bash claude plugin marketplace add drnachio/postext ``` ```bash claude plugin install postext@postext ``` ### Lascia che sia l’agente a installarla Puoi chiedere al tuo agente di farlo, per esempio: *«Installa la skill di porting di Postext (`npx skills add drnachio/postext --skill postext-port`) e usala per portare questo PDF.»* Gli agenti che leggono `https://postext.dev/llms.txt` trovano lì questa pagina e il comando di installazione. ### Strumenti usati dagli script ```bash python3 -m pip install pymupdf pillow fonttools brotli ``` ```bash brew install pandoc poppler ``` ```bash mkdir -p ~/.cache/postext-tools && cd ~/.cache/postext-tools && npm init -y && npm i postext postext-pdf postext-citeproc react @pdf-lib/fontkit @napi-rs/canvas ``` Pandoc serve per i sorgenti Word, PowerPoint, EPUB e HTML, e poppler per le immagini delle pagine del sorgente. I pacchetti Node fanno girare il renderer senza interfaccia (Node 22.15 o successivo); `@napi-rs/canvas` è un canvas precompilato che gli permette di dipingere le pagine del libro direttamente in JPEG. Strumenti facoltativi: `ocrmypdf` per le scansioni, ImageMagick e veraPDF per i controlli PDF/UA. Il ciclo di lavoro gira sulla [riga di comando](https://postext.dev/it/docs/command-line.md), un unico eseguibile autonomo senza nulla da installare: l’agente tiene il progetto non impacchettato e lascia `postext build --watch` in esecuzione sulle pagine su cui sta lavorando, così ogni modifica compare come JPEG circa un secondo dopo, anche in un libro lungo. I pacchetti Node sono facoltativi: eseguono `render.mjs`, che aggiunge i controlli supplementari della Sandbox. Entrambi impaginano il libro con `bodyText.shapingLanguage: 'host'`, qualunque cosa dica la sua configurazione, quindi una riga può andare a capo su una parola diversa rispetto alla Sandbox (vedi [Differenze rispetto alla Sandbox](https://postext.dev/it/docs/command-line.md#differenze-rispetto-alla-sandbox)). ## Come si usa Metti i file sorgente nella tua cartella di lavoro e chiedi il porting. Per esempio: - *«Porta in Postext i capitoli 1–3 di `manual.pdf`, riproducendone l’impaginazione a due colonne, le aperture di capitolo e i riquadri.»* - *«Converti `course.docx` in un libro Postext. Gli stili 'Nota' e 'Actividad' sono riquadri.»* - *«Trasforma `deck.pptx` in una dispensa Postext: le slide diventano sezioni, le note del relatore diventano il testo.»* - *«Abbiamo il pacchetto InDesign (IDML + PDF di stampa) di questo manuale. Costruisci il preset Postext del capitolo 1 in spagnolo e in inglese.»* L’agente segue il flusso di lavoro: 1. **Brief.** Chiede ciò che non può dedurre: una riproduzione fedele o una riprogettazione, un capitolo di prova o il libro intero, le lingue, stampa o schermo, e i diritti su testo, immagini e font. 2. **Inventario e misurazione.** Legge il sorgente e scrive una scheda tecnica di dati misurati: formato rifilato, margini, colonne, interlinea, ruoli tipografici, palette, aperture, testatine, famiglie di riquadri e abitudini di collocazione. 3. **Progetto.** Crea lo scheletro di `my-book/` con un generatore `build_preset.py` che contiene la scheda tecnica come costanti e produce `preset.json`. 4. **Contenuto.** Estrae le bozze dei capitoli con l’estrattore giusto, poi le rifinisce in Markdown di Postext: riquadri, stili di paragrafo, parti, attributi dei titoli per le aperture, citazioni `:ref`, risorse di tabelle e figure. 5. **Verifica.** Passa il progetto al linter e lascia `postext build --watch` in esecuzione sul progetto non impacchettato: cambia un capitolo o un’impostazione, guarda il JPEG della pagina, ridipinto circa un secondo dopo, e cambia di nuovo finché interruzioni di pagina, figure e riquadri non corrispondono al sorgente pagina per pagina. A ogni tappa esegue i controlli completi (`postext check` e il linter). Il PDF si costruisce per i controlli di stampa, non per ogni occhiata. 6. **Consegna.** Imposta carta, rilegatura e copertine del libro per il visualizzatore Folio e impacchetta `my-book.postext`. Apri il risultato nella [Sandbox](https://postext.dev/it/sandbox.md): **Libri → Nuovo → Apri un file .postext…**. L’importazione prende i capitoli e i testi della lingua della Sandbox. Per lavorare su una cartella di progetti in una copia locale di Postext, imposta `POSTEXT_PRIVATE_PRESETS_DIR` (vedi [Sandbox](https://postext.dev/it/docs/sandbox.md)). ### Caricare il risultato dal codice Il file consegnato non è legato alla Sandbox. Il pacchetto `postext` lo apre con `openBundle`, impagina il libro con `buildBundle` e lo rende su canvas, in HTML o in PDF (vedi [Pacchetti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-file-postext)). Un porting può quindi alimentare direttamente un programma. Quando l’output di quel programma va ritoccato, esportalo di nuovo in un file `.postext` con `createBundle`, rifiniscilo nella Sandbox e carica di nuovo il file corretto. Anche lo script senza interfaccia `render.mjs` della skill accetta un file `.postext` impacchettato oltre a una cartella di progetto. ## Che cosa aspettarsi - **Gli estrattori producono bozze; l’agente le rifinisce.** Prevedi un passaggio di revisione per capitolo sulle pagine originali. È da quella revisione che viene la qualità. - **Solo configurazione e Markdown.** La skill non modifica mai il motore per adattarlo a un libro. Quando Postext non riesce a esprimere qualcosa, l’agente sceglie l’espressione più vicina e la elenca come lacuna nota. - **I diritti li decidi tu.** L’agente chiede prima di riprodurre immagini o font con licenze poco chiare. I font con licenza vengono marcati `redistributable: false`, così i progetti esportati li lasciano fuori. - **Fedeltà dove conta.** L’obiettivo è la stessa griglia, gli stessi caratteri, aperture, riquadri, collocazione delle figure e interruzioni di pagina nella maggior parte delle pagine (entro una pagina per capitolo), non le stesse identiche righe. ## Dove si trova La skill è nel repository in [`plugins/postext/skills/postext-port`](https://github.com/drnachio/postext/tree/main/plugins/postext/skills/postext-port). Copre ogni caso incontrato costruendo i preset della Sandbox, pubblici e privati. Quando un porting trova un caso che non copre ancora, apri una issue o una pull request che migliori la skill, così il porting successivo lo avrà gratis.