Capitolo 2. Comandi di Publican

2.1. Opzioni di comando
2.2. Azioni

Publican è uno strumento da riga di comando. Per usare Publican su un computer con Sistema Operativo Linux, occorre avviare un emulatore di terminale (come GNOME Terminal o Konsole) oppure passare ad una console virtuale. Per usare Publican su un computer con sistema operativo Windows, avviare una shell a riga di comando, digitando cmd nello Start menu

I comandi di Publican hanno uno dei seguenti formati:

publican opzione_comando: opzione_comando è una delle opzioni accettate dal comando publican.
publican azione opzioni_azione: azione è una richiesta di elaborazione per Publican, come creare i file XML per un nuovo documento o creare un documento in HTML dai corrispondenti file XML. Le opzioni_azione si applicano ad una azione, per specificare per esempio la lingua di un documento.
publican opzione_comando azione opzioni_azione: Alcune opzioni_comando influenzano il risultato di una azione, come quando si richiede, per esempio, a Publican di usare nell'output la colorazione ANSI.

2.1. Opzioni di comando

Le opzioni per il comando publican, sono:

--help: Questa opzione visualizza i formati del comando ed un sommario delle azioni valide, descritte in questo capitolo.
--man: Questa opzione visualizza la pagina di man su Publican integrando le informazioni dell'opzione --help, oltre a fornire informazioni su licenze e dipendenze.
--help_actions: Questa opzione visualizza un elenco di azioni valide di Publican.
-v: Questa opzione visualizza il numero di versione di una installazione di Publican.
--config file: Questa opzione specifica per un documento, un file di configurazione alternativo al file predefinito publican.cfg.
--nocolours: Questa opzione disabilita la colorazione ANSI nei messaggi di log di Publican.
--quiet: Questa opzione disabilita tutti i messaggi di log.

2.2. Azioni

Publican è in grado di effettuare le seguenti elaborazioni:

build: trasforma i file XML in altri formati (per esempio: PDF, HTML su pagina singola o HTML su pagine multiple). Fare riferimento alla Sezione 3.7, «Creare un documento» per maggiori dettagli ed una descrizione delle opzioni disponibili.
clean: rimuove tutti i file e le cartelle nella sotto-cartella tmp/. La cartella tmp/ viene creata durante l'esecuzione del comando publican build, usato per generare un documento, come publican build --formats=html --langs=it-IT.
clean_ids: modifica tutti gli ID in un formato standard. Questo formato è Nome_Libro-titolo. Per esempio, una sezione con titolo First Section, in un libro con titolo Test_Book avrà il seguente ID dopo l'esecuzione del comando clean_ids: <section id="Test_Book-First_Section">.
Avviso — publican clean_ids
Per facilitare la traduzione, publican clean_ids usa i primi quattro caratteri del tag come prefisso dell'ID. Quindi, prima di eseguire questo comando, controllare le ultime versioni dei sorgenti XML e le corrispondenti traduzioni.
Se prima di eseguire il comando publican clean_ids, non si sono controllate le versioni correnti dei file PO, i file XML e PO non risulteranno più allineati. In tal caso, tutti i link nei file PO dovranno essere aggiornati manualmente.
Importante — Possono verificarsi conflitti tra ID
Il comando publican clean_ids serve a facilitare la costruzione di una struttura di DocBook in quei documenti provenienti da altri formati come HTML. Tuttavia, il comando publican clean_ids è file-based, e ricava le informazioni basandosi solo su file XML e sul nome del documento. Perciò, i nodi dello stesso tipo che hanno lo stesso identico titolo ricevono lo stesso ID. Questa duplicazione di ID inevitabilmente impedirà la compilazione del documento.
Usare il comando publican clean_ids per creare una struttura del documento, ed aggiustare manualmente eventuali duplicazioni di ID. Si raccomanda di non eseguire publican clean_ids su un documento già ben strutturato.
clean_set: rimuove le copie locali di libri remoti facenti parte di un set distribuito. Vedere la Sezione 5.2, «Set distribuiti» per i dettagli sull'uso di set distribuiti.
create: crea un nuovo libro, articolo o un nuovo set. Vedere il Capitolo 3, Creare un documento per i dettagli su come creare un libro o articolo, ed il Capitolo 5, Usare i set per i dettagli sull'uso dei set.
create_brand: crea un nuovo brand. Fare riferimento alla Sezione 4.2, «Creare un brand» per i dettagli.
create_site: crea un sito web di documentazione. Fare riferimento al Capitolo 6, Creare un sito web con Publican per i dettagli.
help_config: visualizza un elenco di parametri di configurazione del file publican.cfg, contenuto in ciascun libro o brand. Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg» per maggiori dettagli.
install_book: installa un documento su un sito web di documentazione. Vedere il Capitolo 6, Creare un sito web con Publican per i dettagli.
install_brand: configura l'installazione di un brand. Fare riferimento alla Sezione 4.1, «Installare un brand» per i dettagli.
lang_stats --lang=codice_lingua: genera un report statistico di traduzione per la lingua specificata da codice_lingua. Per ogni file PO generato da Publican, una tabella mostra il numero delle stringhe non tradotte in tutti i msgid; il numero delle stringhe fuzzy (conteggia le stringhe contenute in msgid, il cui contenuto è variato dall'ultima generazione dei POT), ed il numero delle stringhe tradotte, coincidente, a traduzione avvenuta, con il numero delle stringhe contenute nel msgid.
old2new: crea un file publican.cfg a partire da un Makefile di un libro, articolo o set, originariamente creato con una versione sperimentale di Publican (versioni fino a Publican 0.45, inclusa). Fare riferimento alla Sezione 3.7.2, «Compilare un documento creato con Publican 0» per maggiori dettagli.
package: crea un pacchetto un RPM di un libro, articolo, set o brand. Vedere la Sezione 3.8, «Creare il pacchetto di un documento» e la Sezione 4.4, «Creare il pacchetto di un brand» per maggiori dettagli.
print_banned: visualizza l'elenco dei tag di DocBook non raccomandati da Publican. Vedere l'Appendice A, Elementi ed attributi non permessi per una discussione sull'uso di tag non raccomandati.
print_known: visualizza l'elenco dei tag di DocBook supportati da Publican. I tag supportati sono quelli che hanno superato una minima verifica di qualità per l'uso in Publican. Fare riferimento all'Appendice A, Elementi ed attributi non permessi.
print_tree: visualizza la struttura ad albero dei file XML inclusi, con il tag <xi:include>, in un libro, articolo o set.
print_unused: visualizza l'elenco dei file XML non inclusi, con il tag <xi:include>, in un libro, articolo o set.
remove_book: rimuove un documento da un sito web di documentazione. Vedere il Capitolo 6, Creare un sito web con Publican per i dettagli.
site_stats: genera un report statistico di un sito web di documentazione.
update_po: aggiorna i file PO (Portable Object). Vedere la Sezione 3.6, «Preparare un documento per la traduzione» per maggiori dettagli.
update_pot: aggiorna i file POT (Portable Object Template). Vedere la Sezione 3.6, «Preparare un documento per la traduzione» per maggiori dettagli.
update_site: aggiorna i template del sito web di documentazione. Consultare il Capitolo 6, Creare un sito web con Publican per i dettagli.