Manuale d'Uso Presswork (IT)

Questo manuale descrive tutte le funzionalità di Presswork, con un percorso guidato per ogni area dell’app.

1. Panoramica

Presswork è un editor Markdown professionale per editoria e self‑publishing. Combina scrittura pulita, strumenti editoriali (stile, synopsis, versioni) e export professionali (PDF, PDF/X, EPUB, DOCX, HTML, ICML, FDX). Include Typst per PDF rapidi e supporta LaTeX + Ghostscript per PDF/X certificati.

2. Requisiti e installazione

Inclusi: Pandoc, Typst (PDF Base), motori interni.
Opzionali (Pro): LaTeX e Ghostscript per PDF/X certificati.

Dove controllare:

Strumenti → Controllo Export: verifica e guida all’installazione.

3. Modalità e licenze (Base / Pro)

Base: interfaccia semplificata, PDF rapido con Typst, meno opzioni.
Pro: PDF/X, preflight, multi‑export, opzioni avanzate e strumenti editoriali completi.
Cambi al volo con l'interruttore Base/Pro nell'header; il piano completo e la Licenza si gestiscono da Impostazioni → App → Vista di lavoro.

4. Interfaccia principale

Header: accesso rapido a Documento, Strumenti, Export, Vista, licenza, manuale.
Editor: area Markdown con toolbar e scorciatoie.
Sidebar: Outline, Snapshot, Backlink, Scrivener.
Status bar: parole, caratteri, linea/colonna, obiettivi.

5. Menu Documenti

Nuovo: crea un nuovo documento.
Salva MD / Salva come…: salva in .md.
Importa documento: Word (.docx, .doc), ODT, HTML, Markdown, PDF, ICML, Final Draft. Le immagini entrano con il testo: le figure di un documento Word — comprese le tabelle di Excel incollate come immagine — e quelle incorporate in un PDF vengono estratte in una cartella accanto al file importato. Quello che in un PDF è disegno vettoriale (molti grafici lo sono) non è un'immagine e non può essere estratto.
Apri progetto: carica un progetto a capitoli.
Modalità Struttura: gestione capitoli/ordine.
Gestisci Progetto: crea/aggiorna progetti editoriali.
Stampa: stampa il documento corrente.
Versioni: cronologia autosalvataggi e ripristino.

Uso consigliato:

Crea documento o progetto.
Salva spesso.
Usa Versioni per recuperare revisioni.

6. Menu Strumenti

Obiettivi: target parole giornalieri o per documento.
Statistiche: andamento scrittura, ritmo, difficoltà, flow.
Guida Utente: manuale integrato.
Controllo Export: verifica LaTeX/Ghostscript.
Command Palette: ricerca comandi (Ctrl/Cmd + P).
Analisi di stile: ripetizioni, leggibilità, tono, inclusività.
Assistente AI: riassunti, riscritture, coerenza.
Modalità Vim: comandi Vim.
Collab: sessioni collaborative P2P con invito rapido tramite ID sessione.
- Avvio rapido: apri Strumenti → Collab, imposta il tuo nome, crea o incolla ID sessione (pw-...) e premi Connetti.
- In chiamata: usa i toggle microfono e camera dal pannello flottante; se WebRTC fallisce, configura il relay WebSocket (presswork-collab-relay-url).
Tour: percorso guidato sui formati speciali.
Firma Digitale: firma PDF con certificato (Pro).

7. Menu Export

Formati principali

PDF (Typst, rapido)
PDF/X (LaTeX, certificato)
PDF Sceneggiatura (Hollywood)
FDX (Final Draft)
DOCX / ODT
EPUB
HTML
ICML (InCopy/InDesign)

Opzioni

Stile PDF: selezione template PDF.
PDF/X: profilo ICC, validazione, font incorporati.
Crocini/Bleed: opzioni di stampa.
Metadati EPUB + Cover.
Preflight: checklist qualità e stampa.
Storico export: log esportazioni.
Esporta Multiplo: più file in uno.
Export Multi‑formato: PDF + EPUB + HTML ecc.
Esporta con Asset: include immagini/risorse.
Converti Cartella: batch conversion.

8. Menu Vista

Modalità: Scrittura, Codice, Anteprima, Pagina, Split.
Lingua: 9 lingue UI.
Tema: Chiaro/Scuro.
Macchina da Scrivere: riga centrata.
Focus Mode: nasconde UI (F11).
Presentazione: slide fullscreen.
Accessibilità: dimensione testo, contrasto, font dislessia.

9. Toolbar Editor

Formattazione: grassetto, corsivo, sottolineato.
Titoli: H1/H2/H3.
Elementi: link, immagini, codice inline/blocco.
Liste: puntate/ordinate.
Citazioni.
Tabelle.
CriticMarkup: insert, delete, comment.
Template: preset di impaginazione.
Metadati: YAML front‑matter.
Snapshot: istantanee di scena.
Synopsis: riassunti per capitolo.

10. Pannelli Sidebar

Outline: navigazione sezioni.
Snapshot: gestione istantanee.
Backlink: collegamenti tra documenti.
Scrivener: capitoli e drag&drop.
Scene Navigator: per sceneggiature.

11. Scrivere in Markdown

Sintassi base

# Titolo / ## Sottotitolo
**grassetto**, *corsivo*
- elenco / 1. elenco numerato
[link](url)
![alt](immagine)
> citazione
\newpage per salto pagina

Suggerimenti

Drag & drop immagini.
Usa Split o Anteprima per controllare il layout.

12. Template

Template predefiniti: accesso da toolbar (Tpl).
Template personalizzati:
- Import file singolo o cartella (menu Template → “Importa file / Importa cartella”).
- Classificazione automatica in tab: css→UI Kit, xlsx/xls/ods/csv→Business, altri→Documenti.
- Badge Custom e tooltip completo su hover (nome + descrizione).
- .md: caricabili nell’editor.
- .tex/.pdfx/.pdft: usabili come stili di esportazione PDF.
- .xlsx/.xls/.ods/.csv: usabili nei flussi foglio dati/report.
Auto-pair UI↔PDF: i temi CSS possono auto-abbinarsi al template PDF (toggle + Disaccoppia).
Libreria condivisa: salva preset tipografici condivisi.
Dettaglio completo funzioni template: docs/template-functions-overview-it.md.

13. Metadati e front‑matter

Editor metadati per titolo, autore, ISBN.
Front‑matter YAML per esportazione coerente.
EPUB: cover e metadata obbligatori consigliati.

14. Progetti e Modalità Struttura

Documenti → Gestisci Progetto.
Crea cartella progetto.
Aggiungi capitoli (.md).
Riordina con drag&drop.
Esporta tutto con ordine automatico.

15. Export dettagliato

15.1 PDF Base (Typst)

Rapido, senza LaTeX.
Ideale per bozze e revisioni.

15.2 PDF/X (LaTeX)

Usa template certificato.
Richiede LaTeX + Ghostscript.
Supporta ICC, validazione e preflight.

15.3 PDF Sceneggiatura

Layout Hollywood.
Compatibile con Fountain.

15.4 FDX (Final Draft)

Export per workflow cinematografici, con report .breakdown.json a fianco (scene, personaggi, tag).
Dialogo simultaneo: aggiungi ^ in coda al nome del secondo personaggio (GUIDO^) — in Final Draft le battute escono affiancate in colonna (dual dialogue nativo); importando un .fdx il ^ ricompare da solo.
Tag di produzione: tasto destro su una parola selezionata → Tagga per la produzione, oppure scrivi [[prop: torcia]] o #prop: torcia in coda alla riga. Nell'FDX diventano tag nativi del Tagger (parola evidenziata, categoria nel breakdown); negli altri formati i marcatori vengono rimossi; i tag applicati in Final Draft tornano all'import.
Chiavi principali (italiano o inglese): prop, costume, veicolo, suono, musica, trucco, animale, effetti, location, nota.
Titolo e autore (front matter, oppure # Titolo + "di …" in testa al documento) finiscono nella Title Page di Final Draft.

15.5 DOCX/ODT

Conversione via Pandoc.

15.6 EPUB

Metadati + cover consigliati.
Compatibile con store digitali.

15.7 HTML

Output web con risorse.

15.8 ICML

Stili mappati per InDesign/InCopy.
Titoli, liste, citazioni e sceneggiatura trasformati in stili dedicati.
Preset di template inclusi + importazione di un .icml personalizzato.
Note a piè di pagina vere (numerate da InDesign), link con destinazioni, tabelle con intestazioni e allineamenti, immagini come cornici collegate (pannello Collegamenti), apici/pedici e maiuscoletto — anche dentro celle, note e link.
Reimport fedele: un ICML esportato e riaperto in PressWork conserva il documento (round-trip verificato in CI, anche su manoscritti lunghi).

15.9 Excel

Export Excel con breakdown scene, personaggi e produzione.
Supporto template: scrive nei fogli esistenti per mantenere stili di base.
Import multi‑sheet in tabelle Markdown (con metadati tipo/cella).
Selezione foglio e range in fase di import per evitare dati indesiderati.
Chart Mapper: opzionale, genera grafici in anteprima da dati Excel.

16. Export avanzato

Esporta Multiplo: unisce più documenti.
Export Multi‑formato: genera PDF+EPUB+HTML in una cartella.
Esporta con Asset: copia immagini e risorse.
Storico export: log e risultati.

17. KDP (Amazon)

Quick Export: PDF + EPUB con naming KDP.
Calcolatore: dimensioni e margini.
Template KDP: copertine/impaginazione dedicate.
Validatore ePub: checklist, anteprima Kindle e report scaricabile.

18. Analisi di stile

Frasi lunghe, ripetizioni, voce passiva.
Suggerimenti inline.
Metriche di leggibilità.

19. Assistente AI

Riassunti, riscrittura, coerenza, titoli.
Servizi cloud già pronti nel menu: OpenAI, Anthropic (Claude), Mistral e gli aggregatori come OpenRouter. Sceglierne uno imposta indirizzo e modello: resta solo da incollare la chiave.
Ogni servizio ricorda la sua chiave: passando da uno all'altro non va reinserita ogni volta. Le chiavi stanno nel portachiavi del sistema operativo, non in un file dell'applicazione.
Modelli locali: con «Rileva Ollama» compaiono quelli installati sul tuo computer. Lì non serve nessuna chiave e niente esce dalla macchina.
Test connessione prova il canale che stai usando davvero — quello cloud se hai una chiave, quello locale altrimenti — e dice quale ha verificato.

20. Collaborazione (P2P)

Sessioni condivise con cursori remoti colorati, commenti inline e sincronizzazione live.
Chiamate voce/video integrate durante la sessione.
ID sessione condivisibile (pw-...) per invitare rapidamente altri utenti.

Come usarla (step-by-step)

Apri Strumenti → Collab e scegli un nome riconoscibile.
Crea una nuova sessione oppure incolla l’ID ricevuto da un collega.
Attendi stato Online e verifica i partecipanti nel dock collaborazione.
Se serve voce/video, avvia la chiamata dal pannello Collab e usa i pulsanti mute/camera.
In reti aziendali restrittive, imposta il relay WebSocket (localStorage key: presswork-collab-relay-url).

21. Firma digitale

Firma PDF con certificato PAdES‑T.
Timestamp RFC 3161 (richiede rete).

22. Presentazione

Trasforma documenti in slide.
Layout e palette configurabili.

23. Accessibilità

Dimensione testo 12–18px.
Alto contrasto.
Font dislessia.

24. Scorciatoie principali

Ctrl/Cmd + S → Salva
Ctrl/Cmd + N → Nuovo
Ctrl/Cmd + P → Command Palette
Ctrl/Cmd + Shift + P → Presentazione
F11 → Focus Mode
Ctrl/Cmd + B/I/U → Grassetto/Corsivo/Sottolineato
Ctrl + Alt + V → Vim

25. Risoluzione problemi

PDF/X non disponibile: installa LaTeX + Ghostscript e riavvia.
Template non visibili: usa “Apri cartella template” e verifica estensioni.
Export lento: disattiva validazione in bozza.

26. Percorsi utili

Template personalizzati: cartella presswork/templates dentro la directory di configurazione utente.
PDF/X ICC: cartella presswork/pdfx.

Presswork unisce semplicità e strumenti editoriali professionali: scrivi veloce in Base, pubblica in Pro.

Aggiornamenti recenti (Data Hub / Grafici)

L’inserimento del grafico dall’Excel Data Hub ora mostra subito un’anteprima immagine anche nell’editor, non solo nel pannello di anteprima.
L’anteprima inline è stata ridotta (circa 50%) per essere meno invasiva durante la scrittura.
Toggle bidirezionale: 📝 Mostra codice apre il blocco chart-data, 🖼️ Torna al grafico ripristina la vista immagine.
Il blocco chart-data resta comunque nel Markdown per garantire compatibilità con preview/render/export.
Inserire una tabella o un grafico come immagine ora salva il file negli asset del documento (nomedoc.assets/images/) e nell'editor entra solo il riferimento Markdown: funziona anche con fogli molto grandi.
Se il documento non è ancora salvato, l'app propone di salvarlo al volo (come per il trascinamento immagini); rifiutando, la tabella entra come testo Markdown e il grafico resta nel foglio.
Alla scelta testo/immagine vengono capite anche risposte come "png", "jpg", "immagine", "foto"; una risposta non riconosciuta fa ripetere la domanda.
La griglia dati segue il tema chiaro/scuro attivo.
Salva come Template: finestra ridisegnata nello stile dell'app e tradotta. Richiede dati nella griglia e un modello nell'editor con segnaposto {{NomeColonna}}; "Genera Markdown" ripete il modello per ogni riga.
Export Excel (breakdown): legge il testo dell'editor (scene INT./EXT. o capitoli #); se non trova scene ora avvisa invece di generare un file vuoto.
Menu Tables semplificato: rimossa la voce doppia "Importa come template" (identica ad "Apri foglio Tables").
Pannello Import/Export: nuova scheda Multipli (accanto a Formato base / Stampa pro / Sceneggiatura / Editoria) con le azioni batch: Converti Cartella, Genera Multiplo, Genera più formati, Genera con Asset. Le Opzioni avanzate mostrano solo ciò che riguarda il formato scelto.
🧪 Verifica ICML: nel pannello export (formato ICML) controlla il documento generato — gerarchia, front matter, escape, paragrafi vuoti — senza scrivere nulla su disco; i dettagli compaiono in una finestra dentro l'app. La stessa verifica gira comunque a ogni export ICML.
Export FDX più sicuro: il Markdown generico (liste, tabelle, note) diventa sempre Azione — mai Personaggio/Dialogo per caso; le sceneggiature vere restano interpretate (scene, personaggi, battute, transizioni). \newpage diventa una vera interruzione di pagina (anche in ICML, con stile "Interruzione Pagina" rimappabile).
Stampa via PDF: il pulsante Stampa genera un PDF temporaneo (Typst, stessa tipografia degli export) e lo apre nel visualizzatore di sistema — si stampa dal dialogo nativo con anteprima fedele.
Impostazioni riordinate: sezione Installazioni (LaTeX in un click, stato Ghostscript), lingua in vista compatta, tema con chip Scuro/Chiaro. I prompt rapidi del pannello AI sono richiudibili.

27. Analisi approfondita delle funzioni (gap colmati)

Questa sezione integra le funzioni avanzate che spesso non vengono usate perché poco visibili nei menu.

27.1 AI: configurazione, diagnostica e qualità risposta

Endpoint configurabili cloud/local (OpenAI‑compatible, Ollama, LM Studio) via variabili PRESSWORK_AI_ENDPOINT, PRESSWORK_AI_MODEL, PRESSWORK_AI_API_KEY.
Diagnostica connessione AI con report JSON esportabile (utile per supporto tecnico/team IT).
Controllo stile risposta (sintetica/bilanciata/dettagliata), anteprima prompt tecnico e retry ultimo prompt.
Pin endpoint/modello per progetto: mantiene coerenza editoriale tra documenti diversi.

27.2 Statistiche: metodo di calcolo (operativo)

Produttività media: calcolata su storico giornaliero (7 giorni / 30 giorni).
Velocità scrittura: parole totali divise per finestra sessioni (parole/ora e parole/min).
TTR (Type‑Token Ratio): parole uniche / parole totali.
MSTTR: media TTR su finestre da 50 parole (riduce la distorsione su testi lunghi).
Flow state realtime: intervallo medio battiture + rapporto cancellazioni recenti.
Forecast completamento: stima ottimistica/pessimistica usando medie 7d vs 30d.

27.3 Export avanzati mancanti dalla guida rapida

Final Draft (.fdx): mappa heading in Scene Heading reali, supporta note/page break/numerazione scena e genera sidecar .breakdown.json.
ICML: mapping tipografico avanzato (titoli/liste/citazioni/sceneggiatura) + preset + import .icml custom.
Wizard EPUB/ICML: blocca l’export finché metadati minimi (titolo/autore/ISBN) e cover non sono impostati.
Firma PDF: PKCS#7 detached + timestamp RFC 3161.

27.4 Modalità Bundle (.pwk)

Azione principale: Esporta con scelta destinazione.
Target output automatici per ridurre errori manuali di percorso.
Toggle in header per mostrare temporaneamente i quick-export classici.

27.5 Collaborazione (P2P) in contesti reali

Session ID condivisibile pw-..., cursori remoti colorati, commenti inline, live sync.
Chiamata voce/video integrata nella stessa sessione editoriale.
Fallback relay WebSocket se WebRTC non passa (reti aziendali/firewall), tramite chiave presswork-collab-relay-url.

27.6 Template system (uso professionale)

Import file/cartella con classificazione automatica (Business / Documenti / UI Kit).
Supporto template binari e spreadsheet per flussi report.
Auto-pair UI↔PDF per collegare tema editor e stile export, con opzione Disaccoppia.

27.7 Checklist operativa consigliata

Imposta modalità Base/Pro in base al deliverable.
Verifica prerequisites in Controllo Export (LaTeX/Ghostscript solo se serve PDF/X).
Esegui Preflight prima della consegna.
Per EPUB/ICML completa wizard metadati + cover.
Per documenti firmati abilita firma PKCS#7 + timestamp.
In team, salva Session ID Collab e relay fallback in policy interna.

28. Collega un assistente (MCP)

Dalla 4.2 PressWork fa da ponte MCP: gli assistenti AI da chat (Claude Desktop, Codex CLI, Gemini CLI…) leggono i progetti .pwk direttamente sul tuo computer — capitoli, appunti, statistiche — senza copia-incolla. Solo lettura: il ponte non ha nessuno strumento di scrittura, solo sette letture. Se l'assistente che colleghi ha strumenti propri per accedere ai file del computer, quelli non passano da PressWork.

Configurazione in un click: Impostazioni → AI → Collega un assistente (MCP) → «Configura per me» (Claude Desktop / Codex CLI / Gemini CLI). Viene collegata la cartella del progetto aperto, con tutti i .pwk che contiene.
Chiudi del tutto l'assistente prima di configurare (Claude Desktop riscrive la propria configurazione alla chiusura), poi riaprilo. L'app fa comunque una copia di sicurezza prima di scrivere.
Le cartelle si sommano: configura da progetti in cartelle diverse e l'assistente le vedrà tutte. Funziona anche a PressWork chiuso.
Su Claude: le chat normali vivono nel cloud e non raggiungono il tuo computer — scegli l'attività «Sul tuo computer» o spunta il connettore presswork.
Altri client MCP (Cursor, OpenCode…): snippet di configurazione manuale da copiare. Con Esporta la Competenza generi la skill che insegna a Claude a usare al meglio i tuoi progetti (si aggiunge una volta, vale per sempre).
Privacy, detta onestamente: ciò che l'assistente legge viene inviato al suo servizio cloud per elaborare la risposta — come un copia-incolla, ma automatico. Non collegare progetti che non manderesti in chat.
Richiede la vista di lavoro Complete.

29. Rami e varianti di capitolo

Due strumenti diversi che rispondono alla stessa domanda — «e se invece…» — a due scale diverse.

Il ramo è un altro libro. In ogni libro, ogni capitolo può avere le sue varianti.

29.1 I rami

Un ramo è una versione alternativa dell'intero documento: cambia il finale, togli un personaggio, prova un'altra struttura. Il documento principale resta intatto.
Pannello: Ctrl/Cmd+Shift+B o dal menu. Apri un ramo e ci entri: da quel momento scrivi lì.
Dove sei si vede sempre: in fondo alla finestra compare la pillola con il nome del ramo. Nessuna pillola = sei sul documento principale, quello che va in stampa.
Promuovi rende il ramo il documento vero (il vecchio principale viene archiviato come ramo). Diff confronta riga per riga. Esporta stacca il ramo in un .pwk indipendente.
Tutti i rami stanno dentro lo stesso .pwk: nessun file in più, nessun Git.
Le schede della Sinossi dicono dove le strade si dividono: su ogni scheda-capitolo compare un segno col colore del ramo se lì quel capitolo è diverso, barrato se lì non esiste. Un clic apre i Rami. Le schede identiche in tutti i rami restano pulite: il silenzio significa «qui non si è separato niente». Stando dentro un ramo il confronto include il documento principale, che è proprio quello con cui serve confrontarsi mentre si esplora un'altra strada.
I capitoli che vivono solo altrove non spariscono dal discorso: in fondo alla Sinossi compare, quando serve, l'elenco dei capitoli che esistono solo in un'altra versione. Serve soprattutto per i rinominati, dato che i capitoli si riconoscono dal titolo.

29.2 Le varianti di capitolo

Una variante è una seconda stesura di un singolo capitolo: sulla carta era barrare un pezzo e riscriverlo accanto. Nel testo ne resta viva una sola, ed è quella che esce nei file.
Crearla: Sinossi → passa il mouse sulla scheda del capitolo → ⑂ in alto a destra. Il testo attuale diventa la prima stesura; alla nuova dai un nome.
Scambiarla: clicca la pastiglia ⑂ sulla scheda e scegli. L'attiva è segnata «nel testo». Cambia solo quel capitolo.
Eliminarla: cestino nel menu. L'attiva non si elimina: passa prima a un'altra.
Dove si vede: barra di stato, accanto al conteggio parole — ⑂ variante: nome. Se il capitolo dove hai il cursore non ne ha, lo dice comunque, in grigio.
Ogni ramo ha le sue varianti: quelle create dentro un ramo non compaiono sul principale, ed è voluto.

29.3 Se qualcosa non torna

Capitolo rinominato, varianti sparite: non sono perse. In fondo alla Sinossi c'è la fascia «Varianti senza capitolo» con tutto quello che al momento non trova posto; dal menu «assegna a…» le rimetti al posto giusto. PressWork prova a seguire da solo i titoli rinominati, ma quando non è sicuro preferisce mostrarti il materiale invece di indovinare.
Annulla vale anche qui: uno scambio di variante è una modifica del testo come le altre (Ctrl/Cmd+Z).
Sul disco: versions/branches/<id>/ e versions/variants/ dentro il .pwk. Sono file .md normali: anche senza PressWork il lavoro si legge.