Riferimenti
In breve
Sezione intitolata “In breve”La documentazione di riferimento risponde a domande puntuali: quale simbolo, quale valore, quale livello di supporto, quale clausola. Questa sezione raccoglie la superficie verificata di NextPDF: riferimenti ai moduli, matrici di supporto, superficie dell’API, riferimento degli errori, conformità agli standard e policy pubblicate dal progetto. Non spiega come raggiungere un obiettivo; per le procedure operative, consultare le Guide o il Cookbook.
Mappa dei riferimenti
Sezione intitolata “Mappa dei riferimenti”Motore core
Sezione intitolata “Motore core”Il motore nextpdf/core, documentato modulo per modulo.
| Pagina | A cosa serve |
|---|---|
| Riferimento del motore core | La mappa dei namespace, con le pagine di ogni modulo e le quattro sotto-famiglie. |
| Contratti: 41 interfacce pubbliche (SPI) | Le interfacce pubbliche e le enum con stabilità tracciata. |
| Core: facade Document e concern trait | Il facade Document e la famiglia di trait Has*. |
| HTML: sottosistema di rendering da HTML+CSS verso PDF | Il renderer HTML in streaming e a singolo passaggio. |
| Sicurezza: cifratura, crypto-policy e superficie di firma | Cifratura, permessi e punti di integrazione per la firma. |
Supporto al rendering
Sezione intitolata “Supporto al rendering”Ciò che il renderer verifica e dichiara come supportato, parzialmente supportato o non supportato.
| Pagina | A cosa serve |
|---|---|
| Matrice di supporto CSS | I livelli di supporto delle funzionalità dei Cascading Style Sheets (CSS) nella pipeline HTML. |
| Funzionalità CSS non supportate e alternative | Che cosa rimane fuori ambito e quali alternative usare. |
| Matrice di supporto per font e scritture | Tecnologie dei font e supporto per i sistemi di scrittura. |
| Supporto della scrittura verticale CJK | Supporto per la modalità di scrittura verticale del testo cinese, giapponese e coreano. |
| Supporto dello shaping di script complessi | Supporto allo shaping per gli script che lo richiedono. |
Superficie API
Sezione intitolata “Superficie API”Simboli esatti, valori ammessi e contratti di servizio.
| Pagina | A cosa serve |
|---|---|
| Riferimento delle enum | Tutte le enum pubbliche e i relativi valori ammessi. |
| Configurazione della TSA | L’autorità di marcatura temporale (TSA) predefinita e come cambiarla. |
| Riferimento API REST di Connect | Gli endpoint REST di NextPDF Connect, dal documento OpenAPI 3.1. |
| Explorer dell’API Connect | L’explorer interattivo relativo allo stesso contratto. |
I riferimenti all’Application Programming Interface (API) a livello di pacchetto si trovano accanto ai rispettivi pacchetti: Riferimento API di Connect, Indice delle API per le integrazioni e Riferimento API dell’SDK Python nella sezione Guide.
Riferimento degli errori
Sezione intitolata “Riferimento degli errori”Ogni eccezione sollevata dal motore, suddivisa per dominio, con il relativo contesto strutturato e le indicazioni di ripristino.
| Pagina | A cosa serve |
|---|---|
| Riferimento degli errori | Il modello delle eccezioni: la classe base NextPdfException e il contratto di contesto. |
| Errori core e generali | Errori del ciclo di vita del documento e del motore nel suo complesso. |
| Errori di rendering e I/O | Errori relativi a HTML, font, writer e reader. |
| Errori di sicurezza e firma | Errori di cifratura, firma e PKI. |
| Errori di runtime e supporto | Errori HTTP, di resilienza e di osservabilità. |
| Errori dell’Accelerator | Errori del sidecar di accelerazione opzionale. |
| Errori di conformità | Errori di convalida e degli strumenti di conformità. |
Conformità agli standard
Sezione intitolata “Conformità agli standard”I profili standard a cui punta NextPDF Core, ciascuno con il proprio perimetro dichiarato: il motore produce output destinato a essere conforme; la conformità viene determinata da un validatore esterno.
| Pagina | A cosa serve |
|---|---|
| Conformità agli standard | La postura di conformità e l’indice dei profili. |
| Conformità PDF 2.0 | La baseline ISO 32000-2 a cui punta il motore. |
| Conformità PDF/A-4 | Conformità per l’archiviazione, con la relativa Mappatura delle clausole PDF/A-4. |
| Conformità PDF/UA-2 | Conformità per l’accessibilità, con la relativa Mappatura delle clausole PDF/UA-2. |
| Conformità PDF/X | Conformità per la produzione di stampa. |
| Mappatura delle clausole di PAdES | La mappatura del profilo baseline ETSI EN 319 142 per le firme PDF. |
| Conformità ZUGFeRD / Factur-X | Conformità per le fatture elettroniche ibride. |
Centro di affidabilità
Sezione intitolata “Centro di affidabilità”La postura ingegneristica del motore core, con i confini di ogni dichiarazione.
| Pagina | A cosa serve |
|---|---|
| Centro di affidabilità | L’indice delle posture dichiarate. |
| Licenze del prodotto | I termini di licenza dell’open core e delle edizioni commerciali. |
| Marchio e uso del brand | Come usare il nome e i marchi NextPDF. |
| Gestione dei dati, PII e telemetria | Ciò che il motore legge, memorizza e trasmette. |
| Modello di sicurezza per firma e cifratura | Il design crittografico e i relativi limiti. |
| Modello delle minacce del motore | Le minacce contro cui il motore si difende e quelle escluse. |
| Criteri per la divulgazione delle vulnerabilità | Come segnalare una vulnerabilità. |
Progetto e versioni
Sezione intitolata “Progetto e versioni”| Pagina | A cosa serve |
|---|---|
| Changelog | Che cosa è cambiato in ogni versione. |
| Convenzioni del changelog | Come vengono scritte e classificate le voci del changelog. |
| Politica di versionamento, stabilità, deprecazione e supporto | Le garanzie di compatibilità tra le versioni. |
| Com’è strutturata la documentazione di NextPDF | La struttura e la governance di questa documentazione. |
Glossario
Sezione intitolata “Glossario”Glossario — i termini usati in questa documentazione, definiti una sola volta per essere riutilizzati in tutte le pagine.
Contratto delle voci di riferimento
Sezione intitolata “Contratto delle voci di riferimento”Ogni voce API deve rispondere alle stesse domande:
| Domanda | Risposta richiesta |
|---|---|
| Che cosa viene invocato? | Simbolo completo, endpoint, comando dell’interfaccia a riga di comando (CLI) o chiave di configurazione. |
| Quale input viene accettato? | Tabella dei parametri con tipo, obbligatorietà, valore predefinito e valori accettati. |
| Che cosa accade per impostazione predefinita? | Comportamento quando viene omesso l’input facoltativo. |
| Che cosa viene restituito? | Tipo restituito, corpo della risposta, output come file, flusso o effetto collaterale. |
| Che cosa può fallire? | Eccezione, errore di convalida, stato HTTP o modalità di errore operativo. |
| Come usarlo in modo sicuro? | Note su sicurezza applicativa, sicurezza dei worker, limiti dimensionali, percorsi, timeout e gestione dei segreti. |
Criteri di copertura
Sezione intitolata “Criteri di copertura”Le pagine di riferimento su API e comportamento si basano sul codice sorgente. Le API pubbliche sono documentate a partire dal codice sorgente del pacchetto, dai file di configurazione, dai test e dagli esempi. Le classi helper interne vengono documentate solo quando uno sviluppatore applicativo deve comprenderne il comportamento per configurare o usare il pacchetto.
Preparazione alla traduzione
Sezione intitolata “Preparazione alla traduzione”Le pagine di riferimento privilegiano le tabelle rispetto ai paragrafi densi. Ogni riga deve essere comprensibile anche da sola, perché la successiva segmentazione secondo l’Extensible Localization Interchange File Format (XLIFF) suddividerà il contenuto in blocchi.