1 06/11/2026 8 min

Installazione di HTMLDoc su Debian 9: cosa aspettarsi davvero

Su Debian 9, HTMLDoc si installa senza particolari sorprese se il pacchetto è disponibile nei repository attivi. Il punto vero non è tanto “metterlo su”, quanto verificare che la versione installata sia coerente con il tipo di PDF o di output HTML che devi generare. In ambienti server, infatti, il problema più comune non è l’installazione in sé, ma la mancanza di font, immagini accessibili o permessi corretti sui file in ingresso e in uscita.

Se lavori su Debian 9 in produzione o su una macchina legacy, conviene muoversi con metodo: prima controlli la disponibilità del pacchetto, poi installi, infine fai una conversione di prova con un file minimo. Così distingui subito un problema di installazione da un problema di rendering o di dipendenze esterne.

Verifica della disponibilità nei repository

Prima di installare, aggiorna l’indice dei pacchetti e controlla che HTMLDoc sia presente nei repository configurati. Su Debian 9 il nome del pacchetto è in genere htmldoc.

sudo apt update
apt-cache policy htmldoc
apt-cache search htmldoc

Nel caso più semplice, apt-cache policy mostra una versione candidata e un’origine valida. Se invece il pacchetto non compare, il problema non è HTMLDoc ma il set di repository abilitati. In quel caso va verificato il contenuto di /etc/apt/sources.list e degli eventuali file in /etc/apt/sources.list.d/.

Su Debian 9, se la macchina è rimasta ferma da tempo, può capitare che i repository puntino a mirror non più allineati o a configurazioni incomplete. Prima di aggiungere sorgenti esterne, conviene capire se il pacchetto è già disponibile nel canale ufficiale.

Installazione con APT

Se il pacchetto è disponibile, l’installazione è diretta:

sudo apt install htmldoc

Dopo l’installazione, verifica che il binario sia effettivamente presente nel PATH e che la versione risponda correttamente:

which htmldoc
htmldoc --version

L’output atteso è il percorso del binario, in genere /usr/bin/htmldoc, e una stringa di versione. Se il comando non esiste, significa che l’installazione non è andata a buon fine oppure che il pacchetto non è stato installato nel sistema corretto.

Controllo delle dipendenze utili per PDF e HTML

HTMLDoc può funzionare anche in modo minimale, ma per risultati affidabili su PDF conviene controllare le librerie e i font del sistema. In particolare, su server essenziali o containerizzati, la mancanza di font può alterare impaginazione, spaziature e resa dei caratteri.

Un controllo utile è questo:

dpkg -l | grep -E 'htmldoc|fontconfig|fonts-'

Se lavori con documenti che includono caratteri non standard, tabelle o immagini, valuta anche la presenza di un set font più completo. Non è obbligatorio per avviare HTMLDoc, ma spesso è il dettaglio che fa la differenza tra un PDF leggibile e un output mal distribuito.

Test rapido con un documento HTML minimo

Il modo più pulito per validare l’installazione è creare un file HTML essenziale e convertirlo in PDF. Così separi i problemi del motore HTMLDoc dai problemi del contenuto reale.

cat > /tmp/test-htmldoc.html <<'EOF'
<html>
<head><title>Test HTMLDoc</title></head>
<body>
<h1>HTMLDoc test</h1>
<p>Se leggi questo PDF, l'installazione funziona.</p>
</body>
</html>
EOF htmldoc --webpage -f /tmp/test-htmldoc.pdf /tmp/test-htmldoc.html
ls -lh /tmp/test-htmldoc.pdf

Se il file PDF viene creato e ha dimensioni plausibili, il motore base funziona. Se invece il comando fallisce, il messaggio di errore è già un’indicazione utile: file non trovato, formato non supportato, problemi di permessi o assenza di componenti richiesti.

Uso corretto dei parametri principali

HTMLDoc è abbastanza flessibile, ma il comportamento cambia molto a seconda delle opzioni. Le più usate in pratica sono quelle per scegliere il formato di output, il file finale e l’interpretazione del contenuto come pagina web o documento strutturato.

Un esempio tipico per generare un PDF da una pagina HTML locale è questo:

htmldoc --webpage -f output.pdf input.html

In molti casi --webpage è utile quando il contenuto è una pagina HTML reale, con layout e risorse collegate. Se invece stai convertendo documentazione molto semplice, il risultato può variare meno, ma è bene testare sempre con il tuo materiale reale e non con un esempio troppo banale.

Quando il documento include immagini locali, attenzione ai percorsi relativi. Una pagina che in browser funziona non sempre viene risolta allo stesso modo da HTMLDoc se lanci il comando da una directory diversa. In questi casi è spesso più stabile usare percorsi assoluti o preparare una directory di lavoro dedicata.

Gestione di immagini, link e risorse esterne

Uno dei punti più delicati è il caricamento delle risorse esterne. Se la pagina fa riferimento a immagini via URL, CSS remoti o font esterni, il risultato dipende dalla connettività, dai timeout e dalle regole di accesso del sistema. In ambienti chiusi, dietro proxy o senza uscita internet, questo dettaglio può bloccare la conversione o produrre PDF incompleti.

Per questo motivo conviene preferire, quando possibile, risorse locali e controllate. Se non è possibile, allora il test va fatto nello stesso contesto di rete in cui verrà eseguita la conversione in produzione. Non basta che il file HTML sia valido: devono esserlo anche tutte le dipendenze che il motore deve recuperare.

Se il documento non viene renderizzato come previsto, controlla anche i permessi dei file e la proprietà delle directory. Un errore semplice ma frequente è tentare di leggere un file in una cartella non accessibile all’utente con cui gira il processo o lo script di automazione.

Installazione alternativa da sorgente o pacchetto esterno

Se il pacchetto nei repository Debian 9 non è disponibile o è troppo vecchio per il tuo caso d’uso, puoi valutare una compilazione da sorgente o un pacchetto esterno. Qui però il rischio operativo cresce: entri nel territorio delle dipendenze manuali, delle librerie mancanti e degli aggiornamenti non gestiti da APT.

Questa strada ha senso solo se hai un’esigenza precisa, ad esempio una funzionalità specifica non presente nella build distribuita da Debian 9. In quel caso, prima di procedere, conviene fare un backup della configurazione e annotare la versione di partenza. Se qualcosa si rompe, devi poter tornare al pacchetto di sistema senza ambiguità.

Se compili da sorgente, verifica sempre in anticipo quali librerie servono e dove verranno installati binario e file di supporto. Un’installazione manuale in /usr/local/ può coesistere con quella di sistema, ma solo se sai esattamente quale binario viene richiamato nei tuoi script.

Integrazione in script e automazioni

In molti ambienti HTMLDoc non viene usato a mano, ma dentro script di deploy, job cron o pipeline di generazione documentazione. In questi casi conta molto la prevedibilità: percorso assoluto del binario, directory di lavoro nota, file temporanei puliti e logging sufficiente per capire perché una conversione è fallita.

Un approccio sobrio è salvare sempre input e output in una directory dedicata, per esempio /var/tmp/htmldoc/ o una cartella applicativa con permessi controllati. Così puoi ispezionare i file intermedi senza sporcare il resto del sistema.

Se il comando viene eseguito da un utente non interattivo, non dare per scontato che l’ambiente sia identico a quello della shell amministrativa. PATH, permessi e variabili possono cambiare, e un eseguibile trovato con il tuo utente può non esserlo in cron o in un servizio systemd.

Problemi tipici dopo l’installazione

Il primo problema classico è l’assenza di output o la creazione di un PDF vuoto. In quel caso verifica che l’HTML sia realmente leggibile e che il file contenga markup valido. Un secondo problema frequente è la resa errata dei caratteri accentati, spesso legata a encoding incoerenti tra sorgente HTML e ambiente locale.

Un altro punto da controllare è il supporto alle immagini. Se il documento mostra testo ma non figure, le cause più probabili sono percorsi errati, permessi insufficienti o dipendenze non risolte. Anche qui il test minimo è il più efficace: riduci il documento a un HTML con un solo testo e una sola immagine locale, poi allarghi il perimetro solo dopo aver trovato il punto di rottura.

Se stai lavorando su un server con risorse limitate, considera anche memoria e spazio disco. Una conversione apparentemente semplice può fallire se il filesystem è pieno o se il processo viene terminato per pressione di memoria. In questi casi il controllo non è dentro HTMLDoc, ma nel sistema operativo e nei log di sistema.

Verifica finale e manutenzione

Una volta completata l’installazione, conviene salvare una piccola procedura di verifica ripetibile. Non serve solo per oggi: serve quando tra mesi qualcuno dovrà ricontrollare perché un documento non viene più generato correttamente dopo un aggiornamento o una modifica al contenuto sorgente.

  1. Controlla che il pacchetto sia installato con dpkg -l htmldoc e che lo stato sia ii.
  2. Verifica il binario con which htmldoc e htmldoc --version.
  3. Fai una conversione minima con un HTML di test e conferma la presenza del file di output.
  4. Se usi immagini, font o risorse esterne, prova il documento reale nello stesso contesto di rete e con gli stessi permessi del job finale.

Assunzione operativa: su Debian 9 il pacchetto htmldoc è disponibile dai repository configurati correttamente; se non lo è, il primo problema da risolvere è la sorgente APT, non l’applicazione in sé.