Product SiteDocumentation Site

Capitolo 4. Branding

4.1. Installare un brand
4.2. Creare un brand
4.3. File nella directory brand
4.3.1. Il file publican.cfg
4.3.2. I file defaults.cfg e overrides.cfg
4.3.3. File publican-brand.spec
4.3.4. README
4.3.5. COPYING
4.3.6. Common Content per il brand
4.3.7. La sotto-cartella css
4.3.8. La sotto-cartella images
4.4. Creare il pacchetto di un brand
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 inizare un documento, immagini come loghi ed elementi stlistici 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).

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

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

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

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

4.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 3.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 nele 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 modficati dai redattori.

4.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 4.4, «Creare il pacchetto di un brand» per sapere come configurare il file spec e come usarlo per produrre un pacchetto RPM.

4.3.4. README

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

4.3.5. COPYING

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

4.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 aquisire il suo aspetto distintivo, con il suo schema di colori e i suoi loghi.

4.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 quì questo tipo di informazione.

4.3.7. La sotto-cartella css

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

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

4.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 3.10.2, «Denotare la documentazione draft».

4.4. Creare il pacchetto di un brand

Pacchetti non pacchetti RPM

Questa sezione descrive i pacchetti di documenti distribuiti con il Gestore di pacchetti RPM. Quando si usa il comando publican package, Publican genera un tarball che può essere usato per ricavare un pacchetto, da distribuire con un gestore di pacchetti software differente. Se si esegue publican package su un sistema senza rpmbuild installato, Publican genera ancora il tarball anche se non può creare da esso, il pacchetto RPM.
Dopo aver creato un brand (come descritto nella Sezione 4.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 3.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 4.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_taget.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.