# Guida Utente

## Pubblicare libri, articoli, relazioni e raccolte di volumi con DocBook XML

### Don Domingo

Red Hat
Engineering Content Services
`ddomingo@redhat.com`

### Zac Dover

Red Hat
Engineering Content Services
`zdover@redhat.com`

### Sven Dowdeit

Debian and Docker installation instructions

### Norman Dunbar

OpenSUSE installation instructions

### Brian Forté

Red Hat
Engineering Content Services
`bforte@redhat.com`

### Rüdiger Landmann

Red Hat
Engineering Content Services
`r.landmann@redhat.com`

### Rebecca Newton

Red Hat
Engineering Content Services

### Joshua Oakes

Red Hat
Engineering Content Services

### Joshua Wulf

Red Hat
Engineering Content Services
`jwulf@redhat.com`

### Jeff Fearn

Extensive review, rough drafts, persistent annoyances.
`jfearn@redhat.com`

### Josef Hruška

Checking the Czech examples in Entities and translation
Fedora
Localization Project

Copyright © 2013 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).

Sommario

Questo manuale illustra come installare Publican. 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.

# Prefazione

## 1. Convenzioni del documento

Questo manuale utilizza numerose convenzioni per evidenziare parole e frasi, ponendo attenzione su informazioni specifiche.

### 1.1. Convenzioni tipografiche

Vengono utilizzate quattro convenzioni tipografiche per richiamare l'attenzione su parole e frasi specifiche. Queste convenzioni, e le circostanze alle quali vengono applicate, sono le seguenti.

`Neretto monospazio`

Usato per evidenziare l'input del sistema, incluso i comandi della shell, i nomi dei file ed i percorsi. Utilizzato anche per evidenziare tasti e combinazione di tasti. Per esempio:

> Per visualizzare i contenuti del file `my_next_bestselling_novel` nella vostra directory di lavoro corrente, inserire il comando cat my_next_bestselling_novel al prompt della shell e premere Invio per eseguire il comando.

Quanto sopra riportato include il nome del file, un comando della shell ed un tasto, il tutto riportato in neretto monospazio e distinguibile grazie al contesto.

Le combinazioni si distinguono dai tasti singoli tramite l'uso del segno più, il quale viene usato per creare una combinazione di tasti. Per esempio:

> Premere Invio per eseguire il comando.

> Premere Ctrl+Alt+F2 per usare un terminale virtuale.

Il primo esempio evidenzia il tasto specifico singolo da premere. Il secondo riporta una combinazione di tasti: un insieme di tre tasti premuti contemporaneamente.

Se si discute del codice sorgente, i nomi della classe, i metodi, le funzioni i nomi della variabile ed i valori ritornati indicati all'interno di un paragrafo, essi verranno indicati come sopra, e cioè in `neretto monospazio`. Per esempio:

> Le classi relative ad un file includono `filesystem` per file system, `file` per file, e `dir` per directory. Ogni classe possiede il proprio set associato di permessi.

Proportional Bold

Ciò denota le parole e le frasi incontrate su di un sistema, incluso i nomi delle applicazioni; il testo delle caselle di dialogo; i pulsanti etichettati; le caselle e le etichette per pulsanti di selezione, titoli del menu e dei sottomenu. Per esempio:

> Selezionare Sistema → Preferenze → Mouse dalla barra del menu principale per lanciare Preferenze del Mouse. Nella scheda Pulsanti, fate clic sulla casella di dialogo mouse per mancini, e successivamente fate clic su Chiudi per cambiare il pulsante primario del mouse da sinistra a destra (rendendo così il mouse idoneo per un utilizzo con la mano sinistra).

> Per inserire un carattere speciale in un file gedit selezionare Applicazioni → Accessori → Mappa del carattere dalla barra del menu principale. Selezionare successivamente Cerca → Trova… dal menu Mappa del carattere, digitare il nome desiderato nel campo Cerca e selezionare Successivo. Il carattere desiderato sarà evidenziato nella Tabella dei caratteri. Eseguire un doppio clic sul carattere per poterlo posizionare nel campo Testo da copiare e successivamente fare clic sul pulsante Copia. Ritornare sul documento e selezionare Modifica → Incolla dalla barra del menu di gedit.

Il testo sopra riportato include i nomi delle applicazioni; nomi ed oggetti del menu per l'intero sistema; nomi del menu specifici alle applicazioni; e pulsanti e testo trovati all'interno di una interfaccia GUI, tutti presentati in neretto proporzionale e distinguibili dal contesto.

Corsivo neretto monospazio o Corsivo neretto proporzionale

Sia se si tratta di neretto monospazio o neretto proporzionale, l'aggiunta del carattere corsivo indica un testo variabile o sostituibile . Il carattere corsivo denota un testo che non viene inserito letteralmente, o visualizzato che varia a seconda delle circostanze. Per esempio:

> Per collegarsi ad una macchina remota utilizzando ssh, digitare ssh username@domain.name al prompt della shell. Se la macchina remota è `example.com` ed il nome utente sulla macchina interessata è john, digitare ssh john@example.com.

> Il comando mount -o remount file-system rimonta il file system indicato. Per esempio, per rimontare il file system `/home`, il comando è mount -o remount /home.

> Per visualizzare la versione di un pacchetto attualmente installato, utilizzare il comando rpm -q package. Esso ritornerà il seguente risultato: package-version-release.

Da notare le parole in corsivo grassetto - username, domain.name, file-system, package, version e release. Ogni parola funge da segnaposto, sia esso un testo inserito per emettere un comando o mostrato dal sistema.

Oltre all'utilizzo normale per la presentazione di un titolo, il carattere Corsivo denota il primo utilizzo di un termine nuovo ed importante. Per esempio:

> Publican è un sistema di pubblicazione per DocBook.

### 1.2. Convenzioni del documento

Gli elenchi originati dal codice sorgente e l'output del terminale vengono evidenziati rispetto al testo circostante.

L'output inviato ad un terminale è impostato su `tondo monospazio` e così presentato:

    books        Desktop   documentation  drafts  mss    photos   stuff  svn
    books_tests  Desktop1  downloads      images  notes  scripts  svgs

Gli elenchi del codice sorgente sono impostati in `tondo monospazio` ma vengono presentati ed evidenziati nel modo seguente:

    package org.jboss.book.jca.ex1;

    import javax.naming.InitialContext;

    public class ExClient
    {
       public static void main(String args[])
           throws Exception
       {
          InitialContext iniCtx = new InitialContext();
          Object         ref    = iniCtx.lookup("EchoBean");
          EchoHome       home   = (EchoHome) ref;
          Echo           echo   = home.create();

          System.out.println("Created Echo");

          System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
       }
    }

### 1.3. Admonitions

E per finire, tre stili vengono usati per richiamare l'attenzione su informazioni che in caso contrario potrebbero essere ignorate.

Nota

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Suggerimento

Tips are tips, shortcuts or alternative approaches to the task at hand. Ignoring a tip should have no negative consequences, but you might miss out on a trick that makes your life easier.

Importante

Le caselle 'importante' riportano informazioni che potrebbero passare facilmente inosservate: modifiche alla configurazione applicabili solo alla sessione corrente, o servizi i quali necessitano di un riavvio prima di applicare un aggiornamento. Ignorare queste caselle non causa alcuna perdita di dati ma potrebbe causare irritazione e frustrazione da parte dell'utente.

Attenzione

Un Avvertimento non dovrebbe essere ignorato. Se ignorato, potrebbe verificarsi una perdita di dati.

Avvertimento

Un Avvertimento non dovrebbe essere ignorato. Se ignorato, potrebbe verificarsi una perdita di dati.

## 2. Occorrono commenti!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: https://bugzilla.redhat.com/enter_bug.cgi?product=Publican&component=Publican%20Users%20Guide&version=4.1.

Se si hanno suggerimenti su come migliorare il documento, si cerchi di essere il più possibile specifici nella descrizione. Se si trova un errore, si prega di indicare la sezione e di includere anche parte del testo circostante, in modo da poterlo intercettare facilmente.

# Introduzione

Publican è uno strumento per pubblicare materiale scritto in DocBook XML. Questa guida spiega come creare e compilare libri ed articoli usando Publican. Non si tratta di un tutorial su DocBook XML; per supporto su DocBook XML, fare invece riferimento alla Guida DocBook: The Definitive Guide di Norman Walsh e Leonard Muellner, disponibile su http://www.docbook.org/tdg/en/html/docbook.html.

Publican è nato come strumento interno al Red Hat's Documentation Group (ora noto come Engineering Content Services). All'occorrenza questa eredità verrà evidenziata.

Progetto. Publican è un sistema di pubblicazione, non solo uno strumento di elaborazione di DocBook. Oltre ad assicurare la validità di un DocBook XML, Publican assicura che ogni file XML sia conforme allo standard di pubblicazione.

Le funzionalità di brand consentono di creare regole di presentazione e look personalizzati, in alternativa allo stile predefinito, per soddisfare le proprie esigenze editoriali. Le scelte effettuate nel codice, tuttavia, non sono modificabili.

Per esempio, le entità possono essere validamente definite in ogni file XML. Tuttavia per garantire che la dichiarazione DTD sia presente, valida e standardizzata, Publican riscrive la dichiarazione in ogni file XML prima di compilare un testo o articolo. Di conseguenza, tutte le entità dichiarate nei file XML vengono perse. Quindi Publican richiede di definire le entità nel file `Nome_Doc.ent` (vedere la Sezione 4.1.6, «Nome_Doc.ent»).

Al crescere del lavoro editoriale, la definizione di entità senza restrizioni porta alla duplicazione di entità e ad altre pratiche che causano difficoltà di mantenimento. Consolidare la definizione delle entità in un unico posto noto, serve ad alleviare i problemi di mantenimento e contribuisce ad irrobustire l'automazione del processo di compilazione.

Inoltre le entità presentano un ostacolo sostanzialmente insormontabile sulla qualità della traduzione (fare riferimento alla Sezione 4.1.6.1, «Entità e traduzione»). Quindi, si ritiene opportuno mantenere le attuali funzionalità del file `Nome_Doc.ent` senza aggiungere altre funzionalità o caratteristiche associate all'uso delle entità.

## 1. This section is for testing the output and doesn't ship in the production docs

### 1.1. Testing BZ #1092351 Code Switcher

Perl C++

    #!/usr/bin/perl
    use strict;
    use warnings;

    print "Hello, World!\n";

    #include <iostream>

    int main()
    {
      std::cout << "Hello World!"; &lies;
    }

### 1.2. Testing BZ #1088051 Code Popper

    [Show All][Hide]$ apt-get search libxslt
    gambas3-gb-xml-xslt - Gambas XSLT component
    libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
    libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
    libical-parser-html-perl - generates HTML calendars from iCalendars
    libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
    libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
    libxml-libxslt-perl - Perl interface to the GNOME libxslt library
    libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
    libxslt1-dev - XSLT 1.0 processing library - development kit
    libxslt1.1 - XSLT 1.0 processing library - runtime library
    python-libxslt1 - Python bindings for libxslt1
    python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
    python-lxml - pythonic binding for the libxml2 and libxslt libraries
    python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
    python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
    python3-lxml - pythonic binding for the libxml2 and libxslt libraries
    python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
    php5-xsl - XSL module for php5
    libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
    libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
    swfmill - xml2swf and swf2xml processor
    libxslthl-java - XSLT syntax highlighting

### 1.3. Testing BZ #1112899 Callouts and BZ #1101050 Entities in CDATA

Test a programlisting with a calloutlist

Esempio 1. "Hello world!" in C++

    #include <qpid/messaging/Connection.h>
    #include <qpid/messaging/Message.h>
    #include <qpid/messaging/Receiver.h>
    #include <qpid/messaging/Sender.h>
    #include <qpid/messaging/Session.h> &BZ1101050;

    #include <iostream>

    using namespace qpid::messaging;

    int main(int argc, char** argv) {
        std::string broker = argc > 1 ? argv[1] : "localhost:5672";
        std::string address = argc > 2 ? argv[2] : "amq.topic";
        Connection connection(broker);
        try {
            connection.open();  1
            Session session = connection.createSession(); 2

            Receiver receiver = session.createReceiver(address); 3
            Sender sender = session.createSender(address); 4

            sender.send(Message("Hello world!"));

            Message message = receiver.fetch(Duration::SECOND * 1); 5
            std::cout << message.getContent() << std::endl;
            session.acknowledge(); 6

            connection.close(); 7
            return 0;
        } catch(const std::exception& error) {
            std::cerr << error.what() << std::endl;
            connection.close();
            return 1;
        }
      }

1

  Establishes the connection with the messaging broker.

2

  Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.

3

  Creates a receiver that reads from the given address.

4

  Creates a sender that sends to the given address.

5

  Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

6

  Acknowledges messages that have been read. To guarantee delivery, a message remains on the messaging broker until it is acknowledged by a client. session.acknowledge() acknowledges all unacknowledged messages for the given session—this allows acknowledgements to be batched, which is more efficient than acknowledging messages individually.

7

  Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

And now we test a programlistingco with an areaspec

      <list-index
            column="column_name"                           1
            base="0|1|..."/>                2

1

  `column_name` (required): the name of the column holding the collection index values.

2

  `base` (optional - defaults to `0`): the value of the index column that corresponds to the first element of the list or array.

### 1.4. Testing BZ #752021 Cross-Browser embed external video

### 1.5. Testing BZ #1110611 A line break is automatically inserted after cdata in code.

Is there a newline inserted after this `CDATA`?

### 1.6. Testing BZ #1117561 CDATA tags

=, >, >=, <, <=, <>

!=

<>

### 1.7. Testing BZ #1135827 Single line comment being highlighted in a callout.

    package com.sample;

    import org.kie.api.runtime.process.WorkItem;
    import org.kie.api.runtime.process.WorkItemHandler;
    import org.kie.api.runtime.process.WorkItemManager;

    public class NotificationWorkItemHandler implements WorkItemHandler {

      public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
        String from = (String) workItem.getParameter("From");
        String to = (String) workItem.getParameter("To");
        String message = (String) workItem.getParameter("Message");
        String priority = (String) workItem.getParameter("Priority");

        // send email
        EmailService service = ServiceRegistry.getInstance().getEmailService();
        service.sendEmail(from, to, "Notification", message);                      1

        // notify manager that work item has been completed
        manager.completeWorkItem(workItem.getId(), null);
      }                                                                            2

      public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
      // Do nothing, notifications cannot be aborted
      }

    }

1

  The `ServiceRegistry` class is an example class implementing the task business logic.

2

  The `completeWorkItem()` call completes the work item execution.

### 1.8. Testing BZ #1168765 programlisting no longer support language attribute.

    <?xml version="1.0" encoding="UTF-8"?><test></test>

# Capitolo 1. Installare Publican

## 1.1. Sistemi Operativi Linux

Importante — Disponibilità nei repository

Le procedure indicate in questa sezione assumono che Publican e le sue varie dipendenze siano disponibili nei repository cui ha accesso il proprio sistema.

### 1.1.1. Fedora & Red Hat Enterprise Linux 6

1. Aprire un terminale

2. Diventare utente root: su -

3. Eseguire il seguente comando per installare il pacchetto publican ed il pacchetto publican-doc della documentazione:

       $ yum install publican\*

Con Publican sono disponibili anche diversi pacchetti di brand. Eseguire il seguente comando come utente root, per installare i pacchetti per la costruzione di libri brand:

     yum install publican-brand

Sostituire brand con `redhat`, `fedora`, `jboss`, `ovirt`, o `gimp`. Vedere il Capitolo 5, Branding per una spiegazione del branding in Publican.

### 1.1.2. Ubuntu

1. Aprire un terminale

2. Eseguire il seguente comando per installare il pacchetto publican:

       sudo apt-get install publican

### 1.1.3. Debian

This procedure will install the publican version that is in your default Debian repository. It will also install a large number of packages that publican depends on, like Java, XML and image processing libraries and many ancillary Perl modules.

1. Aprire un terminale

2. Diventare utente root: su -

3. Eseguire il seguente comando per installare il pacchetto publican:

       $ apt-get install publican

4. Run the following command to determine what version of publican is installed:

       $ publican -v
       version=2.8

Important — Installing more recent packages using Apt-Pinning

If you need a more recent release of publican than installed by the procedure above, you can query if there other versions available: http://packages.debian.org/publican.

To date, there has not been any backport (http://backports.debian.org/Instructions/) available for publican, so we need to use Apt Pinning https://wiki.debian.org/AptPreferences

Alternatively, you could run Debian testing or unstable in a virtual machine, chroot or linux container.

Assuming there is a more recent version of publican available in the testing repository, and that you are running the current stable, then you can upgrade by:

1. Aprire un terminale

2. Diventare utente root: su -

3. Con un editor di testo aprire il file `/etc/apt/sources.list`. Per esempio, per modificare il file con gedit, eseguire:

       $ gedit /etc/apt/sources.list

4. Aggiungere la seguente riga alla fine del file:

       #### testing  #########
       deb http://ftp.us.debian.org/debian testing main contrib non-free

5. Salvare il file e chiudere l'editor.

6. Open (or create) your `/etc/apt/preferences` file in a text editor. For example, to edit the file in gedit run:

       $ gedit /etc/apt/preferences

7. Aggiungere la seguente riga alla fine del file:

       Package: *
       Pin: release a=stable
       Pin-Priority: 900

       Package: *
       Pin: release a=testing
       Pin-Priority: 400

       Package: *
       Pin: release o=Debian
       Pin-Priority: -10

8. Salvare il file e chiudere l'editor.

9. Eseguire il seguente comando per aggiornare la lista dei pacchetti disponibili nel sistema:

       $ apt-get update

10. Run the following command to try to install the testing version of publican package, and any updated dependancies:

        $ apt-get -t testing install publican

Because Apt Pinning mixes 2 different debian streams in an un-tested way, incompatibilities may happen. For example, you may get a warning like:

    $ publican
    Warning: program compiled against libxml 209 using older 208
    Warning: XML::LibXML compiled against libxml2 20901, but runtime libxml2 is older 20800
    Warning: program compiled against libxml 209 using older 208
    Warning: XML::LibXSLT compiled against libxslt 10128, but runtime libxslt is older 10126
    Can't open publican: No such file or directory at /usr/bin/publican line 430.

Which indicates that you might need to upgrade libxml2 and libxslt to the testing repository version too. This can be done by searching to find the likely library:

1.     [Show All][Hide]$ apt-get search libxslt
       gambas3-gb-xml-xslt - Gambas XSLT component
       libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
       libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
       libical-parser-html-perl - generates HTML calendars from iCalendars
       libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
       libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
       libxml-libxslt-perl - Perl interface to the GNOME libxslt library
       libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
       libxslt1-dev - XSLT 1.0 processing library - development kit
       libxslt1.1 - XSLT 1.0 processing library - runtime library
       python-libxslt1 - Python bindings for libxslt1
       python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
       python-lxml - pythonic binding for the libxml2 and libxslt libraries
       python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
       python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
       python3-lxml - pythonic binding for the libxml2 and libxslt libraries
       python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
       php5-xsl - XSL module for php5
       libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
       libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
       swfmill - xml2swf and swf2xml processor
       libxslthl-java - XSLT syntax highlighting

   (and the same again for libxml2)

2. And then upgrading those packages to testing.

       $ apt-get -t testing upgrade libxml2 libxslt1.1

### 1.1.4. OpenSuse 12

Publican has not been usable on OpenSuse up until release 12.1. Certain dependencies were missing and could not be found in any known OpenSuse repository. This is not the case with OpenSuse 12.1 as all dependencies can now be found and installed.

The following instructions describe installing Publican from source because, as yet, there is no Publican RPM for OpenSuse 12.1. The version of Publican is 2.9 taken directly from the source repository - previous versions have not been tested but may work.

At the time of writing, Publican 2.8 was the release version and work on 2.9 was still ongoing. For this reason the following instructions are subject to change.

The OpenSuse install was a default one with the following software categories added at install time:

- Technical Writing - for the Docbook tools etc.

- Perl Development

- Web and LAMP Server

The system used had KDE installed which shouldn't make a difference. The following KDE specific categories were also installed:

- KDE Development

- Desktop Effects

Finally, the entire Games category was removed.

After OpenSuse had completed installing, and all current updates had been applied, the following steps were followed to install Publican.

1. Open a terminal session.

2. Install the dependencies that are available from various online repositories - many of these are not present in the installation DVD repository.

       $ sudo zypper install perl-Config-Simple perl-DateTime \ perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \ perl-File-Find-Rule perl-File-Which perl-HTML-Format \ perl-Locale-MakeText-Gettext perl-Template-Toolkit \ perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \ perl-YAML liberation-fonts

   Nota

   `Liberation-fonts` is most likely already installed, but it is required. Zypper will not reinstall it if it is already present.

3. Use cpan to install the remaining dependencies which cannot be installed by zypper:

       $ sudo sh cpan File::pushd File::Copy::Recursive Locale::PO pp \ Syntax::Highlight::Engine::Kate XML::TreeBuilder exit

4. Download the source code:

       $ cd ~ mkdir -p SourceCode/publican cd SourceCode/publican svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./

5. Build the Publican build script:

       $ perl Build.PL

   If all the dependencies are installed, you should see the following:

       WARNING: the following files are missing in your kit:
        META.yml
        Please inform the author.

       Created MYMETA.yml and MYMETA.json
       Creating new 'Build' script for 'Publican' version '2.9'

   If not, then use cpan (as root) to install the missing modules and run the build again. Replace any forward slashes '/' by a double colon '::' and make sure you use exactly the same letter case, for example: If `File/pushd.pm` is reported as missing, you would use this to install it:

       $ sudo sh cpan File::pushd exit

   Assuming all went well, the `Build.PL` script will have created a new script named `Build` which we will use to create, test and install Publican 2.9.

       $ ./Build

   There will be lots of text scrolling up the screen for a few minutes, you should eventually see the following:

       DEBUG: Publican::Builder: end of build

6. Test the build:

       $ ./Build test

   Again, lots of scrolling text at the end of which you may see the following:

       Test Summary Report
       -------------------
       t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)
        Failed test: 5
        Non-zero exit status: 1
       t/pod-coverage.t (Wstat: 256 Tests: 9 Failed: 1)
        Failed test: 7
        Non-zero exit status: 1
       Files=10, Tests=68, 420 wallclock secs ( 0.31 usr 0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)
       Result: FAIL
       Failed 2/10 test programs. 2/68 subtests failed.

   Don't worry. This is because of a missing wkhtmltopdf utility which is undergoing tests to be added to Publican in the future to replace Apache FOP as the pdf generation tool of choice. If Publican finds wkhtmltopdf it will use it, otherwise it uses FOP.

   Unfortunately, at the time of writing, because OpenSuse names one of the dependencies of wkhtmltopdf differently (`ghostscript-fonts-std` as opposed to `ghostscript-fonts`) wkhtmltopdf will not run even if force installed with no dependency checks.

7. Install wkhtmltopdf.

   This step is optional. At the time of writing wkhtmltopdf did not work on OpenSuse 12.1 However, as the problems which prevent it working correctly from Publican may have been resolved, the following instructions give details on installing wkhtmltopdf.

   Nota

   If you intend to create indices in your generated pdf documents, you are advised to use Apache FOP rather than wkhtmltopdf. With FOP you get actual page numbers which is better in a printed document.

       $ JFEARN=http://jfearn.fedorapeople.org/wkhtmltopdf/f15 MYSYSTEM=i686 ## For 64bit system use MYSYSTEM=x86_64 instead. wget $JFEARN/$MYSYSTEM/wkhtmltopdf-qt-4.7.1-1.git20110804.fc15.i686.rpm wget $JFEARN/$MYSYSTEM/wkhtmltopdf-0.10.0_rc2-1.fc15.i686.rpm

   Nota

   If you use a 64 bit system, make sure to set `MYSYSTEM` appropriately.

   Once downloaded, install both rpms as follows:

       $ sudo sh rpm -ivh wkhtmltopdf-qt* rpm -ivh --nodeps wkhtmltopdf-0* exit

   You have to use the option to ignore dependencies on the latter rpm due to the `ghostscript-fonts` problem described above.

8. Install Publican.

   The final stage is to install Publican, even though the testing stage had a couple of sub-tests which failed.

       $ sudo sh ./Build test exit

   The following steps are optional but it's a good idea to test that everything is working before you spend time on your own documents.

9. Test the installed Publican build:

       $ publican create --type=book --product=testing --version=1.2.3 --name=TestPublican
         Processing file en-US/Author_Group.xml -> en-US/Author_Group.xml
         Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml
         Processing file en-US/Chapter.xml -> en-US/Chapter.xml
         Processing file en-US/Preface.xml -> en-US/Preface.xml
         Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml
         Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml

       $ cd TestPublican/ publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub

   Nota

   At the time of writing, creating epubs with Publican 2.9 on OpenSuse gave the following error:

       runtime error: file /usr/share/publican/xsl/epub.xsl element choose
       Variable 'epub.embedded.fonts' has not been declared.
        at /usr/lib/perl5/site_perl/5.14.2/Publican/Builder.pm line 915

   No epub file was created. The individual working files were however, and can be built into an epub book using Sigil, if desired.

   Using the Dolphin file manager, you can browse to `SourceCode/TestPublican/tmp/en-US/` and view the various output formats that you find there.

### 1.1.5. Docker container

Nota

This installation procedure assumes you have already installed a working docker (see http://docker.io) environment.

Docker is a lightweight Jail (currently using LXC) that allows you to install and run publican without installing your main Linux installation with all its dependencies.

1. Aprire un terminale

2. Download and install the svendowideit/publican container from https://index.docker.io/u/svendowideit/publican/:

       $ docker pull svendowideit/publican

   This will take some time, as it downloads a fedora based container, and then the dependencies needed for publican

3. Add a publican bash alias to simplify your usage:

       $ echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc

   This alias assumes that you are running publican in the documentation root directory (the one with the publican.cfg file in it.

4. now you can use publican as per the documentation:

       $ publican --version
       version=3.2.1

### 1.1.6. Running publican from a GIT checkout

It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.

1. To checkout the source from GIT open a terminal.

2. Eseguire il seguente comando per installare il pacchetto publican:

       $ cd PATH TO PLACE SOURCE
       $ git clone git://git.fedorahosted.org/publican.git publican

3. To run publican from this checkout run the following commands:

       $ PUBLICAN_PATH="PATH TO PLACE SOURCE/publican"
       $ perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build  --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html

## 1.2. Sistemi Operativi Windows

1. Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.

2. Spostarsi nella cartella in cui si è scaricato l'eseguibile `Publican-Installer-versione.exe`.

3. Fare doppio click sul file `Publican-Installer-versione.exe`.

4. Il programma di installazione inizia presentando una serie di accordi di licenza. Tutti i file che fanno parte di una installazione di Publican sono disponibili sotto licenza libera. Tuttavia, poiché diverse licenze sono più adatte a certe parti di Publican di altre, i file di Publican non vengono tutti distribuiti sotto la stessa licenza libera. Ogni licenza conferisce differenti diritti e responsabilità sulla copia e sulla modifica dei file di una installazione di Publican. Noi usiamo questa combinazione di licenze per consentire di usare Publican il più liberamente possibile e per consentire di scegliere qualunque licenza per i propri documenti, pubblicati usando Publican.

   Leggere le condizioni dei vari accordi di licenza. Se si concorda con le condizioni, premere I Agree su ciascuna di esse, altrimenti premere Cancel.

5. Il programma di installazione propone di installare diversi componenti: Publican (denominato `Main` nella finestra d'installazione), alcuni brand (`RedHat`, `JBoss`, e `fedora`), e due componenti di DocBook (il DTD o Data Type Definition, e l'XSL o Extensible Stylesheet Language). I tre brand si trovano raggruppati sotto il controllo espandibile `Brands`, mentre i componenti di DocBook si trovano nel controllo espandibile `DocBook` nella finestra di installazione. Vedere il Capitolo 5, Branding per una spiegazione dei brand in Publican. Per rendere i documenti XML in presentazioni di altri formati (come HTML e PDF), Publican usa il DTD e gli stylesheet di XSL. Se non si installano questi componenti, Publican deve scaricare questi dati da Internet ogniqualvolta elabora un documento, il che comporta lunghi ritardi.

   Tutti i componenti sono selezionati per impostazione. Deselezionare i componenti eventualmente non richiesti e poi premere Next, per continuare.

6. Per impostazione, il programma di installazione creare una cartella denominata `Publican` nella cartella `%ProgramFiles%` del proprio computer — tipicamente `C:\Program Files\Publican`. Per selezionare una cartella differente, inserire manualmente il percorso alla cartella, nella casella di testo etichettata Destination Folder.

7. Dopo aver impostato la cartella di destinazione, premere Install.

   A questo punto, durante l'installazione di Publican, viene visualizzata una barra di progressione. Per visualizzare i dettagli sul progresso di installazione, premere Show details.

8. Una volta completato, il programma di installazione visualizza il messaggio `Completed`.

   Premere Close per chiudere il programma di installazione.

## 1.3. OSX Lion

1. Install Xcode from Mac App store.

   Nota

   Xcode is about 4GB. Be prepared to wait. It has things you need, though.

2. Install Macports from http://guide.macports.org/chunked/installing.macports.html. Everything you install with it goes into `/opt/local`, away from your normal OS files.

3. Aprire un terminale

4. Install dependencies for publican, which are available as ports:

       $sudo port install docbook-xml docbook-xsl docbook-sgml-4.2 perl5 bash-completion p5-file-pushd p5-config-simple p5-file-find-rule p5-file-slurp p5-class-trigger p5-time-hires p5-list-moreutils p5-ipc-run3 p5-class-accessor p5-test-perl-critic p5-xml-libxslt p5-locale-gettext p5-image-size p5-file-copy-recursive p5-datetime p5-archive-zip p5-timedate p5-html-format p5-dbd-sqlite p5-xml-simple p5-devel-cover p5-test-pod p5-test-pod-coverage p5-template-toolkit

5. Install CPAN modules for dependencies which can't be satisfied with ports. Note: this step will generate lots of messages, including warnings. Don't worry about them.

       $sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables

6. Install FOP if you want PDFs to work:

       $ sudo port install fop

       $ echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc

7. Check out Publican Main branch. This command should be run from your user home directory, for instance `/Users/yourusername`

       $ git clone git://git.fedorahosted.org/publican.git

8. Change directories:

       $ cd publican/publican

9. This directory should contain a file named `Build.pl`. Verify that you are in the correct directory, then run the following command. Ignore all the messages you get.

       $ perl ./Build.PL

       $ ./Build

10. Run the following command to install Publican and put all of its bits into `/opt/local`:

        $ sudo ./Build install

Procedura 1.1. Create and build a book

1.     $ publican create --name=testbook

2.     $ cd testbook

3.     $ publican build --formats=html --langs=en-US

4. Open the `tmp/en-US/html/index.html` file in a browser to prove that it built correctly.

Procedura 1.2. Install a brand

1. Fix the permissions of the Commons Brand. You have to do this only once. This is a bug that will be addressed eventually.

       $ find /opt/local/share/publican -type f |xargs sudo chmod 644

2. Either check out the SVN for your brand, or get a pre-built brand from a friend.

   1. The SVN location for the brands supplied by Red Hat is http://svn.fedorahosted.org/svn/publican

   2. If you use a pre-built brand, extract it as necessary.

3. If you got the brand from SVN, build it.

       $ cd publican/publican-jboss

       $ publican build --formats=xml --langs=all --publish

4. Install the brand.

       $ sudo publican install_brand --path=/opt/local/share/publican/Common_Content

   You can now use the brand in your books by editing your book's `publican.cfg` file or specifying the `--brand` option when creating your book.

# Capitolo 2. Publican defaults

Users can set their own default values for Publican in `~/.publican.cfg`. Currently, Publican supports the following values:

- firstname

- surname

- email

- formats

- lang

- langs

Nota

This file is completely different to `publican.cfg` that is used to build a book. It does not accept the same parameters.

## 2.1. Publican default examples

Users can set formats, lang, and langs to their standard build parameters.

Esempio 2.1. Setting formats and lang

    $ echo 'formats: "html,html-single,pdf,txt"' >> ~/.publican.cfg
    $ echo 'langs: "en-US"' >> ~/.publican.cfg
    $ publican build
    Setting up en-US
    [...]
     Finished txt

Publican 3.0 allows you to add a revision history entry from the command line. You can set your user details in `~/.publican.cfg`.

Esempio 2.2. Setting user details

    $ echo 'firstname: "Dude"' >> ~/.publican.cfg
    $ echo 'surname: "McPants"' >> ~/.publican.cfg
    $ echo 'email: "dude.mcpants@awesome.com"' >> ~/.publican.cfg
    $ publican add_revision --member "Updated examples in chapter 2." \
    --member "Removed obsolete example in sect 4.1"

# Capitolo 3. Comandi di Publican

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

I comandi di Publican hanno uno dei seguenti formati:

publican opzione_comando

  The command_option is any of several options for the `$` publican command itself. For a complete list of actions see Sezione B.2, «Command actions»

publican azione opzioni_azione

  azione è una richiesta di elaborazione per Publican, come creare i file XML per un nuovo documento o creare un documento in HTML dai corrispondenti file XML. Le opzioni_azione si applicano ad una azione, per specificare per esempio la lingua di un documento.

publican opzione_comando azione opzioni_azione

  Alcune opzioni_comando influenzano il risultato di una azione, come quando si richiede, per esempio, a Publican di usare nell'output la colorazione ANSI.

# Capitolo 4. 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 4.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`

  set version as the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use `5.1`. The default version is `0.1`. The `--version` option sets the `<productnumber>` tag in the `Book_Info.xml` or `Article_Info.xml` file. For more information refer to Sezione 4.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 4.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 4.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 4.1.1, «Il file publican.cfg» per maggiori informazioni sui parametri del file `publican.cfg` ed al Capitolo 6, 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 4.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 5.1, «Installare un brand» per istruzioni su come installare pacchetti di brand per l'uso in Publican. Vedere il Capitolo 5, 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:

    $ 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 Test_Book/
    $ ls

Il risultato dovrebbe assomigliare a:

    it-IT/ publican.cfg

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

### 4.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
    # Wed Jul 18 13:00:40 2012

    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 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"`

Aiuto da riga di comando

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

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

Altri pacchetti non 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 info [
    <!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
    %BOOK_ENTITIES;
    <!ENTITY % sgml.features "IGNORE">
    <!ENTITY % xml.features "INCLUDE">
    <!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
    %DOCBOOK_ENTS;
    ]>
    <info conformance="121" version="5.0" xml:lang="it-IT" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
    	<title>Guida Utente</title>
    	 <subtitle>Pubblicare libri, articoli, relazioni e raccolte di volumi con DocBook XML</subtitle>
    	 <productname>publican</productname>
    	 <productnumber>4.2</productnumber>
    	 <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>
    	 <mediaobject role="logo">
    		<imageobject>
    			<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
    		</imageobject>
    		 <textobject>
    			<phrase>Team Publican</phrase>
    		</textobject>

    	</mediaobject>
    	 <mediaobject role="cover">
    		<imageobject remap="lrg" role="front-large">
    			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
    		</imageobject>
    		 <imageobject remap="s" role="front">
    			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
    		</imageobject>
    		 <imageobject remap="xs" role="front-small">
    			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
    		</imageobject>
    		 <imageobject remap="cs" role="thumbnail">
    			<imagedata fileref="images/cover_thumbnail.png" format="PNG" />
    		</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" />
    </info>

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

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

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

### 4.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" encoding="utf-8"?>
    <authorgroup xmlns="http://docbook.org/ns/docbook" version="5.0">
    	<author>
    		<orgname>FF0000 Headgear Documentation Group</orgname>
    	</author>
    	<author>
    		<personname>
    			<firstname>Dude</firstname>
    			<surname>McDude</surname>
    		</personname>
    		<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.

### 4.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 se 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`.

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

This book contains two chapters. Chapter one contains two sections. Refer to http://docbook.org/tdg/en/html/section.html for further information about sections, and http://docbook.org/tdg/en/html/book.html for further information about books.

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

    <?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>

#### 4.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 illeggibile 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à definita, `&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 soltanto `&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 tradotto 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 4.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 Evo, i pronomi hanno conservato la flessione. 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 oggetto 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.

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

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

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.

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

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

Certain characters are reserved in XML, in particular, `&` and `<`. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as `CDATA` or by replacing them with entities (&amp; and &lt; respectively).[2] If you place these files in the `extras/` directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.

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

1. Creare la cartella extras

       mkdir en-US/extras

2. Copiare il file del codice nella cartella extras

       cp ~/samples/foo.c en-US/extras/.

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

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

[2] Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from http://www.w3.org/TR/2008/REC-xml-20081126/.

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

## 4.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 qualsiasi combinazione. Per esempio:

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

## 4.6. Translating a document

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:

1. Completare l'XML di un documento.

   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.

2. Optional but recommended: drop the document to translation. Run:

       $ publican trans_drop

   Publican creates a new subdirectory, named `trans_drop/`. The `trans_drop/` subdirectory contains a snapshot of the source files of the document. When the `trans_drop/` directory is present in a documentation project, Publican uses its content as the basis for the commands documented later in this procedure.

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

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

   If this is the first time that PO files have been created for a particular language, Publican creates a new subdirectory, named with the language code that you specified with the `--langs=` option. This subdirectory holds a PO file for each POT file in `pot` subdirectory, plus a `Revision_History.xml` file that tracks the history of this particular translation. When created for the first time, the `Revision_History.xml` file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's `Revision_History.xml` file) on which this translation is therefore based.

   If Publican has created PO files for this language previously, Publican updates the existing PO files to reflect any changes in the POT files since the PO files were last updated, and adds a new entry to the translation's `Revision_History.xml` file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the `--langs=all` option:

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

5. Tradurre le stringhe contenute nei file PO.

6. If you are updating a previously published translation of this revision in the source language, use Publican's publican add_revision command to describe your changes or corrections. Publican updates the `Revision_History.xml` file for you.

   If the document has changed in its original language, use the publican trans_drop, publican update_pot, and publican update_po commands as described earlier in this procedure instead.

7. 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 4.7, «Creare un documento» ed alla Sezione 4.8, «Creare il pacchetto di un documento» per maggiori informazioni.

### 4.6.1. Translation Author Group

Translation takes place after a book has been finalized. You do not need to know who will translate your book in order to give them credit. Create `$translation/Author_Group.xml` and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to `$source_lang/Author_Group.xml` when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.

### 4.6.2. Translating Indexes and Glossaries

DocBook automatically collates and sorts `<glossentry>` elements into a book's glossary; and `<primary>`, `<secondary>`, and `<tertiary>` `<indexterm>` elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.

To manually adjust the sort order of a glossary entry or index entry, manually add DocBook's `sortas` attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:

    #. Tag: indexterm
    #, no-c-format
    msgid "<primary>encryption</primary>"
    msgstr "<primary sortas="あんごうか">暗号化</primary>"

Similarly, to ensure that the Japanese word 暗号化 sorts correctly in a glossary, specify:

    #. Tag: glossentry
    #, no-c-format
    msgid "<glossterm>encryption</glossterm>"
    msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"

## 4.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 — fare riferimento a Sezione 4.1.1, «Il file publican.cfg».

Se si mantengono 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:

1. Verificare che nel file `Nome_Doc.ent`, siano state configurate le entità `YEAR` e `HOLDER`, come descritto nella Sezione 4.1.6, «Nome_Doc.ent».

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

3. Eseguire un test, per evitare che ci siano errori di compilazione nel linguaggio desiderato, per esempio:

       publican build --formats=test --langs=it-IT

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

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

## 4.8. Creare il pacchetto di un documento

Altri pacchetti non 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.

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 4.1.1, «Il file publican.cfg»).

Se si mantengono 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.

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

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

#### 4.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, facilitando 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 4.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 deficienza 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 predefinito, 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.

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

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

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

For a full description of how desktop entries work, refer to the Desktop Entry Specification, available from 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>

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

For a full description of how desktop menus work, refer to the Desktop Menu Specification, available from http://standards.freedesktop.org/desktop-menu-spec/latest/

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

Importante

Publican will process the string in menu_category and replace `__LANG__` with the current language. This allows menus to be customized on a per language basis.

    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.

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

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 4.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 release dello stesso documento, nella lingua originale o in altra lingua.

#### 4.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] Fare riferimento a http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA

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

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">`.

### 4.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 4.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 necessario supporto.

In alternativa ai tag condizionali, si consideri di mantenere versioni separate di un libro, in rami separati di un repository con controllo di versione. In tal modo, è anche possibile condividere file XML e PO tra i vari rami; 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 modificare ogni volta il file di configurazione, per la compilazione di un libro o pacchetto.

## 4.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 comunicare chiaramente lo stato del software, della documentazioni o di entrambi a tutti gli interessati: utenti, sviluppatori, lettori e revisori.

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

1. Aggiungere 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>

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

Esempio 4.7. An example of an inline remark

Here is an example of an inline remark.

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.

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

Esempio 4.8. An example of a block marked up as draft

This is an example of a block that is marked as draft
Isn't it pretty!

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

### 4.10.4. Denoting changed content New section

DocBook allows setting the `revisionflag` on many elements to allow easier reviewing on changed documents. Publican, as of version 4.1, will add highlighting to these elements if the book is in draft mode. e.g. `revisionflag="added"`

aggiunto

  This is how an element that has been added to a new revision is marked-up.

changed

  This is how an element that has been changed in a new revision is marked-up.

eliminato

  This is how an element that has been marked for deletion from a new revision is marked-up. Publican will not automatically delete or hide this content, you have to ensure this is done before publication.

# Capitolo 5. Branding

I brand sono collezioni di file usati da Publican per applicare alle presentazioni HTML e PDF, un look ed uno stile consistente. Essi forniscono modelli testuali con cui iniziare un documento, immagini come loghi ed elementi stilistici come schemi di colore. Publican viene distribuito con un unico brand, `common/`. I team che realizzano documentazione possono produrre e distribuire brand ai loro contributori, sia mediante pacchetti (per esempio pacchetti RPM), sia mediante archivi (per esempio file tarball o ZIP).

## 5.1. Installare un brand

In Fedora, i brand Publican per documenti Fedora, Genome e oVirt sono disponibili come pacchetti RPM. Analogamente, Red Hat distribuisce pacchetti RPM contenenti brand di Publican per documenti GIMP, JBoss e Red Hat. Accedendo ai repository dedicati, è possibile installare questi brand su computer che eseguono Red Hat Enterprise Linux o Fedora — o un sistema operativo derivato — con il comando yum install publican-brand o con un gestore grafico di pacchetti come PackageKit.

Se si usa Publican su un sistema operativo che non utilizza pacchetti RPM, il progetto di documentazione può fornire il proprio brand in un altro formato. Qualunque sia il formato di distribuzione del brand, i file di brand devono trovarsi in una sotto-cartella della cartella `Common_Content` di Publican. Per impostazione, questa cartella si trova in `/usr/share/publican/Common_Content` nei Sistemi Operativi Linux, e in `%SystemDrive%/%ProgramFiles%/Publican/Common_Content` nei sistemi operativi Windows — tipicamente `C:/Program Files/Publican/Common_Content`.

Ciascun brand attualmente disponibile, viene distribuito sotto una licenza specifica per brand, come indicato di seguito.

Installare il brand:

1. Se il brand è distribuito come un archivio, per esempio, un file tarball o ZIP, estrarre il brand in una nuova cartella.

2. Spostarsi nella cartella contenente il brand estratto:

       cd publican-brand

   dove brand è il nome del brand.

3. Compilare il brand:

       publican build --formats xml --langs all --publish

4. Installare il brand:

       sudo publican install_brand --path path

   dove path è il percorso ai file Common Content di Publican. Per esempio, su un sistema Linux, eseguire:

       sudo publican install_brand --path /usr/share/publican/Common_Content

   o su un sistema Windows, eseguire:

       publican install_brand --path "C:/Program Files/Publican/Common_Content"

Tabella 5.1. Brand correnti e relativi pacchetti

Brand | Licenza sui file in Common Content | Licenza predefinita sui documenti | Pacchetto | Commento
--- | --- | --- | --- | ---
common | CC0 1.0 | GFDL Version 1.2 | publican | Licenza GPL compatibile. Nessuna opzione.
RedHat | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-redhat |
Fedora | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-fedora |
JBoss | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-jboss | Nessuna opzione.
oVirt | OPL 1.0 | OPL 1.0 | publican-ovirt | Nessuna opzione.
GIMP | GFDL Version 1.2 | GFDL Version 1.2 | publican-gimp | Coincidente con la licenza sulla documentazione GIMP esistente.
Genome | OPL 1.0 | OPL 1.0 | publican-genome | Nessuna opzione.

Notare, nel brand common, la differenza di licenza tra i file di common content (CC0) e la licenza predefinita (GFDL), impostata sui libri generati con il brand common. La licenza CC0 consente di re-distribuire e licenziare i file (inclusi i file CSS e le immagini), che fanno parte del common brand per soddisfare alle proprie esigenze progettuali. Publican suggerisce la licenza GFDL per la documentazione, per impostazione predefinita, poiché Publican è sviluppato in primo luogo per creare documentazione per software. La licenza GFDL è compatibile con la licenza GPL, che è la licenza più comunemente usata per il software open-source.

## 5.2. Creare un brand

Usare l'azione create_brand per creare un nuovo brand. Quando si crea un nuovo brand, occorre fornire un nome e specificare la lingua originale per i file XML del brand. L'opzione `--name` fornisce il nome, e l'opzione `--lang` specifica la lingua. Quindi il comando completo è:

    publican create_brand --name=brand --lang=codice_linguistico

Publican crea una nuova sotto-cartella di nome `publican-brand`, dove brand è il brand specificato con l'opzione `--name`.

Per esempio, per creare un brand di nome `Acme`, con i file XML in Common Content redatti in inglese statunitense, eseguire:

    publican create_brand --name=Acme --lang=en-US

In tal caso, Publican crea il brand nella sotto-cartella `publican-Acme`.

Per configurare il nuovo brand, individuare il termine `SETUP` nei file predefiniti creati da Publican e modificare i file inserendo i necessari dettagli. Sui Sistemi Operativi Linux, la ricerca in questi file, del termine `SETUP` può essere effettuata con il comando:

    $ grep -r 'SETUP' *

## 5.3. File nella directory brand

L'esecuzione del comando publican create_brand --name=brand --lang=codice_linguistico crea la struttura delle cartelle e i file necessari. La cartella brand, inizialmente contiene:

- `COPYING`

- `defaults.cfg`

- `overrides.cfg`

- `publican.cfg`

- `publican-brand.spec`, dove brand è il nome del brand.

- `README`

- una sotto-cartella contenente i file XML di brand, fogli di stile CSS e immagini predefinite. La sotto-cartella ha lo stesso nome del codice linguistico della lingua originale del brand (per esempio, `en-US`). Questi file sono:

  - `Feedback.xml`

  - `Legal_Notice.xml`

  - la sotto-cartella `css`, contenente:

    - `overrides.css`

  - la sotto-cartella `images`, contenente 43 immagini in formato raster o bitmap (PNG) e vettoriale (SVG).

### 5.3.1. Il file publican.cfg

Il file `publican.cfg`, in un brand, svolge una funzione simile al file `publican.cfg` in un documento — configura un certo numero di opzioni di base per definire il brand.

`version`

  specifica il numero di versione del brand. Quando si crea un brand con il comando publican create_brand, la versione è impostata a `0.1`. Aggiornare questo numero di versione presente in `publican.cfg` e in `publican.spec` del brand, in occasione della preparazione di una nuova versione del brand.

  Notare che questo parametro non è correlato al numero di versione dei documenti creati con questo brand. Per esempio, Fedora 12 Installation Guide ha la versione impostata a `12` nel proprio file `publican.cfg`, ma potrebbe essere compilato con la versione 1.0 del brand publican-fedora.

`xml_lang`

  specifica la lingua dei file sorgenti XML per il Common Content del brand, per esempio `en-US`, come impostato nell'opzione `--lang` del comando publican create_brand.

`release`

  specifica il numero di release per il brand. Quando si crea un brand con il comando publican create_brand, la release è impostata a `0`. Aggiornare il numero di release nei file `publican.cfg` e `publican-brand.spec` , in occasione della preparazione di una nuova release per un brand esistente.

`type`

  impostato a `type: brand`, questo parametro identifica il contenuto nella cartella come un brand invece che come un libro, articolo o set.

`brand`

  specifica il nome del brand, come impostato dall'opzione `--name` nel comando publican create_brand.

`type`

  the full path for the Publican site configuration file for non standard RPM websites.

`web_dir`

  the full path to where files will be installed. You must also set wwwdir in `publican-brand.spec`.

`brand`

  the name of the RPM package that will supply the Publican site config file.

### 5.3.2. I file defaults.cfg e overrides.cfg

Ogni documento creato in Publican, ha un file `publican.cfg` nella cartella radice, per configurare le opzioni di creazione dei documenti. Fare riferimento alla Sezione 4.1.1, «Il file publican.cfg» per una completa descrizione di queste opzioni. I file `defaults.cfg` e `overrides.cfg` in un brand, forniscono valori predefiniti ai parametri, che è possibile impostare nel file `publican.cfg` di un documento.

Quando si compila un documento con un particolare brand, Publican dapprima applica i valori nel file `defaults.cfg` del brand e poi i valori impostati nel file `publican.cfg` del documento. Quindi i valori di `publican.cfg` hanno la precedenza su quelli impostati nel file `defaults.cfg` del brand.

Poi Publican applica i valori impostati nel file `overrides.cfg` del brand, per cui quest'ultimo non tiene conto dei valori impostati in `defaults.cfg` del brand e in `publican.cfg` del documento.

Usare il file `defaults.cfg` per impostare valori da applicare per routine al brand e per consentire ai redattori di modificarli nei libri; usare il file `overrides.cfg` per impostare quei valori che non si desidera vengano modificati dai redattori.

You can add a list of banned tags or attributes using banned_tags and banned_attrs respectively to either `defaults.cfg` or `overrides.cfg`. These will be listed by the Publican action print_banned.

### 5.3.3. File publican-brand.spec

Alcuni Sistemi Operativi Linux, usano un Gestore di pacchetti RPM per distribuire software, sotto forma di pacchetti RPM. In termini generali, un pacchetto RPM contiene i file di software compressi in un archivio, insieme ad un file spec che indica al Gestore di pacchetti RPM come e dove installare questi file.

Quando si crea un brand, Publican genera lo schema di un file spec di RPM per il brand. Il file spec generato (automaticamente), fornisce uno schema di partenza da cui creare il pacchetto RPM con cui distribuire il brand. Fare riferimento alla Sezione 5.4, «Creare il pacchetto di un brand» per sapere come configurare il file spec e come usarlo per produrre un pacchetto RPM.

### 5.3.4. README

Il file `README` contiene una breve descrizione del pacchetto di brand.

### 5.3.5. COPYING

Il file `COPYING` contiene i dettagli riguardanti la licenza o COPYRIGHT sul pacchetto e presumibilmente il testo della stessa licenza.

### 5.3.6. Common Content per il brand

All'interno della cartella del brand, si trova una sotto-cartella denominata con il nome della lingua predefinita dei file XML, come impostata con l'opzione `--lang` al momento della creazione del brand. Questa cartella contiene i file XML e le immagini, che si sovrappongono al Common Content predefinito fornito con Publican. La personalizzazione di questi file permette ad un brand di acquisire il suo aspetto distintivo, con il suo schema di colori e i suoi loghi.

#### 5.3.6.1. `Feedback.xml`

Il file `Feedback.xml` è incluso, per impostazione predefinita, nella prefazione di ogni libro prodotto con Publican. Con questo file si invitano i lettori ad inviare commenti sul documento. Personalizzare questo file inserendo i recapiti del progetto. Se il progetto usa un sistema di tracciamento di bug come Bugzilla, JIRA o Trac si potrebbe includere qui questo tipo di informazione.

#### 5.3.6.2. `Legal_Notice.xml`

Il file `Legal_Notice.xml` contiene le informazioni legali che appaiono all'inizio di ogni documento prodotto con Publican. Inserire i dettagli riguardanti la propria licenza sul diritto d'autore in questo file. Tipicamente, ciò potrebbe includere il nome della licenza, con un breve descrizione ed un link ai dettagli completi sulla licenza.

### 5.3.7. La sotto-cartella `css`

La sotto-cartella `css` contiene un solo file: `overrides.css`.

#### 5.3.7.1. overrides.css

Il file `overrides.css` imposta l'apparenza stilistica del brand. I valori in questo file sopravanzano i valori nel file `Common_Content/common/lingua_xml/css/common.css` di Publican.

### 5.3.8. La sotto-cartella `images`

La sotto-cartella `images` contiene 43 immagini in formato PNG (Portable Network Graphics) ed SVG (Scalable Vector Graphics). Queste immagini sono segnaposti per varie icone di navigazione, riquadri contenenti note/suggerimenti/avvisi/, e loghi di brand. Essi includono:

`image_left`

  è un logo per il prodotto cui fa riferimento il documento. Esso compare in alto, nell'angolo sinistro delle pagine HTML, in cui contiene un link alla pagina web per il prodotto, come definito nel parametro `prod_url` del file `publican.cfg` del documento. Si consideri di impostare `prod_url` nei file `defaults.cfg` o `overrides.cfg` del brand.

`image_right`

  è un logo per il team che ha prodotto la documentazione. Esso compare in alto, nell'angolo destro delle pagine HTML, in cui contiene un link alla pagina web per il team, come definito nel parametro `doc_url` del file `publican.cfg` del documento. Se tutta la documentazione per questo brand è prodotta dallo stesso team, si consideri di impostare `doc_url` nei file `defaults.cfg` o `overrides.cfg` del brand.

`title_logo`

  è una versione più grande del logo del prodotto, che compare sulla pagina del titolo nei documenti PDF ed all'inizio nei documenti HTML.

`note`, `important`, `warning`

  sono icone che si accompagnano agli avvisi XML `<note>`, `<important>` e `<warning>`.

`dot`, `dot2`

  sono i punti elenco usati con `<listitem>` in `<itemizedlist>`.

`stock-go-back`, `stock-go-forward`, `stock-go-up`, `stock-home`

  sono le icone di navigazione per le pagine HTML.

`h1-bg`

  è uno sfondo per l'intestazione, contenente il nome del prodotto, come appare all'inizio di un documento HTML.

`watermark_draft`

  è un contrassegno che appare nelle pagine di documentazione in draft (bozza). Fare riferimento alla Sezione 4.10.2, «Denotare la documentazione draft».

### 5.3.9. The brand_dir option

The Publican build option brand_dir allows you to specify the location of brand files. These files do not have to be part of an installed brand.

You can ship custom XSL in a folder named `xsl` in your brand: it sits at the same level as the various language files for your brand. Publican uses any XSL that it finds in that directory to override the XSL templates that we ship in the common brand (which in turn override the XSL templates that the DocBook project ships).

Importante

Brands with custom XSLT need to change the relative path of referencing XSL templates to a URI.

## 5.4. Creare il pacchetto di un brand

Altri pacchetti non 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.

Dopo aver creato un brand (come descritto nella Sezione 5.2, «Creare un brand»), Publican permette di distribuire il brand ai membri di un team di documentazione come pacchetti RPM. I pacchetti RPM vengono impiegati per distribuire software ai computer con sistemi operativi Linux che usano un Gestore di pacchetti RPM. Tra questi sistemi operativi figurano Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux e Yellow Dog Linux, per citarne solo alcuni.

Publican è in grado di produrre sia pacchetti RPM di sorgenti (pacchetti SRPM) sia pacchetti RPM di binari. Come parte del processo, crea anche il file spec — il file contenente i dettagli di come configurare ed installare il pacchetto.

Un pacchetto SRPM contiene il codice sorgente da cui generare il software, invece del software stesso. Per usare un pacchetto SRPM, un sistema deve compilare il codice sorgente trasformandolo in software. I pacchetti SRPM di brand creati con Publican, contengono file di configurazione, file XML e file di immagini che definiscono il brand nella propria lingua originale, più i file PO che generano i file di Common Content nelle varie lingue. Non è possibile installare direttamente i documenti da un pacchetto SRPM con la versione attuale di RPM Package Manager.

Al contrario, i pacchetti RPM di binari contengono software — in questo caso, un brand di Publican — pronto per essere salvato nel file system del computer ed immediatamente usato. I contenuti del pacchetto RPM binario non devono essere prima compilati sul sistema da installare, e quindi il sistema non deve aver Publican, installato.

Per creare il pacchetto di un brand, usare il comando publican package nella cartella del brand. Quando usato senza opzioni, Publican crea un pacchetto SRPM. Le opzioni disponibili sono:

`--binary`

  specifica di compilare il pacchetto come un pacchetto RPM binario.

`--brew`

  specifica di inviare su Brew il pacchetto completato. Brew è il sistema di compilazione interno a Red Hat; questa opzione non ha senso all'esterno di Red Hat.

`--scratch`

  se usato insieme all'opzione `--brew`, specifica di compilare il pacchetto SRPM da inviare su Brew, come uno scratch build (compilazione di prova). Uno scratch build è usato per verificare la correttezza strutturale del pacchetto SRPM, senza aggiornare il database dei pacchetti con il pacchetto risultante.

Le opzioni `--lang`, `--desktop` e `--short_sighted` che si applicano quando si crea il pacchetto di un libro (descritto nella Sezione 4.8, «Creare il pacchetto di un documento») non hanno senso nel caso dei brand. In particolare, notare che sebbene l'opzione `--lang` sia necessaria per la creazione del pacchetto di un libro, essa non occorre quando si crea il pacchetto di un brand.

Per impostazione predefinita, i pacchetti di brand di Publican sono denominati:

`publican-brand-versione-release.build_target.noarch.estensione_file`

Publican usa le informazioni nel file `publican.cfg` per fornire i vari parametri nel nome di file. Fare riferimento alla Sezione 5.3.1, «Il file publican.cfg» per i dettagli sulla configurazione di questo file. Inoltre:

- i pacchetti SRPM hanno estensione `.src.rpm` mentre i pacchetti RPM di binari hanno estensione `.rpm`

- i pacchetti RPM di binari include prima dell'estensione, l'elemento `build_target.noarch`, dove build_target rappresenta il sistema operativo e la versione, per cui il pacchetto viene compilato, come impostato dal parametro `os_ver` nel file `publican.cfg`. L'elemento `noarch` specifica che il pacchetto può essere installato su ogni sistema, a prescindere dall'architettura.

# Capitolo 6. Usare i set

Un set è una raccolta di libri pubblicati come una unica presentazione. Services Plan, per esempio, è un set composto da molti libri come Developer Guide, Engineering Content Services Guide ed Engineering Operations Guide, per citarne solo alcuni. Il comando create_book crea un modello per un set, impostando il parametro `type` con il valore `Set`.

Esistono due tipi di set:

- set a sé stanti

- set distribuiti

## 6.1. Set a sé stanti

Un set a sé stante contiene i file XML di ogni libro, i quali si trovano all'interno della cartella del set. I set a sé stanti sono sempre costruiti come un set; non è possibile costruire i singoli libri senza effettuare modifiche.

Il seguente procedimento indica come creare un set a sé stante di nome My Set, salvato nella cartella `books/My_Set/`. Il set è composto da due libri, Book A e Book B, entrambi creati manualmente all'interno della cartella `books/My_Set/en-US`.

Procedura 6.1. Creare un set a sé stante

1. In una shell, eseguire il seguente comando nella cartella `books/` per creare un set denominato `My_Set` con brand in stile Red Hat e in cui i file XML vengono redatti in inglese americano.

       publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US

2. cd nella cartella `My_Set/en-US` e creare due cartelle (non libri), denominate `Book_A` e `Book_B`.

       $ cd My_Set/en-US
       $ mkdir Book_A Book_B

3. cd nella cartella `books/My_Set/en-US/Book_A`. Creare e modificare i file `Book_A.xml`, `Book_Info.xml` e gli altri file XML richiesti dal libro e gli altri dei vari capitoli. Assicurarsi che il file `Book_A.xml` contenga i corretti riferimenti in `xi:include` a tutti i file XML nella cartella. Per esempio, se Book A contiene `Book_Info.xml` e `Chapter_1.xml`, il file `Book_A.xml` potrebbe essere simile a:

       <?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>
       	  <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
       </book>

4. Usare lo stesso procedimento per il Book_B, salvato nella cartella `books/My_Set/en-US/Book_B`, come indicato sopra.

5. Modificare il file `books/My_Set/en-US/My_Set.xml`. Per ciascun libro nel set, aggiungere un riferimento `xi:include` al file XML principale del libro. Il file XML principale per il Book A è `Book_A.xml` e quello per il Book B, `Book_B.xml`. Il file `My_Set.xml` dovrebbe assomigliare a:

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

       <set>
       	<xi:include href="Set_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="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       </set>

6. Per rendere valido il set, occorre effettuare la seguente modifica:

   1. In `My_Set.xml`, togliere il commento alle seguenti righe:

          <remark>NOTE: the href does not contain a language! This is CORRECT!</remark>
          <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark>
          <setindex></setindex>

   2. In `Preface.xml` e `Book_Info.xml` di ogni libro, aggiungere ../../ all'inizio di ogni stringa Common_Content, presente. Per esempio:

          <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

      Quindi si ha:

          <xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

      Ciò perché in un set a sé stante, la cartella Common Content si trova due cartelle più in là rispetto a dove di solito cerca Publican, perciò occorre inserirlo manualmente. Per compilare i libri singolarmente, senza costruire l'intero set, saltare questo passaggio.

7. Verificare il set, con il comando publican build --formats=test --langs=en-US.

Se si usano libri pre-esistenti, occorre riorganizzarli in modo che i file XML siano al livello del set e tutte le immagini siano all'interno della cartella delle immagini, nello stesso livello. Per esempio:

       -- My_Set
        |-- en-US
        |   |-- Author_Group.xml
        |   |-- Book_A.ent
        |   |-- Book_A.xml
        |   |-- Book_B.ent
        |   |-- Book_B.xml
        |   |-- Book_Info_A.xml
        |   |-- Book_Info_B.xml
        |   |-- chapter_A.xml
        |   |-- chapter_B.xml
        |   |-- images
        |   |   |-- icon.svg
        |   |   `-- image1.png
        |   |-- My_Set.ent
        |   |-- My_Set.xml
        |   |-- Preface.xml
        |   |-- Revision_History.xml
        |   `-- Set_Info.xml
        `-- publican.cfg

I file XML possono trovarsi anche all'interno di sotto-cartelle separate. E lo stesso vale per la cartella delle immagini. Per esempio:

       -- My_Set
        |-- en-US
        |   |-- Author_Group.xml
        |   |-- Book_A
        |   |   |-- Book_A.ent
        |   |   |-- Book_A.xml
        |   |   |-- Book_Info.xml
        |   |   `-- chapter.xml
        |   |-- Book_B
        |   |   |-- Book_B.ent
        |   |   |-- Book_B.xml
        |   |   |-- Book_Info.xml
        |   |   `-- chapter.xml
        |   |-- images
        |   |   |-- icon.svg
        |   |   `-- image1.png
        |   |-- My_Set.ent
        |   |-- My_Set.xml
        |   |-- Preface.xml
        |   |-- Revision_History.xml
        |   `-- Set_Info.xml
        `-- publican.cfg

## 6.2. Set distribuiti

Un set distribuito contiene libri localizzati in un repository di controllo versione. Sebbene esistano diversi sistemi di controllo versione, questa versione di Publican supporta solo un sistema: SVN (Subversion). Impostando, nel file `publican.cfg`, la locazione del repository e i titoli dei libri contenuti nel set, ogni libro può essere esportato per creare il set completo. Il seguente procedimento, indica come creare un set denominato My Set contenente il Book A ed il Book B.

Importante

Di seguito so assume che il Book A ed il Book B siano già esistenti e disponibili in un repository SVN. Al momento, Publican supporta solo SVN.

Procedura 6.2. Creare un set

1. In una shell, eseguire il seguente comando, per creare un set denominato `My_Set` con brand in stile Red Hat e in cui i file XML vengono redatti in inglese americano.

       $ publican create --type=Set --name=My_Set --brand=RedHat  --lang=en-US

2. Aggiungere le seguenti righe al file `publican.cfg`:

       books: Book_A Book_B
       repo: http://PATH-TO-YOUR-SVN-REPOSITORY
       scm: SVN

   Il percorso al repository deve indirizzare per primo, la cartella del libro.

3. Modificare il file `My_Set.xml`. Per ciascun libro del set, aggiungere un riferimento `xi:include` al file XML principale del libro. Il file XML principale per il Book A è `Book_A.xml` e quello per il Book B, `Book_B.xml`. Il file `My_Set.xml` dovrebbe assomigliare a:

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

       <set>
       	<xi:include href="Set_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="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
       </set>

4. Per rendere valido il set, occorre togliere il commento alle seguenti righe in `My_Set.xml`:

       <remark>NOTE: the href does not contain a language! This is CORRECT!</remark>
       <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark>
       <setindex></setindex>

5. Verificare il set, con il comando publican build --formats=test --langs=en-US.

   Importante

   Quando si crea un set, il comando publican clean_ids verrà eseguito su ogni libro poiché la condizione di unicità degli ID deve essere valida su tutti i libri. Prestare particolare attenzione alla creazione di ID basati su contenuto, che potrebbe rendersi indisponibile, se i libri vengono creati isolatamente dal set.

# Capitolo 7. Creare un sito web con Publican

Publican non solo crea documenti per pubblicazione ma può creare e gestire anche un sito web di documentazione. Se occorre mantenere una raccolta di documenti, si può usare Publican per creare un sito sul sistema locale e poi caricare il sito su un server web. Tuttavia questo approccio non è molto scalabile, per cui nei progetti di documentazione basati su team, Publican permette di creare pacchetti RPM di documentazione da installare sul server web. Per installare su un server i pacchetti RPM creati con Publican, occorre che sul server sia installato Publican (versione 2.1 o superiore) e l'applicazione rpm. Se si crea e mantiene il sito su una workstation e poi lo si carica su un server web per pubblicazione, allora non occorre che Publican ed rpm siano installati sul server web.

Il sito web creato da Publican consiste di quattro parti: la struttura del sito, una home page, pagine descrittive su prodotto e versione, e i documenti pubblicati sul sito. La struttura del sito, a sua volta consiste di:

- un file di configurazione

- un file di database SQLite

- una sottocartella per i documenti pubblicati, contenente:

  - `index.html` — una pagina indice che indirizza alle versioni localizzate di una home page per il sito.

  - `interactive.css` — un foglio di stile CSS contenente gli stili per il menu di navigazione, per le pagine map e per le statistiche sul sito.

  - `opds.xml` — un catalogo OPDS (Open Publication Distribution System) per permettere ai lettori di eBook compatibili di individuare facilmente i documenti sul sito.

  - `Sitemap` — A Sitemap is a list of the URLs from your website and metadata about them, like update history, change frequency, and importance relative to other URLs in the site. A Sitemap can be supplied to many major search engines, where it is used to help their crawlers index your site more intelligently. A Sitemap does not guarantee that your site will be ranked higher in search results. However, it does help search engines to return the most relevant results from your website in response to user queries. For more information on Sitemaps, visit sitemaps.org.

  - `site_overrides.css` — un foglio di stile CSS alternativo a quelli presenti in `interactive.css`, per offrire stili specifici per il sito. Questo file non è creato dal processo di creazione del sito, ma deve essere aggiunto manualmente, successivamente o fornito dalla home page del sito.

  - `toc.js` — uno script JavaScript che in base all'impostazione nel browser, indirizza i visitatori al contenuto in lingua locale e che controlla la presentazione del menu di navigazione.

  - subdirectories for each language in which you publish. Initially, this contains `opds.xml` and `toc.html`. Later it also contains `opds-product.xml`:

    - `opds.xml` — un catalogo OPDS di documenti EPUB in questa lingua.

    - `opds-prodotto.xml` — un catalogo OPDS di documenti EPUB per ogni prodotto da pubblicare in questa lingua. All'interno di ogni catalogo, per versioni differenti dello stesso prodotto, la documentazione è suddivisa in `<category>`.

    - `toc.html` — l'indice ai contenuti per la lingua, inizialmente senza alcun link a documento.

    - Una sotto-cartella per ciascun prodotto da pubblicare in questa lingua.

Optionally, the site structure might also include a dump file — an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The site structure might also contain a zipped version of the dump file. Refer to Sezione 7.1, «Creare manualmente un sito web» and Sezione 7.2, «Creare un sito web usando pacchetti RPM» for details of creating a dump file, and to Appendice D, Contenuto del file dump di un sito for a description of the dump file contents.

## 7.1. Creare manualmente un sito web

### 7.1.1. Creare la struttura del sito web

Per creare la struttura del sito web:

1. Sulla propria macchina, creare una nuova cartella, in cui poi spostarsi. Per esempio, su un sistema Linux, eseguire:

       $ mkdir ~/docsite
       $ cd ~/docsite

2. Eseguire publican create_site, specificando i seguenti parametri:

   - `--site_config` — il nome del file di configurazione, per il sito, con estensione `.cfg`

   - `--db_file` — il nome del file di database SQLite, per il sito, con estensione `.db`

   - `--toc_path` — il percorso alla cartella in cui saranno salvati i documenti

   Su un computer con sistema operativo diverso da Linux, impostare anche:

   - `--temp_path` — il percorso alla cartella `templates/` nella directory di installazione di Publican. Sui computer con sistemi operativi Windows, il percorso tipicamente coincide con `%SystemDrive%\%ProgramFiles%\Publican\templates`.

   Per esempio:

       publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs

   E' possibile assegnare dei nomi ai file di configurazione e di database del sito per un miglior riconoscimento del sito di appartenenza. Per esempio, per il sito di documentazione FooMaster, si potrebbe assegnare a questi file, rispettivamente, i nomi `foomaster.cfg` e `foomaster.db`. Il parametro `--toc_path` può essere impostato a piacere.

3. Modificare il file di configurazione specificando il nome del sito, il web host ed opzionalmente, impostare i parametri di ricerca, la lingua predefinita, le impostazioni del file dump e quelle di aggiornamento per il sito:

   1. Specificare il titolo con il parametro `title`, per esempio:

          title: "Foomaster Documentation"

      Normalmente, i visitatori del sito non visualizzano questo titolo perché il JavaScript del sito li reindirizza alla homepage. Comunque il titolo è facilmente individuato ed indicizzato dai motori di ricerca.

   2. Specificare con il parametro `host`, il web host indicando l'URL completo, incluso il protocollo. Per esempio:

          host: http://docs.example.com

      Publican usa il valore impostato in `host` per costruire gli URL nel file XML, `Sitemap`, usato dai motori di ricerca e per limitare le ricerche dalla casella relativa nel menu di navigazione, soltanto ai documenti presenti nel sito.

   3. Opzionalmente, costruire un motore di ricerca da usare con la casella di ricerca nel menu di navigazione, e specificare l'intero contenuto del `<form>` HTML con il parametro `search`. Se non si specifica alcun criterio di ricerca, Publican crea una ricerca basata su Google, limitando la ricerca all'host specificato dal parametro `host`.

      Per esempio, per costruire una ricerca basata su Yahoo!, limitatamente all'host `docs.example.com`, impostare:

          search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'

      Fare riferimento alla documentazione del motore di ricerca scelto, per i dettagli su come creare criteri di ricerca personalizzati.

      Se nel codice di un pulsante di ricerca, si imposta `value="###Search###"`, Publican visualizza il termine `Search` sul pulsante, ovviamente tradotto in ogni lingua supportata da Publican.

      Importante — il parametro `search` non è validato

      Publican non controlla la validità del parametro `search`, ma crea il valore di questo parametro nel menu di navigazione, così come specificato. Prestare particolare attenzione nell'usare questa proprietà.

   4. Opzionalmente, impostare la lingua predefinita del sito web. Publican crea un menu di navigazione distinto e tradotto, per ogni lingua in cui si pubblica la documentazione. Comunque, se un documento non è disponibile in una particolare lingua, Publican indirizza i visitatori alla versione in lingua originale del documento. Per specificare la lingua predefinita, originale del sito, impostare il parametro `def_lang` con il codice linguistico relativo. Per esempio:

          def_lang: it-IT

      Impostando il parametro `def_lang` con il codice `it-IT`, i visitatori che visualizzano il menu di navigazione, per esempio in spagnolo, vengono diretti alla versione italiana del documento se non è presente una traduzione in spagnolo.

   5. Opzionalmente, configurare un file dump per il sito web. Publican può produrre un file XML con i dettagli completi del contenuto del sito per offrire altri servizi, come feed web o pagine di ricerca personalizzate. Questo file viene aggiornato ad ogni installazione o rimozione di un libro dal sito, oppure eseguendo il comando publican update_site. Configurare come indicato di seguito, i parametri `dump`, `dump_file` e `zip_dump`:

      `dump`

        Impostare `dump: 1` per abilitare la funzione di file dump. Il parametro, in modo predefinito, è impostato su `0` (disattivato).

      `dump_file`

        Impostare `dump_file: nome` per specificare il nome del file dump e la cartella in cui salvare il file. Il parametro, in modo predefinito, è impostato su `/var/www/html/DUMP.xml`.

      `zip_dump`

        Impostare `zip_dump: 1` per creare anche una versione zippata del file XML. Il parametro, in modo predefinito, è impostato su `0` (disattivato).

      Refer to Appendice D, Contenuto del file dump di un sito for a description of the contents of the dump file.

   6. Optionally, specify the web style with the `web_style`.

      web_style: 1

        The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)

      web_style: 2

        The website includes a breadcrumb-like navigation bar across the top of the documentation.

      Importante

      The web style set for your site must match the web style set for your content. For example, if you set `web_style: 2` for your website, you need to have `web_style: 2` set in each of the books that you want to install on the site. Consider setting this parameter in the `defaults.cfg` or `overrides.cfg` files of the brands that you intend to use with this site.

   7. Opzionalmente, specificare con il parametro `manual_toc_update`, che le tabelle dei contenuti sono aggiornate manualmente, per esempio:

          manual_toc_update: 1

      Normalmente, Publican aggiorna le tabelle dei contenuti del sito, ogniqualvolta viene aggiunto o rimosso un pacchetto di documentazione. Su un sito con un gran numero di documenti (più di un centinaio), o in cui i documenti sono spesso aggiornati (dozzine per settimana), questo processo è oneroso di risorse. Su un sito di grandi dimensioni o molto occupato, si raccomanda di impostare questo parametro e poi di aggiornare periodicamente le tabelle dei contenuti con il comando publican update_site.

   8. Optionally, override the default JavaScript for the site with the `toc_js` parameter, for example:

          toc_js: "mybrand/scripts/megafoo.js"

      This file will be symlinked as `toc_path`/toc.js with the `$` publican update_site command. This path should be relative to the `toc_path` parameter.

4. Creare un file vuoto di nome `site_overrides.css` nella cartella specificata con l'opzione `doc_path` (la cartella che contiene il foglio di stile `interactive.css` e le cartelle linguistiche). Se si desidera usare degli stili specifici alternativi a quelli forniti da `interactive.css`, aggiungere un file `site_overrides.css` al documento che fornisce la home page del sito — vedere la Sezione 7.1, «Creare manualmente un sito web». Se non si usa uno stile specifico, il file vuoto aggiunto impedirà la comparsa dell'errore 404 sul server. Su un sistema Linux, spostarsi nella cartella specificata con l'opzione `doc_path` ed eseguire:

       touch site_overrides.css

5. Build and install each brand, including the Publican `common` brand.

   1. Change into the directory that holds the source for the brand.

          $ cd brandsrc_dir

   2. Build the brand.

          $ publican build --formats=xml --langs=all --publish

   3. Install the brand on your website.

          $ publican install_brand --web --path=path_to_site_root_dir

      Perform these steps for all brands.

6. Update the site.

       $ publican update_site

Per aggiornare la struttura del sito, eseguire:

    publican update_site --site_config percorso_al_file_di_configuration_del_sito.cfg

### 7.1.2. Creare, installare ed aggiornare la home page

The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook `<article>` with an extra `web_type: home` parameter in its `publican.cfg` file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican. To create the home page:

1. Spostarsi in una cartella opportuna ed eseguire il comando di publican create:

       publican create --type Article --name nome_pagina

   Per esempio:

       publican create --type Article --name Home_Page

   La maggior parte dei brand (incluso il brand `common`), presentano il nome del documento in grandi lettere a colori in cima alla pagina, al di sotto del banner contenente il nome del prodotto (l'opzione `--name` imposta il tag `<title>`). Quindi, per impostazione, il valore impostato con l'opzione `--name` viene presentata in primo piano ai visitatori del sito; nel precedente esempio, i visitatori vengono salutati con le parole `Home Page` sotto il banner del prodotto.

2. Spostarsi nella cartella dell'articolo:

       cd nome_pagina

   Per esempio:

       $ cd Home_Page

3. Scollegare il file `Article_Info.xml` dal file XML radice.

   Il contenuto del file `Article_Info.xml` serve a ben poco alla home page del sito web. Quindi, modificare il file XML radice relativo alla home page, rimuovendo il tag `<xi:include>` che collega `Article_Info.xml`. Ora Publican usa ancora le informazioni in `Article_Info.xml` per creare pacchetti, ma senza includerlo nella home pagina stessa.

4. Modificare il file `publican.cfg`.

   Come minimo, aggiungere il parametro `web_type` ed impostarlo a `home`:

       web_type: home

   The `web_type: home` parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the `publican.cfg` file. Other optional changes to the `publican.cfg` file that are frequently useful for Publican-generated websites include:

   `brand`

     Per assegnare alla home page lo stile dei propri documenti, aggiungere:

         brand: nome_di_brand

   `docname`, `product`

     Se il tag `<title>` o `<product>` impostati nel file `Article_Info` includono caratteri diversi dai caratteri di base, come caratteri accentati, impostare come occorre i parametri `docname` e `product`.

5. Modificare il contenuto del file `nome_pagina.xml` (per esempio, `Home_Page.xml`) come ogni altro documento DocBook.

   Se si rimuove il tag `<xi:include>` che collega a `Article_Info.xml`, specificare un titolo per la pagina nel formato seguente:

       <title role="producttitle">FooMaster Documentation</title>

6. Se si pubblica documentazione in più lingue, creare un set di file POT ed un set di file PO per ciascuna lingua usando i comandi publican update_pot e publican update_po.

7. To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 290 px × 100 px and name it `web_logo.png`. Place this image in the `images/` directory in the document's XML directory, for example `en-US/images/`.

8. Se si desidera usare degli stili specifici alternativi a quelli forniti da `interactive.css` nel sito web, aggiungere gli stili a un file `site_overrides.css` e salvarlo nella radice dei file sorgenti (la cartella che contiene il file `publican.cfg` e le cartelle linguistiche).

9. Creare la home page in formato HTML su singola pagina con l'opzione `--embedtoc` ed installarla nella struttura del sito. Per esempio:

       publican build --publish --formats html-single --embedtoc --langs all
       publican install_book --site_config ~/docsite/foomaster.cfg --lang Codice_Lingua

   Notare che è possibile creare con un unico comando, gli HTML per tutte le lingue, ma occorre installare la home page di ciascuna lingua con un comando publican install_book, individuale.

### 7.1.3. Creare, installare ed aggiornare pagine di prodotto e di versione

Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook `<article>`s with an extra `web_type: product` or `web_type: version` parameter in their `publican.cfg` files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican. To create a product page or version page:

1. Spostarsi in una cartella opportuna ed eseguire il seguente comando di publican create:

       publican create --type Article --name nome_pagina

   Per esempio, per una pagina prodotto si avrebbe:

       publican create --type Article --name FooMaster

   o per una pagina di versione:

       publican create --type Article --name FooMaster_3

2. Spostarsi nella cartella dell'articolo:

       cd nome_pagina

   Per esempio:

       $ cd FooMaster

3. Scollegare il file `Article_Info.xml` dal file XML radice.

   Il contenuto del file `Article_Info.xml` serve a ben poco alle pagine prodotto o versione. Quindi, modificare il file XML radice relativo alla pagina, rimuovendo il tag `<xi:include>` che collega `Article_Info.xml`. Ora Publican usa ancora le informazioni in `Article_Info.xml` per creare pacchetti, ma senza includerlo nella home pagina stessa.

4. Modificare il file `publican.cfg`.

   Come minimo, aggiungere il parametro `web_type` ed impostarlo a `product` o `version`:

       web_type: product

   o

       web_type: version

   Il parametro `web_type` indica di elaborare questo documento non come una documentazione di prodotto. Questa è l'unica modifica necessaria al file `publican.cfg`. Altre modifiche opzionali al file `publican.cfg`, frequentemente utili a pagine prodotto o di versione includono:

   `brand`

     Per assegnare alla home page lo stile dei propri documenti, aggiungere:

         brand: nome_di_brand

   `docname`, `product`

     Se il tag `<title>` o `<product>` impostati nel file `Article_Info` includono caratteri diversi dai caratteri di base non accentati, impostare come occorre i parametri `docname` e `product`.

5. Modificare il contenuto del file `nome_pagina.xml` (per esempio, `FooMaster.xml`) come ogni altro documento DocBook.

   Se si rimuove il tag `<xi:include>` che collega a `Article_Info.xml`, specificare un titolo per la pagina nel formato seguente:

       <title role="producttitle">FooMaster Documentation</title>

6. Se si pubblica documentazione in più lingue, creare un set di file POT ed un set di file PO per ciascuna lingua usando i comandi publican update_pot e publican update_po.

7. Creare la pagina prodotto o di versione in formato HTML su singola pagina con l'opzione `--embedtoc` ed installarla nella struttura del sito. Per esempio:

       publican build --publish --formats html-single --embedtoc --langs all
       publican install_book --site_config ~/docsite/foomaster.cfg --lang codice_lingua

   Notare che è possibile creare con un unico comando, gli HTML per tutte le lingue, ma che occorre installare la pagina prodotto o di versione di ciascuna lingua con un comando publican install_book, individuale.

### 7.1.4. Installare, aggiornare e rimuovere documenti

Per installare un documento su un sito web da creare manualmente, spostarsi nella cartella contenente il sorgente del documento ed eseguire:

    publican build --embedtoc --formats=lista_dei_formati --langs=codici_lingua --publish
    publican install_book --site_config percorso_al_file_di_configurazione_del_sito.cfg --lang codici_lingua

Notare che è possibile creare con un unico comando di publican build, le pubblicazioni per tutte le lingue, ma che occorre un comando publican install_book, individuale per ciascuna lingua. Nel comando publican build, occorre includere `html` come uno dei formato d'uscita ; opzionalmente, è possibile includere anche uno o più dei seguenti formati, separandoli con virgole: `html-single`, `pdf` ed `epub`.

Per aggiornare un documento, spostarsi nella cartella contenente i sorgenti del documento ed eseguire gli stessi comandi relativi ad una prima installazione di un documento. In tal modo, Publican sostituisce la precedente con la nuova versione.

Per rimuovere un documento, spostarsi nella cartella contenente i sorgenti del documento ed eseguire:

    publican remove_book --site_config percorso_al_file_di_configurazione_del_sito.cfg --lang codice_lingua

Una volta installati i documenti, il sito è pronto per essere caricato sul server web attraverso un qualsiasi metodo solitamente usato, come scp, rsync o un client FTP.

## 7.2. Creare un sito web usando pacchetti RPM

### 7.2.1. Creare la struttura del sito web

Avviso — Questa procedura sostituisce i file

Quando si costruisce la struttura del sito web, Publican salva i file nella cartella `/var/www/html/docs`. Quindi usando questa procedura, i file esistenti nella cartella vengono sovrascritti.

Perform the following steps on your webserver.

1. Autenticarsi sul server web.

2. Installare Publican. Per esempio, su un server con Sistema Operativo Fedora, eseguire:

       $ sudo yum install publican publican-common-web

3. Modificare il file `/etc/publican-website.cfg`, specificando il nome del sito, il web host ed opzionalmente impostare i parametri di ricerca, la lingua predefinita e il file dump per il sito:

   1. Specificare il titolo con il parametro `title`, per esempio:

          title: "Foomaster Documentation"

      Normalmente, i visitatori del sito non visualizzano questo titolo perché rediretti alla home page dallo JavaScript del sito. Comunque questo titolo è individuato ed indicizzato dai motori di ricerca.

   2. Specificare il web host con il parametro `host` come un URL completo, includente il protocollo. Per esempio:

          host: http://docs.example.com

      Publican usa il valore impostato in `host` per costruire gli URL nel file XML, `Sitemap`, usato dai motori di ricerca e per limitare le ricerche dalla casella relativa nel menu di navigazione, soltanto ai documenti presenti nel sito.

   3. Opzionalmente, costruire un motore di ricerca da usare con la casella ricerca nel menu di navigazione, e specificare l'intero contenuto del `<form>` HTML con il parametro `search`. Se non si specifica alcun criterio di ricerca, Publican crea una ricerca basata su Google, limitando la ricerca all'host specificato nel parametro `host`.

      Per esempio, per costruire una ricerca basata su Yahoo!, limitatamente all'host `docs.example.com`, impostare:

          search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'

      Fare riferimento alla documentazione del motore di ricerca scelto, per i dettagli su come creare criteri di ricerca personalizzati.

      Se nel codice di un pulsante di ricerca, si imposta `value="###Search###"`, Publican visualizza il termine `Search` sul pulsante, ovviamente tradotto in ogni lingua supportata da Publican.

      Importante — il parametro `search` non è validato

      Publican non controlla la validità del parametro `search`, ma crea il valore di questo parametro nel menu di navigazione, così come specificato. Prestare particolare attenzione nell'usare questa proprietà.

   4. Opzionalmente, impostare la lingua predefinita del sito web. Publican crea un menu di navigazione distinto e tradotto, per ogni lingua in cui si pubblica la documentazione. Comunque, se un documento non è disponibile in una particolare lingua, Publican indirizza i visitatori alla versione in lingua originale del documento. Per specificare la lingua predefinita, originale del sito, impostare il parametro `def_lang` con il codice linguistico relativo. Per esempio:

          def_lang: it-IT

      Impostando il parametro `def_lang` con il codice `it-IT`, i visitatori che visualizzano il menu di navigazione, per esempio in spagnolo, vengono diretti alla versione italiana del documento se non è presente una traduzione in spagnolo.

   5. Opzionalmente, configurare un file dump per il sito web. Publican può produrre un file XML con i dettagli completi del contenuto del sito per offrire altri servizi, come feed web o pagine di ricerca personalizzate. Questo file viene aggiornato ad ogni installazione o rimozione di un libro dal sito, oppure eseguendo il comando publican update_site. Configurare come indicato di seguito, i parametri `dump`, `dump_file` e `zip_dump`:

      `dump`

        Impostare `dump: 1` per abilitare la funzione di file dump. Il parametro, in modo predefinito, è impostato su `0` (disattivato).

      `dump_file`

        Impostare `dump_file: nome` per specificare il nome del file dump e la cartella in cui salvare il file. Il parametro, in modo predefinito, è impostato su `/var/www/html/DUMP.xml`.

      `zip_dump`

        Impostare `zip_dump: 1` per creare anche una versione zippata del file XML. Il parametro, in modo predefinito, è impostato su `0` (disattivato).

      Refer to Appendice D, Contenuto del file dump di un sito for a description of the contents of the dump file.

   6. Optionally, specify the web style with the `web_style`.

      web_style: 1

        The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)

      web_style: 2

        The website includes a breadcrumb-like navigation bar across the top of the documentation.

      Importante

      The web style set for your site must match the web style set for your content. For example, if you set `web_style: 2` for your website, you need to have `web_style: 2` set in each of the books that you want to install on the site. Consider setting this parameter in the `defaults.cfg` or `overrides.cfg` files of the brands that you intend to use with this site.

   7. Opzionalmente, specificare con il parametro `manual_toc_update`, che le tabelle dei contenuti sono aggiornate manualmente, per esempio:

          manual_toc_update: 1

      Normally, Publican updates the site's tables of contents every time a documentation package is added or removed. On a site with a large number of documents on it (more than a few hundred), or where documents are updated very frequently (dozens of updates per week), this process is very demanding on a server. On a large or busy site, we recommend that you set this parameter and then periodically update the tables of contents with the `$` publican update_site command.

   8. Optionally, override the default JavaScript for the site with the `toc_js` parameter, for example:

          toc_js: "mybrand/scripts/megafoo.js"

      This file will be symlinked as `toc_path`/toc.js with the `$` publican update_site command. This path should be relative to the `toc_path` parameter.

4. Creare un file vuoto di nome `site_overrides.css`. Se si desidera usare degli stili specifici alternativi a quelli forniti da `interactive.css`, aggiungere un file `site_overrides.css` al documento che fornisce la home page del sito — vedere la Sezione 7.2, «Creare un sito web usando pacchetti RPM». Se non si usa uno stile specifico, il file vuoto aggiunto impedirà la comparsa dell'errore 404 sul server. Su un sistema Linux, eseguire:

       touch /var/www/html/docs/site_overrides.css

Per dire a Publican di aggiornare la struttura del sito, eseguire:

    $ publican update_site

### 7.2.2. Creare, installare ed aggiornare la home page

The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook `<article>` with an extra `web_type: home` parameter in its `publican.cfg` file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican and is packaged the same way.

1. Usando il procedimento indicato nella Sezione 7.1, «Creare manualmente un sito web», su una macchina creare una home page.

2. Nella cartella contenente la home page creata, eseguire:

       publican package --binary

   Publican crea un pacchetto RPM, salvandolo nella cartella `/tmp/rpms/noarch/` della home page. Notare che per impostazione predefinita, Publican genera un pacchetto RPM da installare su un server che esegua Red Hat Enterprise Linux 5. Per creare un RPM da installare su un server con un sistema operativo differente, impostare il parametro `os_var` nel file `publican.cfg` della home page.

3. Caricare il pacchetto sul server web ed installarlo con rpm -i o yum localinstall, oppure salvare il pacchetto in un repository e configurare il server perché possa installarlo dal repository eseguendo il comando yum install.

Per aggiornare la home page, creare un nuovo pacchetto con un numero più alto di `<edition>` o di `<pubsnumber>`, presenti in `Article_Info.xml`. Publican usa questi valori per impostare i numeri di versione e di release del pacchetto RPM. In tal modo, quando si installa il pacchetto sul server, yum può sostituire la versione precedente con la nuova, sia usando yum localinstall per un pacchetto locale, sia yum update per un pacchetto scaricato da un repository.

### 7.2.3. Creare, installare ed aggiornare pagine di prodotto e di versione

Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook `<article>`s with an extra `web_type: product` or `web_type: version` parameter in their `publican.cfg` files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican and are packaged the same way.

1. On a workstation, create a product or version page using the procedure described in Sezione 7.1.3, «Creare, installare ed aggiornare pagine di prodotto e di versione».

2. Nella cartella contenente la pagina prodotto o di versione, eseguire:

       publican package --binary

   Publican crea un pacchetto RPM, salvandolo nella cartella `/tmp/rpms/noarch/` della pagina prodotto o di versione. Notare che per impostazione predefinita, Publican genera un pacchetto RPM da installare su un server che esegua Red Hat Enterprise Linux 5. Per creare un RPM da installare su un server con un sistema operativo differente, impostare il parametro `os_var` nel file `publican.cfg` della pagina prodotto o di versione.

3. Caricare il pacchetto sul server web ed installarlo con rpm -i o yum localinstall, oppure salvare il pacchetto in un repository e configurare il server perché possa installarlo dal repository eseguendo il comando yum install.

Per aggiornare la pagina prodotto o di versione, creare un nuovo pacchetto con un numero più alto di `<edition>` o di `<pubsnumber>`, presenti in `Article_Info.xml`. Publican usa questi valori per impostare i numeri di versione e di release del pacchetto RPM. In tal modo, quando si installa il pacchetto sul server, yum può sostituire la versione precedente con la nuova, sia usando yum localinstall per un pacchetto locale, sia yum update per un pacchetto scaricato da un repository.

### 7.2.4. Installare, aggiornare e rimuovere documenti

Sulla workstation, spostarsi nella cartella contenente i sorgenti del documento ed eseguire:

    publican package --binary --lang codice_lingua

Publican crea un pacchetto RPM, salvandolo nella cartella `/tmp/rpms/noarch/` del documento. Notare che per impostazione predefinita, Publican genera un pacchetto RPM da installare su un server che esegua Red Hat Enterprise Linux 5. Per creare un RPM da installare su un server con un sistema operativo differente, impostare il parametro `os_var` nel file `publican.cfg` del documento.

Caricare il pacchetto sul server web ed installarlo con rpm -i o yum localinstall, oppure salvare il pacchetto in un repository e configurare il server perché possa installarlo dal repository eseguendo il comando yum install.

Per aggiornare un documento, creare un nuovo pacchetto con un numero più alto di `<edition>` o di `<pubsnumber>`, presenti in `Book_Info.xml` o in `Article_Info.xml`. Publican usa questi valori per impostare i numeri di versione e di release del pacchetto RPM. In tal modo, quando si installa il pacchetto sul server, yum può sostituire la versione precedente con la nuova, sia usando yum localinstall per un pacchetto locale, sia yum update per un pacchetto scaricato da un repository.

Rimuovere un documento dal server web, con il comando rpm -e o yum erase.

Su siti di grandi dimensioni o molto occupati, si raccomanda di impostare il parametro `manual_toc_update` nel file di configurazione. Una volta settato, occorre eseguire il comando publican update_site dopo aver installato, aggiornato o rimosso documenti. Fare riferimento alla Sezione 7.1.1, «Creare la struttura del sito web», per maggiori informazioni.

## 7.3. Submitting Your Sitemap to Search Engines

A Publican website includes an XML Sitemap file. The Sitemap can be submitted to many major search engines, in order to help them index your website more intelligently and thoroughly. Each search engine has its own submission procedure. This section includes documentation on how to submit a Sitemap to Google and Bing.

### 7.3.1. Submitting Your Sitemap to Google.

Procedura 7.1. To Submit Your Sitemap to Google:

1. Sign up for a Google account at Google Webmaster Tools. If you already have a Google account, you can use it.

2. Sign in to your Google Webmaster Tools account at this URL: http://www.google.com/webmasters/tools/home.

3. First you must verify you are the owner of your Publican site. Click the Add A Site button.

4. A dialog box is displayed for you to Add a site with. Enter the URL of your Publican site in the text entry field and click Continue.

5. Follow the instructions that display and upload the HTML file that Google provides to the document root of your website.

6. When you have confirmed that the provided HTML file has been uploaded to the required location by accessing it in a web browser, click the Verify button.

7. When you have successfully verified the ownership of your Publican website to Google, return to the Webmaster Tools home page. Your Publican site is listed. Click on it.

8. You are taken to the Webmaster Tools configuration page for your Publican site. On the left side of the page there is a menu. Click on the Site configuration menu entry to expand it. Its expanded contents includes a Sitemaps entry. Click it.

9. You are taken to a Sitemap submission page. Click the Submit a Sitemap button.

10. A text entry field displays, including the base URL of your Publican site, with room to enter the URL of your Sitemap XML file. Enter its location and click the Submit Sitemap button. The details of the Sitemap are displayed in a table.

Risultato. The Sitemap for your Publican site has been successfully submitted to Google.

### 7.3.2. Submitting Your Sitemap to Bing.

Procedura 7.2. To Submit Your Sitemap to Bing:

1. Sign up for a Bing Webmaster Tools account at Bing Webmaster Tools. If you already have a Windows LiveID account, you can use it.

2. Sign in to your Bing Webmaster Tools account at this URL: http://www.bing.com/toolbox/webmaster/.

3. Click the Add Site button.

4. The Add Site dialog box is displayed. Enter the URL of your Publican site in the text entry field and click Submit.

5. The Verify Ownership dialog displays, with three options. Follow the instructions given when the Option 1: Place an XML file on your web server has been expanded. Upload the `BingSiteAuth.xml` file that Bing provides to the document root of your website.

6. When you have confirmed that the provided `BingSiteAuth.xml` file has been uploaded to the required location by accessing it in a web browser, click the Verify button.

7. When you have successfully verified your ownership of your Publican website to Bing, return to the Bing Webmaster Tools home page. Your Publican site is listed. Click on it.

8. Select the Crawl tab.

9. Select Sitemaps and then Add Feed.

10. The Add Feed dialog displays. Enter the URL of your Sitemap file and click Submit. The details of the Sitemap are displayed.

Result: The Sitemap for your Publican site has been successfully submitted to Bing.

# Capitolo 8. Import book into Drupal

Publican 3.1 has a new functionality which allow user to create and import a book into Drupal. All xml files in a book are transformed into a single CSV file which will later be used to import into Drupal.

## 8.1. How to build a CSV file for Drupal import

The CSV File consists of information that tells Drupal how to import the book. Each row in the CSV file represents a html page.

Use the `$` publican build command to create the CSV file for Drupal import. Before running the command, use the cd command to change into the directory where your book is located. For example, if you have a book call "User_Guide" in your home directory, then run the following command.

    $ cd User_Guide/
    $ publican build --langs en-US --formats=drupal-book

After running the command, you will see CSV file is created in the `tmp/en-US/drupal-book/` directory.

Publican stores all the output files in `/tmp/en-US/drupal-book/` directory. This directory contains the following files:

- CSV file - The naming convention of the file is `$product-$version-$docname-$lang-$edition.csv`

- en-US directory - contains all the html images.

- tar.gz file - the archive of both CSV file and en-US directory.

Important — Use version control system

After running the `$` publican build --langs en-US --formats=drupal-book command, you will notice that the xml files in the `en-US` directory had been changed. This is because Publican added a `'Conformance'` attribute for every xml tag that has id. This attribute contains a number which is unique across xml files in the book. If you are using a version control system like git for your xml files, then you need to commit the changes so that the number won't get reset when other users run it. These unique numbers are very important, because they are use as the url path in drupal. Besides, Publican also created a database file name `max_unique_id.db` in the `en-US` directory. This database file is use to track the current maximum unique number in the book, so that Publican can know where you are up to and add a new unique number for your newly created Chapter or Section. Therefore, it is very important to add the database file to the version control and commit it if there is any change. If you add a new section in the xml, don't set the `'Comformance'` attribute yourself as that will make the database outdated. Just leave it for publican to set it.

## 8.2. Il file publican.cfg

Below are some parameters that can be configure in the publican.cfg file for Drupal import:

`drupal_author`

  specfies the author who should be shown in drupal book page. The name must be a valid Drupal username. 'Redhat' is the default author. Set this parameter in the `publican.cfg` file to override it.

  Important — Setting Author

  The author must have permission to manage (create, update, delete) nodes in Drupal. If the default author is used, make sure you had created an account with username 'Redhat' in Drupal.

`drupal_menu_title`

  override the bookname that will be shown in the Drupal menu. If nothing is set, publican will use the default value which is "$product $version $docname". For example, Publican 3.1 User_Guide.

`drupal_menu_block`

  specfies which menu block the book should show in Drupal. The default value is `"user-guide"`.

  Important — Setting menu block

  The menu block must exist in Drupal. For more information about adding a menu block in Drupal. Please refer to Sezione 8.3.1, «How to add a menu block».

`drupal_image_path`

  specfies the directory where the images should be stored in drupal server. The default value is `"sites/default/files/"`.

## 8.3. Drupal Import Guide

Before you can import a book, you need to install a module call 'Node Import' in Drupal. This module allows Drupal to import and update content from CSV or TSV files. To install this module, simply go to drupal site and follow the instructions on the website to download it. Once this is done, then you need to copy the downloaded module to the 'modules' directory on the Drupal server. For example if your Drupal is located in `/var/www/html/drupal/` directory, then you should copy the module to `/var/www/html/drupal/sites/all/modules/` directory. To enable the installed module, login to the Drupal site and go to Administer -> Site building -> Modules . In the Development section, tick the checkbox and click Save configuration button to activate the Node Import Module.

Important — Enable Drupal Core Modules

You also need to enable the following Drupal core modules:

- Book

- Menu

- Path

Permission to install Module

Please consult your web adminstrator if you don't have permission to install module in drupal.

### 8.3.1. How to add a menu block

You can specify which menu the book should be showing in Drupal. If the specified menu block doesn't exist, Drupal will throw all the imported contents in the primary link. Therefore, if you wish to list your book in a menu block, make sure you create one before importing the book. To add a new menu block, simply login to your Drupal site and go to Administer -> Menus -> Add menu .

- Menu name - The unique name for the menu. This is the value that you should set for the `drupal_menu_block` parameter in `publican.cfg`.

- Title - The title of the menu. It will be displayed on top of the menu block.

### 8.3.2. Setting up Node import

- Import directory - Where the CSV files to be imported are stored. The default path is `sites/default/files/imports/` .

- FTP settings

  - Allow FTP uploads - Make sure the checkbox is checked, so that the new CSV file can be auto-detected when it is uploaded into the `import directory`.

  - File owner - The CSV file that you uploaded to the `import directory` will be assigned ownership to this user.

    Important — File Ownership

    Users will only be allowed to use files they have uploaded themselves and files owned by anonymous. If you leave this field blank, all files uploaded by FTP will be owned by anonymous and so all users will see those files as being available for them. If you enter a username here, files that are uploaded using FTP will be owned by that user and only that user will be able to see those uploaded files. It is recommended to leave this field blank.

- Allowed extensions - The allowed import file's extension. Other extensions will be ignore by the module.

- Default settings

  - Content type - The default content type that will be used for quick import. Make sure the `Book Page content type` is checked.

  - First row contains column names - This tells the node import module that the first row of the csv file is the headers.

### 8.3.3. How to import book

To import book into Drupal:

1. Follow the steps in Sezione 8.1, «How to build a CSV file for Drupal import»

2. Upload the CSV file to `import Directory` in the Drupal Server

3. Upload `en-US` directory to the `"sites/default/files/"` directory in the Drupal server. This value can be overriden in the `publican.cfg`. For more details, please read Sezione 8.2, «Il file publican.cfg»

4. Login to the Drupal website, and go to Administer -> Content management -> Import content. You will see the CSV file that you just uploaded is showing in the 'Pending Tasks" table and it is ready to import.

5. Click Import now to start importing book. You will be redirect to the next page which is showing the import progress. When the progress bar hit 100%, that means the import is done!

6. The book link should be showing in the specified menu block now.

### 8.3.4. How to update book

Simply repeat the steps in Sezione 8.3.3, «How to import book» to update the book.

Warning — Section Chunking

If you update the book with smaller chunks, than the missing chunks will be deleted by Drupal and the URL path for the deleted chunks will be deleted as well.

# Capitolo 9. Frequently Asked Questions

- Domanda: Come si aggiunge una lingua ad un libro?
- Domanda: E se non si specifica il codice di nazione? Per esempio, si può eseguire publican update_po --langs=es,de,fr?
- Domanda: Come si aggiornano tutti i file PO?
- Domanda: Come si ottiene l'elenco completo delle opzioni di build di Publican?
- Domanda: Come si ottiene l'elenco completo dei parametri configurabili nel file publican.cfg?
- Domanda: Dove si trovano i file comuni di Publican?
- Domanda: E' possibile includere nei tarball e nei pacchetti RPM un file qualsiasi?
- Domanda: Perché Publican segnala con warning i tag sconosciuti?
- Domanda: I documenti HTML vengono creati regolarmente, ma provando a creare documenti PDF, si solleva un'eccezione java.lang.NullPointerException senza produzione di file PDF. Cos'è che non va?
- Domanda: Un errore segnala che Batik non è presente nel classpath eppure Batik è installato! Cos'è che non va?
- Domanda: Creando un file PDF si solleva un'eccezione Exception in thread "main" java.lang.OutOfMemoryError: Java heap space. Cos'è che non va?
- Domanda: Versioni precedenti di Publican rimuovevano i tag <para> vuoti. E le versioni di Publican correnti?
- Domanda: Che fine ha fatto il controllo ortografico?
- Domanda: Perché quando si creano file PDF, i tag <segmentedlist> non funzionano?
- Domanda: Come mai, nei PDF, si altera il colore delle immagini?
- Domanda: Creando un documento, si ottiene un errore del tipo ‘undefined language’ — cos'è che non va?
- Domanda: Come abilitare il completamento dei comandi bash per Publican?
- Domanda: Why am I having trouble building my large book?
- Domanda: Perché Jeff chiama Isaac ‘Ivan’?

Domanda:

Come si aggiunge una lingua ad un libro?

Risposta:

Eseguendo il comando publican update_po --langs=codice_linguistico, dove codice_linguistico è il codice della lingua che si vuole aggiungere. Si possono aggiungere più lingue per volta, sperando i codici linguistici con virgole. Per esempio, publican update_po --langs=ja-JP crea la cartella per la lingua giapponese ed i file PO in giapponese, mentre publican update_po --langs=ja-JP,ko-KR crea cartelle e file PO per la lingua giapponese e coreana.

Domanda:

E se non si specifica il codice di nazione? Per esempio, si può eseguire publican update_po --langs=es,de,fr?

Risposta:

Anche così il comando funziona. Tuttavia, se si omette il codice di nazione, il risultato potrebbe essere indefinito nel caso in cui Publican o un brand abbia definizioni per varietà nazionali di una lingua — come nel caso di `zh-CN` (cinese semplificato della Repubblica Popolare Cinese) e `zh-TW` (cinese tradizionale della Repubblica di Cina, o Taiwan). Anche nel caso sia definita correntemente una sola varietà linguista, è sempre opportuno includere anche il codice di nazione, cosicché un futuro aggiornamento di Publican non trasformi inaspettatamente un documento in lingua tedesca (`de-DE`) nel Common Content dello Schweizerdeutsch (`de-CH`) o svizzero tedesco.

Domanda:

Come si aggiornano tutti i file PO?

Risposta:

Eseguendo il comando publican update_po --langs=all.

Domanda:

Come si ottiene l'elenco completo delle opzioni di build di Publican?

Risposta:

Eseguendo il comando publican build --help.

Domanda:

Come si ottiene l'elenco completo dei parametri configurabili nel file `publican.cfg`?

Risposta:

Eseguendo il comando publican help_config in una cartella contenente un documento di Publican.

Domanda:

Dove si trovano i file comuni di Publican?

Risposta:

Per impostazione, nella directory `/usr/share/publican/` nei Sistemi Operativi Linux e in `%SystemDrive%/%ProgramFiles%/publican/Common_Content` nei sistemi operativi Windows — tipicamente, `C:/Program Files/publican/Common_Content`.

Domanda:

E' possibile includere nei tarball e nei pacchetti RPM un file qualsiasi?

Risposta:

Certo. Creando una sotto-cartella denominata `files` nella cartella del linguaggio originale, essa viene inclusa in tutti i tarball o pacchetti SRPM creati da Publican.

Importante

La cartella `files` non è disponibile durante la fase di validazione, per cui non è possibile `xi:include` o inglobare diversamente, i file contenuti in questa cartella nell'XML.

Domanda:

Perché Publican segnala con warning i tag sconosciuti?

Risposta:

Questi warning informano che si sta usando dei tag il cui effetto non è stato testato per attrattiva, conformità a XHTML 1.0 Strict o conformità a Section 508 (Standard d'Accessibilità USA).

Domanda:

I documenti HTML vengono creati regolarmente, ma provando a creare documenti PDF, si solleva un'eccezione `java.lang.NullPointerException` senza produzione di file PDF. Cos'è che non va?

Risposta:

Provare a creare un file PDF con un diverso documento — meglio se con un nuovo documento creato con il comando publican create. Se il problema persiste, allora probabilmente nel sistema in uso, esiste un conflitto tra JRE (Java Runtime Environment) e JDK (Java Development Kit). Se è presente una JDK, FOP richiede che la JDK abbia la stessa versione della JRE. Inoltre, FOP non può usare la GCJ (GNU Compiler for Java).

Eseguire alternatives --config java e alternatives --config javac per determinare la JRE e JDK in uso, poi selezionare le versioni corrispondenti e quelle prive dell'elemento `gcj` nel loro nome. Per esempio, la seguente configurazione Java visualizza una JRE ed una JDK corrispondente che consentono di creare file PDF:

    $ alternatives --config java

    There are 3 programs which provide 'java'.

      Selection    Command
    -----------------------------------------------
       1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
    *  2           /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
     + 3           /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java

    Enter to keep the current selection[+], or type selection number:

    $ alternatives --config javac

    There are 3 programs which provide 'javac'.

      Selection    Command
    -----------------------------------------------
    *+ 1           /usr/lib/jvm/java-1.6.0-openjdk.x86_64/bin/javac
       2           /usr/lib/jvm/java-1.6.0-openjdk/bin/javac
       3           /usr/lib/jvm/java-1.5.0-gcj/bin/javac

    Enter to keep the current selection[+], or type selection number:

Potrebbe essere necessario installare una JDK extra, nel caso non sia presente una JDK corrispondente alle versioni JRE presenti.

Alcune installazioni Java non configurano correttamente gli ambienti con il comando alternatives. Per questo problema non è stata determinata una soluzione.

Domanda:

Un errore segnala che Batik non è presente nel classpath eppure Batik è installato! Cos'è che non va?

Risposta:

Si ritiene che ciò sia dovuto a problemi di classpath causati dall'utilizzo di differenti versioni di JRE e JDK. Fare riferimento alla domanda precedente di questa FAQ, riguardante l'eccezione `java.lang.NullPointerException` ed usare il comando alternatives per assicurarsi di avere JRE e JDK corrispondenti.

Domanda:

Creando un file PDF si solleva un'eccezione `Exception in thread "main" java.lang.OutOfMemoryError: Java heap space`. Cos'è che non va?

Risposta:

The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to FOP. Before running `$` publican build run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.

Domanda:

Versioni precedenti di Publican rimuovevano i tag `<para>` vuoti. E le versioni di Publican correnti?

Risposta:

No. Publican nel passato, rimuoveva i tag `<para>` vuoti durante la trasformazione dei file XML, in quanto i tag `<para>` vuoti creavano problemi agli strumenti di traduzione usati in precedenza in Red Hat e nel Fedora Project. Tag `<para>` vuoti, sono tag validi in DocBook XML ed ora non vengono più rimossi da Publican.

Domanda:

Che fine ha fatto il controllo ortografico?

Risposta:

Precedenti versioni di Publican (fino alla versione 0.45, inclusa) eseguivano un controllo ortografico durante la trasformazione dei file XML. In seguito ai giudizi negativi degli utenti, questa funzione è stata rimossa.

Eseguire il seguente script bash nella cartella radice del documento, per controllare l'ortografia nei file XML con aspell, un controllore ortografico da riga di comando.

    #!/bin/sh
    # Jeff Fearn 2010

    ASPELL_EXCLUDES=programlisting,userinput,screen,filename,command,computeroutput,abbrev,accel,orgname,surname,foreignphrase,acronym,hardware

    for file in `find en-US -wholename '*/extras/*' -prune -o -name \*.xml -print`; do
    	echo "Processing $file";
    	aspell --list --lang=en-US --mode=sgml --add-sgml-skip={$ASPELL_EXCLUDES} < $file  | sort -u;
    	echo;
    done

Domanda:

Perché quando si creano file PDF, i tag `<segmentedlist>` non funzionano?

Risposta:

Contare il numero di colonne presenti nei tag `<segmentedlist>`. Se i `<segmentedlist>` sono formattati come tabelle, l'XSL di DocBook limita il numero delle colonne a due soltanto, e Publican formatta i `<segmentedlist>` come tabelle.

Domanda:

Come mai, nei PDF, si altera il colore delle immagini?

Risposta:

Ciò è dovuto ad un bug in FOP che distorce i colori nelle immagini PNG a 24-bit. Convertire le immagini, in immagini PNG a 32-bit per circuire questo problema.

Domanda:

Creando un documento, si ottiene un errore del tipo ‘undefined language’ — cos'è che non va?

Risposta:

In Publican l'evidenza del codice è generato con il modulo Perl, Syntax::Highlight::Engine::Kate. Se in un tag `<programlisting>` si specifica un linguaggio non riconosciuto da Syntax::Highlight::Engine::Kate, in fase di creazione del libro si riceve un errore. Le prime righe del messaggio d'errore sono simili a:

    undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm
    line 615.
    cannot create plugin for language 'JAVA'

Notare che il modulo Syntax::Highlight::Engine::Kate è molto rigoroso con i nomi dei linguaggi ed è case sensitive. Quindi, `<programlisting language="Java">` funziona, ma `<programlisting language="java">` e `<programlisting language="JAVA">` non funzionano. Il messaggio d'errore specifica il problema relativo all'attributo del linguaggio.

Refer to http://search.cpan.org/dist/Syntax-Highlight-Engine-Kate/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS for the full list of languages that Syntax::Highlight::Engine::Kate supports, including their expected capitalization and punctuation.

Domanda:

Come abilitare il completamento dei comandi bash per Publican?

Risposta:

Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:

1. Installare il pacchetto o i pacchetti che offrono il completamento dei comando bash per il proprio sistema operativo. Per esempio, in Fedora, eseguire il comando sudo yum install bash-completion.

2. Aggiungere al proprio file `~/.bashrc`:

       # Use bash-completion, if available
       if [ -f /etc/bash_completion ]; then
               . /etc/bash_completion
       fi

3. Riavviare il terminale o eseguire source ~/.bashrc.

Domanda:

Why am I having trouble building my large book?

Risposta:

Probably because the kernel can deal with only a certain number of file handles at a time, and you have exceeded that number. On some linuxes you can run ulimit -n 8192 to change the limit for the current shell.

To make this permanent, open `/etc/security/limits.conf` and add these two lines:

    *                 soft    nofile          8192
    *                 hard    nofile          8192

Then save, and log in again for the changes to take effect.

Domanda:

Perché Jeff chiama Isaac ‘Ivan’?

Risposta:

Perché la memoria di Jeff è in mutande!

# Elementi ed attributi non permessi

Supportato, non supportato e non permesso

Non tutti gli elementi (tag) ed attributi che funzionano con Publican sono supportati. Nello specifico, non tutti i tag sono stati testati riguardo agli effetti sulla presentazione di un documento in formato HTML o PDF.

Publican funziona con quasi tutti gli elementi e relativi attributi di DocBook 4.5, la maggior parte dei quali sono supportati. Gli elementi ed attributi supportati sono quelli la cui presentazione in HTML e PDF di Publican sono stati testati e conservano un livello di qualità accettabile.

Altri elementi ed attributi non riconosciuti dannosi o ridondanti, ma che non sono stati testati per qualità sono non supportati. Se il contenuto all'interno di un particolare tag DocBook non viene visualizzato correttamente in un documento HTML o PDF, il problema può derivare da una mancanza di test sulla logica di trasformazione del relativo tag. Provare a ricreare il documento e controllare l'output generato da Publican durante la creazione del documento. Publican presenta avvisi sui tag non supportati man mano che vengono elaborati i file XML.

Infine, un ristretto gruppo di elementi ed attributi sono non permessi. Questi elementi ed attributi sono elencati in basso, accompagnati da una spiegazione del motivo del divieto.

Usare il comando publican print_known per visualizzare l'elenco dei tag supportati da Publican, ed il comando publican print_banned per visualizzare l'elenco dei tag non permessi in Publican.

## A.1. Discouraged elements

`<glossdiv>`

  Questo tag presenta i termini nei glossari in ordine alfabetico; tuttavia, i termini vengono ordinati secondo la lingua originale dell'XML, a prescindere se i termini siano tradotti in altre lingue. Per esempio, un glossario prodotto con `<glossdiv>` che in lingua inglese appare come:

  A

    `Apple` — an apple is…

  G

    `Grapes` — grapes are…

  O

    `Orange` — an orange is…

  P

    `Peach` — a peach is…

  in italiano appare come:

  A

    `Mela` — una mela è…

  G

    `Uva` — l'uva è…

  O

    `Arancia` — un'arancia è…

  P

    `Pera` — la pera è…

  Quindi tradotto in una lingua che non condivide lo stesso sistema di scrittura della lingua originale in cui è redatto l'XML, il risultato del tag è privo di senso.

`<inlinegraphic>`

  Questo elemento presenta le informazioni contenute in un oggetto grafico, privo di una opzione per una presentazione alternativa in modalità testuale. Perciò questo tag limita l'accesso alle informazioni alle persone con ridotte capacità visive. Negli Stati in cui vige una legislazione che garantisce l'accessibilità ai contenuti elettronici alle persone con ridotte capacità visive, i documenti contenenti questo tag quindi non soddisfano queste richieste. La Section 508 del Rehabilitation Act of 1973[4] è un esempio di tali richieste predisposte alle Agenzie Federali degli Stati Uniti d'America.

  Notare che il tag `<inlinegraphic>` non è valido in DocBook versione 5.

`<olink>`

  The `<olink>` tag provides cross-references between XML documents. For `<olink>`s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use `<olink>`s, these URLs can be supplied either as an XML entity or with a server-side script. Publican does not provide any way to build or use a database for these links.

## A.2. Attributi non permessi

`<[element] xreflabel="[ogni_altra_stringa]">`

  La presenza di un attributo `<xreflabel>` riduce l'usabilità delle versioni stampate di un libro. Inoltre, i valori dell'attributo non sono visibili ai traduttori, e perciò non sono traducibili.

  Per esempio, il seguente pezzo:

      <chapter id="ch03" xreflabel="Chapter Three">
      	<title>The Secret to Eternal Life</title>
      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      …see <xref linkend="ch03"> for details.

  durante la trasformazione in HTML del file XML, il tag `<xref>` diventa un tag anchor, come indicato di seguito:

      …see <a href="#ch03">Chapter Three</a> for details.

  Il testo contenuto nel tag anchor coincide con quello nell'attributo `<xreflabel>`. In questo caso, ciò vuol dire che i lettori delle versioni stampate hanno una perdita di informazione.

  Per evitare questo problema si può far coincidere il valore dell'attributo `<xreflabel>` con il testo contenuto tra i tag `<title>``</title>`. Tuttavia questa duplicazione aumenta il rischio di errori di battitura, senza in effetti alcun miglioramento. E riduce anche la quantità di informazione presentata ai lettori delle copie stampate.

  Il seguente XML:

      <chapter id="ch03" xreflabel="The Secret to Eternal Life">
      	<title>The Secret to Eternal Life</title>
      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      …see >xref linkend="ch03"> for details.

  viene trasformato in tag anchor HTML come segue:

      …see <a href="#ch03">The Secret to Eternal Life</a> for details.

  Ciò non è così informativo come il testo presentato senza usare l'attributo `<xreflabel>`. Il seguente:

      <chapter id="ch03">
      	<title>The Secret to Eternal Life</title>
      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      …see <xref linkend="ch03"> for details.

  trasforma l'elemento `<xref>` come segue in formato HTML:

      …see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.

  Comunque, ancora più importanti, sono i problemi di traduzione causati dal tag `<xreflabel>`. I valori degli attributi non sono visibili ai traduttori. Di conseguenza, non possono essere tradotti. Si consideri di nuovo il secondo esempio, di cui sopra:

      <chapter id="ch03" xreflabel="The Secret to Eternal Life">
      	<title>The Secret to Eternal Life</title>
      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      …see <xref linkend="ch03"> for details.

  In inglese, `<xref>` è ancora trasformato in un tag anchor come segue:

      …see <a href="#ch03">The Secret to Eternal Life</a> for details.

  Mentre i lettori della versione in lingua tedesca, visualizzeranno il seguente HTML:

      …Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.

  Rimuovendo l'attributo `<xreflabel>`, i tag del titolo e del capitolo, appaiono propriamente tradotti al lettore. Cioè il seguente pezzo:

      <chapter id="ch03">
      	<title>The Secret to Eternal Life</title>
      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      …see <xref linkend="ch03"> for details.

  per una traduzione in lingua tedesca, viene visualizzato come:

      …Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.

  E ciò, senza meravigliarsi più di tanto, è ciò che si vuole ottenere!

  Quindi l'attributo `xreflabel` è vietato.

`<[element] endterm="[any_string_here]">`

  L'attributo `endterm` permette di presentare il testo relativo all'ipertesto con un nome diverso dalla sezione o capitolo cui punta il collegamento. E ciò riduce l'usabilità della versione stampata del documento e genera difficoltà anche ai traduttori.

  Il testo presentato in un elemento (come un `<xref>`), contenente l'attributo `endterm` è ricavato dal tag `<titleabbrev>` nel capitolo o sezione target. Sebbene il contenuto del tag `<titleabbrev>` sia traducibile nei file PO del documento, esso viene di fatto rimosso dal contesto del tag `<xref>`. L'assenza di questo contesto rende praticamente impossibile la traduzione di articoli e preposizioni, preservando genere e numero.

  Per esempio, il seguente pezzo:

      <chapter id="The_Secret">
      	<title>The Secret to Eternal Life</title>
      	<titleabbrev id="final">the final chapter</titleabbrev>

      	<para>The secret to eternal life is…</para>
      </chapter>

      [more deathless prose here]

      The solution is in <xref linkend="The_Secret" endterm="final"/>.

  Come si vede, il testo che precede il tag `<xref>` presente nella versione inglese del documento è:

  > The solution is in `the final chapter`.

  Un traduttore vede il tag `<titleabbrev>` nel file PO come:

      #. Tag: titleabbrev
      #, no-c-format
      msgid "the final chapter"
      msgstr ""

  e vede il testo contenuto in `<xref>` in qualche altra parte del file PO (o, addirittura in un PO completamente diverso), come:

      #. Tag: para
      #, no-c-format
      msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
      msgstr ""

  Il traduttore non ha idea di come verrà sostituito il tag `<xref linkend="The_Secret" endterm="final"/>` durante la creazione del documento, per cui una traduzione in italiano potrebbe leggersi come:

      #. Tag: para
      #, no-c-format
      msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
      msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."

  Notare la preposizione `in`.

  Se il traduttore di lingua italiana traduce `the final chapter` in `l'ultimo capitolo`, il documento risultante si leggerebbe come:

  > La soluzione è in `l'ultimo capitolo`.

  Il risultato è comprensibile, ma poco elegante, per l'assenza di combinazione tra preposizione ed articolo. Una traduzione più elegante sarebbe stata:

  > La soluzione è nell'`ultimo capitolo`.

  Senza conoscere il testo che compare al posto di <xref linkend="The_Secret" endterm="final"/>, il traduttore in italiano non sa se usare la preposizione `in` invariata, o una delle sette possibili combinazioni con l'articolo determinativo: `nel`, `nei`, `nello`, `nell'`, `negli`, `nella` o `nelle`.

  Inoltre, notare che la combinazione della preposizione con l'articolo pone anche una problema se inserire la preposizione articolata nel tag `<xref>` o nel tag `<titleabbrev>`. E comunque qualunque sia la soluzione scelta dal traduttore, ulteriori problemi si verificano quando l'`endterm` è presente in altri contesti grammaticali, poiché sarebbe richiesta un'altra preposizione articolata.

  A causa di queste difficoltà, in fase di traduzione di `endterm`, Publican non permette l'uso di questo attributo.

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

# Sommario dei comandi

## B.1. Opzioni di comando

--allow_network

  Allow the XML and XSLT processing to access the network. Defaults off.

--brand_dir=s

  Directory to source brand files from.

--common_config=s

  Override path to Common_Config directory

--common_content=s

  Override path to Common_Content directory

--config=s

  Use a nonstandard config file

--help

  Display help message

--nocolours

  Disable ANSI colourisation of logging.

--quiet

  Disable all logging.

## B.2. Command actions

`$` publican add_revision

  Add an entry to the revision history

  --date=DATE

    Date to use for a revision.

  --email=EMAIL

    email to use for a revision.

  --firstname=FIRSTNAME

    firstname to use for a revision.

  --lang=LANG

    The language the XML will be written in

  --member=MEMBER

    An entry to be added to the revision. Can be specified multiple times.

  --revnumber=REVNUMBER

    Revision number to use for a revision.

  --surname=SURNAME

    surname to use for a revision.

`$` publican build

  Transform XML to other formats (pdf, html, html-single, drupal-book, etc)

  --distributed_set

    This flag tells publican the data being processed is a distributed set. Note: do not use distributed_set on the command line. Publican uses this flag when calling itself to process distributed sets. This is the only safe way this flag can be used.

  --embedtoc

    Embed the web site TOC object in the generated HTML

  --formats=FORMATS

    Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub

  --langs=LANGS

    Comma-separated list of languages, for example: en-US,de-DE,all

  --novalid

    Do not run the DTD validation

  --pdftool=PDFTOOL

    Override the tool to use when creating PDFs. Valid options are wkhtmltopdf and fop.

  --pub_dir=PUB_DIR

    Directory to publish files to. Defaults to publish.

  --publish

    Set up built content for publishing

  --showfuzzy

    Show fuzzy translation entries in output. Defaults off.

  --src_dir=SRC_DIR

    Directory to source publican files from.

`$` publican clean

  Remove all temporary files and directories

  --pub_dir=PUB_DIR

    Directory to publish files to. Defaults to publish.

`$` publican clean_ids

  Run clean ids for source XML

`$` publican clean_set

  Remove local copies of remote set books

`$` publican copy_web_brand

  Copy a brand's installed web content to another site

  --brand=BRAND

    The brand to use

  --old_site_config=OLD_SITE_CONFIG

    WebSite configuration file to use when copying content between sites.

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican create

  Create a new book, set, or article

  --brand=BRAND

    The brand to use

  --dtdver=DTDVER

    The version of the DocBook DTD to use

  --edition=EDITION

    The edition of the book, article, or set

  --lang=LANG

    The language the XML will be written in

  --name=NAME

    The name of the book, article, set, or brand

  --product=PRODUCT

    The name of the product

  --type=TYPE

    The type (book, article, or set)

  --version=VERSION

    The version of the product

`$` publican create_brand

  Create a new brand

  --lang=LANG

    The language the XML will be written in

  --name=NAME

    The name of the book, article, set, or brand

`$` publican create_site

  Create a new WebSite in the supplied location.

  --db_file=DB_FILE

    Override default database file.

  --lang=LANG

    The language the XML will be written in

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

  --tmpl_path=TMPL_PATH

    Override the default template path.

  --toc_path=TOC_PATH

    Override the default TOC path.

`$` publican help_config

  Display help text for the configuration file

`$` publican install_book

  Install a book in to a WebSite.

  --lang=LANG

    The language the XML will be written in

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican install_brand

  Install a brand to the supplied location

  --path=PATH

    /path/to/install/to

  --pub_dir=PUB_DIR

    Directory to publish files to. Defaults to publish.

  --web

    Install the web content for a brand.

`$` publican lang_stats

  report PO statistics

  --lang=LANG

    The language the XML will be written in

`$` publican migrate_site

  Migrate a website DataBase from Publican < 3 to Publican 3.

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican package

  Package a language for shipping

  --binary

    Build binary rpm when running package

  --brew

    Push SRPM to brew

  --desktop

    Create desktop instead of web package

  --lang=LANG

    The language the XML will be written in

  --pub_dir=PUB_DIR

    Directory to publish files to. Defaults to publish.

  --scratch

    Use scratch instead of tag build

  --short_sighted

    Create package without using version in package name

  --wait

    Wait for brew to finish building

`$` publican print_banned

  Print a list of banned DocBook tags

`$` publican print_known

  Print a list of QA'd DocBook tags

`$` publican print_tree

  Print a tree of the xi:includes

`$` publican print_unused

  Print a list of unused XML files

`$` publican print_unused_images

  Print a list of unused Image files

`$` publican remove_book

  Remove a book from a WebSite.

  --lang=LANG

    The language the XML will be written in

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican rename

  Rename a publican book

  --name=NAME

    The name of the book, article, set, or brand

  --product=PRODUCT

    The name of the product

  --version=VERSION

    The version of the product

`$` publican report

  Print a readability report for the source text.

`$` publican site_stats

  Report on the contents of a WebSite

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican trans_drop

  Snapshot the source language for use in translation.

`$` publican update_db

  Add or remove database entries. Used for processing pre-build books, such as when building packages.

  --abstract=ABSTRACT

    Abstract for a book

  --add

    Add a database entry

  --book_src_lang=BOOK_SRC_LANG

    The language this translation is based on.

  --book_version=BOOK_VERSION

    The version number of the book being installed.

  --del

    Delete a database entry

  --formats=FORMATS

    Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub

  --lang=LANG

    The language the XML will be written in

  --name=NAME

    The name of the book, article, set, or brand

  --name_label=NAME_LABEL

    name label for a book

  --product=PRODUCT

    The name of the product

  --product_label=PRODUCT_LABEL

    product label for a book

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

  --sort_order=SORT_ORDER

    Order to sort a book

  --subtitle=SUBTITLE

    Sub title for a book

  --version=VERSION

    The version of the product

  --version_label=VERSION_LABEL

    version label for a book

`$` publican update_po

  Update the PO files

  --email=EMAIL

    email to use for a revision.

  --firstname=FIRSTNAME

    firstname to use for a revision.

  --langs=LANGS

    Comma-separated list of languages, for example: en-US,de-DE,all

  --msgmerge

    Use gettext's msgmerge for POT/PO merging.

  --previous

    Keep previous msgid when fuzzy matches are detected in PO updates.

  --surname=SURNAME

    surname to use for a revision.

`$` publican update_pot

  Update the POT files

`$` publican update_site

  Update an existing sites templates.

  --site_config=SITE_CONFIG

    WebSite configuration file to use or create.

`$` publican zt_pull

  Pull translations from Zanata.

`$` publican zt_push

  Push translations to Zanata.

# Configuration summary

## C.1. General options

These are set in the books or brands configuration files.

arch

  Arch to filter output on.

Pubblico

  audience to filter output on.

books

  A space-separated list of books used in this remote set.

brand

  The brand to use when building this package.

  The default value for this parameter is: common

brew_dist

  The brew dist to use for building the standalone desktop rpm.

  The default value for this parameter is: docs-5E

  Avvertimento

  This field is deprecated and will be removed from Publican in the future.

bridgehead_in_toc

  Display bridge head elements in the TOCs?

  The default value for this parameter is: 0

chunk_first

  For HTML, should the first section be on the same page as its parent?

  The default value for this parameter is: 0

chunk_section_depth

  For HTML, what is the deepest level of nesting at which a section should be split onto its own page?

  The default value for this parameter is: 4

classpath

  Path to jar files for FOP.

  The default value for this parameter is: /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

  Path to publican content.

  The default value for this parameter is: /usr/share/publican

common_content

  Path to publican common content.

  The default value for this parameter is: /usr/share/publican/Common_Content

condition

  Conditions on which to prune XML before transformation.

confidential

  Is the content confidential?

  The default value for this parameter is: 0

confidential_text

  The text used to indicate content is confidential.

  The default value for this parameter is: CONFIDENTIAL

conformance

  conformance to filter output on.

debug

  Print out extra messages?

  The default value for this parameter is: 0

doc_url

  URL for the documentation team for this package. Used for top right URL on HTML.

  The default value for this parameter is: https://fedorahosted.org/publican

docname

  Name of this document. Fetched from title tag in xml_lang/TYPE_Info.xml if not set in cfg file.

  This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$

  Suggerimento

  This field is not supported for: brand.

drupal_author

  The author name to be shown in drupal book page. It must be a valid drupal username.

  The default value for this parameter is: Publican

drupal_image_path

  The directory where the image should be stored in drupal server.

  The default value for this parameter is: /sites/default/files/documentation/

drupal_menu_block

  The menu where we can find the book.

  The default value for this parameter is: user-guide

drupal_menu_title

  Override the bookname that will be shown in the drupal menu.

dt_format

  The format to use for the desktop output.

  The default value for this parameter is: html-desktop

dt_obsoletes

  Space-separated list of packages the desktop RPM obsoletes.

dt_requires

  Space-separated list of packages the desktop RPM requires.

dtdver

  Version of the DocBook DTD on which this project is based.

  The default value for this parameter is: 4.5

ec_id

  Eclipse plugin ID. Defaults to "$product.$docname"

ec_name

  Eclipse plugin name. Defaults to "$product $docname"

ec_provider

  Eclipse plugin provider. Defaults to "Publican-v4.2.2"

extras_dir

  Directory where images are located.

  The default value for this parameter is: extras

generate_section_toc_level

  Generate table of contents down to the given section depth.

  The default value for this parameter is: 0

ignored_translations

  Languages to replace with xml_lang regardless of translation status.

img_dir

  Directory where images are located.

  The default value for this parameter is: images

info_file

  Override the default Info file.

lang

  lang to filter output on.

license

  License this package uses.

  The default value for this parameter is: GFDL

mainfile

  The name of the main xml and ent files for this book, sans file extension and language. Fetched from docname if not set.

menu_category

  Semicolon-separated list of menu categories for the desktop package.

os

  os to filter output on.

os_ver

  The OS for which to build packages.

pdf_body_font

  The font to use for body text in PDFs.

  The default value for this parameter is: Liberation Sans

pdf_mono_font

  The font to use for mono text in PDFs.

  The default value for this parameter is: Liberation Mono

prod_url

  URL for the product. Used in top left URL in HTML.

  The default value for this parameter is: https://fedorahosted.org/publican

prodotto

  Product this package covers. Fetched from productname tag in xml_lang/TYPE_Info.xml

  This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$

  Suggerimento

  This field is not supported for: brand.

repo

  Repository from which to fetch remote set books.

rev_dir

  By default Revision History is sorted in descending order. Set this to 'asc' or 'ascending' to reverse the sort.

rev_file

  Override the default Revision History file.

Revisione

  revision to filter output on.

revisionflag

  revisionflag to filter output on.

role

  role to filter output on.

scm

  Type of repository in which books that form part of a remote set are stored. Supported types: SVN, GIT.

security

  security to filter output on.

show_remarks

  Display remarks in transformed output.

  The default value for this parameter is: 0

sort_order

  Override the default sort weighting. Defaults to 50.

src_url

  URL to find tar of source files. Used in RPM Spec files.

stato

  status to filter output on.

tmp_dir

  Directory to use for building.

  The default value for this parameter is: tmp

toc_section_depth

  Depth of sections to include in the main table of contents.

  The default value for this parameter is: 2

txt_formater

  Choose the formatter to use when creating txt output.

  The default value for this parameter is: default

  This parameter is constrained with the following regular expression: ^(links{1}|tables{1}|default)$

type

  Type of content this package contains. Supported: set, book, article, brand

  The default value for this parameter is: Book

userlevel

  userlevel to filter output on.

vendor

  vendor to filter output on.

version

  Version of this package. Fetched from productnumber tag in xml_lang/TYPE_Info.xml

  This parameter is constrained with the following regular expression: ^[0-9][^\p{IsSpace}]*$

web_brew_dist

  The brew dist to use for building the web rpm.

  The default value for this parameter is: docs-5E

web_formats

  A comma-separated list of the formats to use for the web packages.

  The default value for this parameter is: html,html-single,pdf,epub

web_home

  This is a home page for a Publican-generated website, not a standard book.

  Avvertimento

  web_home is deprecated and will be removed from Publican in the future. Use "web_type: home" instead.

web_host

  This is a host name for a Publican-generated website, used for searches and the Sitemap. Be sure to include the full path to your document tree. E.g. if your documents are in the docs directory: http://www.example.com/docs

  Avvertimento

  web_host is deprecated and will be removed from Publican in the future. Use "host" in the web site configuration file instead.

web_name_label

  Override the book name, bottom level, menu label on a Publican website.

web_obsoletes

  Packages to obsolete in web RPM.

web_product_label

  Override the product, top level, menu label on a Publican website.

web_search

  Override the default search form for a Publican website. By default this will use Google search and do a site search if web_host is set.

  Avvertimento

  web_search is deprecated and will be removed from Publican in the future. Use "search" in the web site configuration file instead.

web_type

  This is a special page for a Publican-generated website, not a standard book. Valid types are home, product, and version.

  This parameter is constrained with the following regular expression: ^(home|product|version)$

web_version_label

  Override the version, middle level, menu label on a Publican website. To hide this menu item set this to: UNUSED

wkhtmltopdf_opts

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

wordsize

  wordsize to filter output on.

xml_lang

  Language in which XML is authored.

  The default value for this parameter is: en-US

## C.2. Brand options

These are set in the brands configuration files.

banned_attrs

  A comma-separated list of XML attributes that are not permitted in the source.

banned_tags

  A comma-separated list of XML tags that are not permitted in the source.

base_brand

  The base brand to use for this brand.

  The default value for this parameter is: common

dtd_type

  Override Type for DocType. Must be a complete string.

dtd_uri

  Override URI for DocType. Must be a complete string.

no_embedtoc

  Brand option to disable embedding the navigational toc in web packages

web_cfg

  Full path for the publican site configuration file for non standard RPM websites.

web_dir

  Install path for non standard RPM websites.

web_req

  Name of site package for non standard RPM websites. Required to ensure the site is installed.

## C.3. Site options

These are set in the sites configuration file.

db_file

  The name of the SQLite database file for your site, with the filename extension .db

debug

  Output extra messages when running publican.

  The default value for this parameter is: 0

def_lang

  The default language for this website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available.

  The default value for this parameter is: en-US

dump

  Dump the publican database to an XML file.

dump_file

  The name of the file to dump the publican database to.

  The default value for this parameter is: /var/www/html/DUMP.xml

footer

  HTML to inject in to the footer of every page on the website.

  The default value for this parameter is:

host

  The web host, may be a full URI or a relative path.

  The default value for this parameter is: /docs

manual_toc_update

  Stop publican from automatically rebuilding teh web site everytime a book is installed, updated or removed.

  The default value for this parameter is: 0

search

  The HTML to inject in as the site serach.

  The default value for this parameter is: Google site search

title

  Title used for all site navigation pages.

  The default value for this parameter is: Documentation

tmpl_path

  Full path to the template directory.

  The default value for this parameter is: /usr/share/publican/templates

toc_js

  The source file to use for JavaScript functionality.

  The default value for this parameter is: default.js

toc_path

  The path to the directory in which to create the top-level index.html file.

toc_type

  Template to use for generagting the web style 1 toc file.

  The default value for this parameter is: toc

  Avvertimento

  This field is deprecated and will be removed from Publican in the future.

web_style

  Publican supports mutliple base styles for websites, this picks one.

  The default value for this parameter is: 1

  This parameter is constrained with the following regular expression: [1-2]

  Avvertimento

  This field is deprecated and will be removed from Publican in the future.

zip_dump

  Zip up the dump file after dumping it

  The default value for this parameter is: 0

# Contenuto del file dump di un sito

Il file dump di un sito web generato da Publican contiene i dettagli di alcune configurazioni di base, insieme con i dettagli di ogni documento pubblicato sul sito. I dettagli di configurazione del sito sono:

`<host>`

  L'URL alla radice del sito di documentazione, come impostato dal parametro `host`, nel file di configurazione del sito.

`<def_lang>`

  La lingua predefinita della documentazione sul sito web, come impostato dal parametro `def_lang`, nel file di configurazione del sito.

Ogni documento, in ogni lingua, in ogni formato ha un record separato. Questi record contengono i seguenti dati:

`<name>`

  Il titolo del documento, generato dal tag `<title>` in `Book_Info.xml`, `Article_Info.xml` o `Set_Info.xml`, superato dal parametro `docname` nel file `publican.cfg`. Ogni spazio presente nel titolo è sostituito con un carattere trattino basso.

`<ID>`

  Un numero ID unico per il documento, in un certo formato e lingua.

`<abstract>`

  Una breve descrizione generale del contenuto del documento, generato dal tag `<abstract>` in `Book_Info.xml`, `Article_Info.xml` o `Set_Info.xml`. Publican usa questo stesso contenuto per generare la sezione `%description` del file spec, usato per creare il pacchetto RPM di un documento. Se l'`<abstract>` è tradotto, questo campo contiene il testo tradotto.

`<format>`

  Il formato in cui il documento è prodotto — `html` per html in pagine multiple, `html-single` per html in pagina singola, `pdf` per PDF ed `epub` per EPUB.

`<language>`

  Il codice linguistico per il documento. Fare riferimento all'Appendice F, Codici di lingua, per maggiori informazioni su questi codici in XML.

`<name_label>`

  Il nome del documento che appare nella tabella dei contenuti del sito. Il nome può essere impostato con il parametro `web_name_label` nel file `publican.cfg` del documento. Diversamente, il campo è vuoto per un documento in lingua originale o contiene il titolo del documento tradotto. Ogni spazio presente nel nome è sostituito con il carattere trattino basso.

`<product>`

  Il prodotto descritto dal documento, generato dal tag `<productname>` in `Book_Info.xml`, `Article_Info.xml` o `Set_Info.xml`, se non generato dal parametro `product` nel file `publican.cfg`. Ogni spazio presente nel nome è sostituito con il carattere trattino basso.

`<product_label>`

  Il nome del prodotto che appare nella tabella dei contenuti del sito. Il nome può essere impostato con il parametro `web_product_label` nel file `publican.cfg` del documento. Diversamente, il campo è vuoto per un documento in lingua originale o contiene il titolo del documento tradotto. Ogni spazio presente nel nome è sostituito con il carattere trattino basso.

  Se il nome di prodotto è impostato con `UNUSED`, non viene visualizzata alcuna intestazione nella tabella dei contenuti del sito.

`<subtitle>`

  Un'unica riga descrittiva del contenuto del documento, generato dal tag `<subtitle>` in `Book_Info.xml`, `Article_Info.xml` o `Set_Info.xml`. Publican usa questo stesso contenuto per generare la sezione `Summary` del file spec, usato per creare il pacchetto RPM di un documento. Se il `<subtitle>` è tradotto, questo campo contiene il testo tradotto.

`<update_date>`

  La data di più recente installazione del documento, sul sito, nel formato YYYY-MM-DD.

`<version>`

  La versione del prodotto descritto dal documento (non la versione del documento), generata dal tag `<productnumber>` in `Book_Info.xml`, `Article_Info.xml` o `Set_Info.xml`, se non generata dal parametro `version` nel file `publican.cfg`.

`<version_label>`

  La versione del prodotto che compare nella tabella dei contenuti del sito. La versione può essere impostata con il parametro `web_version_label` nel file `publican.cfg` del documento.

  Se la versione è impostata con `UNUSED`, non viene visualizzata alcuna intestazione per questa versione del prodotto, nella tabella dei contenuti del sito.

Esempio D.1. Record d'esempio da un file `DUMP.xml`

Questi due record da un file `DUMP.xml`, visualizzano lo stesso libro, Red Hat Enterprise Linux 5 Installation Guide, in due formati e due lingue differenti — una versione PDF in lingua inglese ed una versione HTML multi-pagine, in lingua francese.

      <record>
        <name>Installation_Guide</name>
        <ID>22</ID>
        <abstract>This manual explains how to boot the Red Hat Enterprise Linux 5 installation program (anaconda) and to install Red Hat Enterprise Linux 5 on 32-bit and 64-bit x86 systems, 64-bit POWER systems, and IBM System z. It also covers advanced installation methods such as kickstart installations, PXE installations, and installations over VNC. Finally, it describes common post-installation tasks and explains how to troubleshoot installation problems.</abstract>
        <format>pdf</format>
        <language>en-US</language>
        <name_label>Installation_Guide</name_label>
        <product>Red_Hat_Enterprise_Linux</product>
        <product_label>Red_Hat_Enterprise_Linux</product_label>
        <subtitle>Installing Red Hat Enterprise Linux 5 for all architectures</subtitle>
        <update_date>2010-10-07</update_date>
        <version>5</version>
        <version_label></version_label>
      </record>
      <record>
        <name>Installation_Guide</name>
        <ID>149</ID>
        <abstract>Ce manuel explique comment lancer le programme d'installation Red Hat Enterprise Linux 5 et comment installer Red Hat Enterprise Linux 5 sur les systèmes x86 32-bit et 64-bit, sur les systèmes POWER 64-bit, et sur les systèmes IBM System z. Il couvre aussi des méthodes d'installation avancées telles que les installations kickstart, PXE, et les installations au moyen de VNC. Finalement, ce manuel décrit les tâches communes post-installation et explique comment résoudre les problèmes liés à une installation.</abstract>
        <format>html</format>
        <language>fr-FR</language>
        <name_label>Guide_d'installation</name_label>
        <product>Red_Hat_Enterprise_Linux</product>
        <product_label>Red_Hat_Enterprise_Linux</product_label>
        <subtitle>Installation de Red Hat Enterprise Linux 5 pour toutes les architectures</subtitle>
        <update_date>2010-10-19</update_date>
        <version>5</version>
        <version_label></version_label>
      </record>

## D.1. Ricavare gli URL dai file dump

Usando i seguenti campi, si può ricavare l'URL di ogni documento sul sito:

- `<host>`

- `<name>`

- `<format>`

- `<language>`

- `<product>`

- `<version>`

HTML multi-pagine

  `<host>`/`<language>`/`<product>`/`<version>`/`<format>`/`<name>`/`index.html`

  Per esempio, `http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html`

HTML singola-pagina

  `<host>`/`<language>`/`<product>`/`<version>`/`<format>`/`<name>`/`index.html`

  Per esempio, `http://docs.fedoraproject.org/en-US/Fedora/14/html-single/Accessibility_Guide/index.html`

PDF

  `<host>`/`<language>`/`<product>`/`<version>`/`<format>`/`<name>`/`<product>`-`<version>`-`<name>`-`<language>`.`pdf`

  Per esempio, `http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.pdf`

EPUB

  `<host>`/`<language>`/`<product>`/`<version>`/`<format>`/`<name>`/`<product>`-`<version>`-`<name>`-`<language>`.`epub`

  Per esempio, `http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub`

Notare che i campi `<product_label>`, `<version_label>` e `<name_label>` sono privi di significato per gli URL, anche quando sono esplicitamente rimossi dalla tabella dei contenuti con l'impostazione `UNUSED`.

# File spec d'esempio per il pacchetto desktop-menu

Il seguente file spec è un esempio di come creare un pacchetto RPM contenente un file di >desktop entry (file `.directory`) ed un file di desktop menu (file `.menu`). Fare riferimento alla Sezione 4.8.1.3, «Voci nel menu del desktop per i documenti», per la struttura di questi file.

Questo esempio assume che si sia creato un file desktop-entry, `menu-example.directory` ed un file desktop-menu, `menu-example.menu`, con un file `README` localizzati in una cartella di nome `menu-example-0`, archiviata come `menu-example-0.tgz`.

Una volta creato, il pacchetto risultante avrà nome menu-example.

    Name:		menu-example
    Version:	0
    Release:	8%{?dist}.t1
    Summary:	Example of how to do a documentation menu package
    Group:		Development/Tools
    License:	GPLv2+
    URL:		http://engineering.redhat.com
    Source0:	%{name}-%{version}.tgz
    BuildRoot:	%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
    BuildArch:      noarch

    %description
    Example of how to do a documentation menu package

    %prep
    %setup -q

    %build

    %install
    rm -rf %{buildroot}
    mkdir -p $RPM_BUILD_ROOT%{_datadir}/desktop-directories
    mkdir -p $RPM_BUILD_ROOT/etc/xdg/menus/settings-merged

    install -m644 menu-example.directory $RPM_BUILD_ROOT%{_datadir}/desktop-directories/menu-example.directory
    install -m644 menu-example.menu $RPM_BUILD_ROOT%{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

    %{_fixperms} $RPM_BUILD_ROOT/*

    %clean
    rm -rf %{buildroot}

    %files
    %defattr(-,root,root,-)
    %doc README
    %{_datadir}/desktop-directories/menu-example.directory
    %config(noreplace) %{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

    %changelog
    * Tue Nov 23 2010 Jeff Fearn <jfearn@redhat.com> 0-8
    - Creation

# Codici di lingua

Subtag di nazione

L'unica parte del tag linguistico XML, obbligatorio in Publican, è il subtag linguistico. Tuttavia, Publican è progettato con l'assunzione che l'identificazione delle lingue includa regolarmente anche i subtag nazionali. In molte lingue, ortografia e vocaboli variano significativamente da nazione a nazione. Se non si specifica la varietà nazionale di una lingua, in cui il documento viene redatto o in cui viene tradotto, si potrebbero ottenere risultati inaspettati, alla creazione del documento in Publican.

Altri codici linguistici

Il sistema di codici nello standard XML, usato per identificare le lingue, non è l'unico sistema di codici linguistici, attualmente in uso nel mondo. Tuttavia, poiché Publican si sforza di essere compatibile con lo standard XML, questi sono gli unici codici supportati da Publican. In particolare, notare che i codici usati nei prodotti GNU (notabili per l'uso del carattere trattino basso e del simbolo `@` per separare gli elementi — per esempio, `en_GB` o `sr_RS@latin`), non sono compatibili con lo standard XML e perciò non funzionano con Publican.

Publican is an XML publication tool and therefore is designed to use the language codes — or tags — that the World Wide Web Consortium (W3C) designated in the XML specification.[5] These codes are defined in the Internet Engineering Task Force (IETF) document BCP 47: Tags for Identifying Languages.[6]

I tag linguistici sono creati a partire da uno o più subtag, separati da trattini. In ordine di presentazione all'interno di un tag linguistico, questi subtag sono:

`lingua-script-regione-variante`

BCP 47 also allows for considerable customization of language tags for special purposes through the use of extension subtags and private-use subtags. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by `x-` and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).[7] Although Publican will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form `language-region`. A brief description of subtags follows:

subtag lingua

  The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, [8] for example, `zh` (Chinese), `hi` (Hindi), `es` (Spanish), and `en` (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,[9] for example, `bal` (Balochi), `apk` (Kiowa Apache), and `tpi` (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or ISO 639-2 equivalent, such as subtags for the constructed languages `qya` (Quenya) and `tlh` (Klingon), and for the occult language `i-enochian` (Enochian). This last example also illustrates a small number of language subtags grandfathered into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.

  Subtag estesi di lingua

  RFC 5646: Tags for Identifying Languages[10] issued in September 2009 allows for extended language subtags to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, `yue` represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: `zh-yue`. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.

subtag script

  The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.[11] The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, `sr-Latn` represents Serbian written with the Latin alphabet and `sr-Cyrl` represents Serbian written with the Cyrillic alphabet; `az-Arab` represents Azerbaijani written in Arabic script and `az-Cyrl` represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as `fr-Latn`, because French is not commonly written in any script other than the Latin alphabet anywhere in the world.

subtag regione

  The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1[12], for example, `AT` (Austria), `TZ` (Tanzania), and `VE` (Venezuela). The three-digit region subtags are based on those in UN M.49, [13] for example, `015` (Northern Africa), `061` (Polynesia), and `419` (Latin America and the Caribbean).

subtag variante

  I subtag di variante, composti da lettere maiuscole, minuscole e cifre, identificano varianti riconoscibili, ben definite di una lingua o di una scrittura. I subtag di variante che iniziano con una lettera devono essere lunghi almeno cinque caratteri, mentre quelli che iniziano con una cifra, lunghi almeno quattro caratteri. I principali subtag di variante possono essere usati solo in combinazione con subtag specifici oppure in combinazione di subtag. I subtag di variante non si armonizzano con gli altri standard; essi sono il risultato di una registrazione separata, presso l'IETF, da parte di una persona o gruppo interessato.

  Nello standard attuale, i dialetti di varie lingue sono designati con subtag di variante, per esempio, `nedis` denota un dialetto sloveno del Natisone o Nadiza. Questo subtag deve essere usato in congiunzione con il subtag della lingua slovena, quindi si ha `sl-nedis`. Nel settembre 2009, l'IETF ha pubblicato un RFC (Request for Comments) che tra le altre cose, propone di rappresentare i dialetti con i subtag di lingua estesa, da aggiungere ai subtag di lingua.[14]

  I principali subtag di variante contrassegnano una particolare ortografia, la maggior parte usualmente dopo una riforma ufficiale di ortografia o dopo un significativo lavoro di documentazione sulla lingua. Esempi (con i relativi subtag di lingua) comprendono: `fr-1606nicot` (per la lingua francese come documentata da Jean Nicot nel 1606), `de-1901` (per la lingua tedesca la cui ortografia è stata codificata dal 2nd Orthographic Conference nel 1901) e `be-1959acad` (per la lingua bielorussa come codificata dall'Orthography Commission nel 1959).

  Infine, alcuni tag di variante denotano una particolare variante di un sistema di scrittura o di traslitterazione. Per esempio, `zh-Latn-wadegile` rappresenta la lingua cinese scritta con l'alfabeto latino, in accordo la sistema di traslitterazione sviluppato da Thomas Wade ed Herbert Giles; `ja-Latn-hepburn` la lingua giapponese scritta con l'alfabeto latino, usando il sistema di traslitterazione di James Curtis Hepburn.

Publican include supporto per le seguenti lingue:

- ar-SA — arabo

- as-IN — assamese

- ast-ES — asturiano

- bg-BG — bulgaro

- bn-IN — bengalese

- bs-BA — bosniaco

- ca-ES — catalano

- cs-CZ — ceco

- da-DK — danese

- de-CH — tedesco (Svizzera)

- de-DE — tedesco (Germania)

- el-GR — greco

- es-ES — spagnolo

- fa-IR — iraniano

- fi-FI — finlandese

- fr-FR — francese

- gu-IN — gujarati

- he-IL — ebraico

- hi-IN — hindi

- hr-HR — croato

- hu-HU — ungherese

- id-ID — indonesiano

- is-IS — islandese

- it-IT — italiano

- ja-JP — giapponese

- kn-IN — kannada

- ko-KR — coreano

- lv-LV — lettone

- ml-IN — malayalam

- mr-IN — marathi

- nb-NO — norvegese (ortografia Bokmål)

- nl-NL — olandese

- or-IN — oriya

- pa-IN — punjabi

- pl-PL — polacco

- pt-BR — portoghese (Brasile)

- pt-PT — portogehse (Portogallo)

- ru-RU — russo

- si-LK — singalese

- sk-SK — slovacco

- sr-Cyrl-RS — serbo (alfabeto cirillico)

- sr-Latn-RS — serbo (alfabeto latino)

- sv-SE — svedese

- ta-IN — tamil

- te-IN — telugu

- th-TH — thailandese o thai

- uk-UA — ucraino

- zh-CN — cinese (Repubblica Popolare Cinese, alfabeto Han semplificato)

- zh-TW — cinese (Repubblica di Cina, alfabeto Han tradizionale)

[5] http://www.w3.org/TR/REC-xml/#sec-lang-tag

[6] http://tools.ietf.org/html/bcp47

[7] http://www.iana.org/assignments/language-subtag-registry

[8] http://www.infoterm.info/standardization/iso_639_1_2002.php

[9] http://www.loc.gov/standards/iso639-2/

[10] http://tools.ietf.org/html/rfc5646

[11] http://www.unicode.org/iso15924/

[12] http://www.iso.org/iso/country_codes.htm

[13] http://unstats.un.org/unsd/methods/m49/m49.htm

[14] http://tools.ietf.org/html/rfc5646

# Appendice G. Revision History

Diario delle Revisioni
Revisione 4.2-0.6 | Thu Apr 30 2015 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0.5 | Fri Oct 3 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0.4 | Fri Oct 3 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0.3 | Fri Oct 3 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0.2 | Fri Oct 3 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0.1 | Mon Sep 29 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.2-0 dei sorgenti XML

Revisione 4.2-0 | Mon May 12 2014 | Jeff Fearn

Convert to DocBook 5
Update a lot of content

Revisione 4.0-5.1 | Tue May 6 2014 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.0-5 dei sorgenti XML

Revisione 4.0-5 | Thu Mar 27 2014 | Rüdiger Landmann

Corrections to website building instructions

Revisione 4.0-4.1 | Tue Dec 17 2013 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 4.0-4 dei sorgenti XML

Revisione 4.0-4 | Mon Nov 25 2013 | Rüdiger Landmann

Improve instructions for translation BZ#1021287
Document use of "sortas" for indexes and glossaries

Revisione 4.0-3 | Thu Nov 14 2013 | Roman Joost

Clarify where relative paths are used in brand instructions - BZ#1028815

Revisione 4.0-2 | Thu Nov 14 2013 | Norman Dunbar

Corrected OpenSUSE installation instructions - BZ#1000534

Revisione 4.0-1 | Thu Nov 14 2013 | Svein Dowdeit

Updated Debian installation instructions - BZ#1013934
Add Docker installation instructions - BZ#1015943

Revisione 3.2-1 | Thu Jul 11 2013 | Zac Dover

Added command prompts to all commands - BZ#880456
Added quotes around the web_formats list - BZ#839141
Replaced a broken link to kate plugins page on CPAN with a working link - BZ#973461
Updated web site instructions - BZ#979224

Revisione 3.2-0.1 | Thu Jul 11 2013 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 3.2-0 dei sorgenti XML

Revisione 3.2-0 | Thu Jul 11 2013 | Jeff Fearn

Publican 3.2.0
Document site config option 'toc_js'
Document build option --pdftool
Document build option --pub_dir

Revisione 3.1-0.2 | Mon Jul 8 2013 | Jeff Fearn

I file della traduzione sono sincronizzati con con le versioni 3.1-0 dei sorgenti XML

Revisione 3.1-0.1 | Fri Mar 8 2013 | Ruediger Landmann

Translation files synchronised with XML sources 3.1-0

Revisione 3.1-0 | Tue Jan 8 2013 | Norman Dunbar

Add Section on Installing Publican on OpenSuse 12

Revisione 3.0-0 | Mon Feb 20 2012 | Jeff Fearn

Publican 3.0

Revisione 2.7-1 | Tue Sep 6 2011 | Rebecca Newton

Integrata la documentazione sull'uso di <set> a sé stanti

Revisione 2.6-1 | Mon Jul 18 2011 | Rüdiger Landmann

Documentato il nuovo parametro manual_toc_update -- BZ#719573
Documentato la nuova azione update_db -- BZ#661948
Documentato la nuova azione rename -- BZ#694698
Documentato il nuovo parametro mainfile -- BZ#688585
Incluso avviso sui file di configurazione multipli per libri condizionati -- BZ#657132
Corretto i comandi d'esempio -- BZ#663211
Incorporato correzioni di rilettura di Luigi Votta `lewis41@fedoraproject.org` BZ#657576

Revisione 2.4-1 | Wed Dec 1 2010 | Rüdiger Landmann

Incorporato correzioni di rilettura di Luigi Votta `lewis41@fedoraproject.org` BZ#657576
Documentato per lingue note, i problemi con PDF
Documentato il parametro web_formats
Documentato la creazione dei desktop-menu
Documentato site_overrides.css

Revisione 2.3-0 | Mon Oct 25 2010 | Rüdiger Landmann

Documentato il file dump di sito web
Documentato il comando bump
Aggiornato l'informazione sulla larghezza immagini

Revisione 2.3-0 | Tue Oct 5 2010 | Rüdiger Landmann

Aggiornato l'inclusione di più lingue in lang_stats
Corretto i dettagli su web_logo.png BZ#638153
Corretto l'elenco dei caratteri usabili nel nome di prodotto e nel titolo di documento
Documentato il nuovo parametro web_type e ricollocato i parametri web_host e web_search nel file di config di sito
Descritto i cataloghi OPDS
Documentato le pagine di prodotto e di versione
Documentato la presentazione delle pagine di man
Documentato il parametro bridgehead_in_toc
Correzione -- def_langs è un parametro del file config di sito, non un parametro del file di config di home page

Revisione 2.2-0 | Thu Aug 19 2010 | Rüdiger Landmann

Espanso gli esempi di codice BZ#604255
Chiarito l'uso di clean_ids BZ#612819
Documentato --novalid BZ#616142

Revisione 2.1-1 | Fri Jul 16 2010 | Rüdiger Landmann

Corretto e chiarificato le istruzioni su sito web BZ#614259
Chiarificato l'uso di Product-Version-Id per i pacchetti

Revisione 1.6-1 | Mon May 24 2010 | Rüdiger Landmann

Aggiornato le istruzioni di installazioni per Ubuntu

Revisione 1.6-0 | Fri May 7 2010 | Rüdiger Landmann

Rivisto la nomenclatura di azioni ed opzioni
Documentato le azioni print_known, print_banned, e print_unused
Corretto ed espanso la documentazione su installazione di brand
Documentato i parametri max_image_width e confidential_text
Documentato il formato dei plugin di aiuto di Eclipse e i parametri supportati

Revisione 1.5-0 | Fri Feb 26 2010 | Rüdiger Landmann

Documentato le opzioni di --config

Revisione 1.4-0 | Wed Feb 17 2010 | Jeff Fearn

Rimosso obsoleto riferimento al path al file di catalogo di DocBook BZ#565498
Documentato le opzioni di CVS

Revisione 1.3-0 | Mon Dec 7 2009 | Rüdiger Landmann

Aggiunto una FAQ sulla evidenza degli errori nel codice
Aggiunto una sezione sui formati validi
Aggiornato l'elenco degli autori
Aggiunto istruzioni di installazione per Debian; istruzioni di installazione più specifiche per Ubuntu BZ#542711
Metadati nel file Book_Info.xml

Revisione 1.2-0 | Fri Nov 27 2009 | Jeff Fearn

Documentato l'azione lang_stats BZ#540696

Revisione 1.1-1 | Thu Nov 26 2009 | Jeff Fearn

Risolto le condizioni d'uso di errati doc BZ#540691

Revisione 1.1-0 | Thu Oct 22 2009 | Rüdiger Landmann

Risolto varie piccole inconsistenze e pulizia generale

Revisione 1.0-0 | Tue Oct 13 2009 | Rüdiger Landmann

Aggiornato per Publican 1.0

Revisione 0.5-0 | Thu Dec 18 2008 | Jeff Fearn

Aggiunto appendice per i parametri di Makefile
Aggiunto una FAQ sullo spazio di heap in Java

Revisione 0.4-0 | Tue Nov 25 2008 | Brian Forté

Aggiunto la sezione "Pre-release and draft documentation"

Revisione 0.3-0 | Fri Oct 10 2008 | Don Domingo

Aggiunto la sezione "Conditional Tagging"

Revisione 0.2-0 | Fri Sep 05 2008 | Brian Forté

Modifiche generali e aggiornato alla release Publican 0.36. Aggiunto anche una nuova sezione al capitolo 3.3.

Revisione 0.1-1 | Fri Jun 06 2008 | Murray McAllister

Aggiornato il capitolo Branding con una nota sull'aggiunta dei brand oVirt e GIMP

Revisione 0.1-0 | Fri May 16 2008 | Jeff Fearn

Aggiornato FAQ

Revisione 0.0-0 | Thu Dec 13 2007 | Murray McAllister

Contenuto iniziale alla release