Capitolo 3. Creare un documento

Questo capitolo descrive come creare libri ed articoli: i file di configurazione principali, i file in un documento d'esempio, e come compilare un documento.

Usare il comando publican create per creare un nuovo documento corredato di tutti i file necessari.

Il comando publican create accetta diverse opzioni, come indicato in questo capitolo. Quando una opzione accetta un valore, separare il valore con uno spazio o con il segno di uguale; per esempio, publican create --name New_Book o publican create --name=New_Book.

--help: visualizza l'elenco di tutte le opzioni del comando publican create.
--name Nome_Doc: assegna Nome_Doc al nome del libro o articolo. Questa variabile non deve contenere spazi. Per esempio, il comando create_book --name Test_Book crea un libro di nome Test_Book con tutti i file necessari per creare il libro, ed imposta il parametro BOOKID nel file Test_Book.ent.
--lang Codice_Lingua: imposta la lingua, con il Codice_Lingua, in cui il libro o articolo verrà redatto. Se non si specifica un codice linguistico, Publican per impostazione usa en-US (inglese americano). L'opzione --lang imposta il parametro xml_lang nel file di configurazione publican.cfg. Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg» per maggiori informazioni sui parametri di publican.cfg ed all'Appendice F, Codici di lingua per i dettagli sui codici linguistici.
--version versione: imposta il numero di versione del prodotto descritto dal libro. Per esempio, per Red Hat Enterprise Linux 5.1 si userà 5.1. Il valore predefinito è 0.1. L'opzione --version imposta il tag <productnumber> nel file Book_Info.xml o nel file Article_Info.xml. Per maggiori informazioni vedere la Sezione 3.1.2, «Book_Info.xml».
--edition edizione: assegna il numero di edizione del libro. Questo numero serve ad indicare il rilascio di una nuova edizione di un libro. Il primo rilascio pubblico (general availability o GA) di un libro, dovrebbe avere l'edizione 1.0. Il valore predefinito è 0. L'opzione --edition imposta il tag <edition> nel file Book_Info.xml o nel file Article_Info.xml. Per maggiori informazioni fare riferimento alla Sezione 3.1.2, «Book_Info.xml».
--product Nome_Prodotto: assegna Nome_Prodotto al nome del prodotto descritto dal libro. Questa variabile non deve contenere spazi. Per esempio, usare il valore Fedora per la documentazione Fedora di base, ed il nome del prodotto per gli altri documenti, per esempio Fedora_Directory_Server. Il valore pedefinito è Documentation. L'opzione --product imposta il tag <productname> nel file Book_Info.xml o Article_Info.xml e il parametro PRODUCT nel file Doc_Name.ent.
--type Article --name Nome_Articolo: crea un articolo invece di un libro, assegnando Nome_Articolo al nome dell'articolo. Questa variabile non deve contenere spazi. L'opzione --type imposta il parametro type nel file di configurazione publican.cfg. Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg» per maggiori informazioni sui parametri del file publican.cfg.
--type Set --name Nome_Set: crea un set di documenti invece di un libro, assegnando Nome_Set al nome del set. Questa variabile non deve contenere spazi. L'opzione --type imposta il parametro type nel file di configurazione publican.cfg. Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg» per maggiori informazioni sui parametri del file publican.cfg ed al Capitolo 5, Usare i set per i dettagli sull'uso dei set.
--brand brand: assegna lo stile di presentazione o brand, per esempio RedHat, fedora, JBoss, oVirt o GIMP del documento. Il valore predefinito è common, il brand integrato in Publican. L'opzione --brand imposta il parametro brand nel file di configurazione publican.cfg. Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg» per maggiori informazioni sui parametri del file publican.cfg. Questa opzione richiede che sia installato l'appropriato pacchetto di brand di Publican. Per esempio, per compilare libri con brand Red Hat, occorre installare il pacchetto publican-redhat. Fare riferimento alla Sezione 4.1, «Installare un brand» per istruzioni su come installare pacchetti di brand per l'uso in Publican. Vedere il Capitolo 4, Branding per maggiori informazioni.

Prima di eseguire il comando publican create, spostarsi (con il comando shell cd), nella directory in cui si vuole venga creato il libro. Per esempio, per creare un libro di nome Libro_di_Prova nella directory miei_libri/, eseguire i seguenti comandi:

cd miei_libri/
publican create --name Libro_di_Prova --lang=it-IT

Per visualizzare i risultati di questo comando su un computer con Sistema Operativo Linux, eseguire il comando shell:

ls

Il risultato dovrebbe assomigliare a:

Libro_di_Prova/

Per visualizzare il contenuto della nuova cartella Libro_di_Prova/ su un computer con Sistema Operativo Linux, eseguire i comandi:

cd Libro_di_Prova/
ls

Il risultato dovrebbe assomigliare a:

it-IT/ publican.cfg

3.1. I file nella directory del libro

Se si esegue il comando publican create --name Libro_di_Prova --lang it-IT, Publican crea una directory con i file richiesti, che generalmente sono:

publican.cfg
it-IT (una directory)
- Libro_di_Prova.xml
- Libro_di_Prova.ent
- Revision_History.xml
- Preface.xml
- Chapter.xml
- Book_Info.xml
- Author_Group.xml
- images (una directory)
  - icon.svg

3.1.1. Il file publican.cfg

Nota — Personalizzare l'output

Se si mantengono diverse versioni di un documento, si può creare un file di configurazione per ogni versione. Quando si crea un documento o il pacchetto relativo, si può usare l'opzione --config per specificare un file di configurazione diverso dal file publican.cfg, e quindi usare un insieme differente di parametri per una particolare compilazione. Per esempio:

publican build --formats html,pdf --langs de-DE,en-US,it-IT --config community.cfg

Il file publican.cfg configura le opzioni di compilazione, e si trova nella cartella radice del libro. Di seguito si riporta un esempio di file publican.cfg, con una descrizione dei parametri ivi presenti:

# Config::Simple 4.59
# Mon Sep 28 16:38:14 2009

xml_lang: en-US
type: Book
brand: common

Parametri predefiniti

xml_lang: specifica la lingua dei file XML sorgenti, per esempio en-US, come impostato con l'opzione --lang nel comando publican create.
type: specifica il tipo di documento — un <article> DocBook, un <book> DocBook o un <set> DocBook, come impostato con l'opzione --type nel comando publican create.
brand: imposta il brand del documento, per esempio RedHat, fedora, JBoss, oVirt o GIMP, come impostato con l'opzione --brand nel comando publican create. Se non si specifica un brand, Publican usa il brand predefinito. Fare riferimento al Capitolo 4, Branding per maggiori informazioni.

Parametri avanzati

arch

filtra l'output in base all'architettura della macchina. Per esempio, impostando arch: x86_64 nel file publican.cfg, l'applicazione Publican include solo gli elementi XML contenenti l'attributo equivalente, per esempio <para arch="x86_64">.

Usare con cautela

Come accade più in generale con i tag condizionali, il parametro arch può causare notevoli problemi in fase di traduzione di un documento. Vedere la Sezione 3.9.1, «Tagging condizionale e traduzione» per una spiegazione di questi problemi.

parametro `arch` in nodi radice

Se il nodo radice di un file XML viene escluso dal parametro arch, il documento non può essere compilato, poichè file vuoti non sono file XML validi. Per esempio, se il file Installation_and_configuration-PPC.xml è costituito da un solo capitolo:

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="chap-Installation_and_configuration_on_PowerPC" arch="PowerPC">
<title>Installation and configuration on PowerPC</title>

[text of chapter]

</chapter>

ed il capitolo è incluso nel file User_Guide.xml con un tag <xi:include>, il documento non compilerà se viene impostata la condition: x86 nel file publican.cfg.

Per escludere il capitolo, aggiungere il parametro arch al tag <xi:include> in User_Guide.xml, invece che al tag <chapter> in Installation_and_configuration-PPC.xml.

xrefs e parametro `arch`

Se un <xref> punta ad un contenuto escluso dalla compilazione dal parametro arch, la compilazione fallisce. Per esempio, impostando arch: x86 nel file publican.cfg, il comando publican build --formats=pdf --langs=en-US fallisce se il libro ha il tag <xref linkend="Itanium_installation"> che punta a <section id="Itanium_installation" arch="IA64">.

books

specifica un elenco di libri, separati da spazio, usati in un set remoto. Vedere la Sezione 5.2, «Set distribuiti» per maggiori informazioni sui set distribuiti.

brew_dist

specifica il target da usare per creare il pacchetto RPM desktop in Brew, il sistema di creazione di pacchetti interno a Red Hat. Il valore predefinito è docs-5E. Vedere la Sezione 3.8.2, «Il comando publican package» e la Sezione 4.4, «Creare il pacchetto di un brand» per maggiori informazioni sulla compilazione di pacchetti RPM.

bridgehead_in_toc

specifica se includere gli elementi DocBook <bridgehead> (o intestazioni svincolate) tra gli altri titoli (di sezione e di capitoli), nelle tabelle dei contenuti. Per abilitare questa proprietà, impostare bridgehead_in_toc: 1. Per impostazione, quest'ultimo parametro è impostato a 0 e gli elementi <bridgehead> non sono inclusi nel sommario dei contenuti.

chunk_first

controlla se visualizzare la prima sezione in una nuova pagina, nel rendering HTML. Per visualizzare la sezione in una nuova pagina HTML, impostare il parametro su chunk_first: 1. Per impostazione, il valore predefinito è 0, e la prima sezione viene visualizzata nella stessa pagina del proprio capitolo.

chunk_section_depth

controlla il livello di sotto-sezione a partire da cui queste non vengono riportate su una nuova pagina, nel rendering HTML. Per impostazione, il valore predefinito è 4.

Esempio 3.1. Controllare il livello di sotto-sezione con chunk_section_depth

chunk_section_depth: 0: nessuna suddivisione di sezioni. Tutte le sezioni e sotto-sezioni appaiono nella stessa pagina del capitolo cui appartengono. La successione della pagine è capitolo 1, capitolo 2, capitolo 3, …
chunk_section_depth: 1: la suddivisione di sezione è a "livello 1". Ogni sezione di livello uno, con le relative sotto-sezioni, appaiono su una nuova pagina. La successione delle pagine è capitolo 1, 1.2, 1.3, 1.4 … capitolo 2, 2.1, 2.2, … 2.3 …
chunk_section_depth: 2: la suddivisione di sezione è a "livello 2". La successione delle pagine è capitolo 1, 1.2, 1.2.2, 1.2.3, 1.2.4 … 1.3, 1.3.2, 1.3.3 …
chunk_section_depth: 3: la suddivisione di sezione è a "livello 3". La successione delle pagine è capitolo 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.3, 1.2.2.4 … 1.3, 1.3.2, 1.3.2.2, 1.3.2.3 …
chunk_section_depth: 4 (predefinito): la suddivisione di sezione è a "livello 4". La successione delle pagine è capitolo 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.2.2, 1.2.2.2.3, 1.2.2.2.4 … 1.2.3, 1.2.3.2, 1.2.3.2.2, 1.2.3.2.3 …

classpath

imposta il percorso ai file jar (Java archive) per FOP (Formatting Objects Processor). Publican si basa su Apache FOP — una applicazione Java — per rendere i documenti in file PDF. Il percorso predefinito ai file jar di FOP, su un computer con Sistema Operativo Linux è: /usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar.

common_config

imposta il percorso ai file d'installazione di Publican. La locazione predefinita su un Sistema Operativo Linux è /usr/share/publican. Su un computer con sistema operativo Windows, la locazione predefinita è %SystemDrive%/%ProgramFiles%/publican — solitamente C:/Program Files/publican.

common_content

imposta il percorso alla cartella dei file comuni di Publican. I file contenuti forniscono formattazione predefinita, alcuni modelli e grafica generica. La locazione predefinita su un Sistema Operativo Linux è /usr/share/publican/Common_Content. Su un computer con sistema operativo Windows, la locazione predefinita è %SystemDrive%/%ProgramFiles%/publican/Common_Content — solitamente C:/Program Files/publican/Common_Content.

condition

specifica, prima di una trasformazione, le condizioni per escludere file XML. Vedere la Sezione 3.9, «Tagging condizionale» per maggiori informazioni.

Nodi root e tag condizionale

Se il nodo di root di un file XML viene escluso da un tag condizionale, il documento non compila, poichè file vuoti non sono file XML validi. Per esempio, se il file Installation_and_configuration_on_Fedora.xml contiene un solo capitolo:

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora">
<title>Installation and configuration on Fedora</title>

[text of chapter]

</chapter>

ed il capitolo è incluso in User_Guide.xml con un tag <xi:include>, il documento non compila se è presente l'impostazione condition: Ubuntu nel file publican.cfg.

Per escludere il capitolo, aggiungere un attributo condizionale al tag <xi:include> in User_Guide.xml, e non al tag <chapter> in Installation_and_configuration_on_Fedora.xml.

xref e tag condizionale

Se un <xref> punta ad un contenuto escluso nella compilazione da un tag condizionale, la compilazione fallisce. Per esempio, con l'impostazione condition: upstream nel file publican.cfg, il comando publican build --formats=pdf --langs=en-US fallisce se il libro ha un tag <xref linkend="betasection"> che punta alla <section id="betasection" condition="beta">.

confidential

contrassegna un documento come confidenziale. Impostando su 1 questo parametro, Publican aggiunge il testo specificato nel parametro confidential_text (per impostazione, CONFIDENTIAL) a piè di pagina o in testa ad ogni pagina di un documento HTML o PDF, rispettivamente. Il valore predefinito è 0 (nessuna intestazione o piè di pagina).

confidential_text

specifica il testo da usare quando il parametro confidential è impostato ad 1. Il testo predefinito è CONFIDENTIAL.

cvs_branch

il branch (ramo) in CVS in cui importare l'SRPM. Specificare questo parametro quando si crea il pacchetto di un documento con l'opzione --cvs — fare riferimento alla Sezione 3.8.2, «Il comando publican package».

cvs_pck

il pacchetto in CVS in cui importare l'SRPM. Specificare questo parametro quando si crea il pacchetto di un documento con l'opzione --cvs — fare riferimento alla Sezione 3.8.2, «Il comando publican package».

cvs_root

la radice in CVS in cui importare l'SRPM. Specificare questo parametro quando si crea il pacchetto di un documento con l'opzione --cvs — fare riferimento alla Sezione 3.8.2, «Il comando publican package».

debug

controlla se visualizzare il messaggi di debug durante l'elaborazione. Con il valore predefinito impostato a 0, Publican non visualizza messaggi. Modificare il valore ad 1 per vedere i messaggi di debug.

def_lang

imposta la lingua predefinita per un sito web gestito da Publican. La tabelle dei contenuti delle altre lingue fanno riferimento ai documenti della lingua predefinita, se non sono disponibili traduzioni. Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento» per maggiori informazioni.

doc_url

fornisce un URL al team di documentazione del pacchetto. In documenti HTML, Publican crea un link a questo URL in alto a destra di ogni pagina, attraverso l'immagine image_right.png nella cartella Common_Content/images del brand. Il valore predefinito è https://fedorahosted.org/publican.

docname

specifica il nome del documento. Se impostato, questo parametro non tiene conto del contenuto del tag <title> nel file Book_Info.xml in fase di costruzione del pacchetto del documento. Questo valore può contenere solo lettere maiuscole/minuscole non accentate, cifre, il carattere trattino_basso ed il carattere spazio (‘a–z’, ‘A–Z’, ‘0’–‘9’, e ‘_’ e ‘ ’).

dt_obsoletes

il pacchetto reso oboleto dal pacchetto desktop.

dt_requires

il pacchetto richiesto dal pacchetto desktop, per esempio, il pacchetto del menu di una documentazione. Fare riferimenro alla Sezione 3.8.1.3, «Voci nel menu del desktop per i documenti».

dtdver

specifica la versione del DTD (Document Type Definition) di DocBook XML su cui si basa il progetto. Publican fa riferimento alla versione 4.5. Le specifiche della versione DTD 4.5 di DocBook XML sono disponibili su http://www.docbook.org/specs/docbook-4.5-spec.html.

Un DTD differente potrebbe rallentare la compilazione

Quando si installa Publican, si installa anche una copia locale della definizione DTD versione 4.5 di DocBook XML in accompagnamento ad XSL (Extensible Stylesheet Language). Se si imposta una versione di DTD per cui non risulta disponibile una versione locale, Publican deve scaricare DTD ed XSL appropriati da una sorgente in rete, ad ogni compilazione di un documento. In tal caso la compilazione del documento risulta ritardata dal completamento di questo scaricamento. La dimensione complessiva dei file è di circa 70 MB.

ec_id

imposta l'ID per un plugin d'aiuto di Eclipse. Ogni plugin deve possedere un unico ID che generalmente segue le convenzioni sui nomi dei pacchetti JAVA (http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html). Per impostazione, Publican imposta l'ID con org.prodotto.nomedoc. L'ID impostato determina anche il nome della cartella del plugin, nella cartella plugin.

ec_name

imposta il nome per un plugin d'aiuto di Eclipse. E' un nome leggibile che compare nell'elenco d'aiuto di Eclipse. Il nome non deve essere unico o rispettare particolari convenzioni. Per impostazione, Publican imposta il nome con prodotto nomedoc.

ec_provider

imposta il nome del fornitore per un plugin d'aiuto di Eclipse. Può essere un nome di persona, o il nome di un progetto o organizzazione. Questo è visibile agli utenti e non deve essere unico o rispettare particolari convenzioni. Per impostazione, Publican imposta il nome del fornitore con Publican-version di Publican.

edition

specifica il numero di edizione del documento. Se impostato, questo parametro non tiene conto del contenuto del tag <edition> nel file Book_Info.xml in fase di costruzione del pacchetto. Questo valore può contenere solo cifre ed il carattere punto (‘0’–‘9’ e ‘.’).

generate_section_toc_level

controlla il livello di sottosezione nelle tabelle dei contenuti. Con il valore predefinito, 0, Publican genera tabelle contenenti parti, capitoli ed appendici, ma senza sezioni. Se per esempio, il valore è impostato su 2, le tabelle dei contenuti conterranno anche sezioni di "livello 2", come le sezioni 1.1.1, 1.1.2, ed 1.2.1.

Esempio 3.2. Impostare il livello di sezione nelle tabelle dei contenuti

generate_section_toc_level: 0 (predefinito): Publican genera le tabelle dei contenuti all'inizio del documento e nelle parti, nei capitoli e in appendice, ma non nelle sezioni.
generate_section_toc_level: 1: Publican genera le tabelle dei contenuti anche all'inizio delle sezioni di "livello 1", come le sezioni 1.1, 1.2 … 2.1, 2.2 …
generate_section_toc_level: 2: Publican genera le tabelle dei contenuti anche all'inizio delle sezioni di "livello 2", come le sezioni 1.1.1, 1.1.2. 1.1.3 … 1.2.1., 1.2.2, 1.2.3 …

ignored_translations

specifica le traduzioni da ignorare, specificando i codici linguistci separati da virgola, per esempio, es-ES,it-IT. Se si crea un libro o il pacchetto di un libro per una lingua filtrata da questo parametro, Publican ignora ogni traduzione in questa lingua, e crea invece il libro o il pacchetto relativo, nella lingua dei sorgenti XML. Fare riferimento alla Sezione 3.6, «Preparare un documento per la traduzione» ed all'Appendice F, Codici di lingua.

license

specifica la licenza usata dal pacchetto. Per impostazione, Publican seleziona la licenza GFDL (GNU Free Documentation License). Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento».

max_image_width

per le immagini in un documento, specifica la massima larghezza possibile, in pixel. Per impostazione, Publican ridimensiona le immagini più larghe di 444 pixel fino ad adattarle a questo limite. Il limite di 444 pixel assicura che le immagini non eccedano nel margine destro delle pagine HTML e si adattino all'interno delle pagine PDF. Fare riferimento alla Sezione 3.2, «Aggiungere immagini» per maggiori informazioni sull'uso delle immagini.

Importante — 444 pixel è la massima larghezza di sicurezza

Non usare il parametro max_image_width se le immagini contengono importanti informazioni. Le immagini più larghe di 444 pixel potrebbero presentarsi male nei documenti HTML e PDF e rendersi inusabili, in quanto superando i margini esse verrebbero rappresentate incomplete.

Viceversa, le immagini più larghe di 444 pixel che vengono scalate in un browser web o in un visualizzatore PDF, perdono in qualità.

Per preservare la qualità delle immagini, si raccomanda di tagliare o riscalare le immagini ad una larghezza inferiore a 444 pixel, prima di includerle in un documento.

mainfile

specifica il nome del file XML, contenente il nodo XML radice di <article>, <book> o <set>, e il nome del file .ent corrispondente, con le entità del documento. Per esempio, impostando mainfile: master, Publican cerca il nodo XML radice in master.xml e le entità in master.ent.

Se il parametro mainfile non è impostato, Publican cerca il nodo XML radice in un file che corrisponda al <title> del documento in Article_Info.xml, Book_Info.xml, o Set_Info.xml, e cerca le entità in un file con un nome corrispondente.

menu_category

la categoria del menu del desktop (come definito dal file .menu corrispondente), in cui inserire il documento installato con un pacchetto RPM desktop. Fare riferimento alla Sezione 3.8.1.3, «Voci nel menu del desktop per i documenti».

os_ver

specifica il sistema operativo per cui costruire il pacchetto. Publican appende questo valore al nome del pacchetto RPM. Per esempio, .fc15 for Fedora 15. Il valore predefinito è .el5, che significa Red Hat Enterprise Linux 5 e sistemi operativi derivati. Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento» ed alla Sezione 4.4, «Creare il pacchetto di un brand».

prod_url

fornisce un URL per il prodotto a cui fa riferimento il documento. In documenti HTML, Publican crea un link a questo URL nella parte in alto a sinistra, usando l'immagine image_left.png nella cartella Common_Content/images del brand. Il valore predefinito è https://fedorahosted.org/publican.

product

specifica il prodotto cui fa riferimento il documento. Se impostato, questo parametro non tiene conto del contenuto del tag <productname> nel file Book_Info.xml, durante la creazione del pacchetto. Questo valore può contenere solo lettere maiuscole/minuscole non accentate, cifre, il carattere trattino-basso ed il carattere spazio (‘a–z’, ‘A–Z’, ‘0’–‘9’, e ‘_’ e ‘ ’).

release

specifica il numero di rilascio del pacchetto. Se impostato, questo parametro non tiene conto del contenuto del tag <pubsnumber> nel file Book_Info.xml, durante la creazione del pacchetto. Il valore può contenere solo cifre (‘0’–‘9’).

repo

specifica il repository da cui prelevare i libri remoti che fanno parte di un set distribuito. Fare riferimento alla Sezione 5.2, «Set distribuiti».

scm

specifica il sistema di controllo versione (o source code management), usato nel repository contenente i libri remoti di un set distribuito. Al momento, Publican può usare solo SVN (Subversion), e quindi il valore predefinito è SVN. Fare riferimento alla Sezione 5.2, «Set distribuiti».

show_remarks

controlla se visualizzare gli elementi <remark> nel documento. Per impostazione, il parametro è impostato sul valore 0 che nasconde i remark. Impostare questo valore su 1 per visualizzare i remark. Nel brand common di Publican, il testo incluso è evidenziato con colore viola.

show_unknown

controlla se segnalare tag sconosciuti durante la trasformazione dei file XML. Per impostazione, questo parametro ha il valore 1 segnalando i tag sconosciuti. Impostare questo valore su 0 per non visualizzare questi avvisi. Publican ignora questo parametro in strict mode.

src_url

specifica l'URL in cui trovare i tarball dei file sorgente. Questo parametro completa il campo Source: nell'intestazione del file spec dell'RPM. Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento».

strict

imposta Publican in modalità strict per impedire l'uso di tag inutilizzabili in documenti professionali e traduzioni. Per impostazione, il parametro strict è impostato sul valore 0, disabilitando la modalità strict. Per abilitare la modalità strict, impostare il valore su 1. Correntemente la modalità strict non viene applicata.

tmp_dir

specifica la cartella dei prodotti di Publican. Per impostazione, il valore è tmp corrispondente ad una cartella di nome tmp, inclusa nella cartella contenente l'articolo o libro.

toc_section_depth

controlla fino a che livello rappresentare le sotto-sezioni nel sommario principale dei contentuti. Per impostazione, il valore predefinito è 2. Con questa impostazione, appaiono le sezioni 1.1 ed 1.1.1, ma non la sezione 1.1.1.1 . (Notare che il primo numero indica un capitolo, non una sezione).

Esempio 3.3. Controllare il livello di sezioni nella tabella dei contenuti principale

toc_section_depth: 0: Publican genera un sommario principale solo di capitoli.
toc_section_depth: 1: Publican genera un sommario principale solo per i capitoli e le sezioni di "livello 1", come 1, 1.1, 1.2, 1.3 … 9, 9.1, 9.2 … ma non per sezioni 1.1.1, 1.1.2 …
toc_section_depth: 2 (predefinito): Publican genera un sommario principale per i capitoli e le sezioni di "livello 1" e "livello 2", come 1, 1.1, 1.1.1, … 1,2, 1.2.1, 1.2.2 … ma non per le sezioni più interne tipo x.x.x.x .

version

specifica il numero di versione del prodotto a cui fa riferimento il documento. Se impostato, questo parametro non tiene conto del contenuto del tag <productnumber> nel file Book_Info.xml, per la creazione del pacchetto. Il valore può contenere solo cifre ed il carattere punto (‘0’–‘9’ and ‘.’).

web_brew_dist

specifica il target di compilazione brew da usare per la creazione di pacchetti RPM per il web. Brew è il sistema di creazione di pacchetti interno a Red Hat. Per impostazione, questo valore è impostato su docs-5E, rappresentando i pacchetti per la documentazione Red Hat Enterprise Linux 5. Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento».

web_formats

una lista di formati, separati da virgola, da includere nel pacchetto RPM per il web. Fare riferimento alla Sezione 3.8.2, «Il comando publican package».

web_home

specifica che il documento è la home page di un sito web di documentazione, non un documento standard. Fare riferimento al Capitolo 6, Creare un sito web con Publican.

Importante — `web_home` è deprecato

In Publican 2.2, web_home è stato sostituito da web_type: home. Supporto a web_home verrà interrotto in future versioni di Publican.

web_name_label

visualizza il valore impostato, invece del nome del libro, nel menu di un sito web gestito da Publican. Fare riferimento al Capitolo 6, Creare un sito web con Publican.

web_obsoletes

specifica i pacchetti resi obsoleti da questo RPM per il web. Fare riferimento alla Sezione 3.8, «Creare il pacchetto di un documento».

web_product_label

visualizza il valore impostato, invece del nome del prodotto, nel menu di un sito web gestito da Publican. Fare riferimento al Capitolo 6, Creare un sito web con Publican.

web_type

specifica che si tratta di un documento descrittivo per un sito web gestito da Publican, e non del documento di un prodotto. Il contenuto include la home page del sito web (web_type: home), pagine descrittive di prodotto (web_type: product), e pagine descrittive di versione (web_type: version). Fare riferimento al Capitolo 6, Creare un sito web con Publican.

web_version_label

visualizza il valore impostato, invece del numero di versione, nel menu di un sito web gestito da Publican. Impostare il valore su UNUSED per una documentazione generale che non si applica ad una particolare versione di un prodotto. Fare riferimento al Capitolo 6, Creare un sito web con Publican.

Aiuto da riga di comando

Eseguire il comando publican help_config nella cartella radice di un libro per un elenco di questi parametri.

3.1.2. Book_Info.xml

`Article_Info.xml` e `Set_Info.xml`

Questa descrizione del file Book_Info.xml si applica anche ai file Article_Info.xml e Set_Info.xml. Quindi, per semplificare, nel corso di questa sezione si farà riferimento al file Book_Info.xml.

Pacchetti non pacchetti RPM

Questa sezione descrive i pacchetti di documenti distribuiti con il Gestore di pacchetti RPM. Quando si usa il comando publican package, Publican genera un tarball che può essere usato per ricavare un pacchetto, da distribuire con un gestore di pacchetti software differente. Se si esegue publican package su un sistema senza rpmbuild installato, Publican genera ancora il tarball anche se non può creare da esso, il pacchetto RPM.

Il file Book_Info.xml contiene i metadati chiave di un libro: ID del libro; titolo; sottotitolo; autore e numero editoriale. Contiene anche nome e versione del prodotto documentato, ed un abstract.

Oltre a costituire gli elementi introduttivi di un libro, questi metadati sono usati anche per creare il pacchetto RPM di un libro. Solitamente, se si distribuisce un libro come un pacchetto RPM, i vari tag inclusi in maniera predefinita in Book_Info.xml devono contenere dati che siano conformi alle richieste del formato RPM. E' possibile non tenere conto di questi tag, usando i campi equivalenti nel file publican.cfg, come discusso in questa sezione.

A meno che non siano specificati nel file publican.cfg, per realizzare l'RPM di un libro, sono necessari i dati di sette tag predefiniti in Book_Info.xml. Per lo più, il nome di file del pacchetto RPM di un libro è costruito come:

nome_prodotto-titolo-numero_prodotto-codice_lingua-edizione-numero_pub.src.rpm

Ogni dato, escluso codice_lingua, è ricavato dal file Book_Info.xml — la lingua è specificata durante la creazione del libro. Come pure <subtitle> e <abstract> usati nel file spec dell'RPM per fornire il campo Summary: nell'intestazione ed il campo %description, rispettivamente.

Appresso, si riporta un esempio di file Book_Info.xml, per un Libro_di_Prova. Seguono i dettagli riguardanti questo file, e le richieste di conformità al formato RPM per ciascun tag.

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
]>
<bookinfo id="book-Users_Guide-Users_Guide" lang="it-IT">
	<title>Guida Utente</title>
	 <subtitle>Pubblicare libri, articoli, relazioni e raccolte di volumi con DocBook XML</subtitle>
	 <productname>Publican</productname>
	 <productnumber>2.7</productnumber>
	 <edition>1</edition>
	 <pubsnumber>0</pubsnumber>
	 <abstract>
		<para>
			Questo manuale illustra come installare <application>Publican</application>. Inoltre fornisce istruzioni sull'uso di Publican per creare e pubblicare libri, articoli e raccolte di volumi basati su DocBook XML. Questa guida assume che si sia già familiari con DocBook XML.
		</para>

	</abstract>
	 <keywordset>
		<keyword>publican</keyword>
		 <keyword>docbook</keyword>
		 <keyword>publishing</keyword>

	</keywordset>
	 <subjectset scheme="libraryofcongress">
		<subject>
			<subjectterm>Electronic Publishing</subjectterm>

		</subject>
		 <subject>
			<subjectterm>XML (Computer program language)</subjectterm>

		</subject>

	</subjectset>
	 <corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata fileref="Common_Content/images/title_logo.svg" />
			</imageobject>
			 <textobject>
				<phrase>Team Publican</phrase>
			</textobject>

		</inlinemediaobject>

	</corpauthor>
	 <mediaobject role="cover">
		<imageobject remap="lrg" role="front-large">
			<imagedata fileref="images/cover_thumbnail.png" width="444" />
		</imageobject>
		 <imageobject remap="s" role="front">
			<imagedata fileref="images/cover_thumbnail.png" width="444" />
		</imageobject>
		 <imageobject remap="xs" role="front-small">
			<imagedata fileref="images/cover_thumbnail.png" width="444" />
		</imageobject>
		 <imageobject remap="cs" role="thumbnail">
			<imagedata fileref="images/cover_thumbnail.png" width="444" />
		</imageobject>

	</mediaobject>
	 <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	 <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

<bookinfo id="id_libro">, <articleinfo id="id_articolo">, <setinfo id="id_set">: L'ID del documento è usato internamente e non viene visualizzato ai lettori. Se si esegue il comando publican clean_ids, ogni ID inserito manualmente, inclusi questi, viene modificato in un formato Nome_Doc-Titolo, dove Titolo è il titolo associato al libro, articolo, sezione o capitolo.
<productname>nomeprodotto</productname>: Il nome del prodotto o gruppo di prodotto cui si riferisce il libro, articolo, o set, per esempio: Red Hat Enterprise Linux o JBoss Enterprise Application Platform. Quando si crea il pacchetto RPM di un libro, il valore nel tag <productname> viene usato come parte del nome di file dell'RPM.
Per non tenere conto di questo tag, usare il parametro product nel file publican.cfg, in particolare se il nome_prodotto contiene caratteri non-latini, caratteri accentati o caratteri di punteggiatura diversi dal trattino_basso.
Caratteri permessi
Publican usa i dati in questo tag per generare gli elementi del nome di file per i pacchetti RPM, a meno che non siano superati dai dati nel file publican.cfg. Se i dati nel tag non sono superati da quelli in publican.cfg, questo tag può contenere solo caratteri non accentati minuscoli e maiuscoli, cifre, il segno meno, il trattino-basso, il punto ed il carattere somma (‘a–z’, ‘A–Z’, ‘0’–‘9’, ‘-’, ‘.’, ‘_’, e ‘+’).
<title>titolo</title>: Abbastanza ovvio, il titolo del documento (per esempio <title>Server Configuration Guide</title>). Il titolo compare sotto il nome del prodotto in entrambe le presentazioni, HTML e PDF. Un titolo è necessario per la creazione del pacchetto RPM. Quando si crea l'RPM di un libro, il titolo è usato come parte integrante nel nome di file del pacchetto.
I nomi dei pacchetti RPM possono contenere solo particolari caratteri ASCII. Se il titolo di un documento contiene caratteri non latini, caratteri latini accentati o di punteggiatura (escluso il trattino basso), usare il parametro docname nel file publican.cfg per impostare il nome del documento in caratteri ASCII. Compilando il documento, il titolo risultante è quello impostato con il tag <title>, mentre per il nome di pacchetto del documento, il valore usato è quello impostato con il parametro docname.
Caratteri permessi
Publican usa i dati in questo tag per generare gli elementi del nome di file per i pacchetti RPM, a meno che non siano superati dai dati nel file publican.cfg. Se i dati nel tag non sono superati da quelli in publican.cfg, questo tag può contenere solo caratteri non accentati minuscoli e maiuscoli, cifre, il segno meno, il trattino-basso, il punto ed il carattere somma (‘a–z’, ‘A–Z’, ‘0’–‘9’, ‘-’, ‘.’, ‘_’, e ‘+’).
Per impostazione, Publican usa il contenuto di <title> per individuare il file contenente il nodo XML radice: <article>, <book> o <set>. Per esempio, se si imposta il titolo <title>Server Configuration Guide</title>, Publican si aspetta di trovare il nodo XML radice in un file di nome Server_Configuration_Guide.ent. Per usare un nome differente per questi file, impostare il parametro mainfile nel file di configurazione (per impostazione, publican.cfg). Fare riferimento alla Sezione 3.1.1, «Il file publican.cfg».
<subtitle>sottotitolo</subtitle>: Analogamente ovvio come il precedente, il sottotitolo del libro; un titolo alternativo, generalmente esplicativo per il libro (per esempio: Server Configuration Guide: Preparing Red Hat Enterprise Linux for Production Use). Il sottotitolo compare sotto il titolo in entrambe le presentazioni, HTML e PDF. Un sottotitolo è necessario anche per la creazione del pacchetto RPM. In tal caso, il sottotitolo è usato nel Summary del file spec dell'RPM, reso disponibile insieme agli altri campi dello spec file, con il comando rpm -qi.
<productnumber>numeroprodotto</productnumber>: Il numero di versione del prodotto cui si riferisce il documento, per esempio ‘5.2’ per Red Hat Enterprise Linux 5.2 e ‘4.3’ per JBoss EAP 4.3.
L'esecuzione del comando publican create --name Nome_Doc --version versione configura propriamente il numero di prodotto.
Per non tenere conto di questo tag, usare il parametro version nel file publican.cfg, in particolare se il termine versione di prodotto, non contiene solo cifre.
Caratteri permessi
Publican usa i dati in questo tag per generare parti del nome di file per i pacchetti RPM, a meno che non siano supearti dai dati nel file publican.cfg. Se i dati nel tag non sono superati da quelli in publican.cfg, questo tag può contenere solo cifre ed il carattere punto (‘0–9’ e ‘.’).
<edition>edizione</edition>: Il numero di edizione del libro. La prima edizione di un libro dovrebbe coincidere con 1.0 (a meno di usare 0.x per versioni pre-release di un libro). Le edizioni successive dovrebbero incrementare 1.x per indicare ai lettori una nuova edizione del libro. Questo tag imposta il numero di versione nel nome di file di un RPM, creato con publican package.
Per esempio, impostando edition ad 1.2 e compilando il libro con il comando publican package --binary --lang=en-US, si crea un file RPM di nome nomeprodotto-titolo-numeroprodotto-en-US-1.2-0.src.rpm.
L'esecuzione del comando publican create --name Nome_Doc --edition x.y configura propriamente l'edizione.
Per non tenere conto di questo tag, usare il parametro edition nel file publican.cfg, in particolare se il termine edizione non contiene solo cifre.
Caratteri permessi
Publican usa i dati in questo tag per generare parti del nome di file per i pacchetti RPM, a meno che non siano supearti dai dati nel file publican.cfg. Se i dati nel tag non sono superati da quelli in publican.cfg, questo tag può contenere solo cifre ed il carattere punto (‘0–9’ e ‘.’).
<pubsnumber>numero_pub</pubsnumber>: Il pubsnumber imposta il numero di release (l'ultima cifra) nel nome di file di un RPM, creato con publican package. Per esempio, impostando il pubsumber a 1 e compilando il libro con il comando publican package --binary --lang=en-US, si crea un file RPM di nome nomeprodotto-titolo-numeroprodotto-en-US-edizione-1.src.rpm.
Per non tenere conto di questo tag, usare il parametro release nel file publican.cfg, in particolare se il numero di release del documento non contiene solo cifre.
Caratteri permessi
Publican usa i dati in questo tag per generare gli elementi del nome di file per i pacchetti RPM, a meno che non siano superati dai dati nel file publican.cfg. Se i dati nel tag non sono superati da quelli in publican.cfg, questo tag può contenere solo cifre (‘0–9’).
<abstract><para>abstract</para></abstract>: Una breve descrizione e sintesi sull'argomento e sulla finalità del libro, generalmente non più lungo di un paragrafo. L'abstract compare prima del sommario dei contenuti nelle presentazioni HTML e nella seconda pagina nelle presentazioni PDF. Se si compila il pacchetto RPM per un libro, il tag abstract imposta il campo Description nel file spec dell'RPM. Ciò rende disponibile l'abstract con il comando rpm -qi.

Si possono aggiungere metadati extra al file Book_Info.xml di un documento, a supporto di specifiche proprietà nei vari formati d'uscita:

<keywordset>, <keyword>

I termini con il tag <keyword> contenuti in un <keywordset>, sono inseriti all'interno di tag <meta name="keywords">, presenti nel tag head dei file HTML e nel campo Keywords delle proprietà di un documento PDF.

<subjectset>, <subject>

I termini con il tag <subject> contenuti in un <subjectset> sono aggiunti al campo Subject delle prorietà di un documento PDF e nei metadati di un e-book in formato EPUB.

Si consideri di usare un vocabolario controllato per la definizione del soggetto di un documento, per esempio, il descrittore di soggetto dell'LCSH (Library of Congress Subject Headings). Si identifichi il vocabolario scelto con l'attributo scheme nel tag <subjectset>, per esempio <subjectset scheme="libraryofcongress">. In tal modo è possibile ricercare tra i descrittori di LCSH, nella pagina Authorities & Vocabularies di Library of Congress: http://id.loc.gov/authorities/search/.

<mediaobject role="cover" id="epub_cover">

Usare un tag <mediaobject> con attributi role="cover" e id="epub_cover" per impostare cover-art per e-book in formato EPUB. Per esempio:

<mediaobject role="cover" id="epub_cover">
	<imageobject role="front-large" remap="lrg">
		<imagedata width="600px" format="PNG" fileref="images/front_cover.png"/>
	</imageobject>
	<imageobject role="front" remap="s">
		<imagedata format="PNG" fileref="images/front_cover.png"/>
	</imageobject>
	<imageobject role="front-small" remap="xs">
		<imagedata format="PNG" fileref="images/front_cover.png"/>
	</imageobject>
	<imageobject role="thumbnail" remap="cs">
		<imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/>
	</imageobject>
</mediaobject>

Come per le altre immagini in documenti, salvare le cover-art nella sotto-cartella images.

3.1.2.1. Pacchetti RPM, edizioni, ristampe e versioni

Come già notato, il file predefinito Book_Info.xml usato da Publican, include un tag <edition>.

Se si distribuisce un libro come un pacchetto RPM, i dati di questo tag impostano le prime due cifre del numero di versione del file RPM.

Quindi una edizione '1.0' diventa una versione '1.0'.

Il file Book_Info.xml contiene anche il tag <pubsnumber>. I dati di questo tag modificano il numero di release del pacchetto RPM.

Un libro con edizione 1.0 e pubsumber 5, diventerebbe la versione 1.0 e release 5 (1.0-5).

I tag edition e pubsumber non sono correlati al tag <productnumber>, anch'esso presente in Book_Info.xml: infatti <productnumber> specifica la versione del prodotto documentato o descritto.

Del resto, è naturale avere la II edizione di un libro per una particolare versione di un prodotto.

In bibliografia, due copie di un libro fanno parte della stessa edizione se risultano stampati usando sostanzialmente la stessa composizione tipografica o di pagina. ('Sostanzialmente' sono tollerati solo correzioni tipografiche ed altre correzioni minori).

Diversamente, i collezionisti di libri solitamente si riferiscono alla 'prima edizione' come alla 'prima uscita di stampa'; i bibliografi invece prestano attenzione al testo solitamente situato nelle prime pagine interne di un libro, in cui si sepcifica per esempio, 'II ristampa' o 'IV edizione'.

Noi raccomandiamo di seguire il metodo seguito dai bibliografi. Quando si usa Publican per ripubblicare un libro da un file XML sostanzialmente identico, incrementare il tag <pubsnumber>. Esso ha una funzione molto simile alla ristampa nella editoria tradizionale.

Per il cambio di <edition>, si raccomanda di usare lo stesso criterio degli editori tradizionali: nel caso di revisione o di riscrittura significativa. Su cosa sia significativo e su quanto debba essere consistente una riscrittura, da richiedere un incremento intero o decimale nel numero di edizione, resta a discrezione dell'editore.

3.1.3. Author_Group.xml

Il file Author_Group.xml non è richiesto ed è la locazione standard in cui inserire autore, editore, grafico ed altri dettagli di merito. Il seguente è un esempio di file Author_Group.xml:

<?xml version='1.0'?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<authorgroup>
	<corpauthor>FF0000 Headgear Documentation Group</corpauthor>
	<author>
		<firstname>Dude</firstname>
		<surname>McDude</surname>
		<affiliation>
			<orgname>My Org</orgname>
			<orgdiv>Best Div in the place</orgdiv>
		</affiliation>
		<email>dude.mcdude@myorg.org</email>
	</author>
</authorgroup>

Il file Author_Group.xml non necessariamente deve contenere tutte queste informazioni: inserire a discrezione quelle richieste.

3.1.4. Chapter.xml

Articoli e Capitoli

Gli articoli di DocBook non possono contenere capitoli. Se si usa l'opzione --type=article con il comando publican create, Publican non crea anche un file Chapter.xml. Usare le sezioni per organizzare il contenuto degli articoli.

Fare riferimento alla Guida DocBook: The Definitive Guide di Norman Walsh e Leonard Muellner, disponibile su http://www.docbook.org/tdg/en/html/docbook.html, per i dettagli sui vari modi di interazioni tra set, book, articoli, part, capitoli e sezioni. In particolare, notare che gli articoli possono essere documenti a sè stanti, o possono essere incorporati in libri.

Il file Chapter.xml è un modello per creare file di capitoli. Questi file costituiscono il contenuto di un libro. Di seguito si riporta un modello di capitolo (Chapter.xml) creato dal comando publican create. Notare che DOCTYPE è impostato a chapter:

<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="MYBOOK-Test">
	<title>Test</title>
	<para>
		This is a test paragraph
	</para>
	<section id="MYBOOK-Test-Section_1_Test">
		<title>Section 1 Test</title>
		<para>
			Test of a section
		</para>
	</section>
	
	<section id="MYBOOK-Test-Section_2_Test">
		<title>Section 2 Test</title>
		<para>
			Test of a section
		</para>
	</section>

</chapter>

Il capitolo presenta due sezioni, Section 1 Test e Section 2 Test. Per ulteriori informazioni sui capitoli, fare riferimento a http://docbook.org/tdg/en/html/chapter.html della sopra citata guida.

Nota

Il file di capitolo dovrebbe essere rinominato in modo da rispecchiare l'argomento contenuto. Per esempio, un capitolo sull'installazione di un prodotto dovrebbe essere denominato Installation.xml, mentre un capitolo sull'impostazione di un software sarebbe meglio denominato, Setup.xml o Configuration.xml.

3.1.5. `Nome_Doc`.xml

Il file Nome_Doc.xml contiene le direttive xi:include per includere gli altri file XML indispensabili al documento, tra cui i capitoli e le sezioni contenute nei vari file XML. Per esempio, il file Nome_Doc.xml di un libro riunisce i capitoli contenuti in distinti file XML.

Ecco un esempio di Nome_Doc.xml che descrive un libro di DocBook — notare il parametro DOCTYPE impostato con book.

Esempio 3.4. Un libro DocBook

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<book>
	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<index />
</book>

Questo esempio carica i file XML Book_Info.xml, Preface.xml, Chapter.xml e Appendix.xml.

Importante

L'ordinamento dei capitoli è importante. La creazione di questo libro, prevede che Book_Info.xml preceda Preface.xml che a sua volta preceda Chapter.xml, e così via.

Il file Nome_Doc.xml non si limita all'uso delle direttive xi:include. Si possono creare documenti anche con un solo file XML. Di seguito si riporta un esempio di libro, usando un singolo file XML:

<book>

<chapter>
<title>Chapter 1</title>
<para>
	A paragraph in Chapter 1.
</para>
<section id="section1">
<title>Chapter 1 Section 1</title>
	<para>
		A paragraph in Section 1.
	</para>
</section>
<section id="section2">
<title>Chapter 1 Section 2</title>
	<para>
		A paragraph in Section 2.
	</para>
</section>
</chapter>

<chapter>
<title>Chapter 2</title>
<para>
	A paragraph in Chapter 2.
</para>
</chapter>

</book>

Questo libro contiene due capitoli, in cui il I capitolo è costituito da due sezioni. Per ulteriori informazioni su sezioni e book vedere rispettivamente, http://docbook.org/tdg/en/html/section.html e http://docbook.org/tdg/en/html/book.html.

3.1.6. `Nome_Doc`.ent

Il file Nome_Doc.ent è usato per definire entità locali. Le entità YEAR e HOLDER sono usate per informazioni di copyright. Per impostazione, Publican imposta YEAR con l'anno corrente, ed inserisce un messaggio in HOLDER che richiama di specificare la licenza per il documento. Se mancano entrambe le entità YEAR e HOLDER, il documento non compila.

Altre entità potrebbero essere richieste dal brand applicato al documento. Per esempio, il brand per i documenti Fedora, usa l'entità BOOKID per indicare l'identificativo del documento ai lettori che desiderano inviare commenti.

<!ENTITY PRODUCT "MYPRODUCT">
<!ENTITY BOOKID "MYBOOK">
<!ENTITY YEAR "2008">
<!ENTITY HOLDER "YOUR NAME GOES HERE">

3.1.6.1. Entità e traduzione

Usare le entità con particolare attenzione

Le entità sono convenienti, ma dovrebbero essere usate con particolare attenzione in quei documenti che saranno tradotti. Scrivere per esempio, &FDS; invece di Fedora Directory Server è un vantaggio per il redattore del documento; tuttavia le entità non risultano trasformate nei file PO (Portable Object) usati dai traduttori. Di conseguenza, risulta impossibile una traduzione completa di un documento contenente entità.

Le entità rappresentano degli ostacoli per i traduttori, precludendo la possibilità di realizzare traduzioni di qualità. La natura propria di una entità è di rendere esattamente, in ogni occorrenza del documento ed in ogni lingua, la parola o frase rappresentata. Questa scarsa flessibilità comporta che la parola o gruppo di parole, rappresentate dall'entità, possa essere illegibile o incomprensibile in certe lingue e non possa modificarsi al cambiare delle regole grammaticali richieste dalla lingua. Inoltre, poichè durante la conversione in PO dei file XML, le entità non vengono trasformate, i traduttori non possono selezionare correttamente, secondo le regole grammaticali della propria lingua, le parole da inserire intorno all'entità.

Se si definisce una entità — <!ENTITY LIFT "Liberty Installation and Formatting Tome"> — nel file XML si può inserire un riferimento all'entità definità, &LIFT; e in ogni compilazione HTML, PDF o semplice testo, si visualizzerà l'entità Liberty Installation and Formatting Tome.

Le entità non vengono trasformate durante la conversione in PO dei file XML. Quindi, i traduttori non vedono mai Liberty Installation and Formatting Tome, ma soltano &LIFT; che non possono tradurre.

Si consideri per esempio la traduzione in tedesco, del seguente frammento in lingua inglese:

As noted in the Liberty Installation and Formatting Tome, Chapter 3…

Una traduzione potrebbe essere:

Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…

Poichè non esistono entità, il titolo può essere tadotto in un tedesco corretto. Inoltre, notare in questo contesto linguistico, l'uso di ‘dem’, la forma corretta dell'articolo determinativo ('il') quando riferito a Wälzer ('tomo')

Per contrasto, usando le entità, la stessa frase nel file PO risulta:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr ""

La traduzione di ciò, probabilmente sarebbe:

#. Tag: para
#, no-c-format
msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…"
msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"

E nella presentazione si avrebbe:

Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…

In tal caso, ovviamente il titolo rimane in inglese, incluse le parole come 'Tome' e 'Formatting' che il lettore difficilmente comprende. Inoltre, il traduttore è costretto ad omettere l'articolo definitivo ‘dem’, per un costrutto più generico che si avvicina ad un ibrido tra inglese e tedesco, definito Denglisch o Angleutsch, dai madrelingua tedesca. Molti di coloro che parlano il tedesco, ritengono scorretto questo approccio e quasi tutti un modo poco elegante.

Problemi analoghi emergono con un frammento come questo:

However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…

Senza testo nascosto da entità, una traduzione in tedesco potrebbe essere:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…

Se, per salvare tempo di scrittura, si fosse usata un'entità, il traduttore si sarebbe trovato con questo:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr ""

E la traduzione sarebbe stata differente, in modo sottile ma rilevante:

#. Tag: para
#, no-c-format
msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…"
msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"

Presentata al lettore, questa apparirebbe come:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…

Di nuovo, notare l'assenza dell'articolo determinativo (den in questo contesto grammaticale). Ciò è poco elegante ma necessario, in quanto il traduttore può solo tentare di indovinare l'articolo (den, die o das), generando molto probabilmente un errore.

Infine, tener presente che anche se un termine è invariabile in inglese, ciò non necessariamente è vero in altre lingue, anche quando si tratta di un nome proprio come quello di un prodotto. In molte lingue, i nomi cambiano la loro forma (flessione) in accordo al ruolo nel periodo (caso grammaticale). Una entità in un file XML, impostata per rappresentare un nome inglese o un sintagma nominale (noun phrase) rende praticamente impossibile una traduzione corretta in tali lingue.

Per esempio, se si scrive un documento che si può applicare a più di un prodotto, si potrebbe essere tentati di impostare una entità come &PRODUCT;. Il vantaggio di questo approccio è che cambiando semplicemente questo valore nel file Nome_Doc.ent, si può facilmente adattare il libro a una documentazione, per esempio, per Red Hat Enterprise Linux, Fedora, o CentOS. Comunque, mentre il nome proprio Fedora non subisce variazioni nella lingua inglese, (per esempio) in ceco, presenta sei forme differenti, una per ciascuno dei possibili ruoli in un periodo:

Tabella 3.1. 'Fedora' in ceco

Caso	Uso	Forma
Nominativo	il soggetto di un periodo	Fedora
Genitivo	indica possesso	Fedory
Accusativo	l'oggetto diretto di un periodo	Fedoru
Dativo	l'oggetto indiretto di un periodo	Fedoře
Vocativo	rivolto direttamente al soggetto	Fedoro
Locativo	riguarda un argomento o luogo	Fedoře
Strumentale	riguarda un mezzo	Fedorou

Per esempio:

Fedora je linuxová distribuce. — Fedora è una distribuzione Linux.
Inštalácia Fedory — Istallazione di Fedora.
Stáhnout Fedoru — Ottieni Fedora.
Přispějte Fedoře — Contribuire a Fedora.
Ahoj, Fedoro! — Ciao Fedora!
Ve Fedoře 10… — In Fedora 14…
S Fedorou získáváte nejnovější… — Con Fedora, puoi ottenere gli ultimi…

Una frase che inizia con S Fedora získáváte nejnovější… rimane comprensibile al lettore ceco, ma risulta sintatticamente scorretta. Lo stesso effetto si può aver con la lingua inglese, infatti anche se i sostantivi hanno perso l'uso delle desinenze intorno al Medio Evio, i pronomi hanno conservato la flesssione. La frase, 'Me see she' risulta completamente comprensibile ad un inglese, ma non è la forma che ci si aspetterebbe di leggere, poichè non è corretta la forma dei pronomi me e she. Me è la forma accusativa del pronome, ma poichè è il soggetto del periodo, il pronome dovrebbe assumere la forma nominativa, I. Analogamente, she è il caso nominativo, ma come ogetto diretto del periodo il pronome dovrebbe assumere la forma accusativa, her.

I sostantivi nella maggior parte delle lingue slave come russo, ceco, polacco, serbo e croato, hanno sette differenti casi. I sostantivi nelle lingue finno–ugriche come finlandese, ungherese ed estone hanno tra quindici e diciassette casi. Altre lingue modificano i sostantivi per altre ragioni. Per esempio, le lingue scandinave flettono i sostantivi per indicare determinazione — se il sostantivo si riferisce ad 'una cosa' o 'alla cosa' — ed alcuni dialetti di queste lingue flettono i sostantivi per determinazione e per declinazione.

Ora si estendano tali problemi a tutte le lingue (più di 40), attualmente supportate da Publican. Oltre alle poche stringhe non tradotte che Publican specifica per impostazione nel file Nome_Doc.ent, le entità possono risultare utili per specificare i numeri di versione dei prodotti. Al di là di ciò, l'uso delle entità sembra quasi un desiderio di inibire e ridurre la qualità delle traduzioni. Inoltre, il lettore del documento, tradotto in una lingua con inflessione di sostantivi (declinazione, determinazione o altro), non sa di certo che l'errore grammaticale è generato dalle entità impostate nell'XML — concludendo, con buona probabilità, che si tratta di incompetenze del traduttore.

3.1.7. Revision_History.xml

Durante la sua elaborazione, il comando publican package individua nella directory dei file XML, il primo file contenente un tag <revhistory>. Successivamente publican usa questo file per compilare la cronologia di revisione del pacchetto RPM.

3.2. Aggiungere immagini

Salvare le immagini nelle sottocartella images della cartella contenente i file XML. Usare ./images/nome_immagine per inserire le immagini in un libro. Di seguito si riporta un esempio che inserisce l'immagine testimage.png:

<mediaobject>
<imageobject>
	<imagedata fileref="./images/testimage.png" />
</imageobject>
<textobject><phrase>alternate text goes here</phrase></textobject>
</mediaobject>

Assicurarsi di fornire un <textobject> in modo da rendere accessibile il contenuto alle persone con disabilità visiva. In alcuni Stati, potrebbe essere una responsabilità legislativa permettere questa accessibilità — per esempio negli Stati Uniti alle organizzazioni si richiede di rispettare la Section 508 del Rehabilitation Act of 1973.^[1]

Se il libro contiene immagini che occorre localizzare — per esempio, gli screenshot di una interfaccia utente in una altra lingua da quella originale del libro — salvare queste immagini nelle sottocartelle images delle directory linguistiche. Assicurarsi che il file dell'immagine tradotta abbia lo sesso nome del file della lingua originale. Qunado si compila un libro per una lingua, Publican usa il file della sottocartella images/ nella directory linguistica pertinente e non quello nella sottocartella images/ della lingua originale.

Immagini grandi si presentano male in HTML perchè spesso invadono il margine destro del testo. Analogamente, le immagini più larghe di 444 pixel, spesso si estendono al di là del margine destro delle pagine PDF e risultano tagliate, lasciando visibile solo la parte sinistra dell'immagine. Per questo, per impostazione, Publican crea presentazioni HTML e PDF istruendo i browser web e i visualizzatori PDF a scalare le immagini più larghe di 444 pixel. Notare, comunque, che le immagini scalate in questo modo perdono significativamente in qualità. Per migliori risultati, scalare o tagliare le immagini in un software di editazione immagini in modo da garantire una larghezza non superiore a 444 pixel, prima di inserirle in un documento.

Per non tenere conto della limitazione di 444 px imposta da Publican, specificare la larghezza di un'immagine nel tag <imagedata>. Per esempio, per impostare una larghezza di 670 pixel:

<imagedata fileref=".images/image.png" width="670px">

In tal caso, rivedere accuratamente la presentazione per preservare gli standard di qualità richiesti.

Locazioni delle immagini

Publican usa soltanto le immagini nella sottocartella images della cartella contenente i file XML e le corrispondenti immagini nelle sottocartelle images pertinenti alle lingue. Immagini salvate in altre directory non vengono prese in considerazione.

File PNG in documenti PDF

Publican dipende da un'applicazione esterna, FOP, per rendere documenti PDF. Al momento, alcune versioni di FOP contengono un bug che altera i colori in certe immagini in formato PNG. Nello specifico, le immagini PNG a 32-bit vengono visualizzate correttamente, mentre quelle a 24-bit presentano problemi.

Se si nota che Publican produce un file PDF contenente immagini con colori alterati, convertire i file PNG originali nel formato PNG a 32-bit aggiungendo un canale alpha all'immagine e poi ricompilare il libro. Se il software di elaborazione immagine, non include un'opzione specifica denominata Aggiungi canale alpha, usare l'opzione Aggiungi transparenza.

3.3. Aggiungere codice

Se il libro contiene pezzi di codice, salvare il file in una sotto-cartella denominata extras/ nella cartella della lingua originale, ed usare un <xi:include> per caricare il file del codice nella struttura XML del documento. Ogni file contenuto nella cartella extras/ non viene analizzato sintatticamente (parsed) come XML da Publican.

Alcuni caratteri sono riservati in XML, in particolare, & e <. Se si inserisce un pezzo di codice direttamente in un file XML di un documento, occorre fare l'escaping di questi caratteri, rendendoli CDATA o sostituendoli con entità (& e < rispettivamente).^[2] Posizionando questi file nella cartella extras/, non occorre alcun escaping di questi caratteri. Questo approccio risparmia tempo, riduce la possibilità di introdurre errori nell'XML e nel codice; oltre a semplificare il mantenimento del documento e del codice.

Per includere nel documento, un pezzo di codice contenuto nella cartella extras/, seguire questa procedura:

Creare la cartella extras
```
mkdir en-US/extras
```
Copiare il file del codice nella cartella extras
```
cp ~/samples/foo.c en-US/extras/
```

Nel file XML, includere il file di codice in un tag xi:include

<programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>

Ora si può modificare il file en-US/extras/foo.c nel proprio editor preferito, senza doversi preoccupare di eventuali effetti nell'XML.

Lo stesso approccio funziona annotando il codice con callout. Per esempio:

<programlistingco>
	<areaspec>
		<area id="orbit-for-parameter" coords='4 75'/>
		<area id="orbit-for-magnitude" coords='12 75'/>
	</areaspec>
	<programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for"
	xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
	<calloutlist>
		<callout id="callout-for-parameter" arearefs="orbit-for-parameter">
			<para>
				The <firstterm>standard gravitational parameter</firstterm>
				(μ) is a derived value, the product of Newton's gravitational 
				constant (G) and the mass of the primary body.
			</para>
		</callout>
		<callout id="callout-for-magnitude" arearefs="orbit-for-magnitude">
			<para>
				Since the mass of the orbiting body is many orders of magnitude 
				smaller than the mass of the primary body, the mass of the 
				orbiting body is ignored in this calculation.
			</para>
		</callout>
	</calloutlist>
</programlistingco>

Notare gli elementi <area> che definiscono la posizione dei callout che compaiono nel codice. Gli attributi in coords specificano un numero di riga ed un numero di colonna, separati da uno spazio. In questo esempio, i callout sono applicati alle rige 4 e 12 del codice, entrambi allineati sulla colonna 75. Anche se questo approccio prevede di adattare gli attributi coords ad ogni modifica apportata al codice, ciò evita di combinare tag <coords> nel codice.

3.4. Aggiungere file

Publican permette di includere file arbitrari all'interno di un documento. Questi file vengono inclusi nel pacchetto RPM compilato da Publican e vengono installati sul sistema dell'utente insieme al documento. Per esempio, si possono includere file multimediali di tutorial a complemento del documento, o file di codice sorgente o altro materiale utile agli utenti per lavorare con gli esempi o i tutorial.

Per distribuire file arbitrari con un documento, includerli in una cartella denominata files, e salvarla nella cartella della lingua originale (p.e. en-US) del libro (p.e. My_Book).

Nella cartella My_Book:

mkdir en-US/files

Copiare i file nella cartella files:

cp arbitrary_files en-US/files

3.5. Rinominare un documento

Il comando publican rename permette di rinominare facilmente un documento con un nuovo titolo o di modificare il nome o la versione di prodotto, a cui si riferisce il documento. Il comando accetta fino a tre opzioni:

--name nuovo_titolo

modifica il titolo del documento. Per esempio, per rinominare Server Deployment Guide il documento Server Configuration Guide, spostarsi nella directory radice del documento ed eseguire:

publican rename --name "Server Deployment Guide"

Nello specifico, il comando cambia il contenuto del tag <title> in Article_Info.xml, Book_Info.xml o Set_Info.xml, ed imposta un valore nel parametro mainfile in publican.cfg, in modo che publican possa trovare il nodo XML radice e le entità relative al documento.

Notare che il comando publican rename non modifica il nome di nessun file. Quindi, il nodo XML radice e le entità del documento sono localizzate sempre nei file relativi al titolo originale del documento — Server_Configuration_Guide, nel precedente esempio.

--product nuovo_prodotto

modifica il nome del prodotto cui si applica il documento. Per esempio, se il prodotto era ForceRivet ed ora è denominato PendantFarm, spostarsi nella directory radice del documento ed eseguire:

publican rename --product PendantFarm

Il comando modifica il contenuto del tag <productname> in Article_Info.xml, Book_Info.xml o Set_Info.xml.

--version nuova_versione

modifica la versione di prodotto cui si applica il documento. Per esempio, se la versione precedente era 1.0 ma ora è cambiata in 2.0 , spostarsi nella directory radice del documento ed eseguire:

publican rename --version 2.0

Il comando modifica il contenuto del tag <productnumber> in Article_Info.xml, Book_Info.xml o Set_Info.xml.

In un comando, è possibile usare una loro qualsiai combinazione. Per esempio:

publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0

3.6. Preparare un documento per la traduzione

Supporto per la localizzazione di documenti è stata una considerazione chiave del progetto di Publican. Il workflow di traduzione generale dei documenti sviluppati in Publican procede come segue:

Completare l'XML di un docuemnto.
Questa versione XML del documento dovrebbe essere considerata ‘frozen’. Se il documento si trova in un repository con controllo di versione, a questo punto, la versione verrebbe spostata in una cartella separata o branch. In tal modo i redattori possono iniziare a lavorare su versioni successive del documento in un branch, e fornire una base stabile per traduzione in un altro branch.
Generare i file POT (Portable Object Template) dai file XML:
```
$ publican update_pot
```
Se è la prima volta che si creano i file POT per il documento, Publican crea una nuova sottocartella, denominata pot. La sottocartella pot contiene un file pot per ciascun file XML nel documento. Se Publican ha creato i file POT precedentemente, Publican aggiorna i file POT esistenti per rispecchiare i cambiamenti apportati ai file XML dall'ultimo aggiornamento dei file POT.
Rimuovere i file XML non usati
Publican genera un file POT per ogni file XML presente della cartella dei file XML, che siano usati o meno nel documento. Se si trasformano in POT file XML non usati, si spreca il tempo e lo sforzo dei volontari traduttori, e si spreca denaro per le traduzioni commissionate a pagamento.
Usare il comando publican print_unused per visualizzare l'elenco dei file XML non usati nel documento.
Generare dai file POT, i file PO (Portable Object) per poter avviare la traduzione in una particolare lingua.
```
$ publican update_po --langs=codice_lingua
```
dove codice_lingua è il codice per la lingua target. Fare riferimento all'Appendice F, Codici di lingua per maggiori informazioni su questi codici. Si possono fornire codici linguistici multipli, separati da virgole, in modo da generare i file PO per più lingue. Per esempio:
```
$ publican update_po --langs=hi-IN,it-IT,ru-RU,zh-CN
```
Se è la prima volta che i file PO vengono creati per una lingua, Publican crea una nuova sottocartella, il cui nome coincide con il codice linguistico specificato con l'opzione --langs=. La sottocartella contiene un file PO per ciascun file POT nella sottocartella pot. Se Publican ha creato i file PO precedentemente, Publican aggiorna i file PO esistenti per rispecchiare i cambiamenti apportati ai file POT dall'ultimo aggiornamento dei file PO. E' possibile aggiornare i file PO esistenti in tutte le sottocartelle, usando l'opzione --langs=all:
```
$ publican update_po --langs=all
```
Rimuovere i file POT non usati
Publican genera un file PO per ogni file POT presente della cartella pot, a prescindere se il file POT corrisponda o meno ad un file XML usato nel documento, o corrisponda ad un file XML esistente. Se si trasformano in file PO, i POT da file XML non usati od eliminati, si spreca il tempo e lo sforzo dei volontari traduttori, e si spreca denaro per le traduzioni commissionate a pagamento.
Quando si generano i file PO, Publican mostra un avviso per i file POT che non presentano un corrispondente file XML, tuttavia genera comunque il file PO. Comunque, Publican non avvisa se esiste un file POT corrispondente ad un file XML non usato nel documento.
Tradurre le stringhe contenute nei file PO.
Creare il documento per la lingua desiderata, per esempio:
```
$ publican build --formats=html,html-single,pdf --langs=it-IT,nb-NO
```
o il pacchetto per la lingua desiderata, per esempio:
```
$ publican package --lang=it-IT
```
E' possibile creare il documento in tutte le lingue di cui si dispone una traduzione, usando l'opzione --langs=all, mentre i pacchetti vanno compilati individualmente. Fare riferimento alla Sezione 3.7, «Creare un documento» ed alla Sezione 3.8, «Creare il pacchetto di un documento» per maggiori informazioni.
Importante — impostare Project-Id-Version per il pacchetto
Il numero di release dei pacchetti RPM per i documenti tradotti viene impostato con il parametro Project-Id-Version nel file Article_Info.po o Book_Info.po. Per esempio, la release 3 di un libro in lingua giapponese avrebbe la seguente impostazione nel file ja-JP/Book_Info.po:
```
"Project-Id-Version: 3
"
```
Notare che il numero di release di un pacchetto in una certa lingua non condivide nessuna relazione con il numero di rilascio del pacchetto relativo allo stesso documento in lingua originale o in altra lingua. Questo numero si riferisce esclusivamente ad una lingua.

3.7. Creare un documento

Nota — Personalizzare la presentazione

I parametri impostati nel file di configurazione del documento (per impostazione publican.cfg), permettono di controllare molti aspetti riguardanti la presentazione di un documento (Sezione 3.1.1, «Il file publican.cfg»).

Se si mentengono versioni multiple di un documento, si può creare un file di configurazione per ciascuna versione. Quando si crea un documento, si può usare l'opzione --config per specificare il file da usare per una particolare compilazione, per esempio:

publican build --formats html,pdf --langs en-US,de-DE,it-IT --config community.cfg

Per creare un documento:

Verificare che nel file Nome_Doc.ent, siano state configurate le entità YEAR e HOLDER, come descritto nella Sezione 3.1.6, «Nome_Doc.ent».
Spostarsi nella cartella radice del documento. Per esempio, se il documento ha il nome Libro_di_Prova e si trova in ~/libri/, eseguire il seguente comando:
```
cd ~/libri/Libro_di_Prova
```
Eseguire un test, per evitare che ci siano errori di compilazione nel linguaggio desiderato, per esempio:
```
publican build --formats=test --langs=it-IT
```
Eseguire il seguente comando per creare il libro:
```
publican build --formats=formati --langs=lingue
```
Sostituire formati con la lista dei formati d'uscita, separati da virgole, per esempio html,html-single,pdf. Sostituire lingue con la lista dei codici linguistici, separati da virgole, per esempio en-US,sv-SE,it-IT,ko-KR.

Formati per l'azione `build`

html: Publican presenta il documento in multiple pagine HTML, con ciascun capitolo e le principali sezioni su pagine separate. Publican crea un indice all'inizio del documento e posiziona controlli di navigazione su ogni pagina.
Usare i parametri chunk_first e chunk_section depth nel file publican.cfg, per controllare il tipo di suddivisione delle sezioni in questo formato d'uscita.
html-single: Publican presenta il documento in una singola pagina HTML con la tabella dei contenuti posta in cima alla pagina.
html-desktop: Publican presenta il documento in una singola pagina HTML con la la tabella dei contenuti posta in un pannello separato a sinistra del documento.
man: Publican presenta il documento in pagine di manuale (o "man page"), in uso nei Sistemi Operativi Linux, Unix e simili.
pdf: Publican presenta il documento in un file PDF.
test: Publican controlla la validità della struttura XML del libro, senza effettuare nessuna trasformazione.
txt: Publican presenta il documento in un singolo file di testo.
epub: Publican presenta il documento in un e-book in formato EPUB.
eclipse: Publican presenta il documento come un plugin d'aiuto di Eclipse. Vedere la Sezione 3.1.1, «Il file publican.cfg» per i dettagli sui parametri d'impostazione ec_id, ec_name ed ec_provider.

I seguenti esempi mostrano alcuni comandi comunemente usati con publican build:

publican build --help: Elenca le opzioni disponibili in publican build per creare un libro.
publican build --formats=test --langs=lingue: Controlla che il libro compili correttamente. Compilare con --formats=test prima di eseguire ogni altro comando publican build, e prima di riportarlo su un repository di controllo versione, da cui altri contributori possano scaricarlo.
publican build --formats=html --langs=lingue: Compila il libro in formato HTML su pagine multiple. Il documento in HTML viene salvato nella directory Nome_Doc/tmp/lingua/html/. Ogni capitolo e ogni sezione principale viene disposto in un file HTML separato. E' possibile controllare il livello di suddivisione delle sotto-sezioni da presentare su pagine HTML separate, con il parametro chunk-section-depth in publican.cfg — fare riferimento alla Sezione 3.1.1, «Il file publican.cfg».
publican build --formats=html-single --langs=lingue: Crea il libro in formato HTML su una pagina singola. Il documento è un unico file HTML salvato nella directory Nome_Doc/tmp/lingua/html-single/.
publican build --formats=pdf --langs=lingue: Crea il libro in formato PDF. Publican si appoggia ad una applicazione esterna, FOP per rendere il PDF. Quindi, la compilazione per PDF potrebbe non essere disponibile su tutti i sistemi, dipendendo dalla disponibilità di FOP. Il documento è un unico file PDF salvato nella directory Nome_Doc/tmp/lingua/pdf/.
publican build --formats=html,html-single,pdf --langs=lingue: Crea il libro nei formati HTML su pagine multiple e su pagina singola, e PDF.

3.7.1. Compilare un documento senza controllo di validità

Publican controlla la validità della struttura XML con il DTD (Document Type Definition) prima di compilare il contenuto. Tuttavia in certe situazioni, come quando un documento è in fase di sviluppo, si potrebbe voler saltare la validazione durante la compilazione, soprattutto se il documento contiene riferimenti incrociati (<xref>) a sezioni del documento che ancora non esistono. Per saltare la validazione, eseguire publican build con l'opzione --novalid. I riferimenti a contenuto non esistente, nel documento creato, appaiono con tre punti interrogativi, ???.

Poichè il documento non risulta validato con il DTD, la qualità della presentazione prodotta usando l'opzione --novalid è quantomeno sospetta. Non pubblicare i documenti compilati con l'opzione --novalid.

3.7.2. Compilare un documento creato con Publican 0

I documenti prodotti con precedenti versioni di Publican (versioni fino alla 0.45, inclusa) non hanno un file publican.cfg; un insieme di parametri simili veniva definito in un Makefile. Prima di compilare un tale documento con una versione corrente di Publican (versione 0.99 in poi), occorre convertire il Makefile in un file publican.cfg. Publican è in grado di fare automaticamente questa conversione:

Spostarsi nella cartella del documento, contenente il Makefile.
Eseguire publican old2new. Publican analizza il Makefile e crea un file publican.cfg con parametri equivalenti, quando possibile.

Eseguendo il comando publican old2new, Publican non modifica o elimina il Makefile originale. Un Makefile ed un file publican.cfg possono coesistere nello stesso documento.

3.8. Creare il pacchetto di un documento

Pacchetti non pacchetti RPM

Nota — Personalizzare l'output

I parametri impostati nel file di configurazione del documento (per impostazione publican.cfg) permettono di controllare molti aspetti riguardanti il pacchetto di un documento (Sezione 3.1.1, «Il file publican.cfg»).

Se si mentengono versioni multiple di un documento, si può creare un file di configurazione per ciascuna versione. Quando si crea il pacchetto di un documento, si può usare l'opzione --config per specificare il file da usare per una particolare compilazione, per esempio:

publican package --lang it-IT --config community.cfg

Publican non solo crea documenti, ma può creare anche pacchetti RPM di questi contenuti, da distribuire su workstation o server web. I pacchetti RPM sono usati per distribuire software nei computer con sistemi operativi Linux che usano un Gestore di pacchetti RPM. Tra questi sistemi operativi si annoverano Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux e Yellow Dog Linux, per citarne alcuni.

3.8.1. Tipi di pacchetti RPM

Publican può produrre sia pacchetti RPM di sorgenti (pacchetti SRPM) sia pacchetti RPM di binari. Inoltre, sia i pacchetti SRPM sia i pacchetti RPM binari possono essere configurati per essere portati su workstation o server web.

3.8.1.1. Pacchetti RPM di sorgenti e pacchetti RPM di binari

Un pacchetto SRPM contiene il codice sorgente usato per generare il software, invece del software vero e proprio. Per usare un pacchetto SRPM, un sistema deve compilare il codice sorgente in software — o in questo caso in documenti. I pacchetti SRPM generati da Publican contengono i file XML dei documenti ed un file spec, invece di documenti completati (HTML, PDF, EPUB, ecc). Con la versione attuale di RPM Package Manager, non è possibile installare direttamente documentazione da un pacchetto SRPM.

Al contrario, i pacchetti RPM binari contengono software — o in questo caso, un documento — pronto per essere salvato nel file system del computer ed essere immediatamente usato. I contenuti di un pacchetto RPM binario non necessitano di essere compilati dal sistema su cui vengono installati e perciò, il sistema non ha bisogno di installare Publican. L'installazione su un webserver di documentazione, generata da Publican, necessita di Publican, ma in questo caso non per la compilazione del codice sorgente. Fare riferimento alla Sezione 3.8.1.2, «Pacchetti per il desktop e pacchetti per il web» per una descrizione sulle differenze tra documentazione installata per uso locale (RPM per desktop) e documentazione installata per servire contenuti web (RPM per il web).

3.8.1.2. Pacchetti per il desktop e pacchetti per il web

Publican può creare pacchetti di documenti che possono essere consultati su una workstation (pacchetto RPM desktop) o che possono essere installati su un server web e resi pubblici sul World Wide Web (pacchetto RPM web). Il pacchetto RPM desktop generato da Publican, e il pacchetto RPM web dello stesso documento differiscono per il fatto che il pacchetto RPM desktop installa solo la documentazione per l'uso sul computer locale, mentre l'RPM web installa anche il contenuto necessario a servire il World Wide Web.

I pacchetti RPM (binari) desktop di documenti creati con Publican, contengono la documentazione in formato HTML, su pagina singola. I documenti distribuiti con questi pacchetti, vengono installati in una sotto-cartella di /usr/share/doc/, secondo la specifica FHS (Filesystem Hierarchy Standard) della ‘Miscellaneous documentation’.^[3] Il pacchetto RPM desktop contiene anche un file desktop, salvato in /usr/share/applications/. Questo file abilita gli ambienti desktop come GNOME e KDE, ad aggiungere il documento al menu del desktop, facililtando l'accesso agli utenti. In GNOME, per impostazione predefinita, la voce viene inserita sotto il menu Sistema → Documentazione. Se si desidera personalizzare il posizionamento della voce nel menu, occorre creare un pacchetto per il menu dei documenti, che fornisce i file .directory e .menu ed occorre impostare nel file publican.cfg, i parametri dt_requires, per richiedere l'uso del pacchetto per il menu dei documenti, ed il parametro menu_category per fornire la categoria di menu appropriata. Fare riferimento alla Sezione 3.8.1.3, «Voci nel menu del desktop per i documenti».

Per impostazione, i pacchetti RPM web dei documenti di Publican, contengono la documentazione in formato HTML, su pagina singola e pagine multiple, e nei formati EPUB e PDF. I formati inclusi variano se:

si pubblica documentazione in una lingua, al momento priva di supporto per la presentazione in PDF. Publican si basa su FOP per generare il PDF. Allo stato attuale, FOP non supporta la scrittura sinistrorsa, come d'uso nella lingua araba, iraniana o ebraica. Inoltre, poichè allo stato attuale, FOP non è in grado di specificare i font carattere per carattere, una deficenza di font in scritture indo-arie, tra cui anche alcuni glifi latini, impediscono a Publican di generare presentazioni PDF in lingue indo-arie. Per impostazione, Publican non include i file PDF nei pacchetti web generati per la lingua araba, iraniana, ebraica o altra lingua indo-aria.
il libro o brand contiene il parametro web_formats. Il valore di questo parametro, scavalca i formati creati, in modo predefinto, da Publican. Per esempio, per pubblicare un documento solo nei formati HTML su pagina singola, PDF e testo, impostare web_formats: html-single,pdf,txt.

Il contenuto dei pacchetti è installato in sotto-cartelle di /var/www/html/, una comune radice di documenti per server web. Notare che un pacchetto SRPM web genera sia il pacchetto RPM binario per il web sia il pacchetto RPM binario per il desktop.

3.8.1.3. Voci nel menu del desktop per i documenti

Per impostazione, i pacchetti RPM dei documenti di Publican per il desktop, appaiono negli ambienti GNOME, sotto il menu Sistema → Documentazione. All'aumentare del numero di documenti installati, questo menu diventa intricato e di difficile navigazione. Ciò porta ad un menu con molti documenti per differenti prodotti ed in alcuni casi, in diverse lingue, che crea non poca confusione.

Per raggruppare i documenti per un prodotto, in un sotto-menu separato, nel menu Sistema → Documentazione di GNOME, occorre:

creare e distribuire un pacchetto desktop-menu (per il menu del desktop), che crea il sotto-menu.
specificare nel documento, la category del menu, ed opzionalmente, nel pacchetto di documentazione, specificare una direttiva require per richiedere anche l'installazione del pacchetto desktop-menu.

Notare che il menu Documentazione non raggruppa le voci in sotto-menu finchè non sono presenti due o più documenti appartenenti al sotto-menu. Il primo documento compare sotto Sistema → Documentazione.

3.8.1.3.1. Creare un pacchetto desktop-menu

Un pacchetto desktop-menu consiste di:

un file desktop entry (.directory) che fornisce i metadati sul nuovo sotto-menu.
un file desktop menu (.menu) che definisce la posizione del sotto-menu nel menu Documentazione.

La struttura del file .directory, per documentazione generata da Publican, è la seguente:

il group header [Desktop Entry]
il parametro Name, impostato con il nome del sotto-menu da posizionare nel menu Documentazione.
opzionalmente, le localizzazioni per il parametro Name, nel formato Name[codice_lingua], dove codice_lingua è un codice linguistico in formato glibc, non nel formato XML usato da Publican.
il parametro Comment, impostato con una descrizione del sotto-menu.
opzionalmente, le localizzazioni per il parametro Comment, nel formato Comment[codice_lingua], dove codice_lingua è un codice linguistico in formato glibc, non nel formato XML usato da Publican.
il parametro Type, imposto a Directory.
il parametro Encoding, impostato a UTF-8.

Esempio 3.5. Esempio di file .directory

Il seguente file, menu-example.directory mostra la struttura di un file di desktop entry:

[Desktop Entry]
Name=Example
Name[fr]=Exemple
Name[it]=Esempio
Comment=Example Documentation menu
Comment[fr]=Exemple d'une menu de documentation
Comment[it]=Esempio di un menù di documentazione
Type=Directory
Encoding=UTF-8

Il file di desktop entry, è salvato in /usr/share/desktop-directories/

Per una descrizione completa di come funzionano le desktop entry, fare riferimento alla Desktop Entry Specification, disponibile su http://standards.freedesktop.org/entry-spec/latest/

Un file di desktop menu, è un file XML che contiene:

un DTD (Document Type Declaration), per la Desktop Menu Specification di freedesktop.org:

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">

un elemento radice, <Menu>, contenente:
- un elemento <Name> contenente Documentation
- un altro elemento <Menu> che a sua volta, contiene:
  - un elemento <Name> contenente Documentation (come l'elemento radice)
  - un elemento <Directory> contenente il nome del file di desktop entry creato, per esempio:
    <Directory>menu-example.directory</Directory>
  - un elemento <Includes> contenente X-nome_categoria, dove nome_categoria è un identificatore per i documenti da raggruppare nel sotto-menu. Per esempio:
    <Includes>X-Example-Docs</Includes>

Esempio 3.6. Esempio di file .menu

Il seguente file, menu-example.menu mostra la struttura di un file di desktop menu.

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
	<Name>Documentation</Name>
	<Menu>
		<Name>Documentation</Name>
		<Menu>
			<Name>Example</Name>
			<Directory>menu-example.directory</Directory>
			<Include>
				<Category>X-Example-Docs</Category>
			</Include>
		</Menu>
	</Menu> 
</Menu>

Il file di desktop menu è salvato in /etc/xdg/menus/settings-merged/

Per una descrizione completa di come funzionano i desktop menu, fare riferimento alla Desktop Menu Specification, disponibile su http://standards.freedesktop.org/desktop-menu-spec/latest/

3.8.1.3.2. Impostare un categoria di desktop menu

Per posizionare un documento in un sotto-menu di Sistema → Documentazione, impostare il parametro menu_category nel proprio file publican.cfg, in modo da corrispondere al contenuto dell'elemento <Includes> nel relativo file di desktop menu. Per esempio, si consideri il file di desktop menu, contenente l'elemento:

<Includes>X-Example-Docs</Includes>

Per posizionare un documento nel sotto-menu definito da questo file di desktop menu, il file publican.cfg del documento, dovrebbe contenere:

menu_category: X-Example-Docs

Notare che si può includere questo parametro nel file defaults.cfg o nel file overrides.cfg di un brand, cosicchè tutti i documenti creati con il brand siano automaticamente raggruppati nel sotto-menu, senza dover impostare il parametro menu_category in ogni documento.

Se si distribuiscono i file di desktop menu e di desktop entry in un pacchetto RPM, si può impostare che i pacchetti RPM di documenti richiedano il pacchetto di desktop-menu. Impostando questa dipendenza, il pacchetto di desktop-menu è installato automaticamente sul sistema degli utenti, durante l'installazione del pacchetto di documentazione, in modo da apparire nel sotto-menu creato per il progetto. Impostare la dipendenza con il parametro dt_requires, nel file publican.cfg del documento. Per esempio, se si distribuisce un pacchetto di desktop-menu di nome foodocs-menu, impostare:

dt_requires: foodocs-menu

Notare che si può includere il parametro nel file defaults.cfg o nel file overrides.cfg di un brand, cosicchè tutti i documenti creati con il brand richiedano lo stesso pacchetto di desktop-menu.

3.8.2. Il comando `publican package`

Usare il comando publican package --lang=Codice_Lingua per creare il pacchetto del documento, da distribuire nella lingua specificata con l'opzione --lang. Fare riferimento all'Appendice F, Codici di lingua per maggiori ragguagli sull'uso dei codici linguistici.

Se si esegue publican package senza altre opzioni oltre alla obbligatoria opzione --lang, Publican genera un pacchetto SRPM web. La lista completa delle opzioni per publican package è la seguente:

--lang lingua: specifica la lingua per cui creare il pacchetto della documetazione.
Traduzioni incomplete
Se la traduzione in una particolare lingua è incompleta alla scadenza della release, si consideri di segnare la lingua con il parametro ignored_translations nel file publican.cfg del documento. Il pacchetto viene creato con un nome appropriato per la lingua, ma contiene la documentazione nella lingua originale del XML, invece di una traduzione parziale. A traduzione completata, rimuovere il parametro ignored_translations, incrementare il numero di release del campo Project-Id-Version, nel file Book_Info.po per la lingua, e rigenerare il pacchetto. Al momento della distribuzione del pacchetto revisionato, esso sostituisce il pacchetto originale non tradotto.
--config nome_file: specifica di usare un file di configurazione diverso dal predefinto, publican.cfg.
--desktop: specifica di creare un pacchetto RPM desktop invece di un pacchetto RPM web.
--brew: specifica di trasferire il pacchetto completato su Brew. Brew è il sistema di compilazione usato all'interno di Red Hat; questa opzione non ha effetto al di fora di Red Hat.
--scratch: quando usato con le opzioni --brew e --desktop, specifica di compilare il pacchetto SRPM come uno scratch build (compilazione di lavoro) da trasferire su Brew. Gli scratch build sono usati per verificare la correttezza strutturale del pacchetto SRPM, senza aggiornare il database dei pacchetti con il pacchetto risultante.
--short_sighted: specifica di creare il pacchetto senza includere il numero di versione del software (version nel file publican.cfg), nel nome del pacchetto.
Omettere il numero di versione del sofware
Molta documentazione per software è versione specifica. Nella migliore delle ipotesi, le procedure descritte nella documentazione per una versione di un prodotto potrebbero non essere d'aiuto per installare, configurare o usare una versione differente del prodotto. Nella peggiore, le procedure descritte per un prodotto potrebbero essere fuorvianti o addirittura dannose se applicate ad una versione differente.
Se si distribuisce documentazione attraverso pacchetti RPM, senza numeri di versione nei nomi dei pacchetti, il Gestore dei Pacchetti RPM sostituisce automaticamente, sui sistemi degli utenti, la documentazione esistente con l'ultima versione disponibile; gli utenti non potrebbero avere accesso a più di una versione alla volta. Assicurarsi di volere realmente questo risultato.
--binary: specifica di compilare il pacchetto come un pacchetto RPM binario.
--cvs: specifica di importare il pacchetto SRPM nel CVS. Ciò richiede di impostare i parametri cvs_root, cvs_pkg e cvs_branch nel file di configurazione del documento; publican.cfg per impostazione.

Dopo aver eseguito il comando publican package, Publican salva i pacchetti SRPM completati nella cartella tmp/rpm del documento, e i pacchetti RPM binari nella cartella tmp/rpm/noarch.

Per impostazione, i pacchetti di documentazione generati da Publican, sono denominati

nomeprodotto-titolo-numeroprodotto-[web]-lingua-edizione-numeropubblicazione. build_target.noarch.estensione_file.

Publican usa le informazioni nel file di configurazione (publican.cfg per impostazione predefinita), del documento per fornire i vari parametri nel nome di file, e poi le informazioni nel file Book_Info.xml per altre informazioni non presenti nel file di configurazione. Fare riferimento alla Sezione 3.1, «I file nella directory del libro» per i dettagli su questi file di configurazione. Inoltre:

i pacchetti RPM per il web includono l'elemento -web- tra la versione del prodotto ed il codice della lingua.
i pacchetti SRPM hanno l'estensione .src.rpm mentre i pacchetti RPM binari l'estensione .rpm.
i pacchetti RPM binari includono build_target.noarch prima della estensione del file, dove build_target rappresenta sistema operativo e versione relativa, per cui il pacchetto è stato compilato, come specificato dal parametro os_ver, nel file publican.cfg. L'elemento noarch specifica che il pacchetto può essere installato su ogni sistema, indipendentemente dall'architettura di sistema.
l'uso dell'opzione --short_sighted, rimuove il termine -numeroprodotto- dal nome del pacchetto.
i pacchetti di documenti tradotti, prendono i numeri di release dal parametro Project-Id-Version nei file Article_Info.po o Book_Info.po. Questo numero è specifico alla particolare lingua e non ha alcuna relazione con i numeri di relase dello stesso documento, nella lingua originale o in altra lingua.

3.8.2.1. Il comando `publican package` — Esempi d'uso

I seguenti esempi mostrano alcune opzioni comuni, riferite alla II edizione, VI revisione del documento Foomaster 9 Configuration Guide.

publican package --lang=it-IT: genera un pacchetto SRPM per desktop di nome Foomaster-Configuration_Guide-9-web-it-IT-2-6.src.rpm, contenente i sorgenti della documentazione in italiano ed uno spec file.
publican package --desktop --lang=it-IT: genera un pacchetto SRPM per desktop di nome Foomaster-Configuration_Guide-9-it-IT-2-6.src.rpm, contenente la documentazione in italiano e uno spec file.
publican package --binary --lang=it-IT: genera sia un pacchetto RPM per web di nome Foomaster-Configuration_Guide-9-web-it-IT-2-6.el5.noarch.rpm sia un pacchetto RPM binario per desktop di nome Foomaster-Configuration_Guide-9-it-IT-2-6.el5.noarch.rpm, contenenti la documentazione in italiano, compilati per il sistema operativo Red Hat Enterprise Linux 5.
publican package --desktop --binary --lang=it-IT: genera un pacchetto RPM binario per desktop di nome Foomaster-Configuration_Guide-9-it-IT-2-6.el5.noarch.rpm, contenente la documentazione in italiano, compilati per il sistema operativo Red Hat Enterprise Linux 5.
publican package --desktop --short_sighted --lang=it-IT: genera un pacchetto SRPM per desktop di nome Foomaster-Configuration_Guide-it-IT-2-6.src.rpm, contenente la documentazione in italiano. Questo pacchetto sostituisce ogni precedente versione della Configuration Guide di Foomaster, esistente su un sistema. In tal caso, gli utenti non possono avere accesso contemporaneamente alla Foomaster 8 Configuration Guide ed alla Foomaster 9 Configuration Guide.

3.9. Tagging condizionale

In alcuni casi occorre mantenere multiple versioni di un libro; per esempio, un HOWTO per il prodotto FOO può avere una versione upstream ed una versione enterprise, con piccole differenze tra loro.

Publican semplifica la gestione delle differenze tra versioni multiple di un libro, permettendo di usare una sorgente unica per tutte le versioni. Il tagging condizionale garantisce che il contenuto di una versione specifica, compaia soltanto nella versione stabilita; ossia, permette di condizionare il contenuto.

Per condizionare il contenuto di un libro, usare il tag condition. Per esempio, si supponga che il libro How To Use Product Foo abbia una versione "upstream", una versione "enterprise" e una versione "beta".

<para condition="upstream">
	<application>Foo</application> starts automatically when you boot the system.
</para>
	
<para condition="enterprise">
	<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>.
</para>	
	
<para condition="beta">
	<application>Foo</application> does not start automatically when you boot the system.
</para>
	
<para condition="beta,enterprise">
	To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file.
</para>

Per compilare una versione specifica (e quindi catturare solo il conenuto relativo a questa versione), aggiungere il parametro condition: versione al file publican.cfg ed eseguire il comando publican build, ormai noto. Per esempio, aggiungendo condition: upstream al file publican.cfg dell'HOWTO How To Use Product Foo, e poi eseguendo:

publican build --formats=pdf --langs=en-US

Publican filtra i contenuti con i tag condizionali, escluso il tag con l'attributo condition="upstream" e compila l'How To Use Product Foo in un file PDF in lingua inglese statunitense.

Nodi root e tag condizionale

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora">
<title>Installation and configuration on Fedora</title>

[text of chapter]

</chapter>

ed il capitolo è incluso in User_Guide.xml con un tag <xi:include>, il documento non compila se è presente l'impostazione condition: Ubuntu nel file publican.cfg.

Per escludere il capitolo, aggiungere un attributo condizionale al tag <xi:include> in User_Guide.xml, e non al tag <chapter> in Installation_and_configuration_on_Fedora.xml.

xref e tag condizionale

3.9.1. Tagging condizionale e traduzione

Usare con cautela il tagging condizionale

Usare il tagging condizionale con una certa cautela soprattutto nei libri che si presuma vengano tradotti, poichè ciò crea ulteriori difficoltà ai traduttori.

Il tagging condizionale crea difficoltà ai traduttori in due modi: oscura il contesto nei file PO (Portable Object) e rende più ardua la rilettura/correzione del documento, a quei traduttori non molto familiari con i tag condizionali.

I file PO includono tutti i tag presenti in XML, a prescindere dalle condizioni. Per esempio, se un traduttore apre il file PO, relativo all'How To Use Product Foo della Sezione 3.9, «Tagging condizionale», egli vede:

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> starts automatically when you boot the system."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<application>Foo</application> does not start automatically when you boot the system."
msgstr ""

#. Tag: para
#, no-c-format
msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file."
msgstr ""

Poichè i file PO non includono gli attributi dei tag, non è per nulla ovvio indicare ai traduttori che questi paragrafi sono tra loro alternativi e che il redattore non intende realizzare un flusso continuo da un paragrafo al successivo.

In questo esempio, i soli paragrafi in cui il senso scorre logicamente da un paragrafo al successivo è tra il terzo e il quarto. Poichè entrambi i paragrafi sono presenti nella versione beta del libro, essi (si spera), sono i soli ad avere senso. Quindi, l'uso dei tag condizionali costringe i traduttori a lavorare su brevi pezzi di brani, senza possibilità di seguire il contesto globale del discorso, da un paragrafo al successivo. In queste condizioni, ne risente la qualità della traduzione, aumentando di conseguenza il tempo richiesto — ed anche il costo della traduzione.

Inoltre, a meno che i traduttori non sappiano come configurare il file publican.cfg di Publican e non siano a conoscenza dei tag condizionali, essi non riuscirebbero a rivedere il documento finale tradotto. Se i traduttori non sono informati sull'uso di questi tag, quando procedono a rivedere un documento, rimarrebbero sorpresi nel non riuscire a trovare il testo che hanno tradotto e che facilmente trovano nei file PO. Quindi, se occorre usare i tag condizionali, ricordarsi di informare i propri traduttori del loro uso, fornendo loro il neccessario supporto.

In alternativa ai tag condizionali, si consideri di mantenere versioni separate di un libro, in branch separati di un repository con controllo di versione. In tal modo, è anche possibile condividere file XML e PO tra i vari branch; inoltre alcuni sistemi di controllo versione permettono di condividere correttamente le modifiche tra branch.

Se si mantengono due versioni di un libro nello stesso repository, si raccomanda di usare un file di configurazione distinto per ciascuna versione. Per esempio, il file upstream.cfg potrebbe contenere la condizione condition: upstream e il file enterprise.cfg la condizione condition: enterprise. Si potrebbe allora specificare di compilare una versione del documento, con l'opzione --config; per esempio, publican package --lang en-US --config upstream.cfg. Usare due file di configurazione separati, evita di dover editare ognivolta il file di configurazione, per la compilazione di un libro o pacchetto.

3.10. Software pre-release e documentazione draft

La documentazione completata per software pre-release non coincide con la documentazione draft (bozza).

Un documento draft è una versione incompleta di un libro o articolo, ed il cui stato incompleto non è correlato allo stato del software documentato.

Tuttavia in ogni caso, è importante comnunicare chiaramente lo stato del software, della documentazioni o di entrambi a tutti gli interessati: utenti, sviluppatori, lettori e revisori.

3.10.1. Denotare il software pre-release

La documentazione per software pre-release, soprattutto quello distribuito a tester, clienti e partner, dovrebbe portare un contrassegno, a denotare lo status beta del software.

Per creare il contrassegno, seguire la seguente procedura:

Agguingere il numero di versione del software pre-release, o un informazione di stato equivalente, al tag <subtitle> nel file Book_Info.xml. Inserire questa informazione tra tag <remark>. Per esempio:
```
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
```
Aggiungere show_remarks al file publican.cfg ed impostarlo ad '1':
```
show_remarks: 1
```

Compilando il libro con questo tag <remark> e con l'impostazione show_remarks, si definisce in modo chiaro ed inequivocabile la natura pre-release del software. Le compilazioni PDF visualizzano il contrassegno sulla copertina e sulla pagina del titolo. Le compilazioni HTML (sia su pagina singola sia su pagine multiple), visualizzano il contrassegno sulla pagina iniziale del file index.html.

Poichè questo approccio non modifica le informazioni nel file Book_Info.xml usato per generare gli RPM, esso garantisce anche che non ci sia alcuna ambiguità nelle operazioni del sottosistema RPM.

Importante

Rimane una responsabilità del redattore rimuovere il tag <remark> con il suo contenuto e rimuovere o disattivare l'attributo show_remarks quando la documentazione viene aggiornata con la versione di release del software.

3.10.2. Denotare la documentazione draft

La documentazione incompleta resa disponibile per revisione dovrebbe essere indicata chiaramente come tale.

Per far comparire il contrassegno draft ad un documento, aggiungere l'attributo status="draft" al tag <article>, <book> o <set> nel nodo radice del documento. Per esempio:
```
<book status="draft">
```

Per impostazione, il nodo radice coincide con il tag <book> nel file Nome_Doc.xml.

Nel caso di un articolo o set di volumi, il nodo radice coincide con il tag <article> o <set>, rispettivamente, nel file Nome_Doc.xml.

L'aggiunta dell'attributo status="draft" causa la comparsa su ciascuna pagina del documento del contrassegno draft.

Anche se si modificano solo brevi porzioni di un documento da revisionare, contrassegnare le pagine come draft incoraggia i lettori a riportare gli errori ed i refusi intercettati. Serve anche ad assicurare che lettori occasionali evitino di far danni scambiando un draft per una versione finale.

3.10.3. Denotare come draft la documentazione per software pre-release

Per denotare propriamente la documentazione incompleta relativa a software pre-release, seguire entrambe le procedure indicate in precedenza.

^[1] Fare riferimento a http://www.section508.gov/

^[2] Fare riferimento alla sezione 2.4 "Character Data and Markup" dello standard XML 1.0, disponibile su http://www.w3.org/TR/2008/REC-xml-20081126/.

^[3] Fare riferimento a http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA