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.
Questo manuale utilizza numerose convenzioni per evidenziare parole e frasi, ponendo attenzione su informazioni specifiche.
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, edir
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 Preferenze del Mouse. Nella scheda Pulsanti, fate clic sulla casella di dialogo mouse per mancini, e successivamente fate clic su per cambiare il pulsante primario del mouse da sinistra a destra (rendendo così il mouse idoneo per un utilizzo con la mano sinistra).
→ → dalla barra del menu principale per lanciarePer inserire un carattere speciale in un file gedit selezionare → → dalla barra del menu principale. Selezionare successivamente → dal menu Mappa del carattere, digitare il nome desiderato nel campo Cerca e selezionare . 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 . Ritornare sul documento e selezionare → 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.
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")); } }
E per finire, tre stili vengono usati per richiamare l'attenzione su informazioni che in caso contrario potrebbero essere ignorate.
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.
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.
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.
Un Avvertimento non dovrebbe essere ignorato. Se ignorato, potrebbe verificarsi una perdita di dati.
Un Avvertimento non dovrebbe essere ignorato. Se ignorato, potrebbe verificarsi una perdita di dati.
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.
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à.
#!/usr/bin/perl use strict; use warnings; print "Hello, World!\n";
#include <iostream> int main() { std::cout << "Hello World!"; &lies; }
[Show All][Hide]$
apt-get search libxsltgambas3-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
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; } }
Establishes the connection with the messaging broker.
Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.
Creates a receiver that reads from the given address.
Creates a sender that sends to the given address.
Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.
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.
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
column_name
(required): the name of the column holding the collection index values.
base
(optional - defaults to 0
): the value of the index column that corresponds to the first element of the list or array.
Is there a newline inserted after this CDATA
?
=, >, >=, <, <=, <>
!=
<>
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 } }
The ServiceRegistry
class is an example class implementing the task business logic.
The completeWorkItem()
call completes the work item execution.
<?xml version="1.0" encoding="UTF-8"?><test></test>
Le procedure indicate in questa sezione assumono che Publican e le sue varie dipendenze siano disponibili nei repository cui ha accesso il proprio sistema.
Aprire un terminale
Diventare utente root: su -
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.
Aprire un terminale
Eseguire il seguente comando per installare il pacchetto publican:
sudo apt-get install publican
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.
Aprire un terminale
Diventare utente root: su -
Eseguire il seguente comando per installare il pacchetto publican:
$
apt-get install publican
Run the following command to determine what version of publican is installed:
$
publican -vversion=2.8
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:
Aprire un terminale
Diventare utente root: su -
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
Aggiungere la seguente riga alla fine del file:
#### testing ######### deb http://ftp.us.debian.org/debian testing main contrib non-free
Salvare il file e chiudere l'editor.
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
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
Salvare il file e chiudere l'editor.
Eseguire il seguente comando per aggiornare la lista dei pacchetti disponibili nel sistema:
$
apt-get update
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:
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:$
publicanWarning: 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.
[Show All][Hide](and the same again for libxml2)$
apt-get search libxsltgambas3-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 then upgrading those packages to testing.
$
apt-get -t testing upgrade libxml2 libxslt1.1
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.
Open a terminal session.
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
Liberation-fonts
is most likely already installed, but it is required. Zypper will not reinstall it if it is already present.
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
Download the source code:
$
cd ~ mkdir -p SourceCode/publican cd SourceCode/publican svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./
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
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.
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.
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
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.
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.
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
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.
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.
Aprire un terminale
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
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.
now you can use publican as per the documentation:
$
publican --versionversion=3.2.1
It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.
To checkout the source from GIT open a terminal.
Eseguire il seguente comando per installare il pacchetto publican:
$
cd PATH TO PLACE SOURCE$
git clone git://git.fedorahosted.org/publican.git publican
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
Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.
Spostarsi nella cartella in cui si è scaricato l'eseguibile Publican-Installer-versione.exe
.
Fare doppio click sul file Publican-Installer-versione.exe
.
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
su ciascuna di esse, altrimenti premere .
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 , per continuare.
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.
Dopo aver impostato la cartella di destinazione, premere
.A questo punto, durante l'installazione di Publican, viene visualizzata una barra di progressione. Per visualizzare i dettagli sul progresso di installazione, premere .
Una volta completato, il programma di installazione visualizza il messaggio Completed
.
Premere
per chiudere il programma di installazione.Install Xcode from Mac App store.
Xcode is about 4GB. Be prepared to wait. It has things you need, though.
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.
Aprire un terminale
Install dependencies for publican, which are available as ports:
$
sudo port installdocbook-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
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
Install FOP if you want PDFs to work:
$
sudo port installfop
$
echo"FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
Check out Publican Main branch. This command should be run from your user home directory, for instance /Users/yourusername
$
git clonegit://git.fedorahosted.org/publican.git
Change directories:
$
cdpublican/publican
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
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
$
publican create--name=testbook
$
cd testbook
$
publican build--formats=html --langs=en-US
Open the tmp/en-US/html/index.html
file in a browser to prove that it built correctly.
Procedura 1.2. Install a brand
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
Either check out the SVN for your brand, or get a pre-built brand from a friend.
The SVN location for the brands supplied by Red Hat is http://svn.fedorahosted.org/svn/publican
If you use a pre-built brand, extract it as necessary.
If you got the brand from SVN, build it.
$
cd publican/publican-jboss
$
publican build--formats=xml --langs=all --publish
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.
Users can set their own default values for Publican in ~/.publican.cfg
. Currently, Publican supports the following values:
firstname
surname
formats
lang
langs
This file is completely different to publican.cfg
that is used to build a book. It does not accept the same parameters.
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 buildSetting 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"
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
I comandi di Publican hanno uno dei seguenti formati:
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»
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.
Alcune opzioni_comando influenzano il risultato di una azione, come quando si richiede, per esempio, a Publican di usare nell'output la colorazione ANSI.
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
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
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">
.
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.
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
.
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
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, …
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 …
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 …
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 …
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.
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
.
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.
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.
This parameter is only permitted in a brand.
dtdver
Override URI for DocType. Must be a complete string.
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.
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
Publican genera le tabelle dei contenuti all'inizio del documento e nelle parti, nei capitoli e in appendice, ma non nelle sezioni.
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 …
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
Publican genera un sommario principale solo di capitoli.
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 …
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.
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"
Eseguire il comando publican help_config nella cartella radice di un libro per un elenco di questi parametri.
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
.
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.
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
.
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.
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.
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.
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
.
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.
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.
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.
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
.
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
.
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.
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>
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.
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.
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.
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.
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 (& and < 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:
Creare la cartella extras
mkdir en-US/extras
Copiare il file del codice nella cartella extras
cp ~/samples/foo.c en-US/extras/.
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>
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/.
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
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_titolomodifica 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_prodottomodifica 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_versionemodifica 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
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:
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.
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.
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.
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.
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
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.
Tradurre le stringhe contenute nei file PO.
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.
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.
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.
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>"
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:
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».
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
Eseguire un test, per evitare che ci siano errori di compilazione nel linguaggio desiderato, per esempio:
publican build --formats=test --langs=it-IT
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:
Elenca le opzioni disponibili in publican build per creare un libro.
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.
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».
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/
.
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/
.
Crea il libro nei formati HTML su pagine multiple e su pagina singola, e PDF.
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
.
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.
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.
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.
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).
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 → . 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.
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
linguaspecifica la lingua per cui creare il pacchetto della documentazione.
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.
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.
I seguenti esempi mostrano alcune opzioni comuni, riferite alla II edizione, VI revisione del documento Foomaster 9 Configuration Guide.
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.
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.
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.
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.
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.
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.
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
.
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">
.
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.
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.
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:
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>
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.
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.
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!
Per denotare propriamente la documentazione incompleta relativa a software pre-release, seguire entrambe le procedure indicate in precedenza.
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"
This is how an element that has been added to a new revision is marked-up.
This is how an element that has been changed in a new revision is marked-up.
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.
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).
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:
Se il brand è distribuito come un archivio, per esempio, un file tarball o ZIP, estrarre il brand in una nuova cartella.
Spostarsi nella cartella contenente il brand estratto:
cd publican-brand
dove brand è il nome del brand.
Compilare il brand:
publican build --formats xml --langs all --publish
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.
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' *
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).
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.
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.
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.
Il file README
contiene una breve descrizione del pacchetto di brand.
Il file COPYING
contiene i dettagli riguardanti la licenza o COPYRIGHT sul pacchetto e presumibilmente il testo della stessa licenza.
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.
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.
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.
css
La sotto-cartella css
contiene un solo file: 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.
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».
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).
Brands with custom XSLT need to change the relative path of referencing XSL templates to a URI.
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.
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
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
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
.
$
cdMy_Set/en-US
$
mkdirBook_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:
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>
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.
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
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.
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
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 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.
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.
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.
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.
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 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.
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:
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.
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.
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.
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à.
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.
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.
Optionally, specify the web style with the web_style
.
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)
The website includes a breadcrumb-like navigation bar across the top of the documentation.
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.
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.
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.
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
Build and install each brand, including the Publican common
brand.
Change into the directory that holds the source for the brand.
$
cd brandsrc_dir
Build the brand.
$
publican build --formats=xml --langs=all --publish
Install the brand on your website.
$
publican install_brand --web --path=path_to_site_root_dir
Perform these steps for all brands.
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
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:
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
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
.
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.
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/
.
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.
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:
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
, 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
.
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.
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.
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.
Autenticarsi sul server web.
Installare Publican. Per esempio, su un server con Sistema Operativo Fedora, eseguire:
$
sudo yum install publican publican-common-web
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:
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.
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.
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.
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à.
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.
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.
Optionally, specify the web style with the web_style
.
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)
The website includes a breadcrumb-like navigation bar across the top of the documentation.
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.
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.
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.
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
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.
Usando il procedimento indicato nella Sezione 7.1, «Creare manualmente un sito web», 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.
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.
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».
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.
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.
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.
Procedura 7.1. To Submit Your Sitemap to Google:
Sign up for a Google account at Google Webmaster Tools. If you already have a Google account, you can use it.
Sign in to your Google Webmaster Tools account at this URL: http://www.google.com/webmasters/tools/home.
First you must verify you are the owner of your Publican site. Click the
button.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 .
Follow the instructions that display and upload the HTML file that Google provides to the document root of your website.
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
button.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.
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.
You are taken to a Sitemap submission page. Click the
button.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
button. The details of the Sitemap are displayed in a table.Risultato. The Sitemap for your Publican site has been successfully submitted to Google.
Procedura 7.2. To Submit Your Sitemap to Bing:
Sign up for a Bing Webmaster Tools account at Bing Webmaster Tools. If you already have a Windows LiveID account, you can use it.
Sign in to your Bing Webmaster Tools account at this URL: http://www.bing.com/toolbox/webmaster/.
Click the
button.The Add Site dialog box is displayed. Enter the URL of your Publican site in the text entry field and click .
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.
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 button.
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.
Select the
tab.Select Sitemaps and then Add Feed.
The Add Feed dialog displays. Enter the URL of your Sitemap file and click . The details of the Sitemap are displayed.
Result: The Sitemap for your Publican site has been successfully submitted to Bing.
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.
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.
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.
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.
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"
.
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/"
.
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 and click button to activate the Node Import Module.
You also need to enable the following Drupal core modules:
Book
Menu
Path
Please consult your web adminstrator if you don't have permission to install module in drupal.
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.
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.
Procedura 8.1. To import book into Drupal:
Follow the steps in Sezione 8.1, «How to build a CSV file for Drupal import»
Upload the CSV file to import Directory
in the Drupal Server
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»
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.
Click
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!The book link should be showing in the specified menu block now.
Simply repeat the steps in Sezione 8.3.3, «How to import book» to update the book.
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.
Come si aggiunge una lingua ad un libro?
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.
E se non si specifica il codice di nazione? Per esempio, si può eseguire publican update_po --langs=es,de,fr?
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.
Come si aggiornano tutti i file PO?
Eseguendo il comando publican update_po --langs=all.
Come si ottiene l'elenco completo delle opzioni di build di Publican?
Eseguendo il comando publican build --help.
Come si ottiene l'elenco completo dei parametri configurabili nel file publican.cfg
?
Eseguendo il comando publican help_config in una cartella contenente un documento di Publican.
Dove si trovano i file comuni di Publican?
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
.
E' possibile includere nei tarball e nei pacchetti RPM un file qualsiasi?
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.
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.
Perché Publican segnala con warning i tag sconosciuti?
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).
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?
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.
Un errore segnala che Batik non è presente nel classpath eppure Batik è installato! Cos'è che non va?
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.
Creando un file PDF si solleva un'eccezione Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
. Cos'è che non va?
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.
Versioni precedenti di Publican rimuovevano i tag <para>
vuoti. E le versioni di Publican correnti?
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.
Che fine ha fatto il controllo ortografico?
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
Perché quando si creano file PDF, i tag <segmentedlist>
non funzionano?
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.
Come mai, nei PDF, si altera il colore delle immagini?
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.
Creando un documento, si ottiene un errore del tipo ‘undefined language’ — cos'è che non va?
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.
Come abilitare il completamento dei comandi bash per Publican?
Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:
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.
Aggiungere al proprio file ~/.bashrc
:
# Use bash-completion, if available if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
Riavviare il terminale o eseguire source ~/.bashrc.
Why am I having trouble building my large book?
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.
Perché Jeff chiama Isaac ‘Ivan’?
Perché la memoria di Jeff è in mutande!
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.
<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:
Apple
— an apple is…
Grapes
— grapes are…
Orange
— an orange is…
Peach
— a peach is…
in italiano appare come:
Mela
— una mela è…
Uva
— l'uva è…
Arancia
— un'arancia è…
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.
<[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.
Allow the XML and XSLT processing to access the network. Defaults off.
Directory to source brand files from.
Override path to Common_Config directory
Override path to Common_Content directory
Use a nonstandard config file
Display help message
Disable ANSI colourisation of logging.
Disable all logging.
$
publican add_revisionAdd an entry to the revision history
Date to use for a revision.
email to use for a revision.
firstname to use for a revision.
The language the XML will be written in
An entry to be added to the revision. Can be specified multiple times.
Revision number to use for a revision.
surname to use for a revision.
$
publican buildTransform XML to other formats (pdf, html, html-single, drupal-book, etc)
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.
Embed the web site TOC object in the generated HTML
Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
Comma-separated list of languages, for example: en-US,de-DE,all
Do not run the DTD validation
Override the tool to use when creating PDFs. Valid options are wkhtmltopdf and fop.
Directory to publish files to. Defaults to publish.
Set up built content for publishing
Show fuzzy translation entries in output. Defaults off.
Directory to source publican files from.
$
publican cleanRemove all temporary files and directories
Directory to publish files to. Defaults to publish.
$
publican clean_idsRun clean ids for source XML
$
publican clean_setRemove local copies of remote set books
$
publican copy_web_brandCopy a brand's installed web content to another site
The brand to use
WebSite configuration file to use when copying content between sites.
WebSite configuration file to use or create.
$
publican createCreate a new book, set, or article
The brand to use
The version of the DocBook DTD to use
The edition of the book, article, or set
The language the XML will be written in
The name of the book, article, set, or brand
The name of the product
The type (book, article, or set)
The version of the product
$
publican create_brandCreate a new brand
The language the XML will be written in
The name of the book, article, set, or brand
$
publican create_siteCreate a new WebSite in the supplied location.
Override default database file.
The language the XML will be written in
WebSite configuration file to use or create.
Override the default template path.
Override the default TOC path.
$
publican help_configDisplay help text for the configuration file
$
publican install_bookInstall a book in to a WebSite.
The language the XML will be written in
WebSite configuration file to use or create.
$
publican install_brandInstall a brand to the supplied location
/path/to/install/to
Directory to publish files to. Defaults to publish.
Install the web content for a brand.
$
publican lang_statsreport PO statistics
The language the XML will be written in
$
publican migrate_siteMigrate a website DataBase from Publican < 3 to Publican 3.
WebSite configuration file to use or create.
$
publican packagePackage a language for shipping
Build binary rpm when running package
Push SRPM to brew
Create desktop instead of web package
The language the XML will be written in
Directory to publish files to. Defaults to publish.
Use scratch instead of tag build
Create package without using version in package name
Wait for brew to finish building
$
publican print_bannedPrint a list of banned DocBook tags
$
publican print_knownPrint a list of QA'd DocBook tags
$
publican print_treePrint a tree of the xi:includes
$
publican print_unusedPrint a list of unused XML files
$
publican print_unused_imagesPrint a list of unused Image files
$
publican remove_bookRemove a book from a WebSite.
The language the XML will be written in
WebSite configuration file to use or create.
$
publican renameRename a publican book
The name of the book, article, set, or brand
The name of the product
The version of the product
$
publican reportPrint a readability report for the source text.
$
publican site_statsReport on the contents of a WebSite
WebSite configuration file to use or create.
$
publican trans_dropSnapshot the source language for use in translation.
$
publican update_dbAdd or remove database entries. Used for processing pre-build books, such as when building packages.
Abstract for a book
Add a database entry
The language this translation is based on.
The version number of the book being installed.
Delete a database entry
Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
The language the XML will be written in
The name of the book, article, set, or brand
name label for a book
The name of the product
product label for a book
WebSite configuration file to use or create.
Order to sort a book
Sub title for a book
The version of the product
version label for a book
$
publican update_poUpdate the PO files
email to use for a revision.
firstname to use for a revision.
Comma-separated list of languages, for example: en-US,de-DE,all
Use gettext's msgmerge for POT/PO merging.
Keep previous msgid when fuzzy matches are detected in PO updates.
surname to use for a revision.
$
publican update_potUpdate the POT files
$
publican update_siteUpdate an existing sites templates.
WebSite configuration file to use or create.
$
publican zt_pullPull translations from Zanata.
$
publican zt_pushPush translations to Zanata.
These are set in the books or brands configuration files.
Arch to filter output on.
audience to filter output on.
A space-separated list of books used in this remote set.
The brand to use when building this package.
The default value for this parameter is: common
The brew dist to use for building the standalone desktop rpm.
The default value for this parameter is: docs-5E
This field is deprecated and will be removed from Publican in the future.
Display bridge head elements in the TOCs?
The default value for this parameter is: 0
For HTML, should the first section be on the same page as its parent?
The default value for this parameter is: 0
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
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
Path to publican content.
The default value for this parameter is: /usr/share/publican
Path to publican common content.
The default value for this parameter is: /usr/share/publican/Common_Content
Conditions on which to prune XML before transformation.
Is the content confidential?
The default value for this parameter is: 0
The text used to indicate content is confidential.
The default value for this parameter is: CONFIDENTIAL
conformance to filter output on.
Print out extra messages?
The default value for this parameter is: 0
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
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_\-\.\+]+$
This field is not supported for: brand.
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
The directory where the image should be stored in drupal server.
The default value for this parameter is: /sites/default/files/documentation/
The menu where we can find the book.
The default value for this parameter is: user-guide
Override the bookname that will be shown in the drupal menu.
The format to use for the desktop output.
The default value for this parameter is: html-desktop
Space-separated list of packages the desktop RPM obsoletes.
Space-separated list of packages the desktop RPM requires.
Version of the DocBook DTD on which this project is based.
The default value for this parameter is: 4.5
Eclipse plugin ID. Defaults to "$product.$docname"
Eclipse plugin name. Defaults to "$product $docname"
Eclipse plugin provider. Defaults to "Publican-v4.2.2"
Directory where images are located.
The default value for this parameter is: extras
Generate table of contents down to the given section depth.
The default value for this parameter is: 0
Languages to replace with xml_lang regardless of translation status.
Directory where images are located.
The default value for this parameter is: images
Override the default Info file.
lang to filter output on.
License this package uses.
The default value for this parameter is: GFDL
The name of the main xml and ent files for this book, sans file extension and language. Fetched from docname if not set.
Semicolon-separated list of menu categories for the desktop package.
os to filter output on.
The OS for which to build packages.
The font to use for body text in PDFs.
The default value for this parameter is: Liberation Sans
The font to use for mono text in PDFs.
The default value for this parameter is: Liberation Mono
URL for the product. Used in top left URL in HTML.
The default value for this parameter is: https://fedorahosted.org/publican
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_\-\.\+]+$
This field is not supported for: brand.
Repository from which to fetch remote set books.
By default Revision History is sorted in descending order. Set this to 'asc' or 'ascending' to reverse the sort.
Override the default Revision History file.
revision to filter output on.
revisionflag to filter output on.
role to filter output on.
Type of repository in which books that form part of a remote set are stored. Supported types: SVN, GIT.
security to filter output on.
Display remarks in transformed output.
The default value for this parameter is: 0
Override the default sort weighting. Defaults to 50.
URL to find tar of source files. Used in RPM Spec files.
status to filter output on.
Directory to use for building.
The default value for this parameter is: tmp
Depth of sections to include in the main table of contents.
The default value for this parameter is: 2
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 of content this package contains. Supported: set, book, article, brand
The default value for this parameter is: Book
userlevel to filter output on.
vendor to filter output on.
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}]*$
The brew dist to use for building the web rpm.
The default value for this parameter is: docs-5E
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
This is a home page for a Publican-generated website, not a standard book.
web_home is deprecated and will be removed from Publican in the future. Use "web_type: home" instead.
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
web_host is deprecated and will be removed from Publican in the future. Use "host" in the web site configuration file instead.
Override the book name, bottom level, menu label on a Publican website.
Packages to obsolete in web RPM.
Override the product, top level, menu label on a Publican website.
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.
web_search is deprecated and will be removed from Publican in the future. Use "search" in the web site configuration file instead.
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)$
Override the version, middle level, menu label on a Publican website. To hide this menu item set this to: UNUSED
Extra options to pass to wkhtmltopdf. e.g. wkhtmltopdf_opts: "-O landscape -s A3"
wordsize to filter output on.
Language in which XML is authored.
The default value for this parameter is: en-US
These are set in the brands configuration files.
A comma-separated list of XML attributes that are not permitted in the source.
A comma-separated list of XML tags that are not permitted in the source.
The base brand to use for this brand.
The default value for this parameter is: common
Override Type for DocType. Must be a complete string.
Override URI for DocType. Must be a complete string.
Brand option to disable embedding the navigational toc in web packages
Full path for the publican site configuration file for non standard RPM websites.
Install path for non standard RPM websites.
Name of site package for non standard RPM websites. Required to ensure the site is installed.
These are set in the sites configuration file.
The name of the SQLite database file for your site, with the filename extension .db
Output extra messages when running publican.
The default value for this parameter is: 0
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 the publican database to an XML file.
The name of the file to dump the publican database to.
The default value for this parameter is: /var/www/html/DUMP.xml
HTML to inject in to the footer of every page on the website.
The default value for this parameter is:
The web host, may be a full URI or a relative path.
The default value for this parameter is: /docs
Stop publican from automatically rebuilding teh web site everytime a book is installed, updated or removed.
The default value for this parameter is: 0
The HTML to inject in as the site serach.
The default value for this parameter is: Google site search
Title used for all site navigation pages.
The default value for this parameter is: Documentation
Full path to the template directory.
The default value for this parameter is: /usr/share/publican/templates
The source file to use for JavaScript functionality.
The default value for this parameter is: default.js
The path to the directory in which to create the top-level index.html file.
Template to use for generagting the web style 1 toc file.
The default value for this parameter is: toc
This field is deprecated and will be removed from Publican in the future.
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]
This field is deprecated and will be removed from Publican in the future.
Zip up the dump file after dumping it
The default value for this parameter is: 0
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>
Usando i seguenti campi, si può ricavare l'URL di ogni documento sul sito:
<host>
<name>
<format>
<language>
<product>
<version>
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Per esempio, http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Per esempio, http://docs.fedoraproject.org/en-US/Fedora/14/html-single/Accessibility_Guide/index.html
<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
<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
.
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.
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:
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.
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.
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.
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).
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)
Diario delle Revisioni | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Revisione 4.2-0.6 | Thu Apr 30 2015 | ||||||||||
| |||||||||||
Revisione 4.2-0.5 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revisione 4.2-0.4 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revisione 4.2-0.3 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revisione 4.2-0.2 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Revisione 4.2-0.1 | Mon Sep 29 2014 | ||||||||||
| |||||||||||
Revisione 4.2-0 | Mon May 12 2014 | ||||||||||
| |||||||||||
Revisione 4.0-5.1 | Tue May 6 2014 | ||||||||||
| |||||||||||
Revisione 4.0-5 | Thu Mar 27 2014 | ||||||||||
| |||||||||||
Revisione 4.0-4.1 | Tue Dec 17 2013 | ||||||||||
| |||||||||||
Revisione 4.0-4 | Mon Nov 25 2013 | ||||||||||
| |||||||||||
Revisione 4.0-3 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revisione 4.0-2 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revisione 4.0-1 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Revisione 3.2-1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Revisione 3.2-0.1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Revisione 3.2-0 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Revisione 3.1-0.2 | Mon Jul 8 2013 | ||||||||||
| |||||||||||
Revisione 3.1-0.1 | Fri Mar 8 2013 | ||||||||||
| |||||||||||
Revisione 3.1-0 | Tue Jan 8 2013 | ||||||||||
| |||||||||||
Revisione 3.0-0 | Mon Feb 20 2012 | ||||||||||
| |||||||||||
Revisione 2.7-1 | Tue Sep 6 2011 | ||||||||||
| |||||||||||
Revisione 2.6-1 | Mon Jul 18 2011 | ||||||||||
| |||||||||||
Revisione 2.4-1 | Wed Dec 1 2010 | ||||||||||
| |||||||||||
Revisione 2.3-0 | Mon Oct 25 2010 | ||||||||||
| |||||||||||
Revisione 2.3-0 | Tue Oct 5 2010 | ||||||||||
| |||||||||||
Revisione 2.2-0 | Thu Aug 19 2010 | ||||||||||
| |||||||||||
Revisione 2.1-1 | Fri Jul 16 2010 | ||||||||||
| |||||||||||
Revisione 1.6-1 | Mon May 24 2010 | ||||||||||
| |||||||||||
Revisione 1.6-0 | Fri May 7 2010 | ||||||||||
| |||||||||||
Revisione 1.5-0 | Fri Feb 26 2010 | ||||||||||
| |||||||||||
Revisione 1.4-0 | Wed Feb 17 2010 | ||||||||||
| |||||||||||
Revisione 1.3-0 | Mon Dec 7 2009 | ||||||||||
| |||||||||||
Revisione 1.2-0 | Fri Nov 27 2009 | ||||||||||
| |||||||||||
Revisione 1.1-1 | Thu Nov 26 2009 | ||||||||||
| |||||||||||
Revisione 1.1-0 | Thu Oct 22 2009 | ||||||||||
| |||||||||||
Revisione 1.0-0 | Tue Oct 13 2009 | ||||||||||
| |||||||||||
Revisione 0.5-0 | Thu Dec 18 2008 | ||||||||||
| |||||||||||
Revisione 0.4-0 | Tue Nov 25 2008 | ||||||||||
| |||||||||||
Revisione 0.3-0 | Fri Oct 10 2008 | ||||||||||
| |||||||||||
Revisione 0.2-0 | Fri Sep 05 2008 | ||||||||||
| |||||||||||
Revisione 0.1-1 | Fri Jun 06 2008 | ||||||||||
| |||||||||||
Revisione 0.1-0 | Fri May 16 2008 | ||||||||||
| |||||||||||
Revisione 0.0-0 | Thu Dec 13 2007 | ||||||||||
|