Capitolo 6. 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 instalare 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 — una mappa del sito in XML che coadiuva i motori di ricerca nella scansione del sito.
- 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.html — una mappa statica dei documenti presenti sul sito, che coadiuva i visitatori con JavaScript non abilitato nei loro browser.
- 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.
- sottocartelle per ogni lingua in cui pubblicare. Inizialmente, essa contiene solo Site_Tech.html, poi:
  - 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 è siddivisa in <category>.
  - Site_Statistics.html — un sommario sulla documentazione installata sul sito.
  - Site_Tech.html — un sommario sulla tecnologia usata per creare il sito.
  - 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.

Opzionalmente, la struttura del sito può contenere anche un file dump — un file XML che fornisce il dettaglio completo sul contenuto del sito per servire altri servizi, come feed web o ricerca personalizzata di pagine. La struttura potrebbe contenere anche una versione zippata del file dump. Fare riferimento alla Sezione 6.1.1, «Creare la struttura del sito web» ed alla Sezione 6.2.1, «Creare la struttura del sito web» per i dettagli sulla creazione di un file dump; mentre per una descrizione del contenuto di un fle dump, vedere l'Appendice D, Contenuto del file dump di un sito.

6.1. Creare manualmente un sito web

6.1.1. Creare la struttura del sito web

Per creare la struttura del sito web:

Sulla propria macchina, creare una nuova cartella, in cui poi spostarsi. Per esempio, su un sistema Linux, eseguire:
```
mkdir ~/docsite
cd ~/docsite
```
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 operatvio 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 riconoscemento 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.
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 parchè 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 pubblca 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).
  Fare riferimento all'Appendice D, Contenuto del file dump di un sito per una descrizione del contenuto del file dump.
6. 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.
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 6.1.2, «Creare, installare ed aggiornare la home page». 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
```

Per aggiornare la struttura del sito, eseguire:

publican update_site --site_config percorso_al_file_di_configuration_del_sito.cfg

6.1.2. Creare, installare ed aggiornare la home page

La home page genarata da Publican è la pagina di localizzazione a cui sono indirizzati i visitatori dallo JavaScript del sito e che fornisce lo stile alla struttura del sito web. La home page è strutturata come un <article> DocBook ma con un parametro ulteriore web_type: home nel proprio file publican.cfg. Nella sua struttura e presentazione, la home page assomiglia ad un articolo di Publican. Per creare la home page:

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.
Spostarsi nella cartella dell'articolo:
```
cd nome_pagina
```
Per esempio:
```
cd Home_Page
```
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.
Modificare il file publican.cfg.
Come minimo, aggiungere il parametro web_type ed impostarlo a home:
```
web_type: home
```
Il parametro web_type: home 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, frequentamente utili a siti web creati con Publican 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 inludono caratteri diversi dai caratteri di base, come carettri accentati, impostare come occorre i parametri docname e product.
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>
```
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.
Per personalizzare il logo in cima al menu di navigazione, contenente un link alla home page, creare una immagine PNG 290 px × 100 px, di nome web_logo.png. Salvare l'immagine nella cartella images/ della directory dei file XML del documento, per esempio, en-US/images/.
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).
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.

6.1.3. Creare, installare ed aggiornare pagine di prodotto e di versione

Le pagine di prodotto e le pagine di versione generate con Publican, sono pagine localizzabili che offrono una panoramica generale, rispettivamente, su un prodotto o una versione. I visitatori accedono a queste pagine cliccando su prodotto o versione nel menu di navigazione. Le pagine sono strutturate come un <article> DocBook con un ulteriore parametro web_type: product o web_type: version nel proprio file publican.cfg. Nella loro struttura e presentazione, le pagine prodotto e quelle di versione sono pressochè identiche ad ogni altro articolo prodotto con Publican. Per creare una pagina prodotto o di versione:

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
```
Spostarsi nella cartella dell'articolo:
```
cd nome_pagina
```
Per esempio:
```
cd FooMaster
```
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.
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, frequentamente 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 inludono caratteri diversi dai caratteri di base non accentati, impostare come occorre i parametri docname e product.
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>
```
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.
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.

6.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, indivduale 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 qualsiai metodo solitamente usato, come scp, rsync o un client FTP.

6.2. Creare un sito web usando pacchetti RPM

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

Sul server web, effettuare i seguenti passaggi. Occorre accedere con un account con privilegi di root.

Loggarsi sul server web.
Divenire l'utente root:
```
su -
```
Installare Publican. Per esempio, su un server con Sistema Operativo Fedora, eseguire:
```
yum install publican
```
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, construire un motore di ricerca da usare con la casella ri 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 pubblca 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).
  Fare riferimento all'Appendice D, Contenuto del file dump di un sito per una descrizione del contenuto del file dump.
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 6.2.2, «Creare, installare ed aggiornare la home page». 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 aggiornare la struttura del sito, eseguire:

publican update_site --site_config /etc/publican-website.cfg

6.2.2. Creare, installare ed aggiornare la home page

Usando il procedimento indicato nella Sezione 6.1.2, «Creare, installare ed aggiornare la home page», su una macchina creare una home page.
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.
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.

6.2.3. Creare, installare ed aggiornare pagine di prodotto e di versione

Usando il procedimento della Sezione 6.1.3, «Creare, installare ed aggiornare pagine di prodotto e di versione», su una macchina creare una pagina prodotto o di versione.
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.
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.

6.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 6.1.1, «Creare la struttura del sito web», per maggiori informazioni.

6.2.5. Automatizzare la pubblicazione

Giacchè Publican è in grado di creare pacchetti RPM, Publican può essere usato insieme ad un sistema di creazione di RPM come Koji per automatizzare il processo di pubblicazione. Quando un documento è pronto per la pubblicazione, il readattore o il traduttore eseguono il seguente comando:

publican package --cvs

A questo punto, Publican effettua le seguenti operazioni:

genera un SRPM
importa l'SRPM nella radice del CVS secondo l'istanza di Koji specificata nel file publican.cfg del documento
esegue cvs up
esegue make build

Se il server web controlla periodicamente la presenza di aggiornamenti nel repository in cui Koji salva i pacchetti creati, il server può automaticamente installare le versioni aggiornate dei documenti.

Si può anche implementare un sistema di tag in cui un redattore o traduttore può eseguire il comando koji tag-pkg per applicare un'etichetta o tag, al pacchetto creato. In tal modo è possibile avere differenti webserver su cui installare i pacchetti, in base ai tag applicati. Per esempio, si potrebbe configurare un server su una intranet per installare tutti i pacchetti con tag draft per renderli disponibili internamente per revisione e rilettura tecnica. E poi si potrebbe configurare il server che pubblica i documenti sul web in modo da installare i pacchetti solo se con tag public.

Per preparare un documento da compilare tramite una istanza di Koji, modificare il file publican.cfg, specificando:

cvs_branch: il nome del branch per il pacchetto: tipicamente una particolare versione software.
cvs_pkg: il nome del pacchetto in CVS. Per impostazione, in Publican coincide con: prodotto-titolo-versione_prodotto-web-lingua-edizione-numeropub.
cvs_root: la radice di CVS in cui importare l'SRPM. Per esempio, la radice CVS per l'istanza Koji del Fedora Project è :ext:USERNAME@cvs.fedoraproject.org:/cvs/pkgs.

Per maggiori informazioni su Koji, visitare https://fedorahosted.org/koji/wiki.