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 5, Branding per maggiori informazioni.

Advanced parameters Delete me and reference appendix

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 4.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 6.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 4.8.2, «Il comando publican package» e la Sezione 5.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 4.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 4.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.

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 4.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

specifies the document name. If set, this value overrides the content of the <title> tag in the Book_Info.xml file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).

dt_obsoletes

il pacchetto reso obsoleto dal pacchetto desktop.

dt_requires

il pacchetto richiesto dal pacchetto desktop, per esempio, il pacchetto del menu di una documentazione. Fare riferimento alla Sezione 4.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

When you install Publican, you also install a local copy of the DocBook XML DTD version 4.5 and accompanying Extensible Stylesheet Language (XSL). If you set a version of the DTD for which there is no local support, Publican must download the appropriate DTD and XSL from an online source every time that it builds the document. Building your document is delayed while this download takes place. The combined size of the required files is around 70 MB.

type

Override Type for DocType. Must be a complete string.

Nota

This parameter is only permitted in a brand.

dtdver

Override URI for DocType. Must be a complete string.

Nota

This parameter is only permitted in a brand.

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

specifies the edition number for this document.

Nota

The <edition> tag was required by versions of Publican prior to 2.0, which used it to generate the version of a documentation package. This tag is now completely optional and does not affect packaging in any way.

extras_dir

the directory Publican will process extra files from. (Default: extras)

footer

specifies content that will be injected into the bottom of every page on the site.

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 4.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 linguistici 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 4.6, «Translating a document» ed all'Appendice F, Codici di lingua.

tmp_dir

la cartella di output di Publican. (Per impostazione: tmp)

mainfile

overrides the default Info file. Specifies where Publican looks for info fields. Use the full filename without the path.

license

specifica la licenza usata dal pacchetto. Per impostazione, Publican seleziona la licenza GFDL (GNU Free Documentation License). Fare riferimento alla Sezione 4.8, «Creare il pacchetto di 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 4.8.1.3, «Voci nel menu del desktop per i documenti».

os_ver

specifies the operating system for which to build packages. Publican appends the value that you provide here to the RPM packages that it builds. For example, .fc15 for Fedora 15. The default value is .el5, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to Sezione 4.8, «Creare il pacchetto di un documento» and Sezione 5.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

specifies the product to which this documentation applies. If set, this value overrides the content of the <productname> tag in the Book_Info.xml file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).

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 6.2, «Set distribuiti».

release

override the default Revision History file direction. By default Publican assumes the Revision History is sorted in descending order, newest versions at teh top, if you wish to change this and have the oldest revisions at the top, then set this parameter to asc or ascending.

rev_file

override the default Revision History file. Specifies where Publican looks for revision fields. Use the full filename without the path. When combined with the Publican action add_revision, it enables you to build a book without a Revision_History.xml.

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 6.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.

dtdver

override the default sort weighting for books in a Publican website. Books are displayed on the website in descending sort order. For example, a book with sort order 10 appears before a book with sort order 5. By default, this value is set to 50.

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 4.8, «Creare il pacchetto di un documento».

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.

tmpl_path

specifies the path to Publican templates. By default, this is set to /usr/share/publican/templates.

type

allows a site to override the template used when building the embedded toc using in web_style=1 sites. The template must be in the same directory that toc.tmpl is in. The template name must be must be of the form toc_type+.tmpl

toc_type

specifies the name of a custom TOC template. By default, Publican looks for toc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.

toc_section_depth

controlla fino a che livello rappresentare le sotto-sezioni nel sommario principale dei contenuti. 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 4.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 4.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 4.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 7, Creare un sito web con Publican.

Importante — web_home è deprecato

In Publican 2.2, web_home is replaced by web_type: home. Support for web_home will be removed in a future version of 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 7, Creare un sito web con Publican.

web_obsoletes

specifica i pacchetti resi obsoleti da questo RPM per il web. Fare riferimento alla Sezione 4.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 7, Creare un sito web con Publican.

web_type

sets the web style, which determines the layout and presentation of the website. Valid values are 1 and 2. Style 1 features a navigation pane at the left side of the screen that provides access to all of the documents on the site. Style 2 offers a breadcrumb-like navigation system.

web_type

specifies that the document is descriptive content for a Publican-managed website rather than product documentation. This content includes the home page of the website (web_type: home), product description pages (web_type: product), and version description pages (web_type: version). Refer to Capitolo 7, 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 7, Creare un sito web con Publican.

classpath

Extra options to pass to wkhtmltopdf. e.g. wkhtmltopdf_opts: "-O landscape -s A3"

<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 4.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 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 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 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 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.

<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 proprietà 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.

--lang lingua

specifica la lingua per cui creare il pacchetto della documentazione.

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 predefinito, 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 fuori 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 software

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.