Capitolo 5. Usare i set

5.1. Set a sé stanti
5.2. Set distribuiti

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.

Esisitono due tipi di set:

set a sé stanti
set distributi

5.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 5.1. Creare un set a sé stante

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
```
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
```
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>
```
Usare lo stesso procedimento per il Book_B, salvato nella cartella books/My_Set/en-US/Book_B, come indicato sopra.

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>

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 queso passaggio.
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

5.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 unset 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 5.2. Creare un set

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
```
Aggiungere le seguneti 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.

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>

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>

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.