Sommario
publican.cfg parametersNeretto monospazio
Per visualizzare i contenuti del filemy_next_bestselling_novelnella vostra directory di lavoro corrente, inserire il comandocat my_next_bestselling_novelal prompt della shell e premere Invio per eseguire il comando.
Premere Invio per eseguire il comando.Premere Ctrl+Alt+F2 per usare un terminale virtuale.
neretto monospazio. Per esempio:
Le classi relative ad un file includonofilesystemper file system,fileper file, edirper directory. Ogni classe possiede il proprio set associato di permessi.
Choose → → from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).Per 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.
Corsivo neretto monospazioCorsivo neretto proporzionale
Per collegarsi ad una macchina remota utilizzando ssh, digitaresshal prompt della shell. Se la macchina remota èusername@domain.nameexample.comed il nome utente sulla macchina interessata è john, digitaressh john@example.com.Il comandomount -o remountrimonta il file system indicato. Per esempio, per rimontare il file systemfile-system/home, il comando èmount -o remount /home.Per visualizzare la versione di un pacchetto attualmente installato, utilizzare il comandorpm -q. Esso ritornerà il seguente risultato:package.package-version-release
Publican è un sistema di pubblicazione per DocBook.
tondo monospazio e così presentato:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
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")); } }
Nota
Importante
Avvertimento
Nome_Doc.entNome_Doc.ent»).
Nome_Doc.entImportante — Disponibilità nei repository
su -
$yum install publican publican-doc
$yum install publican-brand
brand con redhat, fedora, jboss, ovirt, o gimp. Vedere il Capitolo 5, Branding per una spiegazione del branding in Publican.
Importante — Software non supportato
Importante — Dipendenze disponibili soltanto all'interno di Red Hat
su -
$yum install publican publican-doc
$yum install publican-brand
brand con redhat, fedora, jboss, ovirt, o gimp. Vedere il Capitolo 5, Branding per una spiegazione del branding in Publican.
Importante — Novità in 10.4 "Lucid Lynx"
$sudo apt-get install publican
Avviso — Completare questa procedura
/etc/apt/sources.list, il sistema potrebbe diventare instabile.
squeeze. Abilitando l'accesso a questo repository, si autorizza il computer ad installare nuovo software e nuove versioni di software, rispetto alla corrente versione stabile di Debian. Tuttavia, non tutto il software disponibile nel repository di test ha già superato il controllo di qualità. Quindi, se dopo l'installazione di Publican non si disabilita l'accesso a questo repository, al successivo aggiornamento del sistema, i pacchetti software esistenti verranno sostituiti con nuove versioni scaricate dal repository, e molto probabilmente risulteranno essere versioni non ancora testate.
/etc/apt/sources.list. Per esempio, per modificare il file con gedit, eseguire:
$sudo gedit /etc/apt/sources.list
deb http://ftp.debian.org/debian/ squeeze main
$sudo apt-get update
$sudo apt-get install publican
/etc/apt/sources.list e rimuovere la riga precedentemente inserita.
$sudo zypper install perl-Config-Simple perl-DateTime \ perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \ perl-File-Find-Rule perl-File-Which perl-HTML-Format \ perl-Locale-MakeText-Gettext perl-Template-Toolkit \ perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \ perl-YAML liberation-fonts
Nota
Liberation-fonts is most likely already installed, but it is required. Zypper will not reinstall it if it is already present.
$sudo sh cpan File::pushd File::Copy::Recursive Locale::PO pp \ Syntax::Highlight::Engine::Kate XML::TreeBuilder exit
$cd ~ mkdir -p SourceCode/publican cd SourceCode/publican svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./
$perl Build.PL
WARNING: the following files are missing in your kit:META.ymlPlease inform the author.Created MYMETA.yml and MYMETA.jsonCreating new 'Build' script for 'Publican' version '2.9'
File/pushd.pm is reported as missing, you would use this to install it:
$sudo sh cpan File::pushd exit
Build.PL script will have created a new script named Build which we will use to create, test and install Publican 2.9.
$./Build
DEBUG: Publican::Builder: end of build$./Build test
Test Summary Report-------------------t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)Failed test: 5Non-zero exit status: 1t/pod-coverage.t (Wstat: 256 Tests: 9 Failed: 1)Failed test: 7Non-zero exit status: 1Files=10, Tests=68, 420 wallclock secs ( 0.31 usr 0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)Result: FAILFailed 2/10 test programs. 2/68 subtests failed.
ghostscript-fonts-std as opposed to ghostscript-fonts) wkhtmltopdf will not run even if force installed with no dependency checks.
Nota
$JFEARN=http://jfearn.fedorapeople.org/wkhtmltopdf/f15 MYSYSTEM=i686 ## For 64bit system use MYSYSTEM=x86_64 instead. wget $JFEARN/$MYSYSTEM/wkhtmltopdf-qt-4.7.1-1.git20110804.fc15.i686.rpm wget $JFEARN/$MYSYSTEM/wkhtmltopdf-0.10.0_rc2-1.fc15.i686.rpm
Nota
MYSYSTEM appropriately.
$sudo sh rpm -ivh wkhtmltopdf-qt* rpm -ivh --nodeps wkhtmltopdf-0* exit
ghostscript-fonts problem described above.
$sudo sh ./Build test exit
$publican create --type=book --product=testing --version=1.2.3 --name=TestPublicanProcessing file en-US/Author_Group.xml -> en-US/Author_Group.xml Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml Processing file en-US/Chapter.xml -> en-US/Chapter.xml Processing file en-US/Preface.xml -> en-US/Preface.xml Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml$cd TestPublican/ publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub
Nota
runtime error: file /usr/share/publican/xsl/epub.xsl element chooseVariable 'epub.embedded.fonts' has not been declared.at /usr/lib/perl5/site_perl/5.14.2/Publican/Builder.pm line 915
SourceCode/TestPublican/tmp/en-US/ and view the various output formats that you find there.
Publican-Installer-versione.exe.
Publican-Installer-versione.exe.
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.
Publican nella cartella %ProgramFiles%C:\Program Files\Publican. Per selezionare una cartella differente, inserire manualmente il percorso alla cartella, nella casella di testo etichettata Destination Folder.
Completed.
Nota
/opt/local, away from your normal OS files.
$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
$sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables
$sudo port installfop
$echo"FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
/Users/yourusername
$git clonegit://git.fedorahosted.org/publican.git
$cdpublican/publican
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
/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
tmp/en-US/html/index.html file in a browser to prove that it built correctly.
Procedura 1.2. Install a brand
$find /opt/local/share/publican-type f|xargs sudo chmod 644
$cd publican/publican-jboss
$publican build--formats=xml --langs=all --publish
$sudo publican install_brand--path=/opt/local/share/publican/Common_Content
publican.cfg file or specifying the --brand option when creating your book.
~/.publican.cfg. Currently, Publican supports the following values:
Nota
publican.cfg that is used to build a book. It does not accept the same parameters.
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.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"
$ cmd command from the to open a command prompt.
$ publican command_optioncommand_option is any of several options for the $ publican command itself.
$ publican action action_optionsazione è una richiesta di elaborazione per Publican, come creare i file XML per un nuovo documento o creare un documento in HTML dai corrispondenti file XML. Le opzioni_azione si applicano ad una azione, per specificare per esempio la lingua di un documento.
$ publican command_option action action_optionsopzioni_comando influenzano il risultato di una azione, come quando si richiede, per esempio, a Publican di usare nell'output la colorazione ANSI.
$ publican command are:
--help--man--help, oltre a fornire informazioni su licenze e dipendenze.
--help_actions-v--config filepublican.cfg.
--nocolours--quietRevision_History.xml.
tmp/ subdirectory. The tmp/ subdirectory is created after running the $ publican build command to build a document, such as publican build --formats=html --langs=en-US.
Book_Name-title. For example, a section with a title of First Section in a book named Test_Book will have the following ID after you run $ publican clean_ids: <section id="Test_Book-First_Section">
Warning — $ publican clean_ids
$ publican clean_ids uses the first four characters of the tag as a prefix for the ID. Consequently, you must check out the latest versions of the XML source and translations before running this command.
$ publican clean_ids, the XML and PO files will no longer be in synchrony with each other. In this case, all links in the PO files must be manually updated.
Importante — Possono verificarsi conflitti tra ID
$ publican clean_ids command is intended to facilitate building a DocBook structure around documents ported from other formats such as HTML. However, publican clean_ids is file-based and and only has access to information in the XML file that it is currently processing and to the document name. Therefore, nodes of the same type that have the same title receive the same IDs. These duplicate IDs will prevent the document from building.
$ publican clean_ids command to assist you in laying out your document, but expect that some manual adjustment to IDs might be necessary. We recommend that you do not run publican clean_ids on an already well established document.
publican.cfg, contenuto in ciascun libro o brand. Fare riferimento alla Sezione 4.1.1, «Il file publican.cfg» per maggiori dettagli.
codice_linguacodice_lingua. Per ogni file PO generato da Publican, una tabella mostra il numero delle stringhe non tradotte in tutti i msgid; il numero delle stringhe fuzzy (conteggia le stringhe contenute in msgid, il cui contenuto è variato dall'ultima generazione dei POT), ed il numero delle stringhe tradotte, coincidente, a traduzione avvenuta, con il numero delle stringhe contenute nel msgid.
<xi:include>, in un libro, articolo o set.
<xi:include> tag in a book, article, or set.
<xi:include>, in un libro, articolo o set.
$ publican create command to create a new document, including all the necessary files for the document.
$ publican create command accepts several options, detailed in this chapter. When an option can accept a value, separate the option from the value with a space or an equals sign; for example, publican create --name New_Book or publican create --name=New_Book.
--help$ publican create command options.
--name Nome_DocDoc_Name as the name of the book or article. This variable must not contain any spaces. For example, the command $ create_book --name Test_Book creates a book named Test_Book with all the necessary files to build the book, and sets the BOOKID in the Test_Book.ent file.
--lang Codice_LinguaCodice_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 G, Codici di lingua per i dettagli sui codici linguistici.
--version versioneversione del prodotto descritto dal libro. Per esempio, per Red Hat Enterprise Linux 5.1 si userà 5.1. Il valore predefinito è 0.1. L'opzione --version imposta il tag <productnumber> nel file Book_Info.xml o nel file Article_Info.xml. Per maggiori informazioni vedere la Sezione 4.1.2, «Book_Info.xml».
--edition edizioneedizione 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_ProdottoNome_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 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 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 brandbrand, 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.
$ publican create command, use the $ cd command to change into the directory where you want the book to be created. For example, to create a book named Test_Book in the my_books/ directory, run the following commands:
$cd my_books/$publican create --name Test_Book
$ls
Libro_di_Prova/Libro_di_Prova/ su un computer con Sistema Operativo Linux, eseguire i comandi:
$cd Test_Book/$ls
it-IT/ publican.cfg$ publican create --name Test_Book --lang en-US, Publican creates a directory structure and required files, similar to the following:
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
Nota — Personalizzare l'output
--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 en-US,de-DE,hu-HU --config community.cfg
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_langen-US, as set by the --lang option for $ publican create.
type<article>, DocBook <book>, or DocBook <set>, as set by the --type option for $ publican create.
brandRedHat, fedora, JBoss, oVirt or GIMP , as set by the --brand option for $ publican create. If you do not specify a brand, Publican uses its default brand. Refer to Capitolo 5, Branding for more information.
Parametri avanzati
archarch: x86_64 nel file publican.cfg, l'applicazione Publican include solo gli elementi XML contenenti l'attributo equivalente, per esempio <para arch="x86_64">.
Usare con cautela
arch può causare notevoli problemi in fase di traduzione di un documento. Vedere la Sezione 4.9.1, «Tagging condizionale e traduzione» per una spiegazione di questi problemi.
parametro arch in nodi radice
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: x86 set in the publican.cfg file.
arch al tag <xi:include> in User_Guide.xml, invece che al tag <chapter> in Installation_and_configuration-PPC.xml.
xrefs e parametro arch
<xref> points to content not included in the build due to the arch attribute, the build will fail. For example, with arch: x86 set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="Itanium_installation"> pointing to <section id="Itanium_installation" arch="IA64">.
booksbrew_distdocs-5E. Vedere la Sezione 4.8.2, «The $ publican package command» e la Sezione 5.4, «Creare il pacchetto di un brand» per maggiori informazioni sulla compilazione di pacchetti RPM.
bridgehead_in_toc<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_firstchunk_first: 1. Per impostazione, il valore predefinito è 0, e la prima sezione viene visualizzata nella stessa pagina del proprio capitolo.
chunk_section_depth4.
Esempio 4.1. Controllare il livello di sotto-sezione con chunk_section_depth
classpath/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/usr/share/publican. Su un computer con sistema operativo Windows, la locazione predefinita è %SystemDrive%/%ProgramFiles%/publican — solitamente C:/Program Files/publican.
common_content/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.
conditionNodi root e tag condizionale
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> in User_Guide.xml, e non al tag <chapter> in Installation_and_configuration_on_Fedora.xml.
xref e tag condizionale
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
confidential1 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_textconfidential è impostato ad 1. Il testo predefinito è CONFIDENTIAL.
debug0, Publican non visualizza messaggi. Modificare il valore ad 1 per vedere i messaggi di debug.
def_langsrc_urlimage_right.png nella cartella Common_Content/images del brand. Il valore predefinito è https://fedorahosted.org/publican.
docname<title> nel file Book_Info.xml in fase di costruzione del pacchetto del documento. Questo valore può contenere solo lettere maiuscole/minuscole non accentate, cifre, il carattere trattino basso ed il carattere spazio (‘a–z’, ‘A–Z’, ‘0’–‘9’, e ‘_’ e ‘ ’).
dt_obsoletesdt_requiresdtdverUn DTD differente potrebbe rallentare la compilazione
dtd_typeNota
dtd_uriNota
ec_idorg.prodotto.nomedoc. L'ID impostato determina anche il nome della cartella del plugin, nella cartella plugin.
ec_nameprodotto nomedoc.
ec_providerPublican-version di Publican.
edition<edition> nel file Book_Info.xml in fase di costruzione del pacchetto. Questo valore può contenere solo cifre ed il carattere punto (‘0’–‘9’ e ‘.’).
extras_dirextras)
footergenerate_section_toc_level0, 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
ignored_translationses-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, «Preparare un documento per la traduzione» ed all'Appendice G, Codici di lingua.
img_dirimages)
mainfilelicensemax_image_widthImportante — 444 pixel è la massima larghezza di sicurezza
max_image_width se le immagini contengono importanti informazioni. Le immagini più larghe di 444 pixel potrebbero presentarsi male nei documenti HTML e PDF e rendersi inusabili, in quanto superando i margini esse verrebbero rappresentate incomplete.
mainfile<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.
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.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.fc15 for Fedora 15. Il valore predefinito è .el5, che significa Red Hat Enterprise Linux 5 e sistemi operativi derivati. Fare riferimento alla Sezione 4.8, «Creare il pacchetto di un documento» ed alla Sezione 5.4, «Creare il pacchetto di un brand».
prod_urlimage_left.png nella cartella Common_Content/images del brand. Il valore predefinito è https://fedorahosted.org/publican.
product<productname> nel file Book_Info.xml, durante la creazione del pacchetto. Questo valore può contenere solo lettere maiuscole/minuscole non accentate, cifre, il carattere trattino basso ed il carattere spazio (‘a–z’, ‘A–Z’, ‘0’–‘9’, e ‘_’ e ‘ ’).
release<pubsnumber> nel file Book_Info.xml, durante la creazione del pacchetto. Il valore può contenere solo cifre (‘0’–‘9’).
reporeleaseRevision_History.xml.
scmSVN. Fare riferimento alla Sezione 6.2, «Set distribuiti».
show_remarks<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.
dtdversrc_urlSource: nell'intestazione del file spec dell'RPM. Fare riferimento alla Sezione 4.8, «Creare il pacchetto di un documento».
tmp_dirtmp corrispondente ad una cartella di nome tmp, inclusa nella cartella contenente l'articolo o libro.
tmpl_path/usr/share/publican/templates.
toc_jstoc.tmpl is in. The template name must be must be of the form toc_type+.tmpl
toc_typetoc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
toc_section_depth2. 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
version<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_distdocs-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$ publican package command».
web_homeImportante — web_home è deprecato
web_home è stato sostituito da web_type: home. Supporto a web_home verrà interrotto nelle future versioni di Publican.
web_name_labelweb_obsoletesweb_product_labelweb_style1 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_typeweb_type: home), pagine descrittive di prodotto (web_type: product), e pagine descrittive di versione (web_type: version). Fare riferimento al Capitolo 7, Creare un sito web con Publican.
web_version_labelUNUSED 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.
wkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
Aiuto da riga di comando
$ publican help_config command in the root directory of a book for a summary of these parameters.
Article_Info.xml e Set_Info.xml
Book_Info.xml si applica anche ai file Article_Info.xml e Set_Info.xml. Quindi, per semplificare, nel corso di questa sezione si farà riferimento al file Book_Info.xml.
Altri pacchetti non RPM
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
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.
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.
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.rpmcodice_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.
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 bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY PRODUCT "Publican"> <!ENTITY BOOKID "publican"> <!ENTITY FORMAL-RHI "Red Hat, Inc."> <!ENTITY HOLDER "Red Hat, Inc"> <!ENTITY YEAR "2010"> <!ENTITY D_B "DocBook"> ]> <bookinfo conformance="121" id="book-Users_Guide-Users_Guide"> <title>Guida Utente</title> <subtitle>Pubblicare libri, articoli, relazioni e raccolte di volumi con DocBook XML</subtitle> <productname>Publican</productname> <productnumber>3.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> <corpauthor> <inlinemediaobject> <imageobject> <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> </imageobject> <textobject> <phrase>Team Publican</phrase> </textobject> </inlinemediaobject> </corpauthor> <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" /> </bookinfo>
<bookinfo id="id_libro">, <articleinfo id="id_articolo">, <setinfo id="id_set">$ publican clean_ids command, any manually entered ID, including this one, changes to a Doc_Name-Title format, where Title is the title of the associated book, article, section, or chapter.
<productname>nomeprodotto</productname>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.
product nel file publican.cfg, in particolare se il nome_prodotto contiene caratteri non-latini, caratteri accentati o caratteri di punteggiatura diversi dal trattino basso.
Caratteri permessi
publican.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><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.
docname nel file publican.cfg per impostare il nome del documento in caratteri ASCII. Compilando il documento, il titolo risultante è quello impostato con il tag <title>, mentre per il nome di pacchetto del documento, il valore usato è quello impostato con il parametro docname.
Caratteri permessi
publican.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> 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>Summary del file spec dell'RPM, reso disponibile insieme agli altri campi dello spec file, con il comando rpm -qi.
<productnumber>numeroprodotto</productnumber>$ publican create --name Doc_Name --version version command correctly configures the product number.
version nel file publican.cfg, in particolare se il termine versione di prodotto, non contiene solo cifre.
Caratteri permessi
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>x for pre-release versions of a book). Subsequent editions should increment the 1.x to indicate to readers that the book is a new edition. The edition changes the version number in the file name when building a book with the $ publican package command.
1.2 and building the book using the $ publican package --binary --lang=en-US command creates an RPM file named productname-title-productnumber-en-US-1.2-0.src.rpm$ publican create --name Doc_Name --edition x.y command correctly configures the edition.
edition nel file publican.cfg, in particolare se il termine edizione non contiene solo cifre.
Caratteri permessi
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>$ publican package command. For example, setting the pubsnumber to 1 and building the book using the publican package --binary --lang=en-US command creates an RPM file named productname-title-productnumber-en-US-edition-1.src.rpmrelease nel file publican.cfg, in particolare se il numero di release del documento non contiene solo cifre.
Caratteri permessi
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>Description nel file spec dell'RPM. Ciò rende disponibile l'abstract con il comando rpm -qi.
Book_Info.xml di un documento, a supporto di specifiche proprietà nei vari formati d'uscita:
<keywordset>, <keyword><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><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.
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"><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"> \t<imageobject role="front-large" remap="lrg"> \t\t<imagedata width="600px" format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="front" remap="s"> \t\t<imagedata format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="front-small" remap="xs"> \t\t<imagedata format="PNG" fileref="images/front_cover.png"/> \t</imageobject> \t<imageobject role="thumbnail" remap="cs"> \t\t<imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/> \t</imageobject> </mediaobject>
images.
Book_Info.xml usato da Publican, include un tag <edition>.
Book_Info.xml contiene anche il tag <pubsnumber>. I dati di questo tag modificano il numero di release del pacchetto RPM.
<productnumber>, anch'esso presente in Book_Info.xml: infatti <productnumber> specifica la versione del prodotto documentato o descritto.
<pubsnumber>. Esso ha una funzione molto simile alla ristampa nella editoria tradizionale.
<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.
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'?> <!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <authorgroup> <corpauthor>FF0000 Headgear Documentation Group</corpauthor> <author> <firstname>Dude</firstname> <surname>McDude</surname> <affiliation> <orgname>My Org</orgname> <orgdiv>Best Div in the place</orgdiv> </affiliation> <email>dude.mcdude@myorg.org</email> </author> </authorgroup>
Author_Group.xml non necessariamente deve contenere tutte queste informazioni: inserire a discrezione quelle richieste.
Articoli e Capitoli
--type=article option with $ publican create, Publican does not create a Chapter.xml file. Use sections to organize content within articles.
Chapter.xml file is a template for creating chapter files. Chapter files contain the content that make up a book. The following is a chapter template (Chapter.xml) that is created by the $ publican create command. Note the DOCTYPE is set to 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>
Section 1 Test e Section 2 Test. Per ulteriori informazioni sui capitoli, fare riferimento a http://docbook.org/tdg/en/html/chapter.html della sopra citata guida.
Nota
Installation.xml, mentre un capitolo sull'impostazione di un software sarebbe meglio denominato, Setup.xml o Configuration.xml.
Nome_Doc.xmlxi: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.xmlNome_Doc.xmlDOCTYPE 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>
Book_Info.xml, Preface.xml, Chapter.xml e Appendix.xml.
Importante
Book_Info.xml preceda Preface.xml che a sua volta preceda Chapter.xml, e così via.
Nome_Doc.xmlxi: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> \tA paragraph in Chapter 1. </para> <section id="section1"> <title>Chapter 1 Section 1</title> \t<para> \t\tA paragraph in Section 1. \t</para> </section> <section id="section2"> <title>Chapter 1 Section 2</title> \t<para> \t\tA paragraph in Section 2. \t</para> </section> </chapter> <chapter> <title>Chapter 2</title> <para> \tA paragraph in Chapter 2. </para> </chapter> </book>
Nome_Doc.entYEAR 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.
BOOKID per indicare l'identificativo del documento ai lettori che desiderano inviare commenti.
<!ENTITY PRODUCT "MYPRODUCT"> <!ENTITY BOOKID "MYBOOK"> <!ENTITY YEAR "2008"> <!ENTITY HOLDER "YOUR NAME GOES HERE">
Usare le entità con particolare attenzione
&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à.
<!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.
Liberty Installation and Formatting Tome, ma soltanto &LIFT;, che non possono tradurre.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr ""
#. 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…"
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr ""
#. 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…"
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
&PRODUCT;. Il vantaggio di questo approccio è che cambiando semplicemente questo valore nel file Nome_Doc.entTabella 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 |
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.
Nome_Doc.entimages 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> \t<imagedata fileref="./images/testimage.png" /> </imageobject> <textobject><phrase>alternate text goes here</phrase></textobject> </mediaobject>
<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]
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.
<imagedata>. Per esempio, per impostare una larghezza di 670 pixel:
<imagedata fileref=".images/image.png" width="670px">
Locazioni delle immagini
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.
File PNG in documenti PDF
Aggiungi canale alpha, usare l'opzione Aggiungi trasparenza.
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.
& e <. Se si inserisce un pezzo di codice direttamente in un file XML di un documento, occorre fare l'escaping di questi caratteri, rendendoli CDATA o sostituendoli con entità (& e < rispettivamente).[2] Posizionando questi file nella cartella extras/, non occorre alcun escaping di questi caratteri. Questo approccio risparmia tempo, riduce la possibilità di introdurre errori nell'XML e nel codice; oltre a semplificare il mantenimento del documento e del codice.
extras/, seguire questa procedura:
$mkdiren-US/extras
$cp~/samples/foo.c en-US/extras/.
xi:include
<programlisting> <xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting>
en-US/extras/foo.c nel proprio editor preferito, senza doversi preoccupare di eventuali effetti nell'XML.
<programlistingco> \t<areaspec> \t\t<area id="orbit-for-parameter" coords='4 75'/> \t\t<area id="orbit-for-magnitude" coords='12 75'/> \t</areaspec> \t<programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" \txmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> \t<calloutlist> \t\t<callout id="callout-for-parameter" arearefs="orbit-for-parameter"> \t\t\t<para> \t\t\t\tThe <firstterm>standard gravitational parameter</firstterm> \t\t\t\t(μ) is a derived value, the product of Newton's gravitational \t\t\t\tconstant (G) and the mass of the primary body. \t\t\t</para> \t\t</callout> \t\t<callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"> \t\t\t<para> \t\t\t\tSince the mass of the orbiting body is many orders of magnitude \t\t\t\tsmaller than the mass of the primary body, the mass of the \t\t\t\torbiting body is ignored in this calculation. \t\t\t</para> \t\t</callout> \t</calloutlist> </programlistingco>
<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.
files, e salvarla nella cartella della lingua originale (p.e. en-US) del libro (p.e. My_Book).
My_Book:
$mkdir en-US/files
files:
$cp arbitrary_files en-US/files
$ publican rename command makes it easy for you to rename a document to give it a new title, or to change the name or version of the product to which the document applies. The command accepts up to three options:
--name nuovo_titolo$publican rename --name "Server Deployment Guide"
<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.
$ publican rename command does not change any file names. Therefore, the root XML node and the document entities are still located in files named after the original title of the document — Server_Configuration_Guide in the previous example.
--product nuovo_prodotto$publican rename --product PendantFarm
<productname> in Article_Info.xml, Book_Info.xml o Set_Info.xml.
--version nuova_versione$publican rename --version 2.0
<productnumber> in Article_Info.xml, Book_Info.xml o Set_Info.xml.
$publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0
$publican update_pot
pot. La sottocartella pot contiene un file pot per ciascun file XML nel documento. Se Publican ha creato i file POT precedentemente, Publican aggiorna i file POT esistenti per rispecchiare i cambiamenti apportati ai file XML dall'ultimo aggiornamento dei file POT.
Rimuovere i file XML non usati
$ publican print_unused command to generate a list of XML files that are not used in your document.
$publican update_po --langs=language_code
codice_lingua è il codice per la lingua target. Fare riferimento all'Appendice G, 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,pt-BR,ru-RU,zh-CN
--langs=. La sottocartella contiene un file PO per ciascun file POT nella sottocartella pot. Se Publican ha creato i file PO precedentemente, Publican aggiorna i file PO esistenti per rispecchiare i cambiamenti apportati ai file POT dall'ultimo aggiornamento dei file PO. E' possibile aggiornare i file PO esistenti in tutte le sottocartelle, usando l'opzione --langs=all:
$publican update_po --langs=all
Rimuovere i file POT non usati
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.
$publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
$publican package --lang=is-IS
--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.
Importante — impostare Project-Id-Version per il pacchetto
Project-Id-Version nel file Article_Info.po o Book_Info.po. Per esempio, la release 3 di un libro in lingua giapponese avrebbe la seguente impostazione nel file ja-JP/Book_Info.po:
"Project-Id-Version: 3 "
$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.
Nota — Personalizzare la presentazione
publican.cfg), permettono di controllare molti aspetti riguardanti la presentazione di un documento — fare riferimento a Sezione 4.1.1, «Il file publican.cfg».
--config per specificare il file da usare per una particolare compilazione, per esempio:
$publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
Nome_Doc.entYEAR e HOLDER, come descritto nella Sezione 4.1.6, «Nome_Doc.ent».
Libro_di_Prova e si trova in ~/libri/, eseguire il seguente comando:
$cd ~/books/Test_Book
$publican build --formats=test --langs=en-US
$publican build --formats=formats--langs=languages
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
htmlchunk_first e chunk_section depth nel file publican.cfg, per controllare il tipo di suddivisione delle sezioni in questo formato d'uscita.
html-singlehtml-desktopmanpdftesttxtepubeclipseec_id, ec_name ed ec_provider.
$ publican build commands:
$ publican build --help$ publican build options for building a book.
$ publican build --formats=test --langs=languages--formats=test before running any other $ publican build command, and before checking a book back into a version-controlled repository from which other contributors might download it.
$ publican build --formats=html --langs=languagesNome_Doc/tmp/lingua/html/chunk-section-depth in publican.cfg — fare riferimento alla Sezione 4.1.1, «Il file publican.cfg».
$ publican build --formats=html-single --langs=languagesNome_Doc/tmp/lingua/html-single/$ publican build --formats=pdf --langs=languagesNome_Doc/tmp/lingua/pdf/$ publican build --formats=html,html-single,pdf --langs=languages<xref>s) to sections of the document that do not yet exist. To skip validation, run $ publican build with the --novalid option. Cross-references to non-existent content appear in the built document as three question marks: ???.
--novalid è quantomeno sospetta. Non pubblicare i documenti compilati con l'opzione --novalid.
Altri pacchetti non RPM
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Nota — Personalizzare l'output
publican.cfg) permettono di controllare molti aspetti riguardanti il pacchetto di un documento (Sezione 4.1.1, «Il file publican.cfg»).
--config per specificare il file da usare per una particolare compilazione, per esempio:
$publican package --lang hi-IN --config community.cfg
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.
/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».
web_formats parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"
/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.
.directory) che fornisce i metadati sul nuovo sotto-menu.
.menu) che definisce la posizione del sotto-menu nel menu .
.directory, per documentazione generata da Publican, è la seguente:
[Desktop Entry]
Name, impostato con il nome del sotto-menu da posizionare nel menu .
Name, nel formato Name[codice_lingua], dove codice_lingua è un codice linguistico in formato glibc, non nel formato XML usato da Publican.
Comment, impostato con una descrizione del sotto-menu.
Comment, nel formato Comment[codice_lingua], dove codice_lingua è un codice linguistico in formato glibc, non nel formato XML usato da Publican.
Type, imposto a Directory.
Encoding, impostato a UTF-8.
Esempio 4.5. Esempio di file .directory
menu-example.directory mostra la struttura di un file di desktop entry:
[Desktop Entry] Name=Example Name[fr]=Exemple Name[it]=Esempio Comment=Example Documentation menu Comment[fr]=Exemple d'une menu de documentation Comment[it]=Esempio di un menù di documentazione Type=Directory Encoding=UTF-8
/usr/share/desktop-directories/
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>, contenente:
<Name> contenente Documentation
<Menu> che a sua volta, contiene:
<Name> contenente Documentation (come l'elemento radice)
<Directory> contenente il nome del file di desktop entry creato, per esempio:
<Directory>menu-example.directory</Directory>
<Includes> contenente X-nome_categoria, dove nome_categoria è un identificatore per i documenti da raggruppare nel sotto-menu. Per esempio:
<Includes>X-Example-Docs</Includes>
Esempio 4.6. Esempio di file .menu
menu-example.menu mostra la struttura di un file di desktop menu.
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"> <Menu> <Name>Documentation</Name> <Menu> <Name>Documentation</Name> <Menu> <Name>Example</Name> <Directory>menu-example.directory</Directory> <Include> <Category>X-Example-Docs</Category> </Include> </Menu> </Menu> </Menu>
/etc/xdg/menus/settings-merged/
menu_category nel proprio file publican.cfg, in modo da corrispondere al contenuto dell'elemento <Includes> nel relativo file di desktop menu. Per esempio, si consideri il file di desktop menu, contenente l'elemento:
<Includes>X-Example-Docs</Includes>
publican.cfg del documento, dovrebbe contenere:
menu_category: X-Example-Docs
Importante
__LANG__ with the current language. This allows menus to be customized on a per language basis.
menu_category: X-Example-Docs-__LANG__
defaults.cfg o nel file overrides.cfg di un brand, cosicché tutti i documenti creati con il brand siano automaticamente raggruppati nel sotto-menu, senza dover impostare il parametro menu_category in ogni documento.
dt_requires, nel file publican.cfg del documento. Per esempio, se si distribuisce un pacchetto di desktop-menu di nome foodocs-menu, impostare:
dt_requires: foodocs-menu
defaults.cfg o nel file overrides.cfg di un brand, cosicché tutti i documenti creati con il brand richiedano lo stesso pacchetto di desktop-menu.
$ publican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang option. Refer to Appendice G, Codici di lingua for more information about language codes.
$ publican package with no options other than the mandatory --lang option, Publican produces a web SRPM package. The full range of options for publican package is as follows:
--lang linguaTraduzioni incomplete
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_filepublican.cfg.
--desktop--brew--scratch--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_sightedversion nel file publican.cfg), nel nome del pacchetto.
Omettere il numero di versione del software
--binary$ publican package command, Publican outputs completed SRPM packages to the document's tmp/rpm directory, and completed binary RPM packages to the document's tmp/rpm/noarch directory.
nomeprodotto-titolo-numeroprodotto-[web]-lingua-edizione-numeropubblicazione. build_target.noarch.estensione_file
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:
-web- tra la versione del prodotto ed il codice della lingua.
.src.rpm mentre i pacchetti RPM binari l'estensione .rpm.
build_target.noarchbuild_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.
--short_sighted, rimuove il termine -numeroprodotto- dal nome del pacchetto.
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.
$ publican package --lang=cs-CZ$ publican package --desktop --lang=cs-CZ$ publican package --binary --lang=cs-CZ$ publican package --desktop --binary --lang=cs-CZ$ publican package --desktop --short_sighted --lang=cs-CZ$ condition. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:
<para condition="upstream"> \t<application>Foo</application> starts automatically when you boot the system. </para> \t <para condition="enterprise"> \t<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>. </para>\t \t <para condition="beta"> \t<application>Foo</application> does not start automatically when you boot the system. </para> \t <para condition="beta,enterprise"> \tTo make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file. </para>
$ condition: version parameter to the publican.cfg file and run the $ publican build command as normal. For example, if you add condition: upstream to the publican.cfg file of How To Use Product Foo and run:
$publican build --formats=pdf --langs=en-US
condition="upstream" e compila l'How To Use Product Foo in un file PDF in lingua inglese statunitense.
Nodi root e tag condizionale
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> in User_Guide.xml, e non al tag <chapter> in Installation_and_configuration_on_Fedora.xml.
xref e tag condizionale
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
Usare con cautela il tagging condizionale
#. 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 ""
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.
upstream.cfg file might contain the condition condition: upstream and the enterprise.cfg file might contain the condition condition: enterprise. You could then specify the version of the document to build or package with the --config; for example, $ publican package --lang en-US --config upstream.cfg. Using two separate config files saves you from having to edit the one config file each time you build or package a document.
<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>
show_remarks al file publican.cfg ed impostarlo ad '1':
show_remarks: 1
<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.
Book_Info.xml usato per generare gli RPM, esso garantisce anche che non ci sia alcuna ambiguità nelle operazioni del sottosistema RPM.
Importante
<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.
status="draft" al tag <article>, <book> o <set> nel nodo radice del documento. Per esempio:
<book status="draft">
<book> nel file Nome_Doc.xml<article> o <set>, rispettivamente, nel file Nome_Doc.xmlstatus="draft" causa la comparsa su ciascuna pagina del documento del contrassegno draft.
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).
yum install publican-brand o con un gestore grafico di pacchetti come PackageKit.
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.
$cd publican-brand
brand è il nome del brand.
$publican build --formats xml --langs all --publish
$sudo publican install_brand --pathpath
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
$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. |
$ create_brand action to create a new brand. When you create a new brand, you must give it a name and specify the original language for the brand's XML files. The --name option provides the name, and the --lang option specifies the language. The complete command is therefore:
$publican create_brand --name=brand--lang=language_code
publican-brand, dove brand è il brand specificato con l'opzione --name.
Acme, con i file XML in Common Content redatti in inglese statunitense, eseguire:
$publican create_brand --name=Acme --lang=en-US
publican-Acme.
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' *
$ publican create_brand --name=brand --lang=language_code command creates a directory structure and the required files. The brand directory initially contains:
COPYING
defaults.cfg
overrides.cfg
publican.cfg
publican-brand.spec, dove brand è il nome del brand.
README
en-US). Questi file sono:
Feedback.xml
Legal_Notice.xml
css, contenente:
overrides.css
images, contenente 43 immagini in formato raster o bitmap (PNG) e vettoriale (SVG).
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$ publican create_brand, the version number is set to 0.1. Update the version number here in the brand publican.cfg file and in the publican-brand.spec file when you prepare a new version of the brand.
12 nel proprio file publican.cfg, ma potrebbe essere compilato con la versione 1.0 del brand publican-fedora.
xml_langen-US, as set by the --lang option for $ publican create_brand.
release$ publican create_brand, the release number is set to 0. Update the version number here in the brand publican.cfg file and in the publican-brand.spec file when you prepare a new release of an existing version of the brand.
typetype: brand, questo parametro identifica il contenuto nella cartella come un brand invece che come un libro, articolo o set.
brand--name option for $ publican create_brand.
typeweb_dirwwwdir in publican-brand.spec.
web_reqpublican.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.
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.
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.
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.
banned_tags and banned_attrs respectively to either defaults.cfg or overrides.cfg. These will be listed by the Publican action print_banned.
COPYING contiene i dettagli riguardanti la licenza o COPYRIGHT sul pacchetto e presumibilmente il testo della stessa licenza.
--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 è 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 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 contiene un solo file: overrides.css.
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_leftprod_url del file publican.cfg del documento. Si consideri di impostare prod_url nei file defaults.cfg o overrides.cfg del brand.
image_rightdoc_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_logonote, important, warning<note>, <important> e <warning>.
dot, dot2<listitem> in <itemizedlist>.
stock-go-back, stock-go-forward, stock-go-up, stock-homeh1-bgwatermark_draftxsl in your brand: it sits at the same level as the various language files for your brand. Publican uses any XSL that it finds in that directory to override the XSL templates that we ship in the common brand (which in turn override the XSL templates that the DocBook project ships).
Importante
Altri pacchetti non RPM
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
$ publican package command in the brand directory. When used without any further options, Publican produces an SRPM package. The options for packaging a brand are as follows:
--binary--brew--scratch--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.
--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.
publican-brand-versione-release.build_target.noarch.estensione_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:
.src.rpm mentre i pacchetti RPM di binari hanno estensione .rpm
build_target.noarchbuild_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.
$ create_book command creates a template for a set by setting the type parameter to Set.
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
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 into the My_Set/en-US directory and create two directories (not books) called Book_A and Book_B.
$cdMy_Set/en-US$mkdirBook_ABook_B
$ cd into the books/My_Set/en-US/Book_A directory. Create and edit the Book_A.xml, Book_Info.xml, and any other xml files required for your book such as those required for individual chapters. Ensure that Book_A.xml contains the correct xi:include references to all of your xml files in the directory. For example, if Book A contained Book_Info.xml and Chapter_1.xml, the Book_A.xml file would look like this:
<?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" [ ]> \t <book> \t <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> \t <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> </book>
books/My_Set/en-US/Book_B, come indicato sopra.
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>
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>
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" />
<xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
$ publican build --formats=test --langs=en-US command.
-- 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
-- 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
publican.cfg, la locazione del repository e i titoli dei libri contenuti nel set, ogni libro può essere esportato per creare il set completo. Il seguente procedimento, indica come creare un set denominato My Set contenente il Book A ed il Book B.
Importante
Procedura 6.2. Creare un set
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
publican.cfg:
books: Book_A Book_B
repo: http://PATH-TO-YOUR-SVN-REPOSITORY
scm: SVN
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>
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>
$ publican build --formats=test --langs=en-US command.
Importante
$ publican clean_ids command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.
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.
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.
$mkdir ~/docsite$cd ~/docsite
$ publican create_site, specifying the following parameters:
--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
--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$publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
foomaster.cfg e foomaster.db. Il parametro --toc_path può essere impostato a piacere.
title, per esempio:
title: "Foomaster Documentation"
host, il web host indicando l'URL completo, incluso il protocollo. Per esempio:
host: http://docs.example.com
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.
<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.
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>'
value="###Search###", Publican visualizza il termine Search sul pulsante, ovviamente tradotto in ogni lingua supportata da Publican.
Importante — il parametro search non è validato
search, ma crea il valore di questo parametro nel menu di navigazione, così come specificato. Prestare particolare attenzione nell'usare questa proprietà.
def_lang con il codice linguistico relativo. Per esempio:
def_lang: it-IT
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.
$ publican update_site command is run. Configure the dump, dump_file, and zip_dump parameters as follows:
dumpdump: 1 per abilitare la funzione di file dump. Il parametro, in modo predefinito, è impostato su 0 (disattivato).
dump_filedump_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_dumpzip_dump: 1 per creare anche una versione zippata del file XML. Il parametro, in modo predefinito, è impostato su 0 (disattivato).
manual_toc_update, che le tabelle dei contenuti sono aggiornate manualmente, per esempio:
manual_toc_update: 1
$ publican update_site command.
toc_js parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
toc_path/toc.js with the $ publican update_site command. This path should be relative to the toc_path parameter.
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.2, «Creare, installare ed aggiornare la home page». Se non si usa uno stile specifico, il file vuoto aggiunto impedirà la comparsa dell'errore 404 sul server. Su un sistema Linux, spostarsi nella cartella specificata con l'opzione doc_path ed eseguire:
$touch site_overrides.css
common brand.
$cdbrandsrc_dir
$publican build --formats=xml --langs=all --publish
$publican install_brand --web --path=path_to_site_root_dir
$publican update_site
$publican update_site --site_configpath_to_site_configuration_file.cfg
<article> DocBook ma con un parametro ulteriore web_type: home nel proprio file publican.cfg. Nella sua struttura e presentazione, la home page assomiglia ad un articolo di Publican. Per creare la home page:
$ publican create command:
$publican create --type Article --namepage_name
$publican create --type Article --name Home_Page
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.
$cdpage_name
$cd Home_Page
Article_Info.xml dal file XML radice.
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.
publican.cfg.
web_type ed impostarlo a home:
web_type: home
web_type: home indica di elaborare questo documento non come una documentazione di prodotto. Questa è l'unica modifica necessaria al file publican.cfg. Altre modifiche opzionali al file publican.cfg, frequentemente utili a siti web creati con Publican includono:
brandbrand: nome_di_branddocname, product<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.
nome_pagina.xmlHome_Page.xml) come ogni altro documento DocBook.
<xi:include> che collega a Article_Info.xml, specificare un titolo per la pagina nel formato seguente:
<title role="producttitle">FooMaster Documentation</title>
$ publican update_pot and publican update_po commands.
web_logo.png. Salvare l'immagine nella cartella images/ della directory dei file XML del documento, per esempio, en-US/images/.
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).
--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 --langLanguage_Code
$ publican install_book command.
<article> DocBook con un ulteriore parametro web_type: product o web_type: version nel proprio file publican.cfg. Nella loro struttura e presentazione, le pagine prodotto e quelle di versione sono pressoché identiche ad ogni altro articolo prodotto con Publican. Per creare una pagina prodotto o di versione:
$ publican create command:
$publican create --type Article --namepage_name
$publican create --type Article --name FooMaster
$publican create --type Article --name FooMaster_3
$cdpage_name
$cd FooMaster
Article_Info.xml dal file XML radice.
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.
publican.cfg.
web_type ed impostarlo a product o version:
web_type: product
web_type: version
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:
brandbrand: nome_di_branddocname, product<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.
nome_pagina.xmlFooMaster.xml) come ogni altro documento DocBook.
<xi:include> che collega a Article_Info.xml, specificare un titolo per la pagina nel formato seguente:
<title role="producttitle">FooMaster Documentation</title>
$ publican update_pot and publican update_po commands.
--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 --langLanguage_Code
$ publican install_book command.
$publican build --embedtoc --formats=list_of_formats--langs=language_codes--publish$publican install_book --site_configpath_to_site_configuration_file.cfg --langlanguage_code
$ publican build command for all languages that you want to publish, but must run a separate publican install_book for each language. You must include html as one of the formats in the publican build command; optionally, include any or all of the following formats in a comma-separated list: html-single, pdf, and epub.
$publican remove_book --site_configpath_to_site_configuration_file.cfg --langlanguage_code
Avviso — Questa procedura sostituisce i file
/var/www/html/docs. Quindi usando questa procedura, i file esistenti nella cartella vengono sovrascritti.
$su -
#yum install publican-web publican-$brand-web
/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:
title, per esempio:
title: "Foomaster Documentation"
host come un URL completo, includente il protocollo. Per esempio:
host: http://docs.example.com
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.
<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.
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>'
value="###Search###", Publican visualizza il termine Search sul pulsante, ovviamente tradotto in ogni lingua supportata da Publican.
Importante — il parametro search non è validato
search, ma crea il valore di questo parametro nel menu di navigazione, così come specificato. Prestare particolare attenzione nell'usare questa proprietà.
def_lang con il codice linguistico relativo. Per esempio:
def_lang: it-IT
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.
$ publican update_site command is run. Configure the dump, dump_file, and zip_dump parameters as follows:
dumpdump: 1 per abilitare la funzione di file dump. Il parametro, in modo predefinito, è impostato su 0 (disattivato).
dump_filedump_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_dumpzip_dump: 1 per creare anche una versione zippata del file XML. Il parametro, in modo predefinito, è impostato su 0 (disattivato).
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.2, «Creare, installare ed aggiornare la home page». Se non si usa uno stile specifico, il file vuoto aggiunto impedirà la comparsa dell'errore 404 sul server. Su un sistema Linux, eseguire:
#touch /var/www/html/docs/site_overrides.css
$publican update_site
<article> DocBook ma con un parametro ulteriore web_type: home nel proprio file publican.cfg. Nella sua struttura e presentazione, la home page assomiglia ad un articolo di Publican, il cui pacchetto viene creato allo stesso modo.
$publican package --binary
/tmp/rpms/noarch/ directory of the home page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the home page's publican.cfg file.
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.
<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.
<article> DocBook con un ulteriore parametro web_type: product o web_type: version nel proprio file publican.cfg. Nella loro struttura e presentazione, le pagine prodotto e quelle di versione sono pressoché identiche ad ogni altro articolo prodotto con Publican, i cui pacchetti vengono creati allo stesso modo.
$publican package --binary
/tmp/rpms/noarch/ directory of the product page or version page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the publican.cfg file of the product page or version page.
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.
<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 package --binary --langlanguage_code
/tmp/rpms/noarch/ directory of the document. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the document's publican.cfg file.
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.
<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.
rpm -e o yum erase.
manual_toc_update parameter in the site's configuration file. With this parameter set, you must run the $ publican update_site command after installing, updating, or removing documents. Refer to Sezione 7.1.1, «Creare la struttura del sito web» for more information.
Procedura 7.1. To Submit Your Sitemap to Google:
Procedura 7.2. To Submit Your Sitemap to Bing:
BingSiteAuth.xml file that Bing provides to the document root of your website.
BingSiteAuth.xml file has been uploaded to the required location by accessing it in a web browser, click the button.
$ 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
tmp/en-US/drupal-book/ directory.
/tmp/en-US/drupal-book/ directory. This directory contains the following files:
$product-$version-$docname-$lang-$edition.csv
Important — Use version control system
$ 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.
drupal_authorpublican.cfg file to override it.
Important — Setting Author
drupal_menu_titledrupal_menu_block"user-guide".
Important — Setting menu block
drupal_image_path"sites/default/files/".
/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.
Important — Enable Drupal Core Modules
Permission to install Module
drupal_menu_block parameter in publican.cfg.
sites/default/files/imports/ .
import directory.
import directory will be assigned ownership to this user.
Important — File Ownership
Book Page content type is checked.
Procedura 8.1. To import book into Drupal:
import Directory in the Drupal Server
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, «The publican.cfg file»
Warning — Section Chunking
$ publican update_po --langs=language, where language is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, publican update_po --langs=ja-JP creates the Japanese language directory and Japanese PO files, and publican update_po --langs=ja-JP,ko-KR creates directories and PO files for both Japanese and Korean.
$ publican update_po --langs=es,de,fr?
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.
$ publican update_po --langs=all command.
$ publican build --help command.
$ publican help_config command in a directory that holds any Publican document.
/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.
files nella cartella del linguaggio originale, essa viene inclusa in tutti i tarball o pacchetti SRPM creati da Publican.
Importante
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.
java.lang.NullPointerException senza produzione di file PDF. Cos'è che non va?
$ publican create command. If the problem is not just with one particular document, you probably have a mismatch between the Java Runtime Environment (JRE) and the Java Development Kit (JDK) in use on your system. If you have a JDK installed, FOP requires that the JDK is of the same version as the JRE. Furthermore, FOP cannot use the GNU Compiler for Java (GCJ).
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 javaThere 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 javacThere 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:
alternatives. Per questo problema non è stata determinata una soluzione.
java.lang.NullPointerException ed usare il comando alternatives per assicurarsi di avere JRE e JDK corrispondenti.
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space. Cos'è che non va?
$ 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.
<para> vuoti. E le versioni di Publican correnti?
<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.
#!/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
<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.
<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.pmline 615.cannot create plugin for language 'JAVA'
<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.
sudo yum install bash-completion.
~/.bashrc:
# Use bash-completion, if available if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
source ~/.bashrc.
ulimit -n 8192 to change the limit for the current shell.
/etc/security/limits.conf and add these two lines:
* soft nofile 8192 * hard nofile 8192
Supportato, non supportato e non permesso
$ publican print_known to print a list of tags that Publican supports, and the command publican print_banned to print a list of tags that are banned in Publican.
<caution>, <tip><tip>, <note>, <important>, <caution> e <warning>. Complessivamente, essi rappresentano un insieme di distinzioni a grana molto fine. E' improbabile che queste sottili distinzioni possano applicarsi consistentemente in un documento, in specie quando un documento è redatto o mantenuto da più persone. Inoltre, questo livello di granularità può sembrare insignificante ai lettori. Per progetto, Publican disabilita gli elementi <tip> e <caution>, essendo gli elementi più ridondanti del gruppo.
<note> invece di <tip>, ed usare <important> o <warning> invece di <caution>. Alcuni criteri, in base ai quali selezionare i livelli di severità sono indicati nella sezione ‘Convenzioni del Documento’ della Prefazione dei libri prodotti con il brand predefinito di Publican.
<entrytbl><glossdiv>, <glosslist><glossdiv> che in lingua inglese appare come:
Apple — an apple is…
Grapes — grapes are…
Orange — an orange is…
Peach — a peach is…
Mela — una mela è…
Uva — l'uva è…
Arancia — un'arancia è…
Pera — la pera è…
<inlinegraphic><inlinegraphic> non è valido in DocBook versione 5.
<link><link> offre un generico collegamento ipertestuale e quindi nulla di più dei tag <xref> e <ulink>, rispettivamente, per collegamenti interni ed esterni. Quindi il tag <link> è disabilitato per ridondanza.
<olink><olink> offre riferimenti tra documenti XML. Per usare il tag <olink> per riferimenti ai documenti esterni facenti parte della stessa libreria di file XML, occorre fornire l'URL del documento da collegare. In ambienti che usano il tag <olink>, questi URL possono essere forniti sia con entità XML sia con script server-side. Publican produce documenti di vasta diffusione in cui gli URL sono sempre indispensabili per riferimenti incrociati. Quindi, il tag <olink> non offre alcun vantaggio sul tag <ulink> e perciò per ridondanza, è disabilitato.
<[element] xreflabel="[ogni_altra_stringa]"><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.
<chapter id="ch03" xreflabel="Chapter Three"> \t<title>The Secret to Eternal Life</title> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
<xref> diventa un tag anchor, come indicato di seguito:
…see <a href="#ch03">Chapter Three</a> for details.
<xreflabel>. In questo caso, ciò vuol dire che i lettori delle versioni stampate hanno una perdita di informazione.
<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.
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> \t<title>The Secret to Eternal Life</title> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see >xref linkend="ch03"> for details.
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
<xreflabel>. Il seguente:
<chapter id="ch03"> \t<title>The Secret to Eternal Life</title> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here]\t\t …see <xref linkend="ch03"> for details.
<xref> come segue in formato HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
<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"> \t<title>The Secret to Eternal Life</title> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here]\t\t …see <xref linkend="ch03"> for details.
<xref> è ancora trasformato in un tag anchor come segue:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
<xreflabel>, i tag del titolo e del capitolo, appaiono propriamente tradotti al lettore. Cioè il seguente pezzo:
<chapter id="ch03"> \t<title>The Secret to Eternal Life</title> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here]\t\t …see <xref linkend="ch03"> for details.
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
xreflabel è vietato.
<[element] endterm="[any_string_here]">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.
<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.
<chapter id="The_Secret"> \t<title>The Secret to Eternal Life</title> \t<titleabbrev id="final">the final chapter</titleabbrev> \t<para>The secret to eternal life is…</para> </chapter> [more deathless prose here] The solution is in <xref linkend="The_Secret" endterm="final"/>.
<xref> presente nella versione inglese del documento è:
The solution is inthe final chapter.
<titleabbrev> nel file PO come:
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
<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 ""
<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"/>."
in.
the final chapter in l'ultimo capitolo, il documento risultante si leggerebbe come:
La soluzione è inl'ultimo capitolo.
La soluzione è nell'ultimo capitolo.
in invariata, o una delle sette possibili combinazioni con l'articolo determinativo: nel, nei, nello, nell', negli, nella o nelle.
<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.
endterm, Publican non permette l'uso di questo attributo.
Opzioni di comando
$ publican --help$ publican --man$ publican --help_actions$ publican --v--config filepublican.cfg, predefinito
--nocolours--quietAzioni
$ publican add_revisionRevision_History.xml. Options:
LANGREVNUMBERDATEMEMBERFIRSTNAMESURNAMEEMAIL$ publican buildFORMATSLANGSSRC_DIRPUB_DIR$ publican clean$ publican clean_ids$ publican clean_set$ publican create$ publican create_brandtoc.html di primo livello (necessario)
/usr/share/publican/templates, per impostazione)
$ publican help_configpublican.cfg
$ publican install_brand/usr/share/publican/Common_Content nei Sistemi Operativi Linux e %SystemDrive%/%ProgramFiles%/Publican/Common_Content nei sistemi operativi Windows — tipicamente, C:/Program Files/Publican/Common_Content
$ publican lang_stats$ publican migrate_sitesite_config$ publican package--brew per specificare uno scratch build (irrilevante al di fuori di Red Hat)
$ publican print_tree<xi:include> tag in a book, article, or set.
<imagedata> tag in a book, article, or set.
$ publican renamenome_del_file_di configurazione_del_sito$ publican update_pot$ publican update_ponome_del_file_di_configurazione_del_sito.cfgpdf,html-single
publican update_db --add --lang en-US --formats html,pdf --name Foo \ --name_label "foo is good" --version 0.1 --version_label UNUSED \ --product Bar --product_label "To the bar" \ --subtitle "A guide to Bar Foo" \ --abstract "There once was a Foo from Bar ..." \ --site_config /usr/share/bar/foo.cfg
publican update_db --del --lang en-US --name Foo --version 0.1 --product Bar \ --site_config /usr/share/bar/foo.cfg
publican.cfg nella propria cartella radice. I parametri che possono essere configurati nel file publican.cfg sono:
docname--name
version--version
xml_lang--lang
edition--edition
type<article>, <book> o <set> DocBook, impostato con l'opzione --type
brand--brand
product--product
archbooksbrew_distdocs-5E)
bridgehead_in_tocbridgehead nelle tabelle dei contenuti. (Per impostazione: 0 — bridgehead non sono inclusi)
chunk_first0 — la prima sezione inizia su una nuova pagina HTML)
chunk_section_depth4)
classpath/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/usr/share/publican; nei sistemi operativi Windows: %SystemDrive%/%ProgramFiles%/publican — solitamente C:/Program Files/publican)
common_content/usr/share/publican/Common_Content: nei sistemi operativi Windows: %SystemDrive%/%ProgramFiles%/publican/Common_Content — solitamente C:/Program Files/publican/Common_Content)
conditionconfidential0 — non confidenziale)
confidential_textCONFIDENTIAL)
debug0 — messaggi disabilitati)
def_langen-US — inglese degli Stati Uniti d'America)
doc_urlhttps://fedorahosted.org/publican)
dt_obsoletesdt_requiresdtdver4.5)
dtd_typeNota
dtd_uriNota
ec_idprodotto.nomedoc)
ec_nameprodotto nomedoc)
ec_providerPublican-versione Publican)
extras_dirextras)
generate_section_toc_level0 — nessun indice nelle sezioni)
ignored_translationsimg_dirimages)
mainfilelicensemainfile<article>, <book> o <set>, ed il nome del file .ent corrispondente, che contiene le entità del documento. Per esempio, se si imposta mainfile: master, Publican cerca il nodo XML radice in master.xml e le entità del documento in master.ent.
mainfile non è impostato, Publican cerca il nodo XML radice in un file che corrisponde al <title> del documento in Article_Info.xml, Book_Info.xml o Set_Info.xml, e poi cerca le entità in un file con il nome corrispondente.
max_image_width<imagedata> per una certa immagine. (Per impostazione: 444 — larghezza di 444 pixel)
Importante — 444 pixel è la massima larghezza di sicurezza
max_image_width se le immagini contengono importanti informazioni. Le immagini più larghe di 444 pixel potrebbero presentarsi male nei documenti HTML e PDF e rendersi inusabili, in quanto superando i margini esse verrebbero rappresentate incomplete.
menu_category.menu corrispondente), in cui far comparire un documento quando installato da un pacchetto RPM per desktop. Fare riferimento alla Sezione 4.8.1.3, «Voci nel menu del desktop per i documenti».
src_urlprod_urlhttps://fedorahosted.org/publican)
releasexml_lang, ricavato dal tag title in xml_lang/TYPE_Info.xml o Project-Id-Version in lang/TYPE_Info.po)
reporeleasescmSVN)
show_remarks0 — avvisi non visibili)
os_versrc_urltmp_dirtmp)
toc.html file (mandatory).
toc_section_depth2)
/usr/share/publican/templates).
web_brew_distdocs-5E)
web_formats$ publican package command».
web_homeImportante — web_home è deprecato
web_home è sostituito da web_type: home. Supporto a web_home sarà interrotto in future versioni di Publican.
web_name_labelweb_obsoletesweb_product_labelweb_typeweb_type: home), pagine descrittive di prodotto (web_type: product) e di versione (web_type: version). Vedere il Capitolo 7, Creare un sito web con Publican.
web_version_labelwkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
publican.cfg parameters
archarch: x86_64 in the publican.cfg file, Publican will only include XML elements tagged with the equivalent attribute, such as <para arch="x86_64">.
Use with caution
arch can cause great difficulties when translating documents. Refer to Sezione 4.9.1, «Tagging condizionale e traduzione» for an explanation of the issues.
arch set for root nodes
arch attribute, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration-PPC.xml contains a single chapter:
<?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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: x86 set in the publican.cfg file.
arch attribute to the <xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration-PPC.xml.
xrefs and the arch attribute
<xref> points to content not included in the build due to the arch attribute, the build will fail. For example, with arch: x86 set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="Itanium_installation"> pointing to <section id="Itanium_installation" arch="IA64">.
booksbrandRedHat, fedora, JBoss, oVirt or GIMP , as set by the --brand option for $ publican create. If you do not specify a brand, Publican uses its default brand. Refer to Capitolo 5, Branding for more information.
brew_distdocs-5E. Refer to Sezione 4.8.2, «The $ publican package command» and Sezione 5.4, «Creare il pacchetto di un brand» for more information on building RPM packages.
bridgehead_in_toc<bridgehead> elements (free-floating titles) should be included among other titles (such as section titles and chapter titles) in tables of contents. To enable this feature, set bridgehead_in_toc: 1. Otherwise, the parameter defaults to 0, and <bridgehead>s are not included in tables of contents.
chunk_firstchunk_first: 1. Otherwise, the parameter defaults to 0, and the first section appears on the same page of its chapter.
chunk_section_depth4.
Esempio D.1. Controlling the section depth with chunk_section_depth
classpath/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/usr/share/publican. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican — most usually C:/Program Files/publican.
common_content/usr/share/publican/Common_Content. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican/Common_Content — most usually C:/Program Files/publican/Common_Content.
conditionNodi root e tag condizionale
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>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> in User_Guide.xml, e non al tag <chapter> in Installation_and_configuration_on_Fedora.xml.
xref e tag condizionale
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
confidential1, Publican adds the text specified by the confidential_text parameter (by default, CONFIDENTIAL) to the foot of each HTML page and the head of every page in a PDF document. The default value is 0 (no header or footer).
confidential_textconfidential parameter is set to 1. The default text is CONFIDENTIAL.
debug0, Publican does not display debugging messages. Change this value to 1 to view these messages.
def_langdoc_urlimage_right.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican
docname<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_obsoletesdt_requiresdtdverA different DTD might slow your build
dtd_typeNota
dtd_uriNota
ec_idorg.product.docname. The ID that you set here also determines the directory name for this plugin in the plugin directory.
ec_nameproduct docname.
ec_providerPublican-Publican version.
edition<edition> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
extras_dirextras)
footergenerate_section_toc_level0, Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections. If (for example) the value is set to 1, tables of contents also appear in each "level 1" section, such as sections 1.1, 1.2, 2.1, and 2.2. If set to 2, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.
Esempio D.2. Setting the section depth at which tables of contents appear
ignored_translationses-ES,it-IT. If you build or package a book for a language filtered by this parameter, Publican ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to Sezione 4.6, «Preparare un documento per la traduzione», and to Appendice G, Codici di lingua.
img_dirimages)
info_filelicensemax_image_widthImportante — 444 pixel è la massima larghezza di sicurezza
max_image_width se le immagini contengono importanti informazioni. Le immagini più larghe di 444 pixel potrebbero presentarsi male nei documenti HTML e PDF e rendersi inusabili, in quanto superando i margini esse verrebbero rappresentate incomplete.
mainfile<article>, <book>, or <set>, and the name of the corresponding .ent file that contains the document's entities. For example, if you set mainfile: master, Publican looks for the root XML node in master.xml and the document entities in master.ent.
mainfile is not set, Publican looks for the root XML node in a file that matches the <title> of the document set in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and looks for the document entities in a file with a corresponding name.
menu_category.menu file) in which a document should appear when installed from a desktop RPM package. Refer to Sezione 4.8.1.3, «Voci nel menu del desktop per i documenti».
os_ver.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_urlimage_left.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican.
product<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<pubsnumber> in the Book_Info.xml file when you package a document. This value must include only digits (‘0’–‘9’).
reporev_fileRevision_History.xml.
scmSVN as its default setting. Refer to Sezione 6.2, «Set distribuiti».
show_remarks<remark>s in transformed output. By default, this value is set to 0, which causes Publican to hide remarks. Set this value to 1 to display remarks. In Publican's common brand, displayed remarks are highlighted in magenta.
sort_ordersrc_urlSource: field in the header of an RPM spec file. Refer to Sezione 4.8, «Creare il pacchetto di un documento».
tmp_dirtmp, which creates a directory named tmp inside the directory that holds your article or book.
tmpl_path/usr/share/publican/templates.
toc_jstoc.tmpl is in. The template name must be must be of the form toc_type+.tmpl
toc_typetoc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
toc_section_depth2. With the default setting, sections 1.1 and 1.1.1 will appear in the main table of contents, but section 1.1.1.1 will not. (Note that the first digit in these examples represents a chapter, not a section).
Esempio D.3. Controlling the depth of sections in the main table of contents
type<article>, DocBook <book>, or DocBook <set>, as set by the --type option for $ publican create.
version<productnumber> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
web_brew_distdocs-5E, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Sezione 4.8, «Creare il pacchetto di un documento».
web_formats$ publican package command».
web_homeImportant — web_home is deprecated
web_home is replaced by web_type: home. Support for web_home will be removed in a future version of Publican.
web_name_labelweb_obsoletesweb_product_labelweb_style1 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_typeweb_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_labelUNUSED for general documentation that does not apply to any particular version of a product. Refer to Capitolo 7, Creare un sito web con Publican.
wkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
xml_langen-US, as set by the --lang option for $ publican create.
<host>host, nel file di configurazione del sito.
<def_lang>def_lang, nel file di configurazione del sito.
<name><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><abstract><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>html per html in pagine multiple, html-single per html in pagina singola, pdf per PDF ed epub per EPUB.
<language><name_label>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><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>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.
UNUSED, non viene visualizzata alcuna intestazione nella tabella dei contenuti del sito.
<subtitle><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><version><productnumber> in Book_Info.xml, Article_Info.xml o Set_Info.xml, se non generata dal parametro version nel file publican.cfg.
<version_label>web_version_label nel file publican.cfg del documento.
UNUSED, non viene visualizzata alcuna intestazione per questa versione del prodotto, nella tabella dei contenuti del sito.
Esempio E.1. Record d'esempio da un file DUMP.xml
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>
<host>
<name>
<format>
<language>
<product>
<version>
<host>/<language>/<product>/<version>/<format>/<name>/index.html
http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
<host>/<language>/<product>/<version>/<format>/<name>/index.html
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
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
http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub
<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.
.directory) ed un file di desktop menu (file .menu). Fare riferimento alla Sezione 4.8.1.3, «Voci nel menu del desktop per i documenti», per la struttura di questi file.
menu-example.directory ed un file desktop-menu, menu-example.menu, con un file README localizzati in una cartella di nome menu-example-0, archiviata come menu-example-0.tgz.
Name: menu-example
Version: 0
Release: 8%{?dist}.t1
Summary: Example of how to do a documentation menu package
Group: Development/Tools
License: GPLv2+
URL: http://engineering.redhat.com
Source0: %{name}-%{version}.tgz
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildArch: noarch
%description
Example of how to do a documentation menu package
%prep
%setup -q
%build
%install
rm -rf %{buildroot}
mkdir -p $RPM_BUILD_ROOT%{_datadir}/desktop-directories
mkdir -p $RPM_BUILD_ROOT/etc/xdg/menus/settings-merged
install -m644 menu-example.directory $RPM_BUILD_ROOT%{_datadir}/desktop-directories/menu-example.directory
install -m644 menu-example.menu $RPM_BUILD_ROOT%{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu
%{_fixperms} $RPM_BUILD_ROOT/*
%clean
rm -rf %{buildroot}
%files
%defattr(-,root,root,-)
%doc README
%{_datadir}/desktop-directories/menu-example.directory
%config(noreplace) %{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu
%changelog
* Tue Nov 23 2010 Jeff Fearn <jfearn@redhat.com> 0-8
- Creation
Subtag di nazione
Altri codici linguistici
@ 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.
lingua-script-regione-variantex- e non necessita di registrazione. Subtag private-use a parte, un subtag è valido se è presente nel registro dei subtag mantenuti dall'IETF, attraverso l'autorità IANA (Internet Assigned Numbers Authority).[7] Sebbene Publican accetti ogni tag linguistico valido, secondo le regole stabilite nel BCP 47, esso è progettato con l'assunzione che i tag linguistici, per i documenti, assumano la forma lingua-nazioneit (italiano), hi (hindi), es (spagnolo) ed en (inglese). Dove non esiste un codice di due lettere nell'ISO 639-1, il subtag linguistico solitamente è identico al codice specificato nell'ISO 639-2,[9] per esempio bal (baluchi: lingua iranica), apk (kiowa apache: lingua apache delle pianure) e tpi (Tok Pisin: lingua della Papua Nuova Guinea). Infine, un piccolo numero di subtag linguistici presenti nel registro presso l'IANA, sono privi di codici corrispondenti sia in ISO 639-1 sia in ISO 639-2, come i subtag per le lingue inventate qya (quenya: lingua elfica inventata da J.R.R.Tolkien) e tlh (klingon: lingua extraterrestre della serie Star Trek), e per la lingua occulta i-enochian (enochiano: lingua degli angeli inventata da E.Kelley). Quest'ultimo esempio, mostra anche un ristretto numero di subtag linguistici eccezionalmente inseriti nel registro, senza corrispondere al modello delle due o tre lettere derivato dagli standard ISO 639.
Subtag estesi di lingua
yue, rappresentante la lingua cantonese, deve essere usato sempre con il subtag associato (cinese), quindi: zh-yue. L'IETF non riconosce l'RFC 5646 come la "Miglior Regola d'Arte", e nemmeno questi tag fanno già parte dello standard XML.
sr-Latn rappresenta la lingua serba scritta con l'alfabeto latino, mentre sr-Cyrl rappresenta ancora la lingua serba ma scritta con l'alfabeto cirillico; quindi az-Arab e az-Cyrl rappresentano la lingua azera (dell'Azerbaijani), scritta rispettivamente, in alfabeto arabo e cirillico. D'altro canto, l'italiano non ha bisogno di specificare it-Latn in quanto, comunemente nel mondo, l'italiano è scritto solo con l'alfabeto latino.
IT (Italia), TZ (Tanzania) e VE (Venezuela). I tag di tre cifre si basano su quelli definiti in UN M.49, [13] per esempio, 015 (Nord Africa), 061 (Polynesia) e 419 (America latina e Caraibi).
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]
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).
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.
| Diario delle Revisioni | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Revisione 3.2-1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
| Revisione 3.2-0.1 | Wed Jul 10 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 | ||||||||||
| |||||||||||