Copyright © 2013 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).
Résumé
Cet ouvrage vous aide à installer Publican. Il donne aussi des instructions pour l'utilisation de Publican en vue de créer et publier des ouvrages, des articles ou des ensembles de livres à l'aide du XML DocBook. Ce guide suppose que vous connaissez déjà le XML DocBook.
Ce manuel utilise plusieurs conventions pour souligner l'importance de certains mots ou expressions, mais aussi en vue d'attirer l'attention sur certains passages d'informations précis.
Quatre conventions typographiques sont utilisées pour attirer l'attention sur certains mots et expressions. Ces conventions et les circonstances auxquelles elles s'appliquent sont les suivantes.
Caractères gras à espacement fixe
Utilisé pour surligner certaines entrées du système, y compris les commandes shell, les noms de fichiers et les chemins d'accès. Également utilisé pour surligner les touches et les combinaisons de touches. Par exemple :
Pour consulter le contenu du fichier
mon_nouvel_ouvrage_littéraire
qui se situe dans votre dossier courant, saisissez la commande cat mon_nouvel_ouvrage_littéraire à la demande du terminal et appuyez sur Entrée pour exécuter la commande.
L'exemple ci-dessus contient un nom de fichier, une commande shell et une touche, tous présentés sous forme de caractères gras à espacement fixe et tous bien distincts grâce au contexte.
Les combinaisons de touches se distinguent des touches individuelles par le signe « plus », qui connecte les différentes parties de la combinaison. Par exemple :
Appuyez sur Entrée pour exécuter la commande.
Appuyez sur Ctrl+Alt+F2 pour basculer sur un terminal virtuel.
Le premier exemple présente une touche particulière sur laquelle appuyer. Le second exemple affiche une combinaison de touches : un ensemble de trois touches sur lesquelles il faut appuyer simultanément.
Si le code source est mentionné, les noms de classes, les méthodes, les fonctions, les noms de variables et les valeurs de retour citées dans un paragraphe seront présentées comme ci-dessus, en caractères gras à espacement fixe
. Par exemple :
Les classes de fichiers comprennent le nom de classe
filesystem
pour les noms de fichier,file
pour les fichiers etdir
pour les dossiers. Chaque classe correspond à un ensemble de permissions associées.
Caractères gras proportionnels
Cette convention marque le surlignage des mots ou phrases que l'on rencontre sur un système, comprenant des noms d'application, des boîtes de dialogue textuelles, des boutons étiquettés, des cases à cocher et des boutons d'options mais aussi des intitulés de menus et de sous-menus. Par exemple :
Sélectionnez Préférences de la souris. À partir de l'onglet Boutons, cliquez sur la case à cocher Pour gaucher puis cliquez sur pour faire passer le bouton principal de la souris de la gauche vers la droite (ce qui permet l'utilisation de la souris par la main gauche).
→ → à partir de la barre du menu principal pour lancer lesPour insérer un caractère spécial dans un fichier gedit, choisissez → → depuis la barre du menu principal. Ensuite, choisissez → depuis la barre du menu Table des caractères, saisissez le nom du caractère dans le champ Recherche puis cliquez sur . Le caractère recherché sera surligné dans la Table des caractères. Double-cliquez sur le caractère surligné pour le placer dans le champ Texte à copier, puis cliquez sur le bouton . Vous pouvez désormais revenir à votre document et choisir → depuis la barre du menu gedit.
Le texte ci-dessus contient des noms d'applications, des noms de menus et d'autres éléments s'appliquant à l'ensemble du système, des boutons et textes que l'on trouve dans une interface graphique. Ils sont tous présentés sous la forme gras proportionnel et identifiables en fonction du contexte.
Italique gras à espacement fixe ou Italique gras proportionnel
Qu'ils soient en caractères gras à espacement fixe ou à caractères gras proportionnels, l'ajout de l'italique indique la présence de texte remplaçable ou variable. Les caractères en italique indiquent la présence de texte que vous ne saisissez pas littéralement ou de texte affiché qui change en fonction des circonstances. Par exemple :
Pour se connecter à une machine distante en utilisant ssh, saisissez ssh nom d'utilisateur@domain.name (nom.domaine) après l'invite de commande de la console. Si la machine distante est
exemple.com
et que votre nom d'utilisateur pour cette machine est john, saisissez ssh john@example.com.La commande mount -o remount système de fichiers monte le système de fichiers nommé. Ainsi, pour monter
/home
dans le système de fichiers, la commande est mount -o remount /home.Pour connaître la version d'un paquet actuellement installé, utilisez la commande rpm -q paquet. Elle vous permettra de retourner le résultat suivant : version-de-paquet.
Remarquez que les mots en gras italique ci-dessus — username (nom d'utilisateur), domain.name (nom.domaine), file-system (système de fichiers), package (paquetage), version et release (sortie commerciale). Chaque mot est un espace réservé au texte, soit pour le texte que vous entrez lors de la saisie d'une commande, soit pour le texte affiché par le système.
Mis à part l'utilisation habituelle de présentation du titre d'un ouvrage, les caractères italiques indiquent l'utilisation initiale d'un terme nouveau et important. Ainsi :
Publican est un système de publication DocBook.
Les sorties de terminaux et les citations de code source sont mis en avant par rapport au texte avoisinant.
Les sorties envoyées vers un terminal sont en caractères Romains à espacement fixe
et présentées ainsi :
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Les citations de code source sont également présentées en romains à espacement fixe
mais sont présentés et surlignés comme suit :
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")); } }
Enfin, nous utilisons trois styles visuels pour attirer l'attention sur des informations qui auraient pu être normalement négligées :
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Tips are tips, shortcuts or alternative approaches to the task at hand. Ignoring a tip should have no negative consequences, but you might miss out on a trick that makes your life easier.
Les blocs d'informations importantes détaillent des éléments qui pourraient être facilement négligés : des modifications de configurations qui s'appliquent uniquement à la session actuelle ou des services qui ont besoin d'être redémarrés avant toute mise à jour. Si vous ignorez une case étiquetée « Important », vous ne perdrez aucunes données mais cela pourrait être source de frustration et d'irritation.
Un avertissement ne devrait pas être ignoré. Ignorer des avertissements risque fortement d'entrainer des pertes de données.
Un avertissement ne devrait pas être ignoré. Ignorer des avertissements risque fortement d'entrainer des pertes de données.
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: https://bugzilla.redhat.com/enter_bug.cgi?product=Publican&component=Publican%20Users%20Guide&version=4.1.
Si vous voulez faire une suggestion d'amélioration de la documentation, soyez le plus précis possible pour la décrire. Si vous avez trouvé une erreur, veuillez préciser le numéro du paragraphe et quelques mots du texte environnant pour nous faciliter sa recherche.
Publican est un outil pour publier des documents créés en XML DocBook. Ce guide explique comment créer et construire des ouvrages et des articles en utilisant Publican. Ce guide n'est pas un tutoriel général concernant le XML DocBook ; reportez-vous à DocBook: The Definitive Guide (Docbook : un guide décisif) par Norman Walsh et Leonard Muellner, disponible à l'adresse http://www.docbook.org/tdg/en/html/docbook.html pour une aide plus générale à propos du XML DocBook.
Publican a débuté en tant qu'outil interne utilisé par le Groupe Documentation de Red Hat (connu aujourd'hui sous le nom de « Engineering Content Services » (Services d'ingénierie des contenus documentaires). Parfois, cet héritage est encore apparent.
Conception. Publican est un système de publication, pas seulement un outil de traitement du Docbook. De même que Publican s'assure que votre XML Docbook est valide, il travaille à garantir que votre XML satisfasse à des normes de parution.
La fonctionnalité estampillage permet de créer vos propres standards de présentation et d'affichage ; ils prennent le pas sur les nombreux styles par défaut pour satisfaire vos besoins en matière de publication. Les choix fixés dans le code ne sont, toutefois, pas modifiables.
Des entités, par exemple, peuvent être valablement définies dans tout fichier XML. Mais, pour s'assurer que la déclaration de DTD est présente, valide et normalisée, Publican réécrit cette déclaration dans chaque fichier XML avant de construire l'ouvrage ou l'article. Par conséquent, toute entité déclarée dans n'importe quel fichier XML est perdue. Ainsi, Publican demande que vous définissiez les entités dans le fichier Nom_document.ent
(reportez-vous à la Section 4.1.6, « Nom_document.ent »).
Au fur et à mesure de l'avancement du travail de rédaction, la définition incontrôlée d'entités conduit à des doublons ou autres pratiques à l'origine de difficultés de maintenance. Rassembler les définitions d'entité dans un seul et même endroit bien identifié prévient ces problèmes de maintenance et favorise la robustesse du processus de construction.
Les entités sont également un obstacle quelquefois insurmontable pour des traductions de qualité (reportez-vous à la Section 4.1.6.1, « Entités et traductions »). En conséquence, sans vouloir restreindre les fonctionnalités associés au fichier Nom_document.ent
, nous ne prenons plus en considération les demandes d'ajout de fonctionnalités ou particularités en liaison avec l'utilisation des entités.
#!/usr/bin/perl use strict; use warnings; print "Hello, World!\n";
#include <iostream> int main() { std::cout << "Hello World!"; &lies; }
[Show All][Hide]$
apt-get search libxsltgambas3-gb-xml-xslt - Gambas XSLT component
libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
libical-parser-html-perl - generates HTML calendars from iCalendars
libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
libxml-libxslt-perl - Perl interface to the GNOME libxslt library
libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
libxslt1-dev - XSLT 1.0 processing library - development kit
libxslt1.1 - XSLT 1.0 processing library - runtime library
python-libxslt1 - Python bindings for libxslt1
python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
python-lxml - pythonic binding for the libxml2 and libxslt libraries
python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
python3-lxml - pythonic binding for the libxml2 and libxslt libraries
python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
php5-xsl - XSL module for php5
libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
swfmill - xml2swf and swf2xml processor
libxslthl-java - XSLT syntax highlighting
Test a programlisting with a calloutlist
Exemple 1. "Hello world!" in C++
#include <qpid/messaging/Connection.h> #include <qpid/messaging/Message.h> #include <qpid/messaging/Receiver.h> #include <qpid/messaging/Sender.h> #include <qpid/messaging/Session.h> &BZ1101050; #include <iostream> using namespace qpid::messaging; int main(int argc, char** argv) { std::string broker = argc > 1 ? argv[1] : "localhost:5672"; std::string address = argc > 2 ? argv[2] : "amq.topic"; Connection connection(broker); try { connection.open(); 1 Session session = connection.createSession(); 2 Receiver receiver = session.createReceiver(address); 3 Sender sender = session.createSender(address); 4 sender.send(Message("Hello world!")); Message message = receiver.fetch(Duration::SECOND * 1); 5 std::cout << message.getContent() << std::endl; session.acknowledge(); 6 connection.close(); 7 return 0; } catch(const std::exception& error) { std::cerr << error.what() << std::endl; connection.close(); return 1; } }
Establishes the connection with the messaging broker.
Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.
Creates a receiver that reads from the given address.
Creates a sender that sends to the given address.
Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.
Acknowledges messages that have been read. To guarantee delivery, a message remains on the messaging broker until it is acknowledged by a client. session.acknowledge() acknowledges all unacknowledged messages for the given session—this allows acknowledgements to be batched, which is more efficient than acknowledging messages individually.
Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.
And now we test a programlistingco with an areaspec
<list-index column="column_name" 1 base="0|1|..."/> 2
column_name
(required): the name of the column holding the collection index values.
base
(optional - defaults to 0
): the value of the index column that corresponds to the first element of the list or array.
Is there a newline inserted after this CDATA
?
=, >, >=, <, <=, <>
!=
<>
package com.sample; import org.kie.api.runtime.process.WorkItem; import org.kie.api.runtime.process.WorkItemHandler; import org.kie.api.runtime.process.WorkItemManager; public class NotificationWorkItemHandler implements WorkItemHandler { public void executeWorkItem(WorkItem workItem, WorkItemManager manager) { String from = (String) workItem.getParameter("From"); String to = (String) workItem.getParameter("To"); String message = (String) workItem.getParameter("Message"); String priority = (String) workItem.getParameter("Priority"); // send email EmailService service = ServiceRegistry.getInstance().getEmailService(); service.sendEmail(from, to, "Notification", message); 1 // notify manager that work item has been completed manager.completeWorkItem(workItem.getId(), null); } 2 public void abortWorkItem(WorkItem workItem, WorkItemManager manager) { // Do nothing, notifications cannot be aborted } }
The ServiceRegistry
class is an example class implementing the task business logic.
The completeWorkItem()
call completes the work item execution.
<?xml version="1.0" encoding="UTF-8"?><test></test>
Les procédures documentées dans ce paragraphe présupposent que Publican et ses diverses dépendances sont disponibles dans les dépôts auxquels votre système a accès.
Ouvrez un terminal.
Basculez sur l'utilisateur administrateur : su -
Exécutez la commande suivante pour installer le paquet publican et le paquet de documentation publican-doc :
$
yum install publican\*
Plusieurs paquets d'estampillage sont prêts à être utilisés avec Publican. Exécutez la commande ci-après en tant qu'administrateur pour installer les paquets de construction de fascicules marqués :
$
yum install publican-marque
Remplacez estampille, par exemple, par redhat
, fedora
, jboss
, ovirt
ou gimp
. Reportez-vous au Chapitre 5, Estampillage pour plus d'informations sur l'estampillage.
Ouvrez un terminal.
Exécutez la commande suivante pour installer le paquet publican :
$
sudo apt-get install publican
Cette procédure installe la version de publican dans votre dépôt Debian par défaut. Elle installe aussi un grand nombre de paquets dont publican dépend, comme Java, XML et les librairies de traitement de l'image, de même que des modules Perl auxiliaires.
Ouvrez un terminal.
Devenez administrateur : su -
Pour installer le paquet publican, lancez la commande :
$
apt-get install publican
Pour déterminer la version de publican installée, exécutez :
$
publican -vversion=2.8
Si vous avez besoin d'un version plus récente de publican que celle installée par la procédure ci-dessus, vous pouvez rechercher s'il y a d'autres versions disponibles : http://packages.debian.org/publican.
To date, there has not been any backport (http://backports.debian.org/Instructions/) available for publican, so we need to use Apt Pinning https://wiki.debian.org/AptPreferences
Autrement, vous pouvez lancer Debian en test ou instable dans une machine virtuelle, à partir d'une nouvelle racine (chroot) ou dans un conteneur Linux.
En supposant qu'il y ait une version plus récente de publican disponible dans le dépôt de test, et que vous utilisez la version stable actuelle, vous pouvez alors la mettre à niveau ainsi :
Ouvrez un terminal.
Devenez administrateur : su -
Ouvrez le fichier /etc/apt/sources.list
dans un traitement de texte. Par exemple, pour modifier le fichier dans gedit, exécutez :
$
gedit /etc/apt/sources.list
Ajoutez la ligne ci-après à la fin du fichier :
#### testing ######### deb http://ftp.us.debian.org/debian testing main contrib non-free
Sauvegardez le fichier et fermez le logiciel de traitement de texte.
Ouvrez (ou créez) le fichier /etc/apt/preferences
dans un traitement de texte. Par exemple, pour modifier le fichier dans gedit, exécutez :
$
gedit /etc/apt/preferences
Ajoutez la ligne ci-après à la fin du fichier :
Package: * Pin: release a=stable Pin-Priority: 900 Package: * Pin: release a=testing Pin-Priority: 400 Package: * Pin: release o=Debian Pin-Priority: -10
Sauvegardez le fichier et fermez le logiciel de traitement de texte.
Lancez la commande suivante pour mettre à jour la liste des paquets disponibles pour votre ordinateur :
$
apt-get update
Lancez la commande suivant pour essayer d'installer la version en test du paquet publican, ainsi que toutes les dépendances mises à jour :
$
apt-get -t testing install publican
Comme Apt Pinning mélange 2 flux Debian différents de manière non-testée, des incompatibilités peuvent survenir. Par exemple, vous pouvez obtenir un avertissement comme :
ce qui indique que vous aurez peut-être besoin de mettre à jour libxml2 et libxslt avec la version du dépôt de test également. Ce qui s'effectue en recherchant la bibliothèque possible :$
publicanWarning: program compiled against libxml 209 using older 208
Warning: XML::LibXML compiled against libxml2 20901, but runtime libxml2 is older 20800
Warning: program compiled against libxml 209 using older 208
Warning: XML::LibXSLT compiled against libxslt 10128, but runtime libxslt is older 10126
Can't open publican: No such file or directory at /usr/bin/publican line 430.
[Show All][Hide](et à nouveau la même chose pour libxml2)$
apt-get search libxsltgambas3-gb-xml-xslt - Gambas XSLT component
libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
libical-parser-html-perl - generates HTML calendars from iCalendars
libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
libxml-libxslt-perl - Perl interface to the GNOME libxslt library
libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
libxslt1-dev - XSLT 1.0 processing library - development kit
libxslt1.1 - XSLT 1.0 processing library - runtime library
python-libxslt1 - Python bindings for libxslt1
python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
python-lxml - pythonic binding for the libxml2 and libxslt libraries
python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
python3-lxml - pythonic binding for the libxml2 and libxslt libraries
python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
php5-xsl - XSL module for php5
libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
swfmill - xml2swf and swf2xml processor
libxslthl-java - XSLT syntax highlighting
puis en mettant à jour ces paquets pour le test.
$
apt-get -t testing upgrade libxml2 libxslt1.1
Publican ne pouvait pas être utilisé sur OpenSuse avant la parution de sa version 12.1. Certaines dépendances manquaient et n'étaient disponibles dans aucun dépôt OpenSuse connu. Ce n'est plus le cas avec OpenSuse 12.1 ; toutes les dépendances sont maintenant disponibles et peuvent être installées.
Les directives suivantes décrivent l'installation de Publican à partir des sources, car, jusqu'à ce jour, il n'y a pas de RPM de Publican pour OpenSuse 12.1. La version de Publican est la 2.9, directement prise dans le dépôt source — les versions antérieures n'ont pas été testées, mais pourraient fonctionner.
Au moment de la rédaction de ce guide, Publican 2.8 était la version publiée et les travaux sur la 2.9 étaient encore en cours. Pour cette raison, les instructions ci-après sont sujettes à modifications.
L'installation de OpenSuse est celle par défaut avec, en plus, l'ajout des catégories de logiciels suivantes au moment de l'installation :
Technical Writing — pour les outils Docbook etc.
Perl Development
Serveur Web et LAMP
Le système utilisé avait KDE installé ; cela ne doit pas amener de différences. Les familles suivantes de logiciels propres à KDE étaient également installées :
KDE Development
Desktop Effects
Enfin, la catégorie Jeux avait été supprimée.
Une fois l'installation de OpenSuse terminée, et toutes les mises à jour disponibles appliquées, les étapes suivantes ont été suivies pour installer Publican.
Ouvrir une session de terminal.
Installer les dépendances disponibles à partir des divers dépôts en ligne — nombres de celles-ci ne sont pas présentes dans le dépôt du DVD d'installation.
$
sudo zypper install perl-Config-Simple perl-DateTime \
perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \
perl-File-Find-Rule perl-File-Which perl-HTML-Format \
perl-Locale-MakeText-Gettext perl-Template-Toolkit \
perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \
perl-YAML liberation-fonts
Liberation-fonts
est très vraisemblablement déjà installé, mais il est nécessaire. Zypper ne le réinstallera pas si c'est déjà fait.
Utiliser cpan pour installer les dépendances restantes qui ne peuvent pas être installées à l'aide de zypper :
$
sudo sh
cpan File::pushd File::Copy::Recursive Locale::PO pp \
Syntax::Highlight::Engine::Kate XML::TreeBuilder
exit
Télécharger le code source :
$
cd ~
mkdir -p SourceCode/publican
cd SourceCode/publican
svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./
Créer le script de construction de Publican :
$
perl Build.PL
Si toutes les dépendances ont été installées, vous devez voir ceci :
WARNING: the following files are missing in your kit:
META.yml
Please inform the author.
Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Publican' version '2.9'
Si ce n'est pas le cas, utiliser cpan (en tant qu'administrateur) pour installer les modules manquants et lancer la construction à nouveau. Remplacez toute barre inclinée « / » par deux fois deux-points « :: » et faites attention à utiliser exactement la même casse pour les lettres, par exemple : si File/pushd.pm
est signalé manquant, utiliser ceci pour l'installer :
$
sudo sh
cpan File::pushd
exit
En supposant que tout a bien fonctionné, le script Build.PL
doit avoir créé un nouveau script nommé Build
à utiliser pour créer, tester et installer Publican 2.9.
$
./Build
Une bonne quantité de textes vont dérouler à l'écran pendant quelques minutes ; vous verrez éventuellement :
DEBUG: Publican::Builder: end of build
Testez la construction :
$
./Build test
À nouveau, déroulement de texte à l'écran, puis vous devez voir :
Test Summary Report
-------------------
t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)
Failed test: 5
Non-zero exit status: 1
t/pod-coverage.t (Wstat: 256 Tests: 9 Failed: 1)
Failed test: 7
Non-zero exit status: 1
Files=10, Tests=68, 420 wallclock secs ( 0.31 usr 0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)
Result: FAIL
Failed 2/10 test programs. 2/68 subtests failed.
Pas de souci. Ceci est dû à l'absence de l'utilitaire wkhtmltopdf ; ces tests préparatoires ont été ajoutés à Publican en prévision du remplacement de l'application FOP de Apache comme outil de création des pdf. Si Publican trouve wkhtmltopdf, il l'utilise, sinon il se sert de FOP.
Malheureusement, au moment de la rédaction, comme OpenSuse désigne une des dépendances de wkhtmltopdf sous un nom différent (ghostscript-fonts-std
vs ghostscript-fonts
), wkhtmltopdf ne fonctionnera pas même en cas d'installation forcée sans vérification des dépendances.
Installer wkhtmltopdf.
Cette étape est facultative. Au moment de la rédaction, wkhtmltopdf ne fonctionne pas sur OpenSuse 12.1. Toutefois, comme les problèmes qui l'empêchent de fonctionner correctement à partir de Publican auront peut-être été résolus, les instructions suivantes vous apportent des précisions sur l'installation de wkhtmltopdf.
Si vous avez l'intention de créer des index dans les documents pdf générés, nous vous recommandons d'utiliser Apache FOP plutôt que wkhtmltopdf. Avec FOP, vous obtenez les bons numéros de page, ce qui est préférable pour un document imprimé.
$
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
Si vous travaillez sur un système 64 bits, soyez attentif à définir MYSYSTEM
de manière correcte.
Une fois téléchargés, installer les deux RPM ainsi :
$
sudo sh
rpm -ivh wkhtmltopdf-qt*
rpm -ivh --nodeps wkhtmltopdf-0*
exit
Vous devez utiliser l'option ad-hoc pour ignorer les dépendances dans le dernier RPM en raison du problème posé par ghostscript-fonts
décrit plus haut.
Installez Publican.
La dernière étape consiste à installer Publican, même si la phase de tests a échoué pour les deux sous-tests.
$
sudo sh
./Build test
exit
Les étapes suivantes sont facultatives, mais nous recommandons de vérifier que tout fonctionne bien avant de passer du temps sur vos documents.
Testez la construction du Publican installé :
$
publican create --type=book --product=testing --version=1.2.3 --name=TestPublican Processing file en-US/Author_Group.xml -> en-US/Author_Group.xml Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml Processing file en-US/Chapter.xml -> en-US/Chapter.xml Processing file en-US/Preface.xml -> en-US/Preface.xml Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml$
cd TestPublican/ publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub
Au moment de la rédaction de ce guide, la création des epubs avec Publican 2.9 sur OpenSuse déclenche les erreurs suivantes :
runtime error: file /usr/share/publican/xsl/epub.xsl element choose
Variable 'epub.embedded.fonts' has not been declared.
at /usr/lib/perl5/site_perl/5.14.2/Publican/Builder.pm line 915
Aucun fichier epub n'est créé. Toutefois, les fichiers de travail individuels existent et peuvent être construits en ouvrage epub avec Sigil, si vous le souhaitez.
Avec le gestionnaire de fichiers Dolphin, vous pouvez vous déplacer dans le répertoire SourceCode/TestPublican/tmp/en-US/
et voir là les divers formats de sortie.
This installation procedure assumes you have already installed a working docker (see http://docker.io) environment.
Docker est une encapsulation légère (utilisant actuellement LXC) qui vous permet d'installer et exécuter publican sans modifier votre installation Linux principale et ses dépendances.
Ouvrez un terminal.
Download and install the svendowideit/publican container from https://index.docker.io/u/svendowideit/publican/:
$
docker pull svendowideit/publican
L'exécution de cette commande demandera un certain temps, car elle télécharge un conteneur fondé sur fedora, puis les dépendances nécessaires pour publican.
Ajoutez un alias de l'interpréteur bash de publican pour faciliter son utilisation :
$
echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc
Cet alias suppose que vous faites tourner publican dans le répertoire racine de la documentation (celui contenant le fichier publican.cfg).
Maintenant vous pouvez vous servir de publican conformément à la documentation du produit :
$
publican --versionversion=3.2.1
It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.
To checkout the source from GIT open a terminal.
Exécutez la commande suivante pour installer le paquet publican :
$
cd PATH TO PLACE SOURCE$
git clone git://git.fedorahosted.org/publican.git publican
To run publican from this checkout run the following commands:
$
PUBLICAN_PATH="PATH TO PLACE SOURCE/publican"$
perl -CDAS -I $PUBLICAN_PATH/lib $PUBLICAN_PATH/bin/publican build --brand_dir $PUBLICAN_PATH/datadir/Common_Content/common --formats html
Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.
Naviguez jusqu'au le dossier dans lequel vous avez téléchargé Publican-Installer-version.exe
.
Double-cliquez sur le fichier Publican-Installer-version.exe
.
L'installeur affiche une série de conventions de licence. Tous les fichiers constitutifs de l'installation de Publican sont disponibles sous licence libre. Toutefois, comme certaines licences sont mieux adaptées que d'autres à certaines parties de Publican, tous les fichiers ne sont pas disponibles sous la même licence libre. Chaque licence vous garantit un ensemble différent de droits et de devoirs quand vous copiez ou modifiez les fichiers de votre installation de Publican. Nous avons retenu cette combinaison de licences pour vous permettre d'utiliser Publican le plus librement possible et vous permettre de choisir la licence sous laquelle vous préférez que les documents que vous publiez avec Publican soient placés.
Lisez les termes des divers contrats de licence. Si vous êtes d'accord avec leurs termes, cliquez sur le bouton
de chacun, sinon, cliquez sur le bouton .
L'installeur permet l'installation de plusieurs composants : Publican lui-même (étiqueté Main
dans la fenêtre de l'installeur), un certain nombre d'estampillages (comprenant RedHat
, JBoss
et fedora
) et deux composants DocBook (la Data Type Definition (DTD) (Définition des types de données) DocBook et le Extensible Stylesheet Language (XSL) pour les feuilles de style DocBook). Les trois estampilles sont regroupées sous l'en-tête réductible Brands
et les composants DocBook de même sous DocBook
dans la fenêtre de l'installeur. Reportez-vous au Chapitre 5, Estampillage pour des explications à propos des estampillages dans Publican. Publican utilise le DTD et les feuilles de style XSL pour le rendu des documents XML dans d'autres formats de présentation (comme HTML et PDF). Si vous n'installez pas ces composants, Publican devra télécharger ces données sur internet chaque fois qu'il traitera un document, ce qui allongera vraisemblablement les délais d'exécution.
Par défaut, tous les composants sont sélectionnés. Enlevez la coche des cases pour ne pas sélectionner les composants dont vous ne voulez pas, puis cliquez sur pour poursuivre.
Par défaut, l'installeur du logiciel crée un dossier nommé Publican
dans le répertoire %ProgramFiles%
de votre ordinateur — en règle générale C:\Program Files\Publican
. Vous pouvez modifier à la main le chemin affiché dans la boîte de dialogue Dossier de destination pour choisir un répertoire différent.
Une fois la destination choisie, cliquez sur
.L'installeur affiche une barre de progression pendant l'installation de Publican. Pour avoir des informations plus détaillées lors de la progression de l'installation, cliquez sur .
Une fois le processus achevé, l'installeur vous notifie le message Terminé
.
Cliquez sur
pour quitter l'installeur.Installez Xcode à partir du dépôt Mac App.
La taille de Xcode est d'environ 4 Gio. Attendez-vous à devoir patienter. Mais il contient des choses dont vous avez besoin.
Install Macports from http://guide.macports.org/chunked/installing.macports.html. Everything you install with it goes into /opt/local
, away from your normal OS files.
Ouvrez un terminal.
Installez les dépendances pour Publican, disponibles en tant que ports :
$
sudo port installdocbook-xml docbook-xsl docbook-sgml-4.2 perl5 bash-completion p5-file-pushd p5-config-simple p5-file-find-rule p5-file-slurp p5-class-trigger p5-time-hires p5-list-moreutils p5-ipc-run3 p5-class-accessor p5-test-perl-critic p5-xml-libxslt p5-locale-gettext p5-image-size p5-file-copy-recursive p5-datetime p5-archive-zip p5-timedate p5-html-format p5-dbd-sqlite p5-xml-simple p5-devel-cover p5-test-pod p5-test-pod-coverage p5-template-toolkit
Installez les modules CPAN pour les dépendances non satisfaites avec des ports. Notez : cette étape déclenchera un tas de messages, y compris des avertissements. Ne vous en préoccupez pas.
$
sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables
Installez FOP si vous souhaitez travailler avec des PDF :
$
sudo port installfop
$
echo"FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
Vérifiez la branche Main de Publican. Cette commande doit être lancée à partir de votre répertoire personnel, par exemple /Users/Votre_nom
$
git clonegit://git.fedorahosted.org/publican.git
Changez de répertoire :
$
cdpublican/publican
Ce répertoire doit contenir un fichier nommé Build.pl
. Vérifiez que vous êtes dans le bon répertoire, puis lancez la commande qui suit. Ignorez tous les messages affichés.
$
perl ./Build.PL
$
./Build
Lancez la commande suivante pour installer Publican et mettez tout son contenu dans /opt/local
:
$
sudo ./Build install
Procédure 1.1. Création et construction d'un ouvrage
$
publican create--name=testbook
$
cd testbook
$
publican build--formats=html --langs=en-US
Ouvrez le fichier tmp/en-US/html/index.html
dans un navigateur pour démontrer que la construction s'est correctement passée.
Procédure 1.2. Installation d'une estampille
Définissez les droits d'accès pour Commons Brand. Vous ne devez le faire qu'une seule fois. C'est une anomalie qui sera éventuellement corrigée.
$
find /opt/local/share/publican-type f
|xargs sudo chmod 644
Soit vérifiez le SVN de votre estampille, soit obtenez une estampille pré-construite auprès d'un ami.
The SVN location for the brands supplied by Red Hat is http://svn.fedorahosted.org/svn/publican
Si vous utilisez une estampille pré-construite, procédez à son extraction si nécessaire.
Si vous vous êtes procuré l'estampille à partir du SVN, construisez-la.
$
cd publican/publican-jboss
$
publican build--formats=xml --langs=all --publish
Installez l'estampillage.
$
sudo publican install_brand--path=/opt/local/share/publican/Common_Content
Vous pouvez maintenant utilisez l'estampillage pour vos ouvrages en modifiant le fichier publican.cfg
ou en précisant l'option --brand
lors de la création de l'ouvrage.
Les utilisateurs peuvent définir pour Publican des valeurs par défaut qui leur soient propres dans ~/.publican.cfg
. Actuellement, Publican accepte les valeurs :
firstname
surname
formats
lang
langs
Ce fichier est totalement différent de publican.cfg
utilisé pour construire un ouvrage. Il n'accepte pas les mêmes paramètres.
Les utilisateurs peuvent définir formats, langue et langues pour leur paramètres standard de construction.
Exemple 2.1. Paramétrage des formats et de la langue
$
echo 'formats: "html,html-single,pdf,txt"' >> ~/.publican.cfg$
echo 'langs: "en-US"' >> ~/.publican.cfg$
publican buildSetting up en-US
[...]
Finished txt
Publican 3.0 vous permet d'ajouter une entrée dans l'historique des révisions à partir de la ligne de commande. Vous pouvez définir vos informations personnelles d'utilisateur dans ~/.publican.cfg
.
Exemple 2.2. Paramétrage des informations personnelles d'utilisateur
$
echo 'firstname: "Dude"' >> ~/.publican.cfg$
echo 'surname: "McPants"' >> ~/.publican.cfg$
echo 'email: "dude.mcpants@awesome.com"' >> ~/.publican.cfg$
publican add_revision --member "Updated examples in chapter 2." \ --member "Removed obsolete example in sect 4.1"
Publican est un outil en ligne de commande. Pour utiliser Publican sur un ordinateur avec Linux comme système d'exploitation, vous devez, soit lancer un programme émulateur de terminal (comme GNOME Terminal ou Konsole), soit basculer sur une console virtuelle. Pour utiliser Publican sur un ordinateur avec Windows comme système d'exploitation, exécutez cmd à partir du pour ouvrir un interpréteur de commandes.
Les commandes Publican prennent l'un des formats suivants :
$
publican option_commande
The command_option is any of several options for the $
publican command itself. For a complete list of actions see Section B.2, « Command actions »
$
publican action options_actionaction représente l'une des actions de Publican à réaliser, comme créer des fichiers XML pour un nouveau document ou construire un document HTML à partir des fichiers XML du document. options_action porte sur l'action, comme définir une langue pour un document.
$
publican option_commande action options_actionCertaines options_commande affectent la sortie des actions, par exemple, indiquer si Publican doit utiliser des couleurs ANSI dans sa sortie.
Ce chapitre décrit comment créer des ouvrages ou des articles : les principaux fichiers de configuration, des fichiers exemples de documents et la construction d'un document.
Utilisez la commande $
publican create pour créer un nouveau document comprenant tous les fichiers nécessaires.
La commande $
publican create accepte plusieurs options, précisées dans ce chapitre. Quand une option prend une valeur en paramètre, séparer option et valeur avec une espace ou un signe égale ; par exemple, publican create --name Nouveau_livre ou publican create --name=Nouveau_livre.
--help
affiche la liste de toutes les options de la commande $
publican create.
--name Nom_document
Doc_Name représente le nom de l'ouvrage ou de l'article. Cette variable ne doit comporter aucune espace. Par exemple, la commande $
create_book --name Livre_test crée un fascicule nommé Livre_test
avec tous les fichiers nécessaires à la construction du document ; elle définit la valeur du paramètre BOOKID
dans le fichier Livre_test.ent
.
--lang Language_Code
Language_Code désigne le code de la langue dans lequel l'ouvrage ou l'article sera publié. Si vous ne précisez pas un code de langue, Publican prend par défaut en-US
(anglais US). L'option --lang
fixe le paramètre xml_lang
du fichier publican.cfg
; un répertoire à ce nom est créé dans celui du document. À sa création initiale, ce répertoire contient quelques fichiers XML à contenu standardisé. Voyez la Section 4.1.1, « Le fichier publican.cfg » pour plus d'informations sur les paramètres de publican.cfg
et à l'Annexe F, Codification des langues pour plus de détails à propos des codes de langues.
--version version
set version as the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use 5.1
. The default version is 0.1
. The --version
option sets the <productnumber>
tag in the Book_Info.xml
or Article_Info.xml
file. For more information refer to Section 4.1.2, « Book_Info.xml ».
--edition edition
la valeur de edition indique le numéro de parution de l'ouvrage. Ce nombre indique aux utilisateurs la publication d'une nouvelle édition de l'ouvrage. La première publication de l'ouvrage avec une mise à disposition générale doit être la parution 1.0
. La valeur par défaut est 0
. L'option --edition
fixe la valeur de la balise <edition>
du fichier Book_Info.xml
ou Article_Info.xml
. Pour plus d'informations, reportez-vous à la Section 4.1.2, « Book_Info.xml ».
--product Nom_produit
Product_Name est le nom du produit décrit par l'ouvrage. Cette variable ne doit comporter aucune espace. Par exemple, indiquez Fedora
pour une documentation se rapportant au cœur de Fedora, ou le nom du produit pour d'autres applications, par exemple, Fedora_Directory_Server
. La valeur par défaut est Documentation
. L'option --product
fixe la valeur de la balise <product name>
du fichier Book_Info.xml
ou Article_Info.xml
, ainsi qu'à l'entité PRODUCT
du fichier Doc_Name.ent
.
--type Article --name Article_Name
crée un article au lieu d'un ouvrage. Remplacez Article_Name par le nom de l'article. Cette variable ne doit comporter aucune espace. L'option --type
fixe la valeur du paramètre type
du fichier publican.cfg
. Reportez-vous à la Section 4.1.1, « Le fichier publican.cfg » pour plus d'informations à propos des paramètres de publican.cfg
.
--type Set --name Set_Name
crée une collection de documents au lieu d'un ouvrage isolé. Remplacez Set_Name par le nom de la collection. Cette variable ne doit contenir aucune espace. L'option --type
fixe la valeur du paramètre type
du fichier publican.cfg
. Reportez-vous à la Section 4.1.1, « Le fichier publican.cfg » pour plus d'informations à propos des paramètres de publican.cfg
et à la Chapitre 6, Utilisation des collections pour ce qui concerne les collections.
--brand brand
brand désigne l'estampille à utiliser pour la charte graphique de l'affichage du document, par exemple, RedHat
, fedora
, JBoss
, oVirt
ou GIMP
. La valeur par défaut est common
, une estampille par défaut intégrée à Publican. L'option --brand
fixe le paramètre brand
du fichier publican.cfg
. Reportez-vous à la Section 4.1.1, « Le fichier publican.cfg » pour plus d'informations à propos des paramètres de publican.cfg
. Cette option nécessite que le paquet d'estampillage approprié de Publican soit installé. Par exemple, pour construire des ouvrages estampillés Red Hat, vous devez installer le paquet publican-redhat. Reportez-vous à la Section 5.1, « Installation d'un estampillage » pour des directives sur l'installation des paquets des estampilles pour Publican. Si vous ne précisez pas d'estampille, Publican utilisera l'estampillage par défaut. Voyez le Chapitre 5, Estampillage pour plus d'informations.
Avant de lancer la commande $
publican create, placez-vous avec la commande $
cd dans le répertoire où vous souhaitez créer l'ouvrage. Par exemple, pour créer un ouvrage nommé Test_Book
dans le répertoire my_books/
, exécutez les commandes :
$
cd my_books/$
publican create --name Test_Book
Pour voir le résultat de cette commande sur un ordinateur avec un système d'exploitation Linux, exécutez :
$
ls
La sortie doit ressembler à :
Test_Book/
Pour voir le contenu du nouveau répertoire Test_Book/
sur un ordinateur Linux, exécutez :
$
cd Test_Book/$
ls
La sortie doit ressembler à :
en-US/ publican.cfg
Si vous exécutez la commande $
publican create --name Livre_test --lang en-US, Publican crée une structure de répertoires avec les fichiers requis, semblable à la suivante :
publican.cfg
en-US
(répertoire)
Test_Book.xml
Test_Book.ent
Revision_History.xml
Preface.xml
Chapter.xml
Book_Info.xml
Author_Group.xml
images
(répertoire)
icon.svg
Si vous avez plusieurs versions d'un document en maintenance, vous pouvez créer un fichier de configuration pour chaque version. En construisant ou empaquetant un document, vous pouvez utiliser l'option --config
pour désigner un fichier de configuration autre que publican.cfg
, et, par conséquent, utiliser un jeu de paramètres différents pour cette une construction particulière. Par exemple :
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
Le fichier publican.cfg
sert à configurer les options de construction ; il est situé à la racine du répertoire de l'ouvrage. Voici un exemple de fichier publican.cfg
, suivi d'une description des paramètres possibles pour les fichiers du type publican.cfg
:
# Config::Simple 4.59 # Wed Jul 18 13:00:40 2012 xml_lang: "en-US" type: Book brand: common \t\t \t\t
Paramètres par défaut
xml_lang
définit la langue des fichiers sources du XML, par exemple, en-US
, tel que précisé par l'option --lang
de $
publican create.
type
définit le type de document — un <article>
DocBook, un <book>
DocBook ou un <set>
DocBook, tel que précisé avec l'option --type
de $
publican create.
brand
définit le choix de l'estampille pour le document, par exemple, RedHat
, fedora
, JBoss
, oVirt
ou GIMP
, tel que défini par l'option --brand
de $
publican create. Si vous ne précisez pas d'estampille, Publican utilise la charte graphique par défaut. Voyez le Chapitre 5, Estampillage pour plus d'informations.
Advanced parameters Delete me and reference appendix
arch
filtre les sorties selon l'architecture de l'ordinateur. Par exemple, si vous définissez arch: x86_64
dans le fichier publican.cfg
, Publican n'incorporera que les éléments XML signés de l'attribut équivalent, comme <para arch="x86_64">
.
Comme il en est, plus généralement, avec tout marquage conditionnel, arch
peut créer de grosses difficultés lors de la traduction du document. Reportez-vous à la Section 4.9.1, « Balisage conditionnel et traduction » pour une explication à propos de ces problèmes.
Si le nœud racine d'un fichier XML est exclu à l'aide de l'attribut arch
, la construction du document échouera, car les fichiers vides ne sont pas des XML valides. Par exemple, si Installation_and_configuration-PPC.xml
ne contient qu'un seul chapitre :
<?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> [texte du chapitre] </chapter>
et que ce chapitre est incorporé dans User_Guide.xml
sous la balise <xi:include>
, la construction du document échouera si la directive $
condition: x86 est définie dans le fichier publican.cfg
.
Pour exclure ce chapitre, ajoutez l'attribut arch
sous la balise <xi:include>
dans User_Guide.xml
, et non sous <chapter>
dans Installation_and_configuration-PPC.xml
.
Si un <xref>
pointe sur un contenu non incorporé lors de la construction à cause de l'attribut arch
, la construction échoue. Par exemple, si arch: x86
est défini dans le fichier publican.cfg
, $
publican build --formats=pdf --langs=en-US échoue si l'ouvrage comporte la balise <xref linkend="Itanium_installation">
pointant sur <section id="Itanium_installation" arch="IA64">
.
books
définit une liste d'ouvrages séparés par une espace ; cette liste est utilisée pour regrouper un ensemble éclaté. Voyez la Section 6.2, « Ensembles distribués » pour plus d'informations à propos des ensembles distribués.
brew_dist
définit Brew, système de construction interne de Red Hat, comme cible de construction à utiliser pour un paquet RPM sur bureau. Ce paramètre vaut docs-5E
par défaut. Reportez-vous à la Section 4.8.2, « La commande $
publican package » et à la Section 5.4, « Empaquetage d'une estampille » pour plus d'information à propos de la construction des paquets RPM.
bridgehead_in_toc
indique si les contenus des éléments <bridgehead>
(intitulés flottants) doivent être incorporés dans la table des matières avec les autres intitulés (tels les titres de chapitre ou de section). Pour activer cette fonctionnalité, écrivez bridgehead_in_toc: 1
. Autrement, la valeur du paramètre est 0
par défaut et les intitulés <bridgehead>
ne sont pas incorporés dans la table des matières.
chunk_first
contrôle si, pour un rendu HTML, le premier paragraphe doit s'afficher sur une nouvelle page. Pour ce faire, définissez chunk_first: 1
comme valeur du paramètre. Par défaut, le paramètre vaut 0
et le premier paragraphe est sur la même page que son chapitre.
chunk_section_depth
définit la profondeur de subdivision au delà de laquelle Publican ne dispose plus les sous-sections sur un nouvelle page en rendu HTML. Cette valeur est de 4
par défaut.
Exemple 4.1. Contrôle de la profondeur de subdivision avec chunk_section_depth
pas de subdivision en paragraphes. Tous les paragraphes et leurs alinéas sont disposés sur la page du chapitre auquel ils appartiennent. La suite des pages est : chapitre 1, chapitre 2, chapitre 3, …
la coupure est au niveau « 1 » de subdivision. Chaque paragraphe de niveau un et l'ensemble des sous-sections sont placés sur une nouvelle page. La suite de pages est chapitre 1, 1.2, 1.3, 1.4 … chapitre 2, 2.1, 2.2, 2.3 …
la coupure est au niveau « 2 » de subdivision. La succession des pages est chapitre 1, 1.2, 1.2.2, 1.2.3, 1.2.4 … 1.3, 1.3.2, 1.3.3 …
la coupure est au niveau « 3 » de subdivision. La succession des pages est chapitre 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.3, 1.2.2.4 … 1.3, 1.3.2, 1.3.2.2, 1.3.2.3 …
la coupure est au niveau « 4 » de subdivision. La succession des pages est chapitre 1, 1.2, 1.2.2, 1.2.2.2, 1.2.2.2.2, 1.2.2.2.3, 1.2.2.2.4 … 1.2.3, 1.2.3.2, 1.2.3.2.2, 1.2.3.2.3 …
classpath
définit le chemin des fichiers archives Java (jar) pour FOP. Publican confie le rendu des documents sous forme de fichiers PDF à FOP — une application Java — de Apache. Le chemin par défaut pour les fichiers jar de FOP sur un ordinateur Linux est : /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
définit le chemin d'installation de Publican. L'emplacement par défaut sur un système Linux est /usr/share/publican
. Sur un système Windows, l'emplacement par défaut est %SystemDrive%/%ProgramFiles%/publican
— habituellement C:/Program Files/publican
.
common_content
définit le chemin vers les fichiers Publican de contenu courant. Ces fichiers fournissent les formats par défaut, plus quelques textes de paragraphes et graphiques génériques standardisés. L'emplacement par défaut sur un ordinateur Linux est /usr/share/publican/Common_Content
. Sur un ordinateur Windows, l'emplacement par défaut est %SystemDrive%/%ProgramFiles%/publican/Common_Content
— habituellement C:/Program Files/publican/Common_Content
.
condition
définit les possibilités d'allègement des XML avant transformation. Voyez la Section 4.9, « Balisage conditionnel » pour plus d'informations.
Si le nœud racine d'un fichier XML est exclu par une condition, la construction du document échouera, car les fichiers vides ne sont pas des XML valides. Par exemple, si Installation_and_configuration_on_Fedora.xml
ne contient qu'un seul chapitre :
<?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> [texte du chapitre] </chapter>
et que ce chapitre est inclus dans User_Guide.xml
avec une balise <xi:include>
, le document ne pourra pas être construit si $
condition: Ubuntu est défini dans le fichier publican.cfg
.
Pour exclure ce chapitre, ajoutez une condition à la balise <xi:include>
dans User_Guide.xml
, et non dans la balise <chapter>
dans Installation_and_configuration_on_Fedora.xml
.
Si une balise <xref>
pointe sur un contenu non incorporé dans la construction à cause d'une balise conditionnelle, la construction avortera. Par exemple, si le fichier publican.cfg
définit $
condition: upstream, la commande publican build --formats=pdf --langs=en-US échoue si l'ouvrage est marqué avec la balise <xref linkend="betasection">
pointant sur <section id="betasection" condition="beta">
.
confidential
marque un document comme étant confidentiel. Quand ce paramètre est fixé à la valeur 1
, Publican ajoute le texte défini par le paramètre confidential_text
(par défaut, CONFIDENTIAL
) en pied de chaque page d'un document au format HTML et en tête s'il est au format PDF. La valeur par défaut est 0
(aucun en-tête ou pied de page).
confidential_text
définit le texte à utiliser quand le paramètre confidential
est égal à 1
. Le texte par défaut est CONFIDENTIAL
.
debug
contrôle si Publican doit afficher les messages de débogage en cours de travail. Si le paramètre est égal à sa valeur par défaut, soit 0
, Publican n'affiche pas de messages. Mettez cette valeur à 1
pour voir ces messages.
def_lang
définit la langue par défaut pour un site web géré avec Publican. Les tables des matières pour des langues autres que celles par défaut effectueront les liens vers les documents dans le langage par défaut tant que les traductions ne sont pas disponibles. Reportez-vous à la Section 4.8, « Empaquetage d'un document ».
doc_url
indique l'URL de l'équipe de documentation du paquet. Dans une sortie HTML, Publican met en place un lien vers cet URL en haut et à droite de chaque page, par l'intermédiaire de l'image image_right.png
du répertoire Common_Content/images
particulier à l'estampille. Par défaut, ce paramètre ouvre la page https://fedorahosted.org/publican
.
docname
specifies the document name. If set, this value overrides the content of the <title>
tag in the Book_Info.xml
file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
dt_obsoletes
un paquet déclaré obsolète dans un paquet pour ordinateur de bureau.
dt_requires
un paquet requis par le paquet de tête, par exemple, un paquet de menu de documentation. Voyez la Section 4.8.1.3, « Entrées de menu de bureau pour documents ».
dtdver
définit la version du Document Type Definition (DTD) pour le XML de DocBook sur lequel ce projet se fonde. Par défaut, Publican utilise la version 4.5. Les caractéristiques de la version 4.5 du DTD du XML pour DocBook sont disponibles à la page http://www.docbook.org/specs/docbook-4.5-spec.html.
When you install Publican, you also install a local copy of the DocBook XML DTD version 4.5 and accompanying Extensible Stylesheet Language (XSL). If you set a version of the DTD for which there is no local support, Publican must download the appropriate DTD and XSL from an online source every time that it builds the document. Building your document is delayed while this download takes place. The combined size of the required files is around 70 MB.
dtd_type
écrase le type de DocType. L'expression doit être une chaîne complète.
Ce paramètre n'est autorisé que dans une estampille.
dtd_uri
écrase l'URI de DocType. L'expression doit être une chaîne complète.
Ce paramètre n'est autorisé que dans une estampille.
ec_id
définit l'identifiant du greffon d'aide Eclipse. Chaque greffon d'aide Eclipse doit posséder un identifiant unique ; en règle générale, il suit les conventions de nommage du paquet Java — voyez http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html. Par défaut, Publican définit l'identifiant par org.produit.nom_document. L'identifiant que vous définissez ici détermine également le nom du sous-répertoire pour ce greffon dans le répertoire plugin
.
ec_name
définit le nom du greffon d'aide Eclipse. C'est le nom en clair visible dans la liste des aides Eclipse. Ce nom ne doit pas forcément être unique ou suivre des conventions particulières. Par défaut, Publican le définit à produit nom_document.
ec_provider
définit le nom du fournisseur du greffon d'aide Eclipse. Ce peut être votre nom, ou le nom du projet, ou le nom de votre société. Ce nom est affiché à l'intention des utilisateurs. Il n'a pas à être unique ou à se conformer à des conventions spéciales. Par défaut, Publican définit le nom du fournisseur Publican-version de Publican.
edition
définit l'indice de modification de ce document.
La balise <edition>
était obligatoire dans les versions de Publican antérieures à la version 2.0 ; elle était utilisée pour définir la version d'un paquet de documentation. Cette balise est maintenant optionnelle et n'affecte en rien l'empaquetage.
extras_dir
le nom du répertoire duquel Publican extraira pour traitement les fichiers externes. (Par défault: extras
)
footer
définit le contenu du pied de page pour chacune des pages du site.
generate_section_toc_level
contrôle la profondeur de subdivision avec laquelle Publican créera la table des matières. La valeur par défaut étant 0
, Publican génère des tables des matières en début de document et la divise en parties, chapitres et annexes, mais pas en paragraphes. Si (par exemple) la valeur est fixée à 1
, apparaissent également dans la table des matières les sections de « niveau 1 », comme les paragraphes 1.1, 1.2, 2.1 et 2.2. Si elle fixée à 2
, sont mentionnées les sections de « niveau 2 », comme les paragraphes 1.1.1, 1.1.2 et 1.2.1.
Exemple 4.2. Définition de la profondeur de subdivision de la table des matières
Publican génère une table des matières en début de document divisée en parties, chapitres et annexes, mais pas en paragraphes.
Publican génère une table des matières également en début de chaque section de « niveau 1 », comme les paragraphes 1.1, 1.2 … 2.1, 2.2 …
Publican génère une table des matières également en début de chaque section de « niveau 2 », comme les paragraphes 1.1.1, 1.1.2, 1.1.3 … 1.2.1, 1.2.2; 1.2.3 …
ignored_translations
indique les langues à ignorer lors de la traduction sous forme de codes de langue XML séparés par des virgules : par exemple, es-ES,it-IT
. Si vous construisez ou empaquetez un ouvrage pour une langue filtrée avec ce paramètre, Publican ignore toute traduction existante pour cette langue et, à la place, construit ou empaquette l'ouvrage dans la langue originelle du XML. Voyez la Section 4.6, « Traduction d'un document » et l'Annexe F, Codification des langues.
tmp_dir
Le répertoire dont Publican extraira les images pour traitement. (Par défault: images
)
info_file
écrase le fichier Info par défaut. Ce fichier indique là où Publican doit rechercher les champs des informations. Paramétrez l'option avec le nom complet du fichier sans le chemin.
license
précise la licence utilisée pour le paquet. Par défaut, Publican choisit la « GNU Free Documentation License (GFDL) ». Reportez-vous à la Section 4.8, « Empaquetage d'un document ».
mainfile
définit le nom du fichier XML du document contenant le nœud racine XML avec la balise <article>
, <book>
ou <set>
, ainsi que le nom du fichier .ent
correspondant contenant les entités du document. Par exemple, si vous indiquez mainfile: master
, Publican recherche le nœud racine XML dans master.xml
et les entités du document dans master.ent
.
Si le paramètre mainfile
n'est pas renseigné, Publican recherche le nœud racine XML dans un fichier, dont le nom correspond à la valeur donnée à la balise <title>
pour le document, dans Article_Info.xml
, Book_Info.xml
ou Set_Info.xml
; il recherche les entités du document dans un fichier avec le nom correspondant.
menu_category
la catégorie de « menu de bureau » (définie par le fichier .menu
correspondant) dans laquelle un document doit s'afficher quand il est installé avec un paquet RPM de bureau. Voyez la Section 4.8.1.3, « Entrées de menu de bureau pour documents ».
os_ver
specifies the operating system for which to build packages. Publican appends the value that you provide here to the RPM packages that it builds. For example, .fc15
for Fedora 15. The default value is .el5
, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to Section 4.8, « Empaquetage d'un document » and Section 5.4, « Empaquetage d'une estampille ».
prod_url
indique un URL pour le produit auquel ce document s'applique. Dans une sortie HTML, Publican établit un lien sur cet URL, à gauche en tête de chaque page, par l'intermédiaire de l'image image_left.png
du répertoire Common_Content/images
de l'estampille. Par défaut, ce paramètre renvoie à https://fedorahosted.org/publican
.
product
specifies the product to which this documentation applies. If set, this value overrides the content of the <productname>
tag in the Book_Info.xml
file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
release
définit le numéro de parution de ce paquet. Si définie, cette valeur écrase celle de <pubsnumber>
dans le fichier Book_Info.xml
quand vous empaquetez un document. Cette valeur ne doit comporter que des chiffres (‘0’–‘9’).
repo
définit le dépôt à partir duquel extraire les ouvrages éclatés faisant partie d'un ensemble distribué. Voyez la Section 6.2, « Ensembles distribués ».
rev_file
inverse le sens par défaut du fichier d'historique de révision. Par défaut, Publican suppose que l'historique de révision est trié dans l'ordre décroissant, les versions les plus récentes en haut. Si vous souhaitez modifier cet ordre et avoir les révisions les plus anciennes en début, fixez ce paramètre à la valeur asc
ou ascending
.
rev_file
écrase le fichier « Revision History » par défaut. Il définit l'emplacement où Publican doit rechercher les champs des révisions. Utilisez le nom complet du fichier sans chemin. Combiné à l'action de « add_revision » de Publican, il permet de construire un ouvrage sans fichier Revision_History.xml
.
scm
définit le système de contrôle de version (ou de gestion du code source) utilisé dans le dépôt qui stocke les ouvrages distants dans un ensemble distribué. Actuellement, Publican ne peut utiliser que Subversion (SVN), et donc utilise SVN
comme réglage par défaut. Reportez-vous à la Section 6.2, « Ensembles distribués ».
show_remarks
contrôle l'affichage des textes sous balise <remark>
de Docbook dans la sortie du traitement. Par défaut, cette valeur est égale à 0
; Publican dissimule donc les remarques. Fixez cette valeur à 1
pour les afficher. Avec l'estampille common
de Publican, les remarques affichées sont surlignées en magenta.
sort_order
redéfinit le poids par défaut des ouvrages pour leur tri dans un site Web Publican. Les ouvrages s'affichent sur le site Web par poids décroissant. Ainsi, un ouvrage avec un poids de tri 10 apparaît avant un ouvrage de poids 5. Par défaut, cette valeur est égale à 50.
src_url
définit l'URL à laquelle trouver les archives « tar » des fichiers sources. Ce paramètre renseigne le champ Source:
dans l'en-tête du fichier spec RPM. Voyez la Section 4.8, « Empaquetage d'un document ».
tmp_dir
définit le répertoire des sorties de Publican. Par défaut, le nom de ce répertoire est tmp
; il est créé à l'intérieur du répertoire de l'ouvrage ou de l'article.
tmpl_path
définit le chemin des modèles Publican. Par défaut : /usr/share/publican/templates
.
toc_js
autorise un site à écraser le modèle utilisé lors de la construction de la table des matières incorporée en utilisant le style=1 dans les sites Web. Le modèle doit se trouver dans le même répertoire que toc.tmpl
. Le nom du modèle doit être de la forme toc_type+.tmpl.
toc_type
définit le nom d'un modèle personnalisé de table des matières. Par défaut, Publican recherche un fichier toc-$toc_type.tmpl
dans /usr/share/publican/templates
. Vous pouvez modifier ce réglage en indiquant un autre chemin avec tmpl_path
.
toc_section_depth
contrôle la profondeur de subdivision employée par Publican dans la table des matières principale. Par défaut, cette valeur est fixée à 2
. Avec ce réglage par défaut, les sections 1.1 et 1.1.1 seront mentionnées dans la table des matières principale, mais la section 1.1.1.1 n'y sera pas (notez que le premier chiffre de cet exemple représente un chapitre, et non un paragraphe).
Exemple 4.3. Contrôle de la profondeur des subdivisions dans la table des matières principale
Publican crée une table des matières principale ne comportant que les chapitres.
Publican crée une table des matières principale ne comportant que les chapitres et les sections de « niveau 1 », comme 1, 1.1, 1.2, 1.3 … 9, 9.1, 9.2 … sans mentionner les sections 1.1.1, 1.1.2 …
Publican crée une table des matières principale contenant les chapitres et les sections de « niveau 1 » et de « niveau 2 », comme 1, 1.1, 1.1.1, … 1.2, 1.2.1, 1.2.2 … mais ne mentionne pas les sections de niveau supérieur.
version
définit le numéro de version du produit objet du document. Si indiquée, cette valeur prend le pas sur le contenu de la balise <productnumber>
du fichier Book_Info.xml
lors de l'empaquetage du document. Cette valeur ne doit comporter que des chiffres et le point (‘0’–‘9’ et ‘.’).
web_brew_dist
indique d'utiliser brew comme cible de construction pour les paquets Web RPM. Brew est le système de construction utilisé en interne par Red Hat. Par défaut, cette valeur est docs-5E
, représentant les paquets documentaires pour Red Hat Enterprise Linux 5. Voyez la Section 4.8, « Empaquetage d'un document ».
web_formats
une liste, avec la virgule comme séparateur, des formats à inclure dans le paquet Web RPM. Reportez-vous à la Section 4.8.2, « La commande $
publican package ».
web_home
indique que le document est la page d'accueil d'un site Web de documentation, et non un document standard. Voyez la Chapitre 7, Construction d'un site Web avec Publican.
web_home
In Publican 2.2, web_home
is replaced by web_type: home
. Support for web_home
will be removed in a future version of Publican.
web_name_label
remplace le nom de l'ouvrage tel qu'il apparaît dans le menu d'un site web géré par Publican. Voyez la Chapitre 7, Construction d'un site Web avec Publican.
web_obsoletes
définit les paquets que le RPM Web a rendu obsolètes. Voyez la Section 4.8, « Empaquetage d'un document ».
web_product_label
remplace le nom du produit tel qu'il apparaît dans le menu d'un site Web géré par Publican. Voyez la Chapitre 7, Construction d'un site Web avec Publican.
web_type
définit le style Web ; il détermine la disposition et la présentation du site. Les valeurs valides sont 1
et 2
. Le style 1 dispose un panneau de navigation sur le côté gauche de l'écran permettant un accès à la totalité des documents du site. Le style 2 offre un système de navigation avec des raccourcis.
web_type
specifies that the document is descriptive content for a Publican-managed website rather than product documentation. This content includes the home page of the website (web_type: home
), product description pages (web_type: product
), and version description pages (web_type: version
). Refer to Chapitre 7, Construction d'un site Web avec Publican.
web_version_label
écrase le numéro de version tel qu'il apparaît sur le menu d'un site Web géré par Publican. Fixez cette valeur à UNUSED
pour un documentation d'ordre général qui ne s'applique pas à une version donnée de produit. Reportez-vous à la Chapitre 7, Construction d'un site Web avec Publican.
wkhtmltopdf_opts
Extra options to pass to wkhtmltopdf. e.g. wkhtmltopdf_opts: "-O landscape -s A3"
Lancez la commande $
publican help_config dans le répertoire racine d'un ouvrage pour un résumé à propos de ces paramètres.
Article_Info.xml
et Set_Info.xml
Cette description du fichier Book_Info.xml
est également applicable aux fichiers Article_Info.xml
et Set_Info.xml
. Toutefois, pour simplifier, le fichier Book_Info.xml
sera dans ce paragraphe l'unique référence pour les trois fichiers.
Ce paragraphe traite de l'empaquetage des documents en vue d'une distribution par l'intermédiaire du Gestionnaire de paquets RPM. Néanmoins, si vous utilisez la commande $
publican package, Publican crée une archive « .tar » ; vous pouvez l'utiliser pour construire un paquet à distribuer pour d'autres gestionnaires de paquets. Si vous exécutez publican package sur un ordinateur où rpmbuild n'est pas installé, Publican génère tout de même l'archive « .tar », même s'il ne peut pas créer de paquet RPM pour cette archive.
Le fichier Book_Info.xml
contient les méta-données clés relatives à l'ouvrage : l'identifiant, le titre, le sous-titre, l'auteur et le numéro de l'édition. Il contient également le nom et le numéro de version du produit documenté, ainsi qu'un résumé.
En plus de constituer la majeure partie de la préface de l'ouvrage, ces méta-données sont également utilisées pour le mettre sous forme de paquet RPM. Habituellement, si vous distribuez un ouvrage sous forme de RPM, plusieurs balises incorporées par défaut dans Book_Info.xml
doivent être associées à des valeurs appropriées ; ces données doivent, en outre, satisfaire les exigences de format du RPM. Vous pouvez surcharger les données relatives à ces balises en utilisant les champs équivalents dans le fichier publican.cfg
, comme indiqué dans ce paragraphe.
Sauf si elles ont été surchargées dans le fichier publican.cfg
, les données de sept balises de Book_Info.xml
sont, par défaut, nécessaires pour la construction d'ouvrages sous forme de RPM. Pour commencer, le nom du fichier de construction de l'ouvrage sous forme de RPM est ainsi constitué :
nom_produit-titre-numéro_produit-langue-édition-numéro_publication.src.rpm
Toutes les données ci-dessus, sauf language sont tirées de Book_Info.xml
— language est défini dans la ligne de commande de construction de l'ouvrage. De même, <subtitle>
et <abstract>
sont utilisés dans le fichier spec du RPM, pour renseigner, respectivement, les champs Summary:
et %description
de l'en-tête.
Un exemple de fichier Book_Info.xml
, pour l'ouvrage Test_Book
, est présenté ci-dessous. Des détails à propos de ce fichier, ainsi que les exigences relatives au format RPM pour chaque balise, suivent.
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE info [ <!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent"> %BOOK_ENTITIES; <!ENTITY % sgml.features "IGNORE"> <!ENTITY % xml.features "INCLUDE"> <!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod"> %DOCBOOK_ENTS; ]> <info conformance="121" version="5.0" xml:lang="fr-FR" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Guide utilisateur</title> <subtitle>Publication d'ouvrages, articles, papiers et ensembles en plusieurs tomes avec XML Docbook</subtitle> <productname>publican</productname> <productnumber>4.2</productnumber> <abstract> <para> Cet ouvrage vous aide à installer <application>&PRODUCT;</application>. Il donne aussi des instructions pour l'utilisation de Publican en vue de créer et publier des ouvrages, des articles ou des ensembles de livres à l'aide du XML DocBook. Ce guide suppose que vous connaissez déjà le XML DocBook. </para> </abstract> <keywordset> <keyword>publican</keyword> <keyword>docbook</keyword> <keyword>publication</keyword> </keywordset> <subjectset scheme="libraryofcongress"> <subject> <subjectterm>Electronic Publishing</subjectterm> </subject> <subject> <subjectterm>XML (Computer program language)</subjectterm> </subject> </subjectset> <mediaobject role="logo"> <imageobject> <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> </imageobject> <textobject> <phrase>Team Publican</phrase> </textobject> </mediaobject> <mediaobject role="cover"> <imageobject remap="lrg" role="front-large"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="s" role="front"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="xs" role="front-small"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="cs" role="thumbnail"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> </mediaobject> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </info> \t\t \t\t
<bookinfo id="identifiant_ouvrage">
, <articleinfo id="identifiant_article">
, <setinfo id="identifiant_ensemble">
L'identifiant du document est utilisé en interne et n'apparaît pas au lecteur une fois l'ouvrage construit. Si vous lancez la commande $
publican clean_ids, tout identifiant entré manuellement, y compris celui-ci, modifie le format en Document_Nom-Titre, où Titre est le titre du l'ouvrage, de l'article, de la partie ou du chapitre associé.
<productname>nom_produit</productname>
le nom du produit ou de l'ensemble de produits auquel l'ouvrage, l'article ou l'ensemble s'applique ; par exemple : Red Hat Enterprise Linux
ou JBoss Enterprise Application Platform
. Lors de la construction d'un ouvrage sous forme de paquet RPM, les données de la balise <productname>
sont partiellement utilisées pour former le nom du paquet.
Surchargez la valeur de cette balise avec la variable product
du fichier publican.cfg
si le nom du produit contient des caractères non latins, des caractères latins accentués ou des signes de ponctuation autres que le souligné.
Publican utilise des données dans cette balise pour créer en partie le nom de fichier des paquets RPM, sauf s'il est écrasé par les données du fichier publican.cfg
. Si vous n'écrasez pas la valeur de cette balise dans le fichier publican.cfg
file, cette balise ne doit contenir que des caractères lettres minuscules ou majuscules, non accentués, des chiffres et des tirets (signe moins), des points, des soulignés et le signe plus (‘a–z’, ‘A–Z’, ‘0’–‘9’ et ‘-’, ‘.’, ‘_’ et ‘+’) si vous prévoyez de construire des paquets avec Publican.
<title>titre</title>
le titre du document (par exemple, <title>Server Configuration Guide</title>
). Le titre apparaît sous le nom du produit tant dans les éditions HTML que PDF. La définition du titre est obligatoire pour construire un paquet RPM, car, en construisant un ouvrage sous forme de paquet RPM, le titre est partiellement utilisé dans le nom du paquet.
Les noms des paquets RPM ne peuvent comporter que certains caractères ASCII de base. Si le titre du document contient des caractères non-latins, des caractères accentués ou des marques de ponctuation autres que le souligné, servez-vous du paramètre docname
du fichier publican.cfg
pour donner un nom au document en caractères ASCII. Quand vous construisez le document, le titre apparaît tel qu'indiqué avec la balise <title>
, mais quand vous l'empaquetez, la valeur du paramètre docname
est utilisée dans le nom de fichier du paquet RPM.
Publican utilise des données dans cette balise pour créer en partie le nom de fichier des paquets RPM, sauf s'il est écrasé par les données du fichier publican.cfg
. Si vous n'écrasez pas la valeur de cette balise dans le fichier publican.cfg
file, cette balise ne doit contenir que des caractères lettres minuscules ou majuscules, non accentués, des chiffres et des tirets (signe moins), des points, des soulignés et le signe plus (‘a–z’, ‘A–Z’, ‘0’–‘9’ et ‘-’, ‘.’, ‘_’ et ‘+’) si vous prévoyez de construire des paquets avec Publican.
Par défaut, Publican utilise également le contenu de la balise <title>
pour retrouver le fichier qui contient le nœud racine XML : <article>
, <book>
ou <set>
. Par exemple, si vous avez donné comme titre <title>Guide de configuration serveur</title>
, Publican s'attend à ce que le nœud racine XML soit dans un fichier nommé Guide_de_configuration_serveur.xml
et les entités du document dans Guide_de_configuration_serveur.ent
. Si vous voulez utiliser un nom différent pour ces fichiers, définissez le paramètre mainfile
dans le fichier de configuration du document (par défaut, publican.cfg
). Reportez-vous à la Section 4.1.1, « Le fichier publican.cfg ».
<subtitle>sous-titre</subtitle>
le sous-titre de l'ouvrage : un autre intitulé, généralement plus explicite quant au contenu de l'ouvrage (par exemple : Guide de configuration serveur : préparation pour une utilisation de Red Hat Enterprise Linux en production). Le sous-titre apparaît sous le titre tant dans l'édition HTML que PDF. Un sous-titre est également obligatoire pour qu'un ouvrage soit disponible sous forme de paquet RPM, le sous-titre est utilisé comme valeur de la directive Summary
dans le fichier spec RPM. La commande rpm -qi renvoie le contenu de plusieurs champs du fichier spec, dont celui de Summary
.
<productnumber>numéro_produit</productnumber>
le numéro de la version du produit traité par l'ouvrage, par exemple ‘5.2’ pour Red Hat Enterprise Linux 5.2 et ‘4.3’ pour JBoss EAP 4.3.
Le lancement de la commande $
publican create --name Nom_document --version version configure correctement le numéro du produit.
Si la version du produit est quelque chose d'autre qu'un nombre, surchargez la valeur de cette balise avec celle de la variable version
dans le fichier publican.cfg
.
Publican utilise la donnée de cette balise pour créer une partie du nom de fichier des paquets RPM, excepté si cette donnée a été écrasée par celle définie dans le fichier publican.cfg
. Si vous ne remplacez pas la valeur de la balise par celle de publican.cfg
, elle ne doit comporter que des chiffres et le point (‘0–9’ et ‘.’) si vous avez prévu de construire des paquets avec Publican.
<edition>édition</edition>
définit le rang d'édition de l'ouvrage. La première édition du l'ouvrage doit être 1.0 (sauf si vous utilisez 0.x comme numéro de version des éditions préparatoires). Les numéros des éditions suivantes s'obtiendront en incrémentant 1.x, numéro de la version précédente pour indiquer aux lecteurs qu'il s'agit d'une nouvelle édition de l'ouvrage. L'édition modifie le numéro de version dans le nom du fichier quand on construit un ouvrage avec la commande $
publican package.
Par exemple, le fait de définir un numéro d'édition égal à 1.2
et de construire l'ouvrage avec la commande $
publican package --binary --lang=en-US crée un fichier RPM nommé nom_produit-titre-numéro_produit-en-US-1.2-0.src.rpm
.
Lancer la commande $
publican create --name Nom_document --edition x.y configure correctement le numéro d'édition.
Surchargez la valeur de cette balise par celle de la variable edition
du fichier publican.cfg
si la modification du document est désignée par autre chose qu'un nombre.
Publican utilise la donnée de cette balise pour créer une partie du nom de fichier des paquets RPM, excepté si cette donnée a été écrasée par celle définie dans le fichier publican.cfg
. Si vous ne remplacez pas la valeur de la balise par celle de publican.cfg
, elle ne doit comporter que des chiffres et le point (‘0–9’ et ‘.’) si vous avez prévu de construire des paquets avec Publican.
<pubsnumber>pubsnumber</pubsnumber>
« numéro_publication » désigne le numéro d'ordre de la publication (le dernier chiffre dans le nom du fichier) lors de la construction d'un ouvrage avec $
publican package. Par exemple, le fait de définir « numéro_publication » égal à 1
et de construire l'ouvrage avec la commande publican package --binary --lang=en-US crée un fichier RPM nommé nom_produit-titre-numéro_produit-en-US-édition-1.src.rpm
.
Surchargez la valeur de cette balise par celle de la variable release
du fichier publican.cfg
si le numéro de parution du document n'est pas totalement défini à l'aide de chiffres.
Publican utilise la donnée de cette balise pour créer en partie le nom du fichier des paquets RPM, excepté si cette donnée a été écrasée par celle définie dans le fichier publican.cfg
. Si vous ne remplacez pas la valeur de la balise par celle de publican.cfg
, elle ne doit comporter que des chiffres (‘0–9’) si vous avez prévu de construire des paquets avec Publican.
<abstract><para>résumé</para></abstract>
un court aperçu, un résumé du propos de l'ouvrage et ses objectifs, ne dépassant pas en général un paragraphe. Le résumé est placé avant la table des matières dans les éditions HTML et en deuxième page dans le cas du PDF. Quand un ouvrage est construit sous forme de paquet RPM, ce résumé constitue le corps du champ Description
du fichier spec RPM. Le résumé est donc affiché par l'intermédiaire de la commande rpm -qi.
Vous pouvez ajouter des métadonnées dans le fichier Book_Info.xml
d'un document pour prendre en charge des fonctionnalités particulières dans divers formats de sortie :
<keywordset>
, <keyword>
Les termes à la suite de la balise <keyword>
, placés dans un <keywordset>
, sont ajoutés à une entrée <meta name="keywords">
dans l'en-tête des fichiers HTML et dans le champ Keywords
des propriétés pour un document PDF.
<subjectset>
, <subject>
Les termes à la suite de la balise <subject>
, placés dans un <subjectset>
, sont ajoutés au champ Subject
des propriétés pour un document PDF et dans les métadonnées d'un livre électronique au format EPUB.
Envisagez l'utilisation d'une terminologie normalisée pour la définition du sujet de l'ouvrage, par exemple, les Library of Congress Subject Headings (LCSH) (En-têtes de sujets de la bibliothèque du Congrès). Identifiez les termes choisis à l'aide de l'attribut scheme
sous la balise <subjectset>
, par exemple, <subjectset scheme="libraryofcongress">
. Vous trouverez les en-têtes de sujets LCSH dans la page Authorities & Vocabularies (Autorités et terminologie) de la bibliothèque du Congrès : http://id.loc.gov/authorities/search/.
<mediaobject role="cover" id="epub_cover">
Utilisez une balise <mediaobject>
avec les attributs role="cover"
ou id="epub_cover"
pour définir une page de garde artistique pour un livre électronique au format EPUB. Par exemple :
<mediaobject role="cover" id="epub_cover"> <imageobject role="front-large" remap="lrg"> <imagedata width="600px" format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front" remap="s"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front-small" remap="xs"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="thumbnail" remap="cs"> <imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/> </imageobject> </mediaobject>
Comme pour toute autre image du document, placez les images de la page de garde dans le sous-répertoire images
.
Comme indiqué plus haut, le fichier Book_Info.xml
par défaut utilisé par Publican inclut une balise <edition>
.
Si vous distribuez un livre sous forme d'un paquet RPM, les données placées sous cette balise définissent les deux premiers chiffres du numéro de version dans le nom du fichier RPM.
Ainsi, une édition « 1.0 » devient une version « 1.0 ».
Book_Info.xml
comprend également une balise <pubsnumber>
. Toute donnée placée sous cette balise modifie le numéro de parution des ouvrages empaquetés sous forme RPM.
Un ouvrage édition « 1.0 » et publication « 5 », sera la version 1.0, parution 5 (1.0-5).
Les numéros d'édition et de parution ne sont pas liés à la balise <productnumber>
également trouvée dans Book_Info.xml
: <productnumber>
marque le numéro de version du produit documenté ou auquel se rapporte le document.
Il est parfaitement possible d'avoir une deuxième édition d'un ouvrage se rapportant à une même version d'un produit.
En bibliographie, deux copies d'un ouvrage sont une même édition si elles sont imprimées en utilisant essentiellement les mêmes pages ou planches maîtresses de composition (« essentiellement » vise la possibilité de corriger les fautes d'orthographe ou autres modifications sans conséquence).
Les collectionneurs de livres confondent systématiquement « première édition » avec « première impression », alors que les bibliographes font attention à ce qui est écrit en en-tête de l'ouvrage et ils distinguent une deuxième impression des mêmes (ou essentiellement les mêmes) planches avec « 1ère édition, 2e impression » ou « Réimpression de la 1ère édition ».
Nous recommandons de suivre la pratique des bibliographes à ce propos. Si vous utilisez Publican pour publier à nouveau un ouvrage à partir d'un « XML substantiellement identique », incrémentez la balise <pubsnumber>
, et non la balise <edition>
. Ce fonctionnement est sensiblement équivalent aux décomptes des éditions traditionnelles.
De même que pour changer le numéro d'édition, nous recommandons la méthode de la publication traditionnelle pour le changement d'édition d'un ouvrage : s'il est revu et ré-écrit de manière significative. La mesure du « significatif » ou la quantité de réécriture nécessaire pour incrémenter d'un entier le numéro d'édition d'une unité comparée à celle nécessaire pour ne l'augmenter que d'une fraction est laissée à l'initiative du rédacteur.
Author_Group.xml
n'est pas obligatoire mais c'est le bon endroit pour enregistrer l'auteur, l'éditeur, l'artiste et autres détails à mettre au crédit de quelqu'un. Voici un exemple de fichier Author_Group.xml
:
<?xml version="1.0" encoding="utf-8"?> <authorgroup xmlns="http://docbook.org/ns/docbook" version="5.0"> <author> <orgname>FF0000 Headgear Documentation Group</orgname> </author> <author> <personname> <firstname>Dude</firstname> <surname>McDude</surname> </personname> <affiliation> <orgname>My Org</orgname> <orgdiv>Best Div in the place</orgdiv> </affiliation> <email>dude.mcdude@myorg.org</email> </author> </authorgroup> \t\t \t\t
Author_Group.xml
n'a pas à contenir la totalité des informations ci-dessus : incorporez-en plus ou moins selon nécessité.
Les articles DocBook ne peuvent pas être subdivisés en chapitres. Si vous vous servez de l'option --type=article
avec $
publican create, Publican ne crée pas de fichier Chapter.xml
. Utilisez les sections pour organiser le contenu des articles.
Reportez-vous à l'ouvrage DocBook: The Definitive Guide par Norman Walsh et Leonard Muellner disponible à l'adresse http://www.docbook.org/tdg/en/html/docbook.html pour plus de détails sur les diverses manières dont collections, ouvrages, articles, parties, chapitres et paragraphes interagissent. En particulier, notez que les articles peuvent être des documents en soi ou bien peuvent être incorporés dans des ouvrages.
Le fichier Chapter.xml
est un canevas de création des fichiers « chapitres ». Les fichiers chapitres sont le contenu constitutif d'un ouvrage. Voici un canevas de découpage en chapitres (Chapter.xml
) créé par la commande $
publican create. Notez que DOCTYPE
est égal à 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>
Ce chapitre comporte deux sections, Section 1 Test
et Section 2 Test
. Voyez la page http://docbook.org/tdg/en/html/chapter.html pour plus d'informations à propos des chapitres.
Le fichier « chapitre » peut être renommé pour refléter son objet. Ainsi, un chapitre à propos de l'installation d'un produit sera nommé Installation.xml
par exemple, alors qu'un chapitre sur le paramétrage d'un logiciel sera plutôt appelé Setup.xml
ou Configuration.xml
.
Le fichier Nom_document.xml
contient des directives xi:include
pour incorporer les autres fichiers XML constitutifs du document, y compris des chapitres ou des sections contenues dans d'autres fichiers XML. Ainsi, un fichier Nom_document.xml
d'ouvrage rassemble les chapitres contenus dans plusieurs fichiers XML distincts.
Voici un exemple de fichier Nom_document.xml
décrivant un livre DocBook — notez que le paramètre DOCTYPE
est égal à book
.
Exemple 4.4. Un livre 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>
Cet exemple charge les fichiers XML Book_Info.xml
, Preface.xml
, Chapter.xml
et Appendix.xml
.
L'ordre dans lequel les chapitres sont énumérés a de l'importance. Quand cet exemple de livre est construit, Book_Info.xml
doit précéder Preface.xml
, qui lui-même doit précéder Chapter.xml
, etc.
Le fichier Nom_document.xml
n'est pas limité à l'utilisation de directives xi:include
. Vous pouvez créer des documents avec un seul fichier XML. Voici un exemple d'ouvrage créé avec un seul fichier XML :
<book> <chapter> <title>Chapter 1</title> <para> A paragraph in Chapter 1. </para> <section id="section1"> <title>Chapter 1 Section 1</title> <para> A paragraph in Section 1. </para> </section> <section id="section2"> <title>Chapter 1 Section 2</title> <para> A paragraph in Section 2. </para> </section> </chapter> <chapter> <title>Chapter 2</title> <para> A paragraph in Chapter 2. </para> </chapter> </book>
This book contains two chapters. Chapter one contains two sections. Refer to http://docbook.org/tdg/en/html/section.html for further information about sections, and http://docbook.org/tdg/en/html/book.html for further information about books.
Le fichier Nom_document.ent
s'utilise pour définir les entités locales. Les entités YEAR
et HOLDER
sont employées pour les informations de copyright. Par défaut, Publican définit YEAR
au millésime de l'année actuelle et insère un message dans HOLDER
pour vous rappeler de définir le tenant des droits d'auteur du document. Si l'une ou l'autre des entités YEAR
et HOLDER
sont manquantes, le document ne se construit pas.
D'autres entités peuvent être nécessaires pour l'estampille du document. Par exemple, l'estampille de Publican pour des documents Fedora utilise l'entité BOOKID
pour indiquer aux lecteurs comment ils doivent référencer le document s'ils souhaitent des retours à son propos.
<?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>
Les entités offrent des commodités, mais elles doivent être utilisées avec beaucoup de discernement dans les documents à traduire. Écrire, par exemple, &FDS;
au lieu de Fedora Directory Server économise le temps de celui qui écrit, mais les entités transformées n'apparaîtront pas dans les fichiers « portable object » (PO) utilisés par le traducteur. Les traductions complètes de documents contenant des entités sont, en conséquence, impossibles.
Les entités sont des obstacles spécialement pour les traducteurs en empêchant la production de traductions de bonne qualité. Intrinsèquement, un mot ou une phrase représentés par une entité sont rendus de la même façon chaque fois que l'entité apparaît dans le document, quelle que soit la langue. Il résulte de cette rigidité que le mot, ou le groupe de mots, représenté par l'entité peut devenir illisible ou incompréhensible dans la langue cible ; de même, ce mot ou ce groupe de mots ne peut pas suivre les variations résultant de l'application de règles grammaticales pour la cible. Plus, comme les entités ne sont pas transformées lorsque le XML est converti en PO, les traducteurs ne peuvent pas choisir des termes corrects dans le contexte, comme l'exigeraient les règles grammaticales de la langue cible.
Si vous définissez une entité — <!ENTITY LIFT "Liberty Installation and Formatting Tome">
— vous pouvez saisir, à la place, &LIFT;
dans le XML ; l'expression sera développée en Liberty Installation and Formatting Tome
chaque fois que l'ouvrage sera construit au format HTML, PDF ou texte.
Les entités n'étant pas transformées quand le XML est converti en PO, les traducteurs, en conséquence, ne voient jamais Liberty Installation and Formatting Tome
. Au lieu de cela, ils voient &LIFT;
, qu'il leur est impossible de traduire.
Examinons quelque chose d'aussi banal que le morceau suivant de phrase en anglais à traduire dans une langue de la même famille : l'allemand.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
Une traduction possible serait :
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
Comme l'intégralité du texte est disponible, le titre a pu être élégamment traduit en allemand. Notez l'utilisation de ‘dem’, forme correcte de l'article défini (« le ») se rapportant à Wälzer (« tome ») dans son contexte grammatical.
A contrario, si des entités ont été utilisées, l'entrée dans le fichier PO est ainsi rédigée :
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr ""
La traduction donnerait alors probablement :
#. 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…"
Et le rendu serait :
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
Ceci, bien entendu, laisse le titre en anglais, avec des mots comme « Tome » et « Formatting » que des lecteurs pourraient ne pas comprendre. De même, le traducteur est forcé d'omettre l'article défini ‘dem’, construction générale s'approchant d'une hybridation anglais et allemand que les locuteurs allemands appellent Denglisch ou Angleutsch. Beaucoup de locuteurs allemands considèrent cette approche comme incorrecte et pratiquement tous la trouvent inélégante.
Des problèmes semblables sont constatés avec un fragment comme :
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
S'il n'y a pas de texte dissimulé dans une entité, une traduction possible en allemand serait :
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
Si une entité avait été employée pour que le rédacteur économise un peu de temps, le traducteur aurait été confronté à :
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr ""
Et la traduction aurait présenté des différences sournoises, mais importantes :
#. 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…"
Présenté au lecteur, cela donne :
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
À nouveau, notez l'absence de l'article défini (den dans ce contexte grammatical). Ce n'est pas élégant, mais imparable car le traducteur ne peut pas deviner quelle forme de l'article défini utiliser (den, die ou das) ; cela conduit inévitablement à une erreur.
Pour terminer, sachez que, même si un mot donné ne change jamais de forme en anglais, cela n'est pas nécessairement vrai dans d'autres langues, même quand le nom est un nom propre, comme le nom d'un produit. Dans beaucoup de langues, les termes changent de forme (présentent une flexion) selon leur rôle dans la phrase (leur cas grammatical). Une entité XML définie pour représenter un nom ou une phrase en anglais peut rendre une traduction correcte impossible dans de telles langues.
Par exemple, si vous écrivez un document qui s'applique à plusieurs produits, vous pouvez être tenté d'utiliser une entité comme &PRODUCT;
. L'avantage de cette approche est qu'en changeant simplement sa valeur dans le fichier Nom_document.ent
, vous pourrez facilement adapter l'ouvrage au document (par exemple) Red Hat Enterprise Linux, Fedora ou CentOS. Toutefois, alors que le nom propre Fedora
ne change jamais en anglais, il a plusieurs formes dans d'autres langues. Par exemple, en tchèque, le nom Fedora
a six formes différentes, selon l'une des sept possibilités d'utilisation dans une phrase :
Tableau 4.1. « Fedora » en tchèque
Cas | Utilisation | Forme |
---|---|---|
Nominatif | le sujet du verbe | Fedora |
Génitif | indique la possession | Fedory |
Accusatif | complément d'objet direct | Fedoru |
Datif | complément d'objet indirect | Fedoře |
Vocatif | appel direct du sujet | Fedoro |
Locatif | relatif à un emplacement | Fedoře |
Instrumental | relatif à une méthode | Fedorou |
Par exemple :
Fedora je linuxová distribuce. — Fedora est une distribution Linux.
Inštalácia Fedory — installation de Fedora
Stáhnout Fedoru — obtenez Fedora
Přispějte Fedoře — contribuez à Fedora
Ahoj, Fedoro! — Hello Fedora !
Ve Fedoře 10… — dans Fedora 10…
S Fedorou získáváte nejnovější… — avec Fedora, vous obtenez la dernière …
Une phrase qui commence par S Fedora získáváte nejnovější… reste compréhensible au lecteur tchèque, mais le résultat n'est pas grammaticalement correct. Le même effet peut être simulé en anglais, car même si les mots anglais ont perdu leurs déclinaisons au cours du Moyen Âge, les pronoms anglais sont restés fléchis. La phrase, « Me see she » est tout à fait compréhensible pour les locuteurs anglais, mais ce n'est pas ce à quoi ils s'attendent, parce que la forme des pronoms me
et she
n'est pas correcte. Me
est l'accusatif du pronom, et comme il est le sujet de la phrase, le pronom aurait dû être au nominatif, I
. De même, she
est au nominatif, mais comme complément direct d'objet dans la phrase il aurait dû être à l'accusatif, her
.
Les noms dans la plupart des langues slaves comme le russe, l'ukrainien, le tchèque, le polonais, le serbe ou le croate ont sept cas différents. Les noms dans les langues finno-ougriennes comme le finnois, le hongrois ou l'este ont entre quinze et dix-sept cas. D'autres langues modifient les mots pour d'autres raisons. Par exemple, les langues scandinaves fléchissent les noms pour indiquer leur caractère défini ou pas — i.e. si le nom se rapporte à « une chose » ou à « la chose » — et quelques dialectes de ces langues fléchissent les noms à la fois selon leur caractère défini ou non et selon leur cas grammatical.
Maintenant, multipliez ces problèmes par 40, nombre de langues que Publican prend en charge actuellement. Mises à part les quelques chaînes non-traduites que Publican définit par défaut dans le fichier Nom_document.ent
, les entités peuvent trouver une utilité pour les numéros de version des produits. Exceptés ces cas, l'utilisation d'entités équivaut à s'efforcer de restreindre la qualité des traductions en toute connaissance de cause. De plus, les lecteurs du document dans les langues qui fléchissent les noms (que ce soit pour respecter le cas, le caractère défini ou autre raison) ignorent que cette mauvaise grammaire résulte de la définition des entités XML — ils vont probablement supposer que le traducteur est incompétent.
La commande $
publican package recherche dans le répertoire du document le premier fichier XML contenant une balise <revhistory>
. Puis Publican utilise ce fichier pour construire l'historique de révision.
Mettez les images dans le sous-répertoire images
du dossier qui contient vos fichiers XML. Utilisez ./images/nom_image
pour insérer des images dans un ouvrage. Voici un exemple d'insertion de l'image testimage.png
:
<mediaobject> <imageobject> <imagedata fileref="./images/testimage.png" /> </imageobject> <textobject><phrase>alternate text goes here</phrase></textobject> </mediaobject>
Assurez-vous de ne pas avoir oublié de définir un <textobject>
de façon à ce que le contenu reste accessible aux personnes mal-voyantes. Dans certaines juridictions, vous pourriez avoir une responsabilité légale à garantir ce type d'accès — par exemple, si votre société doit se conformer à la section 508 de la loi Rehabilitation Act of 1973[1] des États-Unis.
Si votre ouvrage contient des images nécessitant d'être localement adaptées — par exemple, des captures d'écran d'une interface utilisateur dans une langue autre que la langue originelle de l'ouvrage — placez ces images dans le sous-répertoire images
de chaque répertoire de langue. Assurez-vous que le fichier de l'image « traduite » porte bien le même nom que l'image de la langue d'origine. Quand vous construisez l'ouvrage dans la langue traduite, Publican utilisera le fichier du sous-répertoire images/
de la traduction à la place de celui du sous-répertoire images/
d'origine.
Publican n'utilise que les images du sous-répertoire images
du dossier XML et les images correspondantes du sous-répertoire de même nom des dossiers de langues. Le stockage d'images dans d'autres répertoires que images
ne fonctionne pas.
Si votre ouvrage comporte des exemples de code, placez-les dans un répertoire nommé extras/
de votre dossier de langue source et utilisez une balise <xi:include>
pour mettre le fichier de code dans la structure XML du document. Publican ne fait pas d'analyse de la sémantique XML des fichiers situés dans le répertoire extras/
.
Certain characters are reserved in XML, in particular, &
and <
. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as CDATA
or by replacing them with entities (& and < respectively).[2] If you place these files in the extras/
directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.
Voici la procédure pour incorporer un exemple de code dans le document à partir du répertoire extras/
:
créer le répertoire « extras »
$
mkdiren-US/extras
copier le fichier de code dans le répertoire « extras »
$
cp~/samples/foo.c en-US/extras/.
incorporer avec la balise xi:include
le fichier exemple dans le xml
<programlisting> <xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" /> </programlisting>
vous pouvez maintenant modifier le fichier en-US/extras/foo.c
dans votre éditeur préféré sans vous soucier de la façon dont il affecte le XML.
La même approche fonctionne quand vous souhaitez légender le code par des annotations externes. Par exemple :
<programlistingco> <areaspec> <area id="orbit-for-parameter" coords='4 75'/> <area id="orbit-for-magnitude" coords='12 75'/> </areaspec> <programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <calloutlist> <callout id="callout-for-parameter" arearefs="orbit-for-parameter"> <para> The <firstterm>standard gravitational parameter</firstterm> (μ) is a derived value, the product of Newton's gravitational constant (G) and the mass of the primary body. </para> </callout> <callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"> <para> Since the mass of the orbiting body is many orders of magnitude smaller than the mass of the primary body, the mass of the orbiting body is ignored in this calculation. </para> </callout> </calloutlist> </programlistingco>
Notez les éléments <area>
qui définissent la position des repères d'annotation apparaissant dans l'exemple de code. Les attributs coords
définissent un numéro de ligne et de colonne séparés par une espace. Dans cet exemple, les repères d'annotation sont placés sur les lignes 4 et 12 du code, à l'aplomb de la colonne 75. Même si cette approche implique que vous aurez à ajuster les attributs coords
si vous modifiez le code auquel ces annotations s'appliquent, elle évite le mélange des balises XML <coords>
avec le code lui-même.
[2] Refer to section 2.4 "Character Data and Markup" in the XML 1.0 standard, available from http://www.w3.org/TR/2008/REC-xml-20081126/.
Publican permet d'incorporer n'importe quel fichier dans un document. Ils sont inclus dans le paquet RPM construit avec Publican, puis installés sur le système de l'utilisateur avec le document lui-même. Par exemple, vous pouvez vouloir incorporer des fichiers multimédia de tutoriels pour compléter le document, ou des fichiers exemples en binaire ou autre matériau permettant à l'utilisateur de travailler avec des exemples ou des tutoriels dans un document.
Pour joindre des fichiers avec un document, créez un sous-répertoire nommé files
dans le dossier de la langue d'origine (par ex. en-US
) de l'ouvrage (par ex. Mon_Livre
).
Dans le répertoire Mon_livre
:
$
mkdir en-US/files
Copiez les fichiers dans le répertoire files
:
$
cp tout_fichier en-US/files
La commande $
publican rename facilite le renommage d'un document pour lui donner un nouvel intitulé, ou bien, pour changer le nom ou la version du produit auquel le document s'applique. Elle accepte trois options :
--name
nouveau_titremodifie le titre du document. Par exemple, pour modifier le nom d'un document intitulé Guide de configuration du serveur en Guide de déploiement du serveur, placez-vous dans le répertoire racine du document, puis exécutez :
$
publican rename --name "Guide de déploiement du serveur"
Plus précisément, la commande change le contenu de la balise <title>
dans le fichier Article_Info.xml
, Book_Info.xml
ou Set_Info.xml
et donne une valeur au paramètre mainfile
du fichier publican.cfg
de façon à ce que Publican puisse toujours trouver le nœud racine XML et les entités du document.
Notez que la commande $
publican rename ne modifie aucun nom de fichier. Ainsi, le nœud racine XML et les entités du document sont toujours situés dans les fichiers nommés d'après le titre originel du document — Guide_de_configuration_du_serveur
dans l'exemple précédent.
--product
nouveau_produitmodifie le nom du produit auquel le document s'applique. Par exemple, si le produit s'appelait à l'origine ForceRivet et que son nom soit maintenant PendantFarm, placez-vous dans le répertoire racine du document, puis exécutez :
$
publican rename --product PendantFarm
La commande modifie le contenu de la balise <productname>
dans le fichier Article_Info.xml
, Book_Info.xml
ou Set_Info.xml
.
--version
nouvelle_versionmodifie le numéro de version auquel le document s'applique. Par exemple, si le numéro de version du produit était à l'origine 1.0 mais est maintenant 2.0 , placez-vous dans le répertoire racine du document, puis exécutez :
$
publican rename --version 2.0
La commande change le contenu de la balise <productnumber>
dans le fichier Article_Info.xml
, Book_Info.xml
ou Set_Info.xml
.
Vous pouvez regrouper toute combinaison de ces options en une seule commande. Par exemple :
$
publican rename --name "Guide de déploiement du serveur" --product PendantFarm --version 2.0
La prise en charge d'une adaptation locale des documents a été un souci permanent dans la conception de Publican. Voici le processus général de gestion des traductions de documents avec Publican :
Terminer le XML du document.
Le XML d'une version donnée d'un document ne doit pas être considéré comme ‘figé’. Si le document est stocké dans un dépôt avec contrôle des versions, vous devez déplacer la version considérée dans un répertoire ou une branche séparés. L'auteur peut donc commencer à travailler sur la version suivante du document dans une nouvelle branche, tout en donnant à la traduction une base stable dans la branche précédente.
Facultatif mais recommandé : récupérer le document à traduire. Exécuter :
$
publican trans_drop
Publican crée un nouveau sous-répertoire, nommé trans_drop/
. Le sous-répertoire trans_drop/
contient un instantané des fichiers source du document. Quand le répertoire trans_drop/
est présent dans un projet de documentation, Publican utilise son contenu en tant que base des commandes documents documentés plus bas dans ce chapitre.
Créez les fichiers modèles d'objet portable (POT) à partir des fichiers XML :
$
publican update_pot
Si c'est la première fois que les fichiers POT sont générés pour le document, Publican crée un nouveau sous-répertoire, nommé pot
. Ce sous-répertoire pot
contient un fichier POT pour chaque XML du document. Si Publican avait déjà créé des fichiers POT pour le document, Publican met à jour les fichiers existants pour tenir compte de tout changement dans le XML depuis la dernière version.
Publican crée un fichier POT pour chaque XML dans le répertoire racine, que le fichier soit utilisé ou non. Si vous produisez des fichiers POT à partir de XML inutilisés, vous faites perdre du temps aux traducteurs volontaires en travaux superflus et vous dépensez inutilement de l'argent si vous appointez pour ces tâches.
Servez-vous de la commande $
publican print_unused pour créer la liste des fichiers XML non utilisés dans le document.
Créez des fichiers portable objet (PO) à partir des fichiers POT pour débuter la traduction dans une langue donnée :
$
publican update_po --langs=code_langue
où code_langue est le code pour la langue cible. Reportez-vous à l'Annexe F, Codification des langues. Vous pouvez indiquer plusieurs codes de langue, séparés par des virgules, pour créer des fichiers PO pour plusieurs langues d'un coup. Par exemple :
$
publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
À la création initiale des fichiers PO pour une langue donnée, Publican génére un nouveau sous-répertoire du nom du code de la langue précisé à l'option --langs=
. Ce sous-répertoire contient un fichier PO correspondant à chaque fichier POT du sous-répertoire pot
, plus un fichier Revision_History.xml
pour le suivi de cette traduction particulière. À son initialisation, le fichier Revision_History.xml
enregistre la date de création des fichiers PO pour cette traduction, et la version du XML du langage source (pris dans le fichier Revision_History.xml
de la langue source), version sur laquelle la traduction se fonde.
Si Publican avait déjà créé des fichiers PO pour cette langue, Publican met à jour les fichiers PO existants pour refléter toute modification dans les fichiers POT depuis la précédente mise à jour, et ajoute une nouvelle entrée dans le fichier Revision_History.xml
de la traduction pour enregistrer la date à laquelle les fichiers PO de cette traduction ont été rafraîchis, et la version du XML du langage source sur lequel il se fonde. Vous pouvez mettre à jour les fichiers PO existants de chaque sous-répertoire avec l'option --langs=all
:
$
publican update_po --langs=all
Publican crée un fichier PO pour chaque POT du répertoire pot
, que le fichier POT ait été généré à partir d'un fichier XML utilisé ou non, ou même que le XML correspondant existe ou pas. Si vous produisez des fichiers PO à partir de fichiers POT issus de XML inutilisés ou supprimés, vous faites perdre du temps aux traducteurs volontaires en travaux superflus et vous dépensez inutilement de l'argent si vous appointez pour ces tâches.
Quand vous créez des fichiers PO, Publican affiche un avertissement pour tout fichier POT qui n'aurait pas de XML correspondant, mais il le génère quand même. Néanmoins, Publican ne vous avertira pas pour des fichiers POT créés à partir de XML inutilisés dans le document.
Traduisez les chaînes contenues dans les fichiers PO.
Si vous mettez à jour une traduction précédemment publiée suite à une révision ne résultant pas d'une modification de la langue source, utilisez la commande de Publican, publican add_revision, pour décrire les changements ou les corrections apportés. Publican met à jour le fichier Revision_History.xml
pour vous.
Si le document a été modifié au niveau de sa langue d'origine, utilisez, en lieu et place, les commandes publican trans_drop, publican update_pot et publican update_po comme décrit plus haut dans ce chapitre.
Construire le document dans la langue cible, par exemple :
$
publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
ou empaquetez-le dans la langue cible, par exemple :
$
publican package --lang=is-IS
Vous pouvez construire le document dans toutes les langues pour lesquelles vous disposez de traductions avec l'option --langs=all
, mais notez bien que vous devez empaqueter séparément pour chaque langue. Voyez la Section 4.7, « Construction d'un document » pour plus d'informations à propos de la construction d'un document et la Section 4.8, « Empaquetage d'un document » pour empaqueter un document.
La traduction intervient une fois que l'ouvrage est terminé. Vous n'avez pas besoin de savoir par avance quels seront les traducteurs de votre ouvrage pour les en remercier. Créez un fichier $translation/Author_Group.xml
dans lequel vous mettez un groupe auteur Docbook valide. Le traducteur peut ajouter ses propres détails dans ce fichier et Publican les ajoute lors de la construction à $source_lang/Author_Group.xml
. Les auteurs peuvent ainsi mettre un point final au texte original sans avoir besoin de savoir qui traduira l'ouvrage.
Docbook collationne et trie automatiquement les éléments <glossentry>
dans le glossaire de l'ouvrage ; il fait de même pour les éléments <indexterm>
, <primary>
, <secondary>
et <tertiary>
dans l'index du livre. Les entrées sont triées automatiquement ; alors que le système fonctionne bien pour les langues écrites avec un alphabet, un alphasyllabaire ou un script syllabaire, les langues écrites à l'aide de logogrammes sont moins bien triées.
Pour ajuster manuellement l'ordre de tri d'une entrée de glossaire ou d'index, ajoutez à la main l'attribut DocBook sortas
à l'élément XML. Par exemple, pour être sûr que le mot japonais 暗号化 est correctement placé dans l'index, indiquez :
#. Tag: indexterm #, no-c-format msgid "<primary>encryption</primary>" msgstr "<primary sortas="あんごうか">暗号化</primary>"
De même, pour s'assurer que le mot japonais est correctement placé dans un glossaire, précisez :
#. Tag: glossentry #, no-c-format msgid "<glossterm>encryption</glossterm>" msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"
Les paramètres définis dans le fichier de configuration du document (par défaut, publican.cfg
) vous permettent de contrôler divers rendus de présentation du document — voyez la Section 4.1.1, « Le fichier publican.cfg ».
Si vous entretenez plusieurs versions d'un document, vous pouvez créer un fichier de configuration pour chaque version. À la construction du document, vous pouvez utiliser l'option --config
pour préciser le fichier de configuration (et donc le jeu de paramètres associés) à utiliser dans une construction donnée, par exemple :
$
publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
Pour construire un document :
confirmer que les entités YEAR
et HOLDER
ont été définies dans le fichier Nom_document.ent
, comme décrit dans la Section 4.1.6, « Nom_document.ent ».
se placer dans le répertoire racine du document. Par exemple, si le document s'intitule Livre_test
et est situé dans le répertoire ~/livres/
, exécuter la commande :
$
cd ~/livres/Livre_test
lancer un test pour détecter une éventuelle anomalie qui empêcherait la construction de l'ouvrage dans la langue choisie, par exemple :
$
publican build --formats=test --langs=en-US
pour construire l'ouvrage, lancer :
$
publican build --formats=formats --langs=langues
Remplacer formats par la liste des formats, séparés par des virgules, que vous souhaitez construire ; par exemple, html,html-single,pdf
. Remplacer langues par la liste des langues, séparées par des virgules, pour lesquelles vous voulez construire le document ; par exemple, en-US,sv-SE,uk-UA,ko-KR
.
Formats acceptables pour l'action build
html
Publican crée une sortie du document au format HTML sur plusieurs pages, avec chaque chapitre et section majeure sur une page distincte. Publican met un index en tête du document, et place des éléments de navigation sur chaque page.
Utiliser les paramètres chunk_first
et chunk_section depth
dans le fichier publican.cfg
pour contrôler la façon dont Publican découpera les chapitres dans ce format.
html-single
Publican crée la sortie sur une page HTML unique avec la table des matières en tête de page.
html-desktop
Publican crée une sortie du document sur une seule page HTML avec la table des matières dans un panneau séparé à gauche du document.
man
Publican prépare une sortie du document sous forme d'une page de manuel (« man page ») à utiliser avec Linux, UNIX ou des systèmes d'exploitation semblables.
pdf
Publican crée une sortie du document sous forme d'un fichier PDF.
test
Publican valide la structure XML de l'ouvrage, mais ne transpose pas le XML dans un autre format.
txt
Publican prépare une sortie du document sous forme d'un fichier texte unique.
epub
Publican prépare une sortie du document sous forme d'un livre électronique au format EPUB.
eclipse
Publican sort le document sous forme d'un greffon d'aide Eclipse. Voir la Section 4.1.1, « Le fichier publican.cfg » pour des précisions pour la définition des paramètres id
, name
et provider-name
de Eclipse avec les paramètres ec_id
, ec_name
et ec_provider
de Publican.
Voici des exemples montrant des commandes courantes avec $
publican build :
$
publican build --help
liste les options de $
publican build disponibles pour construire un ouvrage.
$
publican build --formats=test --langs=langues
vérifie que l'ouvrage peut être correctement construit. Lancer la commande --formats=test avant d'exécuter tout autre commande de $
publican build et avant de téléverser un ouvrage dans un dépôt à version contrôlée à partir duquel d'autres contributeurs pourraient le télécharger.
$
publican build --formats=html --langs=langues
construit l'ouvrage au format HTML sur plusieurs pages. La sortie HTML est située dans le répertoire Nom_document/tmp/langue/html/
. Chaque chapitre et division majeure est placée dans un fichier HTML distinct. Vous pouvez contrôler la profondeur de subdivision avec laquelle Publican met les sous-sections dans des fichiers séparés avec le paramètre chunk-section-depth
dans publican.cfg
— reportez-vous à la Section 4.1.1, « Le fichier publican.cfg ».
$
publican build --formats=html-single --langs=langues
construit l'ouvrage au format HTML sur une seule page. La sortie sera un fichier HTML unique situé dans le répertoire Nom_document/tmp/langue/html-single/
.
$
publican build --formats=pdf --langs=langues
construit l'ouvrage sous forme d'un fichier PDF. Publican compte sur une application externe, FOP, pour le rendu en PDF. En conséquence, la construction de PDF peut ne pas être possible sur tous les systèmes ; elle dépend de la disponibilité de FOP. La sortie sera un fichier PDF unique situé dans le répertoire Nom_document/tmp/langue/pdf/
.
$
publican build --formats=html,html-single,pdf --langs=languesconstruit l'ouvrage dans les formats HTML multi-pages, HTML page unique et PDF.
Publican valide le XML vis à vis du DTD DocBook (définition type du document) avant la construction de son contenu. Toutefois, tant que le développement d'un document est en cours, vous pouvez souhaiter sauter cette phase pendant la construction, en particulier si le document comporte des références croisées (<xref>
) vers des sections qui ne sont pas encore rédigées. Pour sauter l'étape de la validation, exécuter $
publican build avec l'option --novalid
. Les références croisées inexistantes apparaîtront dans le document construit sous forme de trois points d'interrogation : ???
.
Comme le document n'a pas été validé vis à vis du DTD, la qualité de la sortie produite avec l'option --novalid
est forcément suspecte. Ne publiez pas de documentation construite avec l'option --novalid
.
Ce paragraphe traite de l'empaquetage des documents en vue d'une distribution par l'intermédiaire du Gestionnaire de paquets RPM. Néanmoins, si vous utilisez la commande $
publican package, Publican crée une archive « .tar » ; vous pouvez l'utiliser pour construire un paquet à distribuer pour d'autres gestionnaires de paquets. Si vous exécutez publican package sur un ordinateur où rpmbuild n'est pas installé, Publican génère tout de même l'archive « .tar », même s'il ne peut pas créer de paquet RPM pour cette archive.
Les paramètres définis dans le fichier de configuration du document (par défaut, publican.cfg
) vous permettent de contrôler divers aspects de la manière dont le document est présenté et empaqueté — voyez la Section 4.1.1, « Le fichier publican.cfg ».
Si vous entretenez plusieurs versions d'un document, vous pouvez créer un fichier de configuration pour chaque version. À l'empaquetage du document, vous pouvez utiliser l'option --config
pour préciser le fichier de configuration (et donc le jeu de paramètres associés) à utiliser dans une construction donnée, par exemple :
$
publican package --lang hi-IN --config community.cfg
Publican ne se contente pas de construire une documentation ; il peut empaqueter son contenu sous forme de paquets RPM en vue d'une distribution sur des stations de travail autonomes ou des serveurs Web. Les paquets RPM s'utilisent pour distribuer des logiciels pour les ordinateurs avec le système d'exploitation Linux utilisant le Gestionnaire de paquets RPM. Parmi ces systèmes d'exploitation, indiquons : Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux et Yellow Dog Linux, pour ne citer que quelques uns.
Publican peut produire à la fois des paquets RPM sources (SRPM packages) et des paquets RPM binaires. De plus, les deux types de paquets RPM peuvent être configurés pour un déploiement sur des stations de travail ou des serveurs Web.
Les paquets SRPM contiennent le code source utilisé pour créer le logiciel au lieu du logiciel lui-même. Pour utiliser un paquet SRPM, l'ordinateur doit compiler le code source en logiciel — ou, dans notre cas, en document. Les paquets SRPM de documents Publican contiennent des fichiers XML et un fichier spec plutôt que des documents finis aux formats tels que HTML ou PDF. Vous ne pouvez pas installer directement une documentation à partir de paquets SRPM avec des versions actuelles du Gestionnaire de paquets RPM.
À l'opposé, des paquets RPM binaires contiennent un logiciel — dans notre cas, un document — prêt à être copié à un certain emplacement dans le système de fichiers de l'ordinateur ; il est utilisable immédiatement. Le contenu du paquet RPM binaire n'a pas besoin d'être compilé par l'ordinateur sur lequel il est installé. Donc, en installant une documentation uniquement pour un usage local, il n'est pas nécessaire d'avoir installé Publican. Installer une documentation créée avec Publican sur un serveur Web nécessite que Publican soit installé, mais pour des raisons autres que la compilation du code source. Voyez la Section 4.8.1.2, « Paquets pour ordinateur de bureau et paquets Web » pour une description des différences entre une documentation installée pour un usage local (RPM bureau) et une documentation installée pour servir de contenu Web (RPM Web).
Publican peut empaqueter des documents pour une lecture sur station de travail (un paquet RPM pour ordinateur de bureau) ou pour une installation sur serveur Web et publication sur la Toile (un paquet RPM web). Le paquet RPM pour ordinateur de bureau d'un document Publican et le paquet RPM Web sont différents en ce que le paquet RPM pour ordinateur de bureau n'installe la documentation que pour une utilisation locale sur un ordinateur, alors que le RPM Web l'installe non seulement pour une utilisation locale mais également pour la servir sur la Toile.
Les paquets RPM ordinateur de bureau (binaires) des documents Publican contiennent la documentation au format HTML page unique. Les documents distribués dans ces paquets sont installés dans un sous-répertoire de /usr/share/doc/
, emplacement défini par la norme sur les hiérarchies dans les systèmes de fichiers (Filesystem Hierarchy Standard) (FHS) pour ‘documentations diverses’[3]. Le paquet RPM pour ordinateur de bureau contient également un fichier .desktop, à placer dans /usr/share/applications/
. Ce fichier, activé par l'environnement bureau, ajoute le document installé dans les menus pour faciliter son référencement par les utilisateurs. Par défaut, l'article de menu sera affiché sous → dans le bureau GNOME. Pour personnaliser l'emplacement de l'article du menu, créez un paquet menu de documentation pour avoir des fichiers .directory
et .menu
et définissez des paramètres dt_requires
et menu_category
dans le fichier publican.cfg
pour demander ce paquet et fournir la catégorie de menu appropriée. Voyez la Section 4.8.1.3, « Entrées de menu de bureau pour documents ».
Par défaut, les paquets RPM Web des documents Publican contiennent la documentation aux formats simple page HTML, pages multiples HTML, EPUC et PDF. Les formats inclus varient si :
si vous publiez une documentation dans une langue dans laquelle les sorties PDF ne sont pas actuellement prises en charge. Publican s'appuie sur l'application FOP pour créer la sortie PDF. Présentement FOP ne gère pas les textes s'écrivant de droite à gauche (par exemple, l'arabe, le persan ou l'hébreu). En plus, comme FOP ne peut pas définir aujourd'hui des polices sur une base caractère par caractère, il manque des polices pour les écritures indo-aryennes, y compris certains glyphes latins ; en conséquence, Publican ne peut pas être fiable dans la création de sorties pour les langues indo-aryennes (ou « indiques »). Par défaut, Publican ne comporte pas de fichiers PDF dans les paquets RPM Web générés pour l'arabe, le perse, l'hébreu ou toute langue « indique ».
votre ouvrage ou votre estampille contient le paramètre web_formats
. La valeur de ce paramètre écrase les formats par défaut des paquets Publican. Par exemple, pour publier le document aux formats HTML page unique, PDF et texte, définissez web_formats: html-single,pdf,txt
Le contenu de la construction est installé dans des sous-répertoires de /var/www/html/
, une racine de document courante sur les serveurs Web. Notez que le paquet SRPM Web génère à la fois un paquet RPM binaire web et un paquet RPM binaire bureau.
$
publican package
Utilisez la commande $
publican package --lang=Code_langue pour empaqueter des documents dans la langue définie par l'option --lang
. Reportez-vous à l'Annexe F, Codification des langues pour plus de détails à propos des codes de langues.
Si vous exécutez $
publican package sans autre option que l'option obligatoire --lang
, Publican produit un paquet Web SRPM. Voici la totalité des options disponibles pour publican package :
--lang
languedéfinit la langue dans laquelle la documentation sera empaquetée.
Si la traduction dans une langue donnée n'est pas complète à la date de parution programmée, envisagez de marquer la langue avec la paramètre ignored_translations
dans le fichier publican.cfg
du document. Le paquet sera nommé de manière appropriée pour la langue, mais il contiendra une documentation dans la langue d'origine du XML au lieu d'une traduction partielle. Quand la traduction est complète, supprimez le paramètre ignored_translations
, incrémentez le numéro de parution dans le champ Project-Id-Version
dans le fichier Book_Info.po
de cette langue, et générez le paquet à nouveau. Quand vous distribuerez le paquet révisé, il remplacera le paquet originel non traduit.
--config
nom_fichier
indique à Publican qu'il doit utiliser un fichier de configuration autre que le fichier par défaut publican.cfg
.
--desktop
indique que Publican doit créer un paquet RPM bureau au lieu d'un paquet RPM Web.
--brew
indique que Publican doit charger le paquet complété sur Brew. Brew est le système de construction utilisé en interne par Red Hat ; cette option est sans signification en dehors de Red Hat.
--scratch
utilisée conjointement avec les options --brew
et --desktop
, indique que le paquet SRPM doit avoir été construit à partir de zéro lorsqu'il est envoyé à Brew. Les reconstructions complètes, sans mise à jour de la base de données du paquet à utiliser pour le paquet résultant, s'utilisent pour s'assurer que le paquet SRPM est correctement structuré.
--short_sighted
indique que Publican doit construire le paquet sans inclure le numéro de version du logiciel (paramètre version
dans le fichier publican.cfg
) dans le nom du paquet.
Beaucoup de documentations de logiciels sont propres à une version. Au mieux, les procédures décrites dans la documentation pour une version du produit peuvent ne vous être d'aucune aide pour installer, configurer ou utiliser une autre version du produit. Au pire, elles peuvent prêter à confusion ou même être nuisibles lorsqu'elles sont appliquées à d'autres versions.
Si vous distribuez des documentations sous forme de paquets RPM sans numéro de version dans le nom des paquets, le Gestionnaire de paquet RPM de l'ordinateur de l'utilisateur remplace automatiquement toute documentation existante par la documentation pour la dernière version ; les utilisateurs n'auront donc accès qu'à tout au plus une seule documentation pour la dernière version. Assurez-vous bien que vous souhaitez ce comportement.
--binary
indique que Publican doit construire le paquet comme paquet RPM binaire.
Après avoir exécuté la commande $
publican package, Publican effectue la sortie des paquets SRPM complétés dans le répertoire tmp/rpm
du document et celle des paquets binaires complétés dans tmp/rpm/noarch
.
Par défaut, les paquets de documentation Publican sont nommés :
nom_produit-titre-numéro_produit-[web]-langue-édition-numéro_publication. [.[cible_construction].noarch].extension_fichier
.
Publican utilise l'information dans le fichier de configuration du document (par défaut, publican.cfg
) pour définir les divers paramètres du nom du fichier, puis les informations du fichier Book_Info.xml
pour tout paramètre manquant dans le fichier de configuration. Reportez-vous à la Section 4.1, « Fichiers dans le répertoire de l'ouvrage » pour des précisions sur les paramètres utilisés dans ces fichiers. En plus, veuillez noter que :
les paquets RPM Web incorporent l'élément -web-
entre le numéro de version du produit et le code de la langue.
les paquets SRPM ont l'extension .src.rpm
alors que les paquets RPM binaires ont l'extension .rpm
les paquets RPM binaires incluent cible_construction.noarch
avant l'extension du fichier. cible_construction représente le système d'exploitation et la version pour lesquels le paquet a été construit, tels que définis par le paramètre os_ver
dans le fichier publican.cfg
. L'élément noarch
précise que le paquet peut être installé sur n'importe quel système, quelle que soit l'architecture du système.
utiliser l'option --short_sighted
pour supprimer le -numéro_produit-
du nom du paquet.
les paquets des documents traduits prennent leurs numéros de version à partir du paramètre Project-Id-Version
dans le fichier Article_Info.po
ou Book_Info.po
. Ce numéro de parution est particulier à une langue donnée et n'a aucun rapport avec les numéros de parution du même document dans la langue d'origine ou toute autre langue.
$
publican package — exemples d'utilisationVoici des exemples illustrant quelques options courantes pour le Guide de configuration de Foomaster 9, 2e édition, révision 6.
$
publican package --lang=cs-CZproduit un paquet SRPM Web nommé Guide_de_configuration_de_Foomaster-9-web-cs-CZ-2-6.src.rpm contenant les fichiers XML source en tchèque, de même que le fichier spec.
$
publican package --desktop --lang=cs-CZproduit un paquet SRPM bureau nommé Guide_de_configuration_de_Foomaster-9-cs-CZ-2-6.src.rpm contenant les fichiers XML source en tchèque, de même que le fichier spec.
$
publican package --binary --lang=cs-CZproduit à la fois un paquet RPM web binaire nommé Guide_de_configuration_de_Foomaster-9-web-cs-CZ-2-6.el5.noarch.rpm et un paquet RPM binaire bureau nommé Guide_de_configuration_de_Foomaster-9-cs-CZ-2-6.el5.noarch.rpm contenant une documentation en tchèque, construits pour le système d'exploitation Red Hat Enterprise Linux 5.
$
publican package --desktop --binary --lang=cs-CZproduit un paquet RPM binaire bureau nommé Guide_de_configuration_de_Foomaster-9-cs-CZ-2-6.el5.noarch.rpm contenant une documentation en tchèque, construit pour le système d'exploitation Red Hat Enterprise Linux 5.
$
publican package --desktop --short_sighted --lang=cs-CZproduit un paquet SRPM nommé Guide_de_configuration_de_Foomaster-cs-CZ-2-6.src.rpm contenant une documentation en tchèque. Ce paquet remplacera tout guide de configuration pour les précédentes versions de Foomaster existant sur le système. Les utilisateurs ne pourront pas avoir accès à la fois au Guide de configuration de Foomaster 8 et au Guide de configuration de Foomaster 9.
[3] Reportez-vous à la page http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA
En certaines circonstances, vous pouvez avoir besoin de maintenir plusieurs versions d'un ouvrage ; par exemple, un guide HOWTO pour le produit FOO peut avoir une version amont et une version entreprise, avec de très subtiles différences entre elles.
Publicanfacilite la gestion des différences entre plusieurs versions d'un ouvrage en vous permettant d'utiliser une source unique pour toutes les versions. Le balisage conditionnel vous permet de vous assurer qu'un contenu propre à une version n'apparaît que dans la dite version ; autrement dit, le contenu est conditionnel.
Pour soumettre un contenu à une condition dans un ouvrage, servez-vous de l'attribut de balise $
condition. Par exemple, disons que le manuel Comment utiliser le produit Foo a une version « amont », une version « entreprise » et une version « bêta » :
<para condition="upstream"> <application>Foo</application> starts automatically when you boot the system. </para> <para condition="enterprise"> <application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>. </para> <para condition="beta"> <application>Foo</application> does not start automatically when you boot the system. </para> <para condition="beta,enterprise"> To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file. </para>
Pour construire une version donnée (et de la sorte intégrer tout contenu conditionnel propre à la version), ajouter le paramètre condition: version dans le fichier publican.cfg
et exécuter normalement la commande $
publican build. Par exemple, si condition: upstream
est défini dans le fichier publican.cfg
pour Comment utiliser le produit Foo, exécuter :
$
publican build --formats=pdf --langs=en-US
Publican écarte toutes les balises avec des attributs autres que condition="upstream"
et construit Comment utiliser le produit Foo au format PDF en langue anglaise (américain).
Si le nœud racine d'un fichier XML est exclu par une condition, la construction du document échouera, car les fichiers vides ne sont pas des XML valides. Par exemple, si Installation_and_configuration_on_Fedora.xml
ne contient qu'un seul chapitre :
<?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> [texte du chapitre] </chapter>
et que ce chapitre est inclus dans User_Guide.xml
avec une balise <xi:include>
, le document ne pourra pas être construit si $
condition: Ubuntu est défini dans le fichier publican.cfg
.
Pour exclure ce chapitre, ajoutez une condition à la balise <xi:include>
dans User_Guide.xml
, et non dans la balise <chapter>
dans Installation_and_configuration_on_Fedora.xml
.
Si une balise <xref>
pointe sur un contenu non incorporé dans la construction à cause d'une balise conditionnelle, la construction avortera. Par exemple, si le fichier publican.cfg
définit $
condition: upstream, la commande publican build --formats=pdf --langs=en-US échoue si l'ouvrage est marqué avec la balise <xref linkend="betasection">
pointant sur <section id="betasection" condition="beta">
.
N'utilisez les balises conditionnelles qu'avec grande précaution dans les ouvrages prévus pour être traduits ; cette fonctionnalité crée des difficultés supplémentaires pour les traducteurs.
Les balises conditionnelles créent des difficultés de deux sortes pour les traducteurs : elles obscurcissent le contexte dans les fichiers « portable object » (PO) sur lesquels le traducteur travaille et rendent la relecture plus délicate pour les traducteurs n'ayant pas une connaissance précise de l'ouvrage et des conditions imposées.
Le fichier PO du document contient l'ensemble complet des balises provenant des fichiers XML, quelles que soient les conditions définies. Quand un traducteur ouvre un fichier PO, par exemple celui de Comment utiliser le produit Foo dans Section 4.9, « Balisage conditionnel », il voit :
#. 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 ""
Comme les fichiers PO n'incluent pas les attributs de balise, il n'y a ici rien de bien évident pour indiquer au traducteur que ces paragraphes sont des alternatives s'excluant mutuellement et que l'auteur n'entendait pas introduire une continuité de signification d'une phrase à l'autre.
Dans cet exemple, les seuls paragraphes avec une continuité logique de signification sont les paragraphes trois et quatre. Et comme ce deux paragraphes n'apparaissent dans l'ouvrage qu'au titre de la version bêta du produit, il prennent (heureusement) du sens dans la continuité. Ainsi, l'utilisation de conditions demande ici au traducteur d'opérer sur le contenu de façon parcellaire sans possibilité de suivre une continuité contextuelle d'un paragraphe l'autre. Quand les traducteurs travaillent dans ces conditions, la qualité de la traduction en souffre, ou bien, cela demande plus de temps — et donc le coût de la traduction en est accru.
Plus encore, excepté si les traducteurs travaillant sur l'ouvrage savent comment configurer le fichier publican.cfg
de Publican et sont avertis des conditions de validation, il ne peuvent pas relire leur traduction. Dans l'ignorance, à la relecture, il vont s'étonner de ne pas retrouver des phrases trouvées dans le fichier PO qu'ils savent avoir traduites. Si vous utilisez des balises conditionnelles dans vos ouvrages, prévoyez de fournir une prise en charge plus poussée des traducteurs, comparée à celle habituellement consentie.
Comme alternative aux balises conditionelles, envisagez l'entretien de versions séparées de l'ouvrage dans des branches séparées d'un dépôt à versions contrôlées. Vous pourrez encore partager les fichiers XML et même les fichiers PO entre les diverses branches si nécessaire ; tout système de contrôle des versions vous permettra de partager rapidement les modifications selon les branches.
Si vous entretenez deux versions d'un ouvrage dans le même dépôt, nous recommandons l'utilisation d'un fichier de configuration distinct pour chaque version. Par exemple, le fichier upstream.cfg
peut contenir la condition condition: upstream
et le fichier enterprise.cfg
condition: enterprise
. Puis vous préciserez la version du document à construire ou à empaqueter avec l'option --config
; par exemple, $
publican package --lang en-US --config upstream.cfg. L'utilisation de deux fichiers de configuration distincts économise la modification d'un fichier de configuration unique chaque fois que vous construisez ou empaquetez un document.
Une documentation complète pour un logiciel en pré-parution n'est pas la même chose qu'un brouillon de documentation.
Des brouillons sont des versions non terminées d'un ouvrage ou d'un article, et leur statut d'incomplétude n'est pas lié à l'état du logiciel qu'ils documentent.
Dans les deux circonstances, toutefois, il est important de définir clairement l'état du logiciel, de la documentation ou des deux auprès des utilisateurs, des développeurs, des lecteurs et des réviseurs.
Une documentation pour un logiciel en pré-parution, et particulièrement pour celui venant d'être distribué aux testeurs, utilisateurs et partenaires, doit porter clairement un marquage indiquant l'état de bêta-test du logiciel.
Pour créer ce marquage, effectuez les opérations suivantes :
ajoutez le numéro de version de pré-parution du logiciel, ou une information équivalent sur son état, sous la balise <subtitle>
dans le fichier Book_Info.xml
. Mettez un texte complémentaire dans des balises <remark>
. Par exemple :
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
ajoutez le paramètre show_remarks
dans le fichier publican.cfg
et fixer sa valeur à « 1 » :
show_remarks: 1
Quand vous construisez l'ouvrage avec la balise <remark>
, complétée du paramétrage de show_remarks
, la nature de l'état de pré-parution du logiciel est affichée clairement et sans erreur possible. Un PDF ainsi construit affiche la remarque sur la couverture et les pages titre. Un HTML ainsi construit (page unique ou pages multiples) affichera la remarque au début de index.html
.
Comme cette approche n'effectue aucune modification de l'information dans le fichier Book_Info.xml
utilisée pour générer le RPM, elle assure également qu'il n'y a aucune ambiguïté dans une opération avec le sous-système RPM.
Exemple 4.7. An example of an inline remark
Here is an example of an inline remark.
Il est de la responsabilité de l'auteur de supprimer la balise <remark>
et son contenu, ainsi que de supprimer ou désactiver le paramètre show_remarks
quand la documentation est mise à jour pour être utilisée avec la version de la parution finale du logiciel.
Un documentation non terminée mise à disposition d'autres personnes pour revue doit être clairement marquée comme telle.
Pour ajouter le filigrane « draft » ajoutez l'attribut status="draft"
à la balise <article>
, <book>
ou <set>
dans le nœud racine du document. Par exemple :
<book status="draft">
Par défaut, le nœud racine est la balise <book>
dans le fichier Nom_document.xml
.
Si vous travaillez sur un article ou sur une collection, le nœud racine est la balise <article>
ou <set>
dans le fichier Nom_document.xml
.
L'ajout de l'attribut status="draft"
déclenche l'apparition dans chaque page du document du filigrane « draft ». À dessein.
Même si vous modifiez uniquement une partie de votre travail avant de l'adresser pour revue, le fait de marquer chaque page comme étant « draft » (brouillon) va inciter les réviseurs à rapporter les erreurs ou les fautes de frappe qu'ils auront remarquées au passage. De plus cela prévient les simples lecteurs de l'ouvrage de ne pas confondre un brouillon avec une version achevée.
Exemple 4.8. An example of a block marked up as draft
This is an example of a block that is marked as draft
Isn't it pretty!
Pour marquer proprement une documentation inachevée pour un logiciel en pré-parution, effectuez les deux procédures de marquage ci-dessus.
DocBook allows setting the revisionflag
on many elements to allow easier reviewing on changed documents. Publican, as of version 4.1, will add highlighting to these elements if the book is in draft mode. e.g. revisionflag="added"
This is how an element that has been added to a new revision is marked-up.
This is how an element that has been changed in a new revision is marked-up.
This is how an element that has been marked for deletion from a new revision is marked-up. Publican will not automatically delete or hide this content, you have to ensure this is done before publication.
Les estampilles sont composées d'un ensemble de fichiers que Publican utilise pour donner un aspect et un style en accord avec le produit ou la distribution dans ses sorties HTML ou PDF. Ces fichiers indiquent le texte standard à afficher en tête des documents, les images comme les logos et des éléments stylistiques comme les schémas de couleurs. Publican est livré avec l'estampille, common/
. Des projets de documentation peuvent produire et distribuer leur propre estampille aux contributeurs, soit sous forme d'un paquet (RPM, par exemple) ou d'une archive (par exemple, un fichier « .tar » ou ZIP).
Les chartes graphiques Publican pour les documents des marques Fedora, Genome et oVirt sont disponibles sous forme de paquets RPM dans Fedora. De même, Red Hat distribue en interne des paquets RPM contenant les estampilles Publican pour les documents GIMP, JBoss et Red Hat. En présupposant que vous avez accès aux dépôts concernés, vous pouvez installer ces chartes sur un ordinateur tournant sous Red Hat Enterprise Linux ou Fedora — ou un système d'exploitation dérivé de l'un ou l'autre — avec la commande yum install publican-estampille ou avec un gestionnaire graphique de paquets comme PackageKit.
Si vous utilisez Publican sur un système d'exploitation qui n'utilise pas l'empaquetage RPM, votre projet de documentation a la possibilité de signer sa marque dans un autre format. Quel que soit le format dans lequel l'estampille est fournie, vous devez mettre les fichiers dans un sous-répertoire de Common_Content
de Publican. Par défaut, ce répertoire est /usr/share/publican/Common_Content
dans les systèmes d'exploitation Linux et %SystemDrive%/%ProgramFiles%/Publican/Common_Content
dans Windows — en règle générale, C:/Program Files/Publican/Common_Content
.
Chaque estampille actuellement disponible est distribuée avec une licence qui lui est propre :
Pour installer l'estampillage :
Si l'estampille vous a été fournie dans une quelconque archive, par exemple, « .tar » ou un fichier ZIP, décompressez-la dans un nouveau répertoire du système.
Placez-vous dans le répertoire dans lequel vous avez créé ou décompressé l'estampille :
$
cd publican-estampille
où estampille désigne son nom.
Construisez l'estampille :
$
publican build --formats xml --langs all --publish
Installez-la :
$
sudo publican install_brand --path chemin
où chemin désigne le chemin vers les fichiers de « Common Content » de Publican. Par exemple, sur un système Linux, exécutez :
$
sudo publican install_brand --path /usr/share/publican/Common_Content
ou bien, sur un système Windows, exécutez :
$
publican install_brand --path "C:/Program Files/Publican/Common_Content"
Tableau 5.1. Estampilles courantes et leurs paquets
Marque | Licence des fichiers « Common Content » | Licence par défaut pour les documents | Paquet | Commentaire |
---|---|---|---|---|
common | CC0 1.0 | GFDL Version 1.2 | publican | Licence compatible avec la GPL. Aucune option. |
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 | Aucune option. |
oVirt | OPL 1.0 | OPL 1.0 | publican-ovirt | Aucune option. |
GIMP | GFDL Version 1.2 | GFDL Version 1.2 | publican-gimp | Correspond à la licence de la documentation GIMP existante. |
Genome | OPL 1.0 | OPL 1.0 | publican-genome | Aucune option. |
Veuillez noter la différence entre la licence des fichiers de contenu commun donnés avec la marque « common » et celle indiquée par défaut pour les ouvrages créés avec cette même marque. La licence CC0 vous autorise à redistribuer avec une nouvelle licence les fichiers qui constituent la marque « common » (y compris les fichiers CSS et image) pour s'adapter à votre projet. Publican suggère par défaut la GFDL pour une documentation étant donné que Publican a été développé essentiellement pour construire des documentations de logiciels. La licence GFDL est compatible avec la GPL, qui est la licence la plus couramment utilisée pour les logiciels « Open source ».
Servez-vous de la commande $
create_brand pour fabriquer une nouvelle estampille. Quand vous créez une nouvelle estampille, vous devez lui donner un nom et définir la langue d'origine des fichiers XML de celle-ci. L'option --name
permet d'indiquer le nom et --lang
la langue. Donc, la commande complète est :
$
publican create_brand --name=estampille --lang=code_langue
Publican crée un nouveau sous-répertoire nommé publican-estampille
, où estampille est le nom de cette dernière tel que défini à l'option --name
.
Par exemple, pour créer une estampille nommée Acme
, ayant ses fichiers XML de contenu commun originellement écrits en anglais (américain), exécutez :
$
publican create_brand --name=Acme --lang=en-US
Publican crée l'estampille dans un sous-répertoire nommé publican-Acme
.
Pour configurer la nouvelle estampille, recherchez le mot SETUP
dans les fichiers par défaut que Publican a créés et modifiez-les pour indiquer les détails manquants. Sur les systèmes d'exploitation Linux, vous retrouverez le mot SETUP
dans ces fichiers avec la commande :
$
grep -r 'SETUP' *
Le fait d'exécuter la commande $
publican create_brand --name=estampille --lang=code_langue crée une structure de répertoire avec les fichiers requis. Le répertoire de l'estampille contient initialement :
COPYING
defaults.cfg
overrides.cfg
publican.cfg
publican-estampille.spec
, où estampille est le nom qui la désigne.
README
un sous-répertoire pour les fichiers XML de l'estampille, les feuilles de style CSS et les images par défaut. Le sous-répertoire porte le nom du code de la langue d'origine de l'estampille (par exemple, en-US
). Ces fichiers sont :
Feedback.xml
Legal_Notice.xml
le sous-répertoire css
, qui comporte :
overrides.css
le sous-répertoire images
, qui contient 43 images à la fois au format matriciel (PNG) et au format vectorisé (SGV).
Le fichier publican.cfg
d'une estampille a un rôle analogue à celui du fichier publican.cfg
d'un document — il permet de régler un certain nombre d'options de base pour la définition de l'estampille.
version
définit le numéro de version de l'estampille. Si vous créez celle-ci avec $
publican create_brand, le numéro de version est 0.1
. Mettez à jour le numéro de version dans le fichier publican.cfg
de l'estampille et dans le fichier publican-estampille.spec
quand vous préparez une nouvelle version de l'estampille.
Notez que ce paramètre n'a aucun rapport avec le numéro de version des documents construits avec cette estampille. Par exemple, le Guide d'installation de Fedora 12 a un numéro de version égal à 12
dans son fichier publican.cfg
, mais il peut très bien avoir été construit avec la version 1.0 de l'estampille publican-fedora.
xml_lang
définit la langue des fichiers source XML du répertoire « Common Content » de l'estampille, par exemple, en-US
, comme cela a été précisé par l'option --lang
de $
publican create_brand.
release
indique le numéro de parution de l'estampille. Quand vous en créez une avec $
publican create_brand, le numéro de parution est initialement fixé à 0
. Mettez à jour sa valeur dans le fichier publican.cfg
de l'estampille et dans le fichier publican-estampille.spec
quand vous préparez une nouvelle parution d'une version existante.
type
défini sous la forme type: brand
, ce paramètre identifie le contenu du répertoire comme étant une estampille, et non un ouvrage, un article ou une collection.
brand
définit le nom de l'estampille, tel qu'indiqué à l'option --name
de $
publican create_brand.
web_cfg
le chemin complet vers le fichier de configuration du site Publican pour les sites Web non standards.
web_dir
le chemin complet vers l'emplacement d'installation des fichiers. Vous devez également définir répertoire_www dans publican-estampille.spec
.
web_req
le nom du paquet RPM fournissant le fichier de configuration du site Publican.
Tout document construit dans Publican possède dans son répertoire racine un fichier publican.cfg
qui sert à définir les options de construction du document. Reportez-vous à la Section 4.1.1, « Le fichier publican.cfg » pour une description complète de ces options. Les fichiers defaults.cfg
et overrides.cfg
d'une estampille donnent les valeurs par défaut à utiliser pour tout paramètre qui pourrait être par ailleurs défini dans le fichier publican.cfg
du document.
Quand vous construisez un document avec une estampille donnée, Publican applique d'abord les valeurs du fichier defaults.cfg
de l'estampille avant d'appliquer celles du fichier publican.cfg
. Ainsi les valeurs dans le fichier publican.cfg
du document surchargent celles du fichier defaults.cfg
.
Publican ensuite applique les valeurs du fichier overrides.cfg
de l'estampille, valeurs qui, à leur tour, surchargent celles des fichiers defaults.cfg
et publican.cfg
.
Utilisez le fichier defaults.cfg
pour définir les valeurs couramment appliquées à votre estampille, mais pour lesquelles vous voulez autoriser des modifications dans certains ouvrages de la part d'auteurs de documentations ; utilisez le fichier overrides.cfg
pour définir les valeurs que vous ne voulez pas voir modifiées par ces auteurs.
Vous pouvez ajouter une liste de balises ou d'attributs interdits en précisant banned_tags et banned_attrs respectivement dans defaults.cfg
et dans overrides.cfg
. Publican peut en dresser la liste avec l'action print_banned.
Certains systèmes d'exploitation utilisent l'application Gestionnaire de paquets RPM pour distribuer des logiciels sous forme de paquets RPM. En règle générale, un paquet RPM contient les fichiers du logiciel compressés dans une archive, accompagnés d'un fichier spec qui indique au Gestionnaire de paquets RPM comment et où installer ces fichiers.
Quand vous créez une estampille, Publican génère les grandes lignes d'un fichier spec RPM pour celle-ci. Ce fichier automatiquement généré vous donne un point de départ pour créer le paquet RPM à distribuer avec votre marque. Reportez-vous à la Section 5.4, « Empaquetage d'une estampille » pour savoir comment configurer le fichier spec et comment l'utiliser pour produire un paquet RPM.
Le fichier README
contient une courte description du contenu du paquet de l'estampille.
Le fichier COPYING
contient des précisions sur la licence de copyright pour le paquet, et quelquefois le texte de la licence lui-même.
À l'intérieur du répertoire de l'estampille, il y a un sous-répertoire nommé selon la langue par défaut de cette dernière, langue définie par l'option --lang
à sa création. Ce sous-répertoire contient des fichiers XML et image qui surchargent le contenu commun par défaut livré avec Publican. Particulariser ces fichiers personnalise l'aspect de la charte graphique de votre estampille, y compris le thème de couleurs et le logo.
Feedback.xml
Le fichier Feedback.xml
est incorporé par défaut dans la préface de chaque ouvrage construit avec Publican. Il invite le lecteur à donner un avis à propos du document. Indiquez dans ce fichier la référence des contacts du projet. Si vous utilisez un système de suivi d'anomalies comme Bugzilla, JIRA ou Trac, c'est le bon endroit pour donner cette information.
Legal_Notice.xml
Le fichier Legal_Notice.xml
contient les mentions légales apparaissant en début de chaque document produit avec Publican. Indiquez les détails de la licence de copyright choisie dans ce fichier. Généralement, cela comporte le nom de la licence, un court résumé de celle-ci et un lien vers le texte complet de ladite licence.
css
Le sous-répertoire css
ne contient que le fichier overrides.css
.
Le fichier overrides.css
définit le style visuel de l'estampille. Les valeurs à l'intérieur de ce fichier écrasent celles du fichier Common_Content/common/langue_xml/css/common.css
de Publican.
images
Le sous-répertoire images
contient 43 images, à la fois au format portable network graphics (PNG) (graphiques portables) et scalable vector graphics (SVG)(graphiques vectorisés). Ces images sont des emplacements réservés pour diverses icônes de navigation, des graphiques pour avertissements et des logos d'estampilles. Elles comprennent :
image_left
logo du produit auquel le document s'applique. Il apparaît dans l'angle supérieur gauche des pages HTML ; il contient un lien vers la page Web du produit, telle que définie avec le paramètre prod_url
du fichier publican.cfg
du document. Paramétrez prod_url
dans le fichier defaults.cfg
ou overrides.cfg
de l'estampille, comme vous le jugerez opportun.
image_right
logo de l'équipe auteur de la documentation. Il apparaît dans l'angle supérieur droit des pages HTML ; il contient un lien vers la page Web de l'équipe de documentation, telle que définie au paramètre doc_url
dans le fichier publican.cfg
du document. Si toute la documentation pour cette estampille provient d'une même équipe, envisagez une définition de doc_url
dans le fichier defaults.cfg
ou overrides.cfg
.
title_logo
est la version grande taille du logo du produit ; elle apparaît sur la page titre des documents PDF et en tête des documents HTML.
note
, important
, warning
sont des icônes accompagnant les avertissements XML <note>
, <important>
ou <warning>
.
dot
, dot2
sont des puces utilisées pour les éléments <listitem>
d'une liste <itemizedlist>
.
stock-go-back
, stock-go-forward
, stock-go-up
, stock-home
sont des icônes de navigation pour les pages HTML.
h1-bg
représente le fond de l'en-tête contenant le nom du produit, tel qu'il apparaît en début de chaque document HTML.
watermark_draft
est un filigrane qui apparaît sur les pages des brouillons de documentation. Voyez la Section 4.10.2, « Marquage d'un brouillon de documentation ».
L'option de construction brand_dir de Publican vous permet de définir l'emplacement des fichiers de l'estampille. Ces fichiers n'ont pas besoin de faire partie d'une estampille installée.
Vous pouvez mettre un XSL personnalisé dans le dossier xsl
de l'estampille : il se situe au même niveau que les divers fichiers de langue de votre estampille. Publican utilise tout XSL trouvé dans ce répertoire pour écraser les modèles d'XSL placés dans l'estampille commune (qui, eux-même, s'ils existent, surchargent les modèles XSL du projet Docbook).
Pour des estampilles avec des XSLT personnalisés, il est nécessaire d'échanger le chemin relatif renvoyant aux modèles XLS par un URI.
Ce paragraphe traite de l'empaquetage des documents en vue d'une distribution par l'intermédiaire du Gestionnaire de paquets RPM. Néanmoins, si vous utilisez la commande $
publican package, Publican crée une archive « .tar » ; vous pouvez l'utiliser pour construire un paquet à distribuer pour d'autres gestionnaires de paquets. Si vous exécutez publican package sur un ordinateur où rpmbuild n'est pas installé, Publican génère tout de même l'archive « .tar », même s'il ne peut pas créer de paquet RPM pour cette archive.
Après avoir créé une estampille (comme décrit dans la Section 5.2, « Création d'une estampille »), Publican facilite sa distribution aux membres du projet de documentation sous forme de paquet RPM. Les paquets RPM s'utilisent pour distribuer des logiciels pour les ordinateurs avec le système d'exploitation Linux utilisant le Gestionnaire de paquets RPM. Parmi ces systèmes d'exploitation, indiquons : Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux et Yellow Dog Linux, pour ne citer que quelques uns.
Publican produit à la fois des paquets RPM source (paquets SRPM) et des paquets RPM binaires. Faisant partie du processus, il crée également le fichier spec — fichier contenant les précisions sur la manière d'installer et configurer le paquet.
Les paquets SRPM contiennent le code source utilisé pour créer le logiciel au lieu du logiciel lui-même. Pour utiliser un paquet SRPM, l'ordinateur doit compiler le code source en logiciel. Les paquets SRPM des marques Publican contiennent les fichiers de configuration, des fichiers XML et des fichiers image qui définissent l'estampille dans sa langue d'origine, plus des fichiers PO qui génèrent les fichiers « Common Content » dans les langues traduites. Vous ne pouvez pas installer directement une documentation à partir de paquets SRPM avec des versions actuelles du Gestionnaire de paquets RPM.
À l'opposé, des paquets RPM binaires contiennent un logiciel — soit dans notre cas, une estampille Publican — prête à être copiée à un certain emplacement dans le système de fichiers du l'ordinateur ; elle est utilisable immédiatement. Le contenu du paquet RPM binaire n'a pas besoin d'être compilé par l'ordinateur sur lequel il est installé. Donc, il n'est pas nécessaire d'avoir installé Publican.
Pour empaqueter une estampille, utilisez la commande $
publican package dans le répertoire de l'estampille. Lorsque elle est exécutée sans autre option, Publican crée un paquet SRPM. Les options d'empaquetage d'une estampille sont :
--binary
demande à Publican de construire le paquet en tant que paquet RPM binaire.
--brew
indique que Publican doit charger le paquet complété sur Brew. Brew est le système de construction utilisé en interne par Red Hat ; cette option est sans signification en dehors de Red Hat.
--scratch
utilisée conjointement avec l'option --brew
, indique que le paquet SRPM doit avoir été construit à partir de zéro lorsqu'il est envoyé à Brew. Les reconstructions complètes, sans mise à jour de la base de données du paquet à utiliser pour le paquet résultant, s'utilisent pour s'assurer que le paquet SRPM est correctement structuré.
Les options --lang
, --desktop
et --short_sighted
, s'appliquant à l'empaquetage d'ouvrages ( elles sont décrites dans la Section 4.8, « Empaquetage d'un document ») n'ont aucun sens quand vous empaquetez des estampilles. En particulier, alors que l'option --lang
est obligatoire lors de l'empaquetage d'un ouvrage, notez qu'il n'est pas nécessaire de l'utiliser pour empaqueter une estampille.
Par défaut, les paquets d'estampilles Publican sont nommés :
publican-marque-version-parution.cible_construction.noarch.extension
.
Publican utilise les informations contenues dans le fichier publican.cfg
pour renseigner divers paramètres du nom de fichier. Reportez-vous à la Section 5.3.1, « Le fichier publican.cfg » pour plus de précisions à propos de la configuration de ce fichier. En outre :
les paquets SRPM ont l'extension de fichier .src.rpm
, alors que celle des paquets RPM binaires est .rpm
;
les paquets RPM binaires ont l'indication cible_construction.noarch
avant l'extension ; [cible_construction] désigne le système d'exploitation et la version pour laquelle le paquet a été construit telle que définie par le paramètre os_ver
dans le fichier publican.cfg
. L'élément noarch
indique que le paquet peut être installé sur n'importe quel système, quelle que soit l'architecture du système.
Une collection est un ensemble d'ouvrages, publiés sur une sortie unique. Par exemple, l'Organisation des services est un ensemble de plusieurs ouvrages comme le Guide du développeur, Guide des Services Ingénierie des contenus et le Guide d'Ingénierie des Opérations pour n'en citer que quelques uns. La commande $
create_book crée un canevas pour une collection en fixant la valeur du paramètre type
à Set
.
Il y a deux types de collections :
les ensembles autonomes,
les ensembles distribués.
Un ensemble autonome contient les fichiers XML de chaque ouvrage, chacun d'entre eux situé dans le répertoire de la collection. Les ensembles autonomes sont toujours construits en tant qu'ensemble ; vous ne pouvez pas construire isolément chaque livre de la collection sans modification.
La procédure suivante vous guide dans le processus de création d'une collection autonome nommée My Set, située dans un répertoire nommé books/My_Set/
. Cet ensemble contient Book A et Book B, chacun d'entre eux rédigé manuellement et placé dans le répertoire books/My_Set/en-US
.
Procédure 6.1. Création d'un ensemble autonome
Exécutez, dans un terminal, la commande suivante en vous plaçant dans le répertoire books/
pour créer un ensemble nommé My_Set
avec la charte graphique Red Hat et dans laquelle les XML sont écrits en anglais (américain).
publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
À l'aide de la commande $
cd, placez-vous dans le répertoire My_Set/en-US
et créez deux répertoires (et non livres) nommés Book_A
et Book_B
.
$
cdMy_Set/en-US
$
mkdirBook_A
Book_B
Placez-vous à l'aide de $
cd dans le répertoire books/My_Set/en-US/Book_A
. Créer et modifiez Book_A.xml
, Book_Info.xml
et les autres fichiers XML nécessaires à l'ouvrage tels ceux requis pour des chapitres individualisés. S'assurer que Book_A.xml
contient les références correctes xi:include
vers tous les fichiers XML du répertoire. Par exemple, si Book A contient Book_Info.xml
et Chapter_1.xml
, le fichier Book_A.xml
doit ressembler à :
<?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <book> <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> </book>
Suivez un processus identique pour Book_B, situé dans le répertoire books/My_Set/en-US/Book_B
.
Ouvrez le fichier books/My_Set/en-US/My_Set.xml
dans un traitement de texte brut. Pour chacun des ouvrages dans la collection, ajoutez une référence xi:include
au fichier XML principal de l'ouvrage. Le fichier XML principal de Book A est Book_A.xml
et celui de Book B, Book_B.xml
. Le fichier My_Set.xml
ressemble maintenant à quelque chose comme :
<?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> \t\t\t\t
Pour rendre votre ensemble XML valide, modifiez :
Dans My_Set.xml
, mettez en commentaire les lignes :
<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>
Dans Preface.xml
et Book_Info.xml
de chaque ouvrage utilisé, ajoutez ../../ en tête de chaque chaîne Common_Content que vous voyez. Par exemple :
<xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
doit devenir :
<xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Dans un ensemble autonome, le dossier « Common Content » est deux répertoires au dessous de l'emplacement dans lequel Publican le cherche généralement : il faut indiquer cette particularité manuellement. Pour construire vos ouvrages individuellement, sans construire la collection, passez cette étape.
Testez l'ensemble en exécutant la commande publican build --formats=test --langs=en-US.
Si vous utilisez des ouvrages existants, vous devez les aménager de façon à ce que les fichiers XML soient au niveau de l'ensemble et toutes les images dans le répertoire images sur un même niveau. Par exemple :
-- 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
Les fichiers XML peuvent aussi être dans des sous-répertoires pour les garder séparées. Ce qui est également vrai pour le répertoire images. Par exemple :
-- 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
Une collection distribuée est constituée d'ouvrages situés dans un dépôt à versions contrôlées. Bien qu'il existe plusieurs systèmes de contrôle des versions, Publican ne prend en charge qu'un seul système : Subversion (SVN). En définissant l'emplacement du dépôt et les titres des ouvrages à inclure dans le fichier publican.cfg
, chacun d'entre eux peut être exporté pour construire la totalité de la collection. La procédure suivante est un guide pour créer une collection nommée My Set contenant Book A et Book B.
Elle suppose que Book A et Book B existent déjà et sont disponibles dans le dépôt SVN. Actuellement, Publican ne prend en charge que SVN.
Procédure 6.2. Création d'une collection
Exécutez la commande suivante dans un terminal pour créer une collection nommée My_Set
avec la charte graphique Red Hat et dans laquelle les XML sont écrits en anglais (américain).
$ publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
Ajouter les lignes suivantes au fichier publican.cfg
:
books: Book_A Book_B repo: http://CHEMIN-VERS-LE-DÉPÔT-SVN scm: SVN
Le chemin vers le dépôt doit mener dans le répertoire contenant le livre dont vous avez besoin.
Ouvrez le fichier My_Set.xml
dans un éditeur de texte. Pour chaque ouvrage de la collection, ajoutez une référence xi:include
sur le fichier XML principal du livre. Le fichier XML principal pour Book A doit être Book_A.xml
et pour Book B, Book_B.xml
. Le fichier My_Set.xml
doit maintenant ressembler à ceci :
<?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> \t\t\t\t
Pour que le XML soit valide, mettez en commentaire dans My_Set.xml
les lignes :
<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>
Testez l'ensemble en exécutant la commande publican build --formats=test --langs=en-US.
En construisant une collection, la commande publican clean_ids doit être lancée pour chaque ouvrage étant donné qu'il est obligatoire d'avoir un identifiant unique dans l'ensemble des livres. Soyez attentif à créer des identifiants en rapport avec le contenu et qui ne soient pas disponibles pour la construction d'ouvrages indépendants de la collection.
Outre construire des documents en vue de leur publication, Publican permet aussi de créer et gérer un site Web de documentation. Pour un ensemble de documents maintenus par vos soins, vous pourrez utiliser Publican pour la construction d'un site local sur votre système ; puis, téléverser le site sur un serveur Web par la méthode de votre choix. Cette approche, toutefois, ne cadre pas bien pour les projets de documentation en équipe. Publican peut créer des paquets RPM de documentation à installer sur un serveur Web. Pour installer des paquets RPM créés avec Publican sur un serveur Web, Publican (version 2.1 ou supérieure) et rpm doivent être installés sur le serveur. Si vous construisez et maintenez le site Web sur une station de travail et le téléversez pour publication, il n'est pas nécessaire d'y installer Publican et rpm.
Les sites Web créés par Publican comprennent quatre parties : la structure du site Web, une page d'accueil, des pages de description du produit et sa version, et, les documents publiés sur le site. La structure du site Web lui-même consiste en :
un fichier de configuration,
un fichier de base de données SQLite,
un sous-répertoire pour les documents publiés ; il contient :
index.html
— un page d'index qui redirige vers la version régionalisée d'une page d'accueil du site.
interactive.css
— une feuille de style CSS contenant les formes pour le menu de navigation.
opds.xml
— un catalogue « Open Publication Distribution System (OPDS) » (Système ouvert de distribution de publications) pour permettre aux lecteurs conformes eBook de trouver facilement les documents EPUB sur le site.
Sitemap
— un « Sitemap » (carte du site) est une liste des URL du site et des métadonnées à leur propos, comme l'historique des mises à jour, la fréquence des modifications et leur importance relativement aux autres URL du site. Un Sitemap peut être fourni à la plupart des principaux moteurs de recherche, où il sera utilisé pour aider les robots d'indexation à lister les sites intelligemment. Un Sitemap ne garantit pas que votre site sera placé plus avant dans les résultats de recherche. Mais, il aide les moteurs de recherche à renvoyer des résultats plus pertinents concernant un site Web sonné en réponse aux demandes des utilisateurs. Pour plus d'informations à propos des Sitemaps, voyez sitemaps.org.
site_overrides.css
— une feuille de style CSS qui prend le pas sur les styles contenus dans interactive.css
pour fournir une touche graphique propre au site. Ce fichier n'est pas généré lors du processus de création du site, mais il doit être ajouté manuellement plus tard ou fourni par la page d'accueil du site.
default.js
— un script Java qui dirige les visiteurs vers le contenu régionalisé selon la langue définie dans le navigateur et qui contrôle la présentation du menu de navigation.
des sous-répertoires pour chaque langue dans laquelle vous publiez. Initialement, ils contiennent opds.xml
et toc.html
. Ultérieurement, ils contiennent également opds-produit.xml
:
opds.xml
— un catalogue OPDS des documents EPUB dans la langue indiquée.
opds-produit.xml
— un catalogue OPDS des documents EPUB pour chacun des produits pour lesquels vous publiez une documentation dans la langue. Dans chaque catalogue de produit, la documentation est divisée en <category>
pour les diverses versions d'un même produit.
toc.html
— la table des matières pour la langue, initialement sans lien vers un quelconque document.
Un sous-répertoire pour chaque produit pour lequel vous publiez une documentation dans la langue indiquée.
Optionally, the site structure might also include a dump file — an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The site structure might also contain a zipped version of the dump file. Refer to Section 7.1, « Construction d'un site Web à la main » and Section 7.2, « Construction d'un site Web avec des paquets RPM » for details of creating a dump file, and to Annexe D, Contenu du fichier de vidage d'un site Web for a description of the dump file contents.
Pour construire la structure du site Web :
Sur la station de travail, créez un nouveau répertoire et placez-vous y. Par exemple, sur un système Linux, exécutez :
$
mkdir ~/docsite$
cd ~/docsite
Lancez la commande publican create_site, en précisant les paramètres :
--site_config
— le nom du fichier de configuration pour le site, avec l'extension de nom de fichier .cfg
--db_file
— le nom du fichier de base de données SQLite pour le site, avec l'extension de nom de fichier .db
--toc_path
— le chemin vers le répertoire dans lequel vous placerez les documents
Sur un ordinateur avec un système d'exploitation autre que Linux, définissez également :
--tmpl_path
— le chemin vers le répertoire templates/
de l'installation de Publican. Sur les ordinateurs avec Windows, c'est généralement %SystemDrive%\%ProgramFiles%\Publican\templates
.
Par exemple :
$
publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
Vous avez intérêt à intituler les fichiers de configuration du site et de la base de données de manière à identifier immédiatement le site auquel ils se rapportent. Par exemple, pour le site de la documentation de FooMaster, vous appelleriez ces fichiers foomaster.cfg
et foomaster.db
. Vous pouvez définir --toc_path
où bon vous semble.
Modifiez le fichier de configuration du site pour indiquer le nom du site, l'hôte Web et, facultativement, les paramètres de recherche, la langue par défaut, les paramétrages du fichier de vidage et mettre à jour les réglages pour le site :
Définissez le titre avec le paramètre title
, par exemple :
title: "Documentation de Foomaster"
Normalement, les visiteurs du site Web ne voient pas ce titre étant donné que le JavaScript du site les redirige vers la page d'accueil. Toutefois, cet intitulé sera vraisemblablement retrouvé et indexé par les moteurs de recherche.
Définissez l'hôte Web à l'aide du paramètre host
sous forme d'un URL complet, avec le protocole (par exemple, http://
). Par exemple :
host: http://docs.example.com
Publican utilise la valeur définie pour host
pour construire les URL dans le fichier XML Sitemap
qu'il crée pour les moteurs d'indexation et pour limiter les recherches aux résultats de votre seul site, recherches commandées par l'intermédiaire de la boîte ad-hoc du menu de navigation .
Facultativement, construisez une requête de moteur de recherche à utiliser avec la boîte ad-hoc dans le menu de navigation et définissez le contenu complet d'une <form>
HTML avec le paramètre search
. Si vous ne définissez pas une recherche Web personnalisée, Publican crée une recherche Google limitée à l'hôte que vous avez défini au paramètre host
.
Par exemple, pour construire une recherche Yahoo! limitée à docs.example.com
, écrivez :
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>'
Reportez-vous à la documentation de votre moteur de recherche préféré pour des précisions sur la manière de construire des recherches personnalisées.
Si vous définissez value="###Search###"
dans le code pour un bouton de soumission, Publican utilise le mot Search
dans le bouton, régionalisé avec toute langue que Publican prend en charge.
Publican ne valide pas le paramètre search
, mais construit la valeur de ce paramètre dans le menu de navigation exactement comme vous l'avez défini. Soyez spécialement attentif quand vous utilisez cette fonctionnalité.
Facultativement, définissez la langue par défaut du site Web. Publican crée un menu de navigation séparé, traduisible pour chaque langue dans laquelle vous publiez la documentation. Mais, si un document n'est pas disponible dans une langue donnée, Publican renvoie les visiteurs à la version non traduite du document. Pour définir la langue par défaut non traduite du site, fixez la valeur de def_lang
avec le code de la langue. Par exemple :
def_lang: fr-FR
Si def_lang
est défini égal à fr-FR
, les visiteurs visionnant le menu de navigation en espagnol (par exemple) seront renvoyés sur la version française originale du document si celui-ci n'a pas encore été traduit en castillan.
Facultativement, configurez un fichier de vidage pour le site. Publican peut émettre en sortie un fichier XML donnant des détails complets sur le contenu du site à livrer à d'autres services, comme des sources Web ou des pages de recherche personnalisées. Le fichier est mis à jour chaque fois qu'un ouvrage est installé ou enlevé du site, ou bien que la commande $
publican update_site est lancée. Configurez les paramètres dump
, dump_file
et zip_dump
ainsi :
dump
Définissez dump: 1
pour activer la fonction fichier de vidage. Ce paramètre est fixé par défaut à 0
(off).
dump_file
Définissez dump_file: nom
pour préciser le nom du fichier de vidage et le répertoire dans lequel Publican doit le placer. Par défaut, ce paramètre est /var/www/html/DUMP.xml
.
zip_dump
Définissez zip_dump: 1
pour indiquer que Publican doit créer une version compressée du fichier XML en même temps qu'un version normale. Par défaut, ce paramètre est égal à 0
(off).
Reportez-vous à l'Annexe D, Contenu du fichier de vidage d'un site Web pour une description du contenu d'un fichier de vidage.
Facultativement, définissez le style Web avec le paramètre web_style
.
The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)
Le site Web comporte une barre de navigation de type « émietté » en haut de la documentation.
The web style set for your site must match the web style set for your content. For example, if you set web_style: 2
for your website, you need to have web_style: 2
set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg
or overrides.cfg
files of the brands that you intend to use with this site.
En option, précisez que la table des matières du site sera mise à jour manuellement avec le paramètre manual_toc_update
, par exemple :
manual_toc_update: 1
Normalement, Publican met à jour les tables des matières d'un site chaque fois qu'un paquet de documentation est ajouté ou supprimé. Sur un site avec un grand nombre de documents (plus d'une centaine), ou bien si les documents sont mis à jour très fréquemment (des dizaines de mises à jour par semaine), ce processus est très gourmand pour un serveur. Sur un site important ou occupé, nous recommandons d'activer ce paramètre et de mettre à jour périodiquement les tables des matières avec la commande $
publican update_site.
Facultativement, écrasez le JavaScript par défaut pour le site en utilisant le paramètre toc_js
, par exemple :
toc_js: "mybrand/scripts/megafoo.js"
Ce fichier fera l'objet d'un lien symbolique sur toc_path
/toc.js avec la commande $
publican update_site. Le chemin doit être relatif au paramètre toc_path
.
Créez un fichier vide nommé site_overrides.css
dans le répertoire défini par doc_path
(le répertoire contenant interactive.css
et les divers sous-répertoires des langues). Si vous souhaitez utiliser des styles propres à un site de sorte qu'ils prennent le pas sur ceux de interactive.css
, vous pouvez ajouter un fichier site_overrides.css
au document définissant la page d'accueil — voyez la Section 7.1.2, « Création, installation et mise à jour de la page d'accueil ». Si vous ne voulez pas utiliser de styles propres au site, le fichier vide ajouté ici préviendra l'apparition d'erreurs 404 sur le serveur. Sur un système Linux, placez-vous dans le répertoire précisé par doc_path
et exécutez :
$
touch site_overrides.css
Construisez et installez chaque estampille, y compris l'estampille common
de Publican.
Placez-vous dans le répertoire qui contient les sources de l'estampille.
$
cd brandsrc_dir
Construisez l'estampille :
$
publican build --formats=xml --langs=all --publish
Installez l'estampille sur votre site Web.
$
publican install_brand --web --path=path_to_site_root_dir
Effectuez ces étapes pour chacune des estampilles.
Mettez à jour le site.
$
publican update_site
Pour faire en sorte que Publican rafraîchisse la structure du site, lancez quand bon vous semble :
$
publican update_site --site_config chemin_vers_le_fichier_de_configuration_du_site.cfg
The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <article>
with an extra web_type: home
parameter in its publican.cfg
file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican. To create the home page:
Mettez vous dans un répertoire adapté et lancez la commande $
publican create :
$
publican create --type Article --name nom_page
Par exemple :
$
publican create --type Article --name Home_Page
La plupart des estampillages (y compris l'estampille common
) présentent le nom du document en grandes lettres de couleur près du haut de la page, au dessous de la bannière comportant le nom du produit (l'option --name
définit la balise <title>
). Ainsi, par défaut, la valeur que vous indiquez avec l'option --name
est présentée bien en évidence aux visiteurs du site ; dans l'exemple ci-dessus, les visiteurs sont accueillis par les mots Home Page
juste au dessous de la bannière du produit.
Placez-vous dans le répertoire de l'article :
$
cd nom_page
Par exemple :
$
cd Home_Page
Enlevez le lien avec le fichier Article_Info.xml
dans votre fichier racine XML.
Pratiquement rien du contenu du fichier Article_Info.xml
n'est susceptible d'avoir une utilité pour la page d'accueil de votre site Web. Ainsi, modifiez le fichier racine XML de votre page d'accueil pour supprimer la balise <xi:include>
liant à Article_Info.xml
. Publican utilise toujours des informations situées dans Article_Info.xml
pour l'empaquetage, mais il ne les incorpore pas dans la page elle-même.
Modifiez le fichier publican.cfg
.
Tout à fait à la fin, vous devez ajouter le paramètre web_type
et lui donner la valeur home
:
web_type: home
The web_type: home
parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg
file. Other optional changes to the publican.cfg
file that are frequently useful for Publican-generated websites include:
brand
Pour harmoniser le style de la page d'accueil avec vos documents, ajoutez :
brand: nom_estampille
docname
, product
Dans les balises <title>
ou <product>
définies dans le fichier Article_Info
ne comportant rien d'autre que des caractères latins de base sans accents, définissez les paramètres docname
et product
comme il convient.
Modifiez le contenu du fichier nom_page.xml
(par exemple, Home_Page.xml
) comme vous le feriez pour tout autre document DocBook.
Si vous supprimez la balise <xi:include>
liant à Article_Info.xml
, donnez un titre pour votre page avec le format :
<title role="producttitle">Documentation de FooMaster</title>
Si vous publiez la documentation en plus d'une langue, créez un ensemble de fichiers POT et des ensembles de fichiers PO pour chaque langue avec les commandes $
publican update_pot et publican update_po.
To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 290 px × 100 px and name it web_logo.png
. Place this image in the images/
directory in the document's XML directory, for example en-US/images/
.
Pour définir des styles propres au site prenant le pas sur les styles définis dans le fichier interactive.css
, ajoutez des styles dans un fichier nommé site_overrides.css
et placez-le dans la racine de votre source de documents (le répertoire contenant publican.cfg
et les répertoires de langues).
Construisez la page d'accueil au format HTML page unique avec l'option --embedtoc
et installez-la dans la structure du site Web. Par exemple :
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Code_langue
Notez que vous pouvez construire toutes les langues simultanément, mais vous devez installer la page d'accueil pour chaque langue à l'aide d'une commande $
publican install_book distincte.
Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook <article>
s with an extra web_type: product
or web_type: version
parameter in their publican.cfg
files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican. To create a product page or version page:
Placez-vous dans un répertoire adéquat et exécutez la commande $
publican create comme ceci :
$
publican create --type Article --name nom_page
Par exemple, une page de produit peut être :
$
publican create --type Article --name FooMaster
et une page version :
$
publican create --type Article --name FooMaster_3
Placez-vous dans le répertoire de l'article :
$
cd nom_page
Par exemple :
$
cd FooMaster
Enlevez le lien avec le fichier Article_Info.xml
dans votre fichier racine XML.
Pratiquement rien du contenu du fichier Article_Info.xml
n'est susceptible d'avoir une utilité pour les pages produit ou version. Ainsi, modifiez le fichier racine XML de votre page d'accueil pour supprimer la balise <xi:include>
liant à Article_Info.xml
. Publican utilise toujours des informations situées dans Article_Info.xml
pour l'empaquetage, mais il ne les incorpore pas dans la page elle-même.
Modifiez le fichier publican.cfg
.
Tout à fait à la fin, vous devez ajouter le paramètre web_type
et lui donner la valeur product
ou version
:
web_type: product
ou
web_type: version
Le paramètre web_type: home
indique à Publican de traiter le document différemment d'une documentation de produit. C'est le seul changement obligatoire dans le fichier publican.cfg
. Voici d'autres modifications facultatives pour publican.cfg
, souvent utiles pour les pages du produit ou les pages des versions :
brand
Pour harmoniser le style de la page d'accueil avec vos documents, ajoutez :
brand: nom_estampille
docname
, product
Dans les balises <title>
ou <product>
définies dans le fichier Article_Info
ne comportant rien d'autre que des caractères latins de base sans accents, définissez les paramètres docname
et product
comme il convient.
Modifiez le contenu du fichier nom_page.xml
(par exemple, Foomaster.xml
) comme vous le feriez pour tout autre document DocBook.
Si vous supprimez la balise <xi:include>
liant à Article_Info.xml
, donnez un titre à votre page avec le format :
<title role="producttitle">Documentation de FooMaster</title>
Si vous publiez la documentation en plus d'une langue, créez un ensemble de fichiers POT et des ensembles de fichiers PO pour chaque langue avec les commandes $
publican update_pot et publican update_po.
Construisez la page du produit ou la page de version au format HTML page unique avec l'option --embedtoc
et installez-la dans la structure du site Web. Par exemple :
$
publican build --publish --formats html-single --embedtoc --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Code_langue
Notez que vous pouvez construire toutes les langues simultanément, mais vous devez installer la page du produit ou la page de version pour chaque langue à l'aide d'une commande $
publican install_book distincte.
Pour installer un document sur un site Web construit à la main, placez-vous dans le répertoire contenant la source du document et exécutez :
$
publican build --embedtoc --formats=liste_de_formats --langs=codes_langues --publish$
publican install_book --site_config chemin_vers_fichier_configuration_site.cfg --lang code_langue
Notez que vous pouvez exécuter une seule commande $
publican build pour l'ensemble des langues que vous souhaitez publier, mais vous devez lancer une commande publican install_book séparée pour chaque langue. Vous devez inclure html
dans les formats de la commande publican build ; facultativement, ajoutez un ou plusieurs autres formats dans un liste avec la virgule comme sépatateur : html-single
, pdf
et epub
.
Pour mettre à jour un document, placez-vous dans le répertoire contenant le document source mis à jour et lancez les mêmes commande que lors de la première installation. Publican remplace l'ancienne version par la nouvelle.
Pour supprimer un document, placez-vous dans le répertoire contenant le document source et exécutez :
$
publican remove_book --site_config chemin_vers_fichier_de_configuration_du_site.cfg --lang code_langue
Une fois les documents installés, le site Web est prêt à être téléversé sur le serveur à l'aide du processus que vous utilisez habituellement, par exemple scp, rsync ou un client FTP.
Quand vous créez une structure de site Web, Publican place des fichiers dans le répertoire /var/www/html/docs
. Les fichiers existants dans ce répertoire peuvent être écrasés par cette procédure.
Parcourez les étapes suivantes sur le serveur Web.
Connectez-vous au serveur Web.
Installez Publican. Par exemple, sur un serveur avec Fedora comme système d'exploitation, exécutez :
$
sudo yum install publican publican-common-web
Avec les privilèges d'administrateur, modifiez le fichier /etc/publican-website.cfg
pour définir le nom du site, l'hôte Web et, facultativement, les paramètres de recherche, la langue par défaut, les réglages du fichier de vidage pour le site et le style du site :
Définissez l'intitulé avec le paramètre title
, par exemple :
title: "Documentation de Foomaster"
Normalement, les visiteurs du site Web ne voient pas ce titre parce que le JavaScript du site les redirige vers la page d'accueil. Toutefois, cet intitulé sera vraisemblablement retrouvé et indexé par les moteurs de recherche.
Définissez l'hôte Web à l'aide du paramètre host
sous forme d'un URL complet, en précisant le protocole (par exemple, http://
). Par exemple :
host: http://docs.example.com
Publican utilise la valeur définie pour host
pour construire les URL dans le fichier XML Sitemap
qu'il crée pour les moteurs d'indexation et pour limiter aux résultats de votre seul site les recherches opérées par l'intermédiaire de la boîte ad-hoc dans le menu de navigation.
Facultativement, construisez une requête de moteur de recherche à utiliser avec la boîte ad-hoc dans le menu de navigation et définissez-en le contenu complet d'une <form>
HTML avec le paramètre search
. Si vous ne définissez pas une recherche Web personnalisée, Publican crée une recherche Google limitée à l'hôte que vous avez défini au paramètre host
.
Par exemple, pour construire une recherche Yahoo! limitée à docs.example.com
, écrivez :
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>'
Reportez-vous à la documentation de votre moteur de recherche préféré pour des précisions sur la manière de construire des recherches personnalisées.
Si vous définissez value="###Search###"
dans le code pour un bouton de soumission, Publican utilise le mot Search
dans le bouton, traduit dans toute langue que Publican prend en charge.
Publican ne valide pas le paramètre search
, mais construit la valeur de ce paramètre dans le menu de navigation exactement comme vous l'avez défini. Soyez spécialement attentif quand vous utilisez cette fonctionnalité.
Facultativement, définir la langue par défaut du site Web. Publican crée un menu de navigation séparé, traduisible pour chaque langue dans laquelle vous publiez la documentation. Mais, si un document n'est pas disponible dans une langue donnée, Publican liera les visiteurs à la version non traduite du document. Pour définir la langue par défaut non traduite du site, fixez la valeur de def_lang
avec le code de la langue. Par exemple :
def_lang: fr-FR
Si def_lang
est défini égal à fr-FR
, les visiteurs visionnant le menu de navigation en espagnol (par exemple) seront reliés à la version française originale du document si celui-ci n'a pas encore été traduit en castillan.
Facultativement, configurez un fichier de vidage pour le site. Publican peut émettre en sortie un fichier XML donnant des détails complets sur le contenu du site à livrer à d'autres services, comme des sources Web ou des pages de recherche personnalisées. Le fichier est mis à jour chaque fois qu'un ouvrage est installé ou enlevé du site, ou bien que la commande $
publican update_site est lancée. Configurez les paramètres dump
, dump_file
et zip_dump
ainsi :
dump
Définissez dump: 1
pour activer la fonction fichier de vidage. Ce paramètre est fixé par défaut à 0
(off).
dump_file
Définissez dump_file: nom
pour préciser le nom du fichier de vidage et le répertoire dans lequel Publican doit le placer. Par défaut, ce paramètre est /var/www/html/DUMP.xml
.
zip_dump
Définissez zip_dump: 1
pour indiquer que Publican doit créer une version compressée du fichier XML en même temps qu'une version normale. Par défaut, ce paramètre est égal à 0
(off).
Voyez l'Annexe D, Contenu du fichier de vidage d'un site Web pour la description du contenu d'un fichier de vidage.
Facultativement, définissez le style Web avec le paramètre web_style
.
The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)
Le site Web comporte une barre de navigation de type « émietté » en haut de la documentation.
The web style set for your site must match the web style set for your content. For example, if you set web_style: 2
for your website, you need to have web_style: 2
set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg
or overrides.cfg
files of the brands that you intend to use with this site.
En option, précisez que la table des matières du site sera mise à jour manuellement avec le paramètre manual_toc_update
, par exemple :
manual_toc_update: 1
Normalement, Publican met à jour les tables des matières d'un site chaque fois qu'un paquet de documentation est ajouté ou supprimé. Sur un site avec un grand nombre de documents (plus d'une centaine), ou bien si les documents sont mis à jour très fréquemment (des dizaines de mises à jour par semaine), ce processus est très gourmand pour un serveur. Sur un site important ou occupé, nous recommandons d'activer ce paramètre et de mettre à jour périodiquement les tables des matières avec la commande $
publican update_site.
Facultativement, écrasez le JavaScript par défaut pour le site en utilisant le paramètre toc_js
, par exemple :
toc_js: "mybrand/scripts/megafoo.js"
Ce fichier fera l'objet d'un lien symbolique sur toc_path
/toc.js avec la commande $
publican update_site. Le chemin doit être relatif au paramètre toc_path
.
Créez un fichier vide nommé site_overrides.css
. Si vous souhaitez utiliser des styles propres à un site en sorte qu'ils prennent le pas sur ceux de interactive.css
, vous pouvez ajouter un fichier site_overrides.css
au document définissant la page d'accueil — voyez la Section 7.1.2, « Création, installation et mise à jour de la page d'accueil ». Si vous ne voulez pas utiliser de style propre au site, le fichier vide ajouté ici prévient l'apparition d'erreurs 404 sur le serveur. Sur un système Linux, exécutez :
#
touch /var/www/html/docs/site_overrides.css
Pour faire en sorte que Publican rafraîchisse la structure du site, lancez quand bon vous semble :
$
publican update_site
The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <article>
with an extra web_type: home
parameter in its publican.cfg
file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican and is packaged the same way.
Sur une station de travail, créer une page d'accueil en suivant la procédure décrite dans Section 7.1.2, « Création, installation et mise à jour de la page d'accueil ».
Dans le répertoire dans lequel vous avez créé la page d'accueil, exécuter :
$
publican package --binary
Publican construit un paquet RPM et le place dans le répertoire /tmp/rpms/noarch/
de la page d'accueil. Par défaut, Publican crée un paquet RPM à installer sur un système d'exploitation identique à celui sur lequel vous avez exécuté Publican. Pour construire un paquet RPM à installer sur un serveur avec un système d'exploitation autre, définir le paramètre os_ver
dans le fichier publican.cfg
de la page d'accueil.
Soit téléverser le paquet de la page d'accueil sur le serveur Web et l'installer avec la commande rpm -i ou yum localinstall, soit placer le paquet dans un dépôt et configurer le serveur Web pour l'installer à partir de ce dépôt en lançant la commande yum install.
Pour mettre à jour la page d'accueil, construire un paquet avec un numéro <edition>
ou <pubsnumber>
plus grand dans Article_Info.xml
. Publican utilise ces valeurs pour définir les numéros de version ou de parution du paquet RPM. Quand vous installez ce paquet sur le serveur Web, yum peut remplacer l'ancienne version par la nouvelle quand vous lancez yum localinstall pour un paquet local, ou bien yum update pour un paquet extrait d'un dépôt.
Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook <article>
s with an extra web_type: product
or web_type: version
parameter in their publican.cfg
files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican and are packaged the same way.
Sur une station de travail, créez une page produit ou version en suivant la procédure décrite à la Section 7.1.3, « Création, installation et mise à jour des pages du produit et des pages des versions ».
Dans le répertoire dans lequel vous avez créé la page du produit ou la page de la version, exécutez :
$
publican package --binary
Publican construit un paquet RPM et le place dans le répertoire /tmp/rpms/noarch/
de la page du produit ou de la page de la version. Par défaut, Publican crée un paquet RPM à installer sur un serveur s'exécutant sous le même système d'exploitation que celui sous lequel tourne Publican. Pour construire un paquet RPM à installer sur un serveur avec un système d'exploitation autre, définir le paramètre os_ver
dans le fichier publican.cfg
de la page du produit ou de la page de la version.
Soit téléverser le paquet sur le serveur Web et l'installer avec la commande rpm -i ou yum localinstall, soit placer le paquet dans un dépôt et configurer le serveur Web pour l'installer à partir de ce dépôt en lançant la commande yum install.
Pour mettre à jour la page du produit ou la page de la version, construire un paquet avec un numéro <edition>
ou <pubsnumber>
plus grand dans Article_Info.xml
. Publican utilise ces valeurs pour définir les numéros de version ou de parution du paquet RPM. Quand vous installez ce paquet sur le serveur Web, yum peut remplacer l'ancienne version par la nouvelle quand vous lancez yum localinstall pour un paquet local, ou bien yum update pour un paquet extrait d'un dépôt.
Sur une station de travail, placez-vous dans le répertoire contenant la source du document et exécutez :
$
publican package --binary --lang code_langue
Publican construit un paquet RPM et le place dans le répertoire /tmp/rpms/noarch/
du document. Par défaut, Publican crée un paquet RPM pour le système d'exploitation sous lequel Publican s'exécute. Pour construire un paquet RPM à installer sur un serveur avec un système d'exploitation autre, définir le paramètre os_ver
dans le fichier publican.cfg
du document.
Soit téléversez les paquets documents sur le serveur Web et installez les avec la commande rpm -i ou yum localinstall, soit placez les paquets dans un dépôt et configurez le serveur Web pour les installer à partir de ce dépôt en lançant la commande yum install.
Pour mettre à jour un document, construisez un nouveau paquet avec un numéro <edition>
ou <pubsnumber>
plus grand dans Book_Info.xml
ou Article_Info.xml
. Publican utilise ces valeurs pour définir les numéros de version ou de parution du paquet RPM. Quand vous installez ce paquet sur le serveur Web, yum peut remplacer l'ancienne version par la nouvelle quand vous lancez yum localinstall pour un paquet local, ou bien yum update pour un paquet extrait d'un dépôt.
Supprimez un document du serveur Web avec la commande rpm -e ou yum erase.
Sur des sites importants ou occupés, nous vous recommandons de définir le paramètre manual_toc_update
dans le fichier de configuration du site. Une fois ce paramètre défini, vous lancez la commande $
publican update_site après avoir installé, mis à jour ou supprimé des documents. Reportez-vous à la Section 7.1.1, « Création d'une structure de site Web » pour plus d'informations.
Un site Web Publican comprend un fichier XML Sitemap. Ce fichier peut être soumis à plusieurs des principaux moteurs de recherche, afin de les aider à indexer votre site Web plus intelligemment et plus minutieusement. Chaque moteur de recherche à ses propres procédures de soumission. Ce paragraphe comporte la description de la manière de soumettre un fichier Sitemap à Google et Bing.
Procédure 7.1. Pour soumettre le fichier Sitemap à Google :
Inscrivez-vous pour obtenir un compte Google à l'adresse Google Webmaster Tools. Si vous en possédez déjà un, vous pouvez l'utiliser.
Ouvrez une session dans le compte « Google Webmaster Tools » (Outils Google pour webmestres) à l'URL : http://www.google.com/webmasters/tools/home.
Tout d'abord, il faut certifier que vous êtes bien le propriétaire du site Publican. Cliquez sur le bouton
.Une boîte de dialogue s'affiche ; elle vous permet d'Ajouter un site. Entrez l'URL de votre site Publican dans le champ de saisie texte et cliquez sur .
Suivez les instructions affichées et téléversez, à la racine des documents de votre site Web, le fichier HTML fourni par Google.
Quand il est confirmé que le fichier HTML fourni a bien été téléversé à l'emplacement requis en y ayant accès par l'intermédiaire d'un navigateur, cliquez sur le bouton
.Quand vous avez certifié avec succès la propriété du site Web Publican pour le compte de Google, revenez à la page d'accueil de « Webmaster Tools ». Votre site Publican est listé. Cliquez dessus.
Vous êtes amené à la page de configuration des « Webmaster Tools » pour votre site Publican. Sur le côté gauche de la page, se trouve un menu. Cliquez sur l'entrée Configuration du site pour la développer. Le contenu développé contient une entrée Sitemaps. Cliquez dessus.
Vous êtes amené à la page de soumission du fichier Sitemap. Cliquez sur le bouton
.Un champ d'entrée texte affiche le début de l'URL de votre site Publican, avec de la place pour préciser l'URL de votre fichier XML SiteMap. Entrez cet emplacement et cliquez sur le bouton
. Les détails du Sitemap sont affichés dans un tableau.Résultat : Le fichier Sitemap de votre site Publican a été soumis à Google avec succès.
Procédure 7.2. Pour soumettre un fichier Sitemap à Bing :
Inscrivez-vous pour obtenir un compte « Bing Webmaster Tools » à l'adresse Bing Webmaster Tools. Si vous en possédez déjà un, vous pouvez l'utiliser.
Ouvrez une session dans le compte « Bing Webmaster Tools » (Outils Google pour webmestres) à l'URL : http://www.bing.com/toolbox/webmaster/.
Cliquez sur le bouton
.La boîte de dialogue Ajouter un site est affichée. Entrez l'URL de votre site Publican dans le champ d'entrée texte et cliquez sur le bouton .
La boîte de dialogue Certifier la propriété s'affiche, avec trois options. Suivez les instruction données après développement de Option 1 : Verser un fichier XML sur votre serveur Web. Téléversez le fichier BingSiteAuth.xml
que Bing fournit à la racine de votre site Web.
Quand vous avez confirmé que le fichier BingSiteAuth.xml
fourni a bien été téléversé à l'emplacement requis en l'ouvrant dans un navigateur Web, cliquez sur le bouton .
Quand vous avez certifié avec succès la propriété de votre site Web Publican pour le compte de Bing, revenez à la page d'accueil des outils pour webmestre de Bing. Votre site Publican y est listé. Cliquez dessus.
Sélectionnez l'onglet
.Sélectionnez Sitemaps, puis Ajouter une source.
La boîte de dialogue Ajouter une source s'affiche. Entrez l'URL de votre fichier Sitemap et cliquez sur . Les détails du fichier Sitemap sont affichés.
Résultat : Le fichier Sitemap de votre site Publican a été soumis à Bing avec succès.
Publican 3.1 possède une nouvelle fonctionnalité qui permet à l'utilisateur de créer et d'importer un ouvrage dans Drupal. Tous les fichiers XML de l'ouvrage sont transformés en un fichier CSV unique utilisé plus tard pour l'importation dans Drupal.
Le fichier CSV indique à Drupal la manière d'importer l'ouvrage. Chaque ligne du fichier CSV représente une page html.
Utilisez la commande $
publican build pour créer le fichier CSV d'importation dans Drupal. Avant de lancer la commande, utilisez « cd » pour vous déplacer dans le répertoire où votre ouvrage est situé. Par exemple, si vous avez un ouvrage nommé « Guide utilisateur » dans votre répertoire personnel, exécutez la commande :
$
cd Guide_utilisateur/$
publican build --langs en-US --formats=drupal-book
Une fois la commande exécutée, vous constatez qu'un fichier CVS a été créé dans le répertoire tmp/en-US/drupal-book/
.
Publican stocke tous les fichiers de sortie dans le répertoire /tmp/en-US/drupal-book/
. Il contient les éléments suivants :
un fichier CVS — la convention de nommage de ce fichier est $product-$version-$docname-$lang-$edition.csv
un répertoire en-US — il contient toutes les images html.
un fichier tar.gz — l'archive à la fois du fichier CSV et du répertoire en-US.
Après avoir exécuté la commande $
publican build --langs en-US --formats=drupal-book, vous remarquerez que les fichiers xml dans le répertoire en-US
ont été modifiés. En effet, Publican a ajouté un attribut de « conformité »
pour chaque balise qu'il a identifiée. Cet attribut contient un nombre unique dans l'ensemble des fichiers xml de l'ouvrage. Si vous utilisez un système de contrôle de version comme git pour les fichiers xml, vous devrez enregistrer les changements de façon à ce que ce nombre ne soit pas réinitialisé quand d'autres utilisateurs exécutent « git ». Ces nombres uniques sont importants : ils sont utilisés dans le chemin de l'URL dans Drupal. Conjointement, Publican a créé un fichier base de données max_unique_id.db
dans le répertoire en-US
. Cette base de données s'utilise pour suivre le plus grand nombre unique dans les documents ; ainsi, Publican sait où vous en êtes pour ajouter un nouveau nombre unique pour les chapitres ou les sections nouvellement créés. Donc, il est important d'ajouter le fichier base de données pour le contrôle de version et de l'enregistrer s'il y a eu un quelconque changement. Si vous ajoutez une nouvelle section dans le xml, ne définissez pas l'attribut du paramètre de « conformité »
vous-même car cela rendrait la base de données caduque. Laissez publican le faire pour vous.
Voici quelques paramètres à configurer dans le fichier publican.cfg en vue d'une importation par Drupal :
drupal_author
définit le nom d'auteur qui sera affiché dans les pages de l'ouvrage Drupal. Le nom doit être un nom d'utilisateur Drupal valide. « Redhat » est l'auteur par défaut. Pour le surcharger, définissez une autre valeur pour ce paramètre dans le fichier publican.cfg
.
L'auteur doit être autorisé à gérer (créer, mettre à jour, supprimer) des nœuds dans Drupal. Si vous utilisez l'auteur par défaut, assurez-vous d'avoir créé un compte avec le nom d'utilisateur « Redhat » dans Drupal.
drupal_menu_title
renomme l'ouvrage tel qu'il sera affiché dans le menu Drupal. Si rien n'est défini, publican utilisera la valeur par défaut qui est « $product $version $docname ». Par exemple, Publican 3.1 Guide_utilisateur.
drupal_menu_block
définit le bloc de menu que l'ouvrage doit afficher dans Drupal. La valeur par défaut est le paramètre « user-guide »
.
Le bloc de menu doit exister dans Drupal. Pour plus d'informations à propos de l'ajout d'un bloc de menu dans Drupal, voyez la Section 8.3.1, « Comment ajouter un bloc menu ? ».
drupal_image_path
définit le répertoire dans lequel des images doivent être enregistrées dans le serveur Drupal. La valeur par défaut est « sites/default/files/ »
.
Avant de pouvoir importer un ouvrage, vous devez installer un module nommé « Node Import » dans Drupal. Ce module permet à Drupal d'importer et mettre à jour des contenus à partir de fichiers CVS ou TVS. Pour installer ce module, allez simplement sur le site Drupal et suivez les instructions du site pour le télécharger. Ceci fait, vous devez copier le module téléchargé dans le répertoire « modules » sur le serveur Drupal. Par exemple, si Drupal est situé dans le répertoire /var/www/html/drupal/
, vous devez copier le module dans le répertoire /var/www/html/drupal/sites/all/modules/
. Pour activer le module installé, connectez-vous sur le site Drupal et allez dans Administrer -> Construction d'un site -> Modules. Dans la section Développement, cochez la , puis cliquez sur le bouton pour activer le module Node Import.
Vous devez également activer les modules du cœur de Drupal suivants :
Book
Menu
Path
Veuillez consulter votre administrateur réseau si vous n'avez pas l'autorisation d'installer un module dans Drupal.
Répertoire d'importation — endroit où les fichiers CVS à importer sont stockés. Le chemin par défaut est sites/default/files/imports/
.
Réglages FTP
Autoriser de téléverser avec FTP — assurez-vous que la case est cochée, de sorte que le nouveau fichier CSV puisse être détecté automatiquement quand il est téléversé dans le répertoire d'importation
.
Propriété du fichier — cet utilisateur se verra affecter la propriété du fichier CVS que vous téléversez dans le répertoire d'importation
.
Les utilisateurs n'ont l'autorisation d'utiliser que les fichiers téléversés par leurs soins et ceux attribués anonymement. Si vous laissez ce champ en blanc, tous les fichiers téléversés par FTP appartiennent à un anonyme ; ces fichiers sont donc disponibles à tous. Si vous entrez un nom d'utilisateur, les fichiers téléversés avec FTP sont la propriété de celui-ci et il sera le seul susceptible de les voir. Il est recommandé de laisser ce champ en blanc.
Extensions autorisées — l'extension autorisée pour les fichiers à importer. Les autres extensions seront ignorées par le module.
Réglages par défaut
Type de contenu — le type de contenu par défaut utilisé pour une importation rapide. Assurez-vous que le type de contenu Page de livre
est coché.
Première ligne contenant les noms de colonnes — ceci indique au module d'importation des nœuds que la première ligne du fichier CSV est constitué par les en-têtes.
Procédure 8.1. Pour importer un ouvrage dans Drupal :
Parcourir les étapes précisées dans la Section 8.1, « Comment construire un fichier CSV pour importation dans Drupal ? ».
Téléverser le fichier CSV dans le répertoire d'importation
du serveur Drupal,
Téléverser le répertoire en-US
dans le répertoire « sites/default/files/ »
du serveur Drupal. Cette valeur peut être écrasée avec celle indiquée dans publican.cfg
. Pour plus de détails, veuillez lire la Section 8.2, « Le fichier publican.cfg ».
Se connecter au site Web Drupal et allez à Administrer -> Gestion du contenu -> Importer un contenu. Vous constaterez que le fichiers CSV que vous venez de téléverser est indiqué dans le tableau des « tâches en attente » et est prêt à être importé.
Cliquer sur
pour commencer l'importation de l'ouvrage. Vous serez redirigé sur la page suivante qui montre la progression de l'importation. Quand la barre de progression a atteint 100 %, cela signifie que l'importation est effectuée !Un lien vers l'ouvrage est maintenant affiché dans le bloc de menu défini.
Refaites simplement les étapes de la Section 8.3.3, « Comment importer un ouvrage ? » pour mettre à jour l'ouvrage.
Si vous mettez à jour un ouvrage avec moins de sections, les sections manquantes seront détruites par Drupal et les URL vers les sections détruites seront également supprimés.
Comment ajouter une langue à mon ouvrage ?
Exécutez $
publican update_po --langs=langue, où langue est le code de la nouvelle langue à ajouter. Vous pouvez ajouter plus d'une langue simultanément, en séparant par une virgule les divers codes de langue entre eux. Par exemple, publican update_po --langs=ja-JP crée le répertoire pour la langue japonaise et les fichiers PO pour le japonais et publican update_po --langs=ja-JP,ko-KR crée les répertoires et les fichiers PO à la fois pour le japonais et le coréen.
Que se passe-t-il si je ne souhaite pas utiliser le code pays ? Par exemple, puis-je exécuter $
publican update_po --langs=es,de,fr ?
Oui — cette commande fonctionne. Mais, si vous omettez le code pays, la sortie pourrait être imprévisible quand Publican ou une estampille a des définitions couvrant plus d'une variété régionale de langue — par exemple, zh-CN
(chinois simplifié utilisé en République Populaire de Chine) et zh-TW
(chinois traditionnel utilisé en République de Chine à Formose). Même quand un seul type est actuellement défini, il est toujours plus sûr d'inclure le code du pays en prévision, par exemple, qu'une future mise à jour de Publican ne fasse pas en sorte que des documents en allemand (de-DE
) basculent en dialecte alémanique (Suisse allemand, de-CH
) dans les en-têtes et le « Common Content ».
Comment mettre à jour tous les fichiers po ?
Exécutez la commande $
publican update_po --langs=all.
Où puis-je obtenir une liste complète des options de construction de Publican ?
Exécutez la commande $
publican build --help.
Où puis-je obtenir une liste complète des paramètres pouvant être définis dans publican.cfg
?
Exécutez la commande $
publican help_config dans un répertoire contenant n'importe quel document Publican.
Où sont situés les fichiers courants de Publican ?
Par défaut, il sont dans /usr/share/publican/
pour les systèmes d'exploitation Linux et dans %SystemDrive%/%ProgramFiles%/publican/Common_Content
pour Windows — généralement, C:/Program Files/publican/Common_Content
.
Est-il possible d'incorporer des fichiers quelconques dans les archives tar et les paquets RPM ?
Oui. Si vous créez un répertoire nommé files
dans le répertoire de la langue source, il sera incorporé avec son contenu dans n'importe quelle archive tar ou paquet SRPM que Publican crée.
Le répertoire files
n'est pas compris dans le processus de validation ; vous ne pouvez donc pas incorporer un quelconque fichier de ce répertoire dans le XML avec xi:include
.
Pourquoi Publican donne-t-il des avertissements à propos de balises inconnues ?
Ces avertissements vous informent que vous utilisez des balises dont les sorties n'ont pas été agréées comme étant en stricte conformité avec XHTML 1.0 ou avec la section 508 (accessibilité).
Je peux construire sans problème des documents HTML, mais quand j'essaie de construire des PDF, j'obtiens des erreurs comme java.lang.NullPointerException
et aucun PDF n'est produit. Qu'est-ce qui n'est pas correct ?
Essayez de construire une version PDF d'un autre document — un nouveau créé avec la commande $
publican create. Si le problème n'est pas déclenché uniquement avec un document donné, vous avez probablement un défaut de concordance entre le Java Runtime Environment (JRE) (Machine virtuelle Java) et le Java Development Kit (JDK)(Kit de développement Java) en service sur le système. Si vous avez un JDK installé, FOP requiert que le JDK soit de la même version que le JRE. Plus, FOP ne peut pas utiliser le GNU Compiler for Java (GCJ) (Compilateur GNU pour Java).
Exécutez alternatives --config java et alternatives --config javac pour déterminer quels sont les JRE et JDK en cours d'utilisation, puis choisissez des versions en accord n'ayant pas gcj
dans le nom. Par exemple, la configuration Java suivante montre un JRE et un JDK accordés permettant la construction des PDF :
$
alternatives --config java
There are 3 programs which provide 'java'.
Selection Command
-----------------------------------------------
1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java
* 2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
+ 3 /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java
Enter to keep the current selection[+], or type selection number:
$
alternatives --config javac
There are 3 programs which provide 'javac'.
Selection Command
-----------------------------------------------
*+ 1 /usr/lib/jvm/java-1.6.0-openjdk.x86_64/bin/javac
2 /usr/lib/jvm/java-1.6.0-openjdk/bin/javac
3 /usr/lib/jvm/java-1.5.0-gcj/bin/javac
Enter to keep the current selection[+], or type selection number:
Vous devrez installer un autre JDK si celui sur le système ne correspond à aucun JRE.
Certaines installations de Java ne paramètrent pas un environnement correct pour alternatives. Aucun correctif n'a été trouvé à cette situation.
J'ai obtenu une erreur disant que Batik n'est pas dans le « classpath » (variable d'environnement indiquant à la machine virtuelle Java où trouver les bibliothèques de classe) alors que Batik est bien installé ! Qu'est-ce qui n'est pas correct ?
Les problèmes de « classpath » sont dus, selon nous, au fait d'avoir des versions différentes du JRE et JDK en cours d'utilisation. Reportez-vous à la question précédente à propos des erreurs java.lang.NullPointerException
et utilisez la commande alternatives pour vous assurer que le JRE et le JDK sont en accord.
J'ai obtenu une erreur Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
en essayant de construire un PDF. Qu'est-ce qui n'est pas correct ?
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to FOP. Before running $
publican build run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
Les précédentes version de Publican supprimaient les balises <para>
vides. Publican fait-il toujours cela ?
Non. Auparavant Publican supprimait les balises <para>
vides pendant la transformation du XML étant donné que ces balises vides <para>
cassaient les premières chaînes d'outils de traduction utilisées dans les projets Red Hat et Fedora. Les balises <para>
vides sont des expressions XML DocBook valides et Publican ne les supprime plus.
Qu'est-il arrivé au vérificateur d'orthographe ?
Les premières versions de Publican (jusqu'à la version 0.45 incluse) activaient un vérificateur d'orthographe lors de la transformation du XML du document. En raison des retours négatifs de la part des utilisateurs, cette fonctionnalité a été abandonnée.
Lancez le script bash ci-après dans le répertoire racine du document pour vérifier l'orthographe des fichiers XML avec le vérificateur en ligne de commande aspell.
#!/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
Pourquoi la balise <segmentedlist>
ne fonctionne pas lors de la construction des PDF ?
Vérifiez le nombre de colonnes dans vos <segmentedlist>
. Quand des <segmentedlist>
sont formatés en tant que tableaux, le XSL de DocBook limite le nombre de colonnes à deux, et, Publican formate les <segmentedlist>
en tant que tableaux.
Qu'est-il arrivé aux couleurs des images dans ce PDF ?
Cela provient d'une anomalie de FOP qui distord les couleurs dans les images PNG sur 24 bits. Convertissez les images en PNG sur 32 bits pour contourner ce problème.
Quand je construis le document, j'obtiens une erreur ‘langage non défini’ — qu'est-ce qui n'est pas correct ?
La coloration syntaxique du code dans Publican est créée à l'aide du module Perl Syntax::Highlight::Engine::Kate. Si vous précisez un langage non reconnu par Syntax::Highlight::Engine::Kate dans une balise <programlisting>
, vous obtenez une erreur à la construction de l'ouvrage. Les premières lignes du message d'erreur ressemblent à :
undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm
line 615.
cannot create plugin for language 'JAVA'
Notez que Syntax::Highlight::Engine::Kate est très strict à propos des noms de langages et est sensible à la casse. Ainsi, <programlisting language="Java">
fonctionne, mais <programlisting language="java">
et <programlisting language="JAVA">
ne fonctionnent pas. Le message d'erreur reçu identifie le nom du langage posant problème.
Refer to http://search.cpan.org/dist/Syntax-Highlight-Engine-Kate/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS for the full list of languages that Syntax::Highlight::Engine::Kate supports, including their expected capitalization and punctuation.
Comment puis-je activer l'auto-complétion automatique bash sur la ligne de commande pour Publican ?
Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:
Installez le ou les paquets fournissant cette fonctionnalité pour votre système d'exploitation. Par exemple, pour Fedora, exécutez sudo yum install bash-completion.
Ajoutez au fichier ~/.bashrc
:
# Utiliser l'auto-complémentation bash, si disponible if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
Redémarrez le terminal ou bien exécutez source ~/.bashrc.
Pourquoi ai-je des difficultés quand je construis de gros ouvrages ?
Probablement parce que vous avez dépassé la limite du nombre de fichiers ouverts que le noyau soit capable de gérer simultanément. Avec certains Linux vous pouvez lancer la commande ulimit -n 8192 pour modifier cette limite dans l'interpréteur en cours d'activité.
Pour rendre cette modification permanente, ouvrez /etc/security/limits.conf
et ajoutez-y ces deux lignes :
* soft nofile 8192 * hard nofile 8192
Puis enregistrez la modification et reconnectez-vous pour qu'elle prenne effet.
Pourquoi Jeff appelle-t-il Isaac ‘Ivan’ ?
Parce que Jeff a la mémoire qui flanche !
Tout élément (balise) ou attribut régulier n'est pas automatiquement pris en charge dans le fonctionnement de Publican. En particulier, toutes les balises n'ont pas été testées quant à leurs effets sur la présentation d'un document une fois celui-ci construit en HTML ou PDF.
Publican fonctionne avec pratiquement tous les éléments DocBook 4.5 et leurs attributs, et la plupart de ces éléments sont pris en charge. Les éléments et attributs pris en charge sont ceux dont le rendu dans les sorties HTML ou PDF de Publican a été testé et est d'une qualité acceptable.
D'autres éléments ou attributs non connus pour être mauvais ou redondants, mais qui n'ont pas été testés au plan de la qualité sont réputés non pris en charge. Si un matériau dans une balise DocBook donnée ne paraît pas correct quand vous construisez un document en HTML ou PDF, le problème peut résulter du fait que la logique de transformation de cette balise n'a pas encore été testée. Construisez le document à nouveau et examinez les sorties de Publican au cours de la construction. Publican affiche des avertissements concernant les balises non prises en charge rencontrées dans les fichiers XML.
Enfin, un petit groupe d'éléments et d'attributs sont rejetés. Ces éléments et attributs sont précisés plus bas, chacun étant accompagné d'une explication rationnelle des raisons de son rejet.
Utilisez la commande $
publican print_known pour afficher une liste des balises que Publican prend en charge et la commande $
publican print_banned pour afficher les balises rejetées.
<glossdiv>
Ce groupe de balises présente des termes dans l'ordre alphabétique sous forme de glossaire ; toutefois, les termes sont triés selon la langue d'origine du XML, sans prendre en considération la façon dont les termes sont traduits dans une autre langue. Par exemple, un glossaire construit avec <glossdiv>
qui ressemblerait à ce qui suit en anglais :
Apple
— an apple is…
Grapes
— grapes are…
Orange
— an orange is…
Peach
— a peach is…
se présente ainsi en espagnol :
Manzana
— la manzana es…
Uva
— la uva es…
Naranja
— la naranja es…
Melocotón
— el melocotón es…
Traduit dans une langue qui ne partage pas le même système d'écriture que la langue d'origine du XML, le résultat est encore plus dépourvu de signification.
<inlinegraphic>
Cet élément présente l'information sous forme d'un graphique au lieu d'un texte et ne fournit pas d'option pour offrir une alternative textuelle au graphique. Cette balise cache donc une information aux personnes avec des déficiences visuelles. Dans les sites officiels, qui ont obligation légale de présenter des contenus accessibles aux mal-voyants, des documents qui utiliseraient cette balise ne satisfont pas cette prescription. La section 508 de Rehabilitation Act of 1973[4] est un exemple de telles obligations pour des agences fédérales aux États-Unis.
Notez que <inlinegraphic>
n'est plus une balise valide dans DocBook version 5.
<olink>
The <olink>
tag provides cross-references between XML documents. For <olink>
s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>
s, these URLs can be supplied either as an XML entity or with a server-side script. Publican does not provide any way to build or use a database for these links.
<[element] xreflabel="[chaîne_quelconque_ici]">
La présence d'un attribut <xreflabel>
n'a pas d'utilité dans la version imprimée d'un ouvrage. De même, les valeurs de l'attribut ne sont pas vues par les traducteurs et, en conséquence, ne peuvent pas être traduites.
Par exemple, si vous avez :
<chapter id="ch03" xreflabel="Chapter Three"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
quand le XML est construit en HTML, la balise <xref>
devient une balise d'ancre HTML comme suit :
…see <a href="#ch03">Chapter Three</a> for details.
Le texte contenu dans la balise d'ancrage est le même que celui contenu dans l'attribut <xreflabel>
. Dans ce cas, cela signifie que les lecteurs des copies imprimées disposent de moins d'informations à ce propos.
Vous pouvez contourner ce problème si vous faites en sorte que la valeur de l'attribut <xreflabel>
soit le même que celui entre les balises de l'élément <title>
</title>
. Toutefois, cette duplication augmente les risques d'erreurs typographiques et n'apporte aucune amélioration sous-jacente. Et, encore une fois, la quantité d'information présentée aux lecteurs des copies imprimées en est réduite.
Le XML :
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see >xref linkend="ch03"> for details.
donnera une balise d'ancrage HTML comme suit :
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Ce n'est pas autant porteur d'information que le texte présenté au lecteur si vous n'utilisez pas l'attribut <xreflabel>
. Ainsi :
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
transforme l'élément <xref>
comme suit lors de la construction du HTML :
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
Mais, les problèmes posés par <xreflabel>
lors de la traduction sont encore plus importants. Les valeurs des attributs en sont pas vues par les traducteurs. Donc, ils ne sont pas traduits. Reprenons le deuxième exemple ci-dessus :
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
En anglais, <xref>
est toujours transformé en une balise d'ancrage ainsi :
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Mais, quelqu'un lisant la version en allemand, verra ceci comme HTML sous-jacent :
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
Si l'attribut <xreflabel>
n'est pas utilisé, l'indication du titre et du chapitre, tous deux correctement traduits, sont visibles au lecteur. Ainsi :
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
se présentera, après traduction, à un locuteur allemand :
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
Qui est, sans surprise, ce que nous souhaitons.
Pour ces motifs, l'attribut xreflabel
est rejeté.
<[element] endterm="[chaîne_quelconque_ici]">
L'attribut endterm
vous permet de présenter un texte d'hyperlien autre que le nom du paragraphe ou du chapitre sur lequel le lien pointe. Donc, son utilité dans les versions imprimées est restreinte, et elle pose des problèmes aux traducteurs.
Le texte, présenté dans un élément (comme une balise <xref>
) contenant l'attribut endterm
, est pris d'une balise <titleabbrev>
du chapitre ou du paragraphe cible. Même si le contenu de la balise <titleabbrev>
est à disposition des traducteurs dans les fichiers PO du document, ce contenu est sorti du contexte de <xref>
. Cette absence de contexte peut rendre une traduction fiable impossible dans des langues qui marquent grammaticalement les prépositions ou les articles en nombre et en genre.
Par exemple, si vous avez :
<chapter id="The_Secret"> <title>The Secret to Eternal Life</title> <titleabbrev id="final">the final chapter</titleabbrev> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] The solution is in <xref linkend="The_Secret" endterm="final"/>.
Le texte autour de <xref>
se présente ainsi dans la version anglaise :
The solution is in
the final chapter
.
Un traducteur voit <titleabbrev>
dans un fichier PO ainsi :
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
et voit le texte contenant la balise <xref>
ailleurs dans le fichier PO (ou, plus vraisemblablement, dans un fichier PO différent) sous la forme :
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>." msgstr ""
Le traducteur n'a pas le moyen de savoir ce qui sera substitué à <xref linkend="The_Secret" endterm="final"/>
lors de la construction du document ; ainsi, une traduction en italien pourra s'écrire :
#. 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"/>."
Notez la préposition in
.
Si le traducteur a rendu en italien the final chapter
par l'ultimo capitolo
, le résultat à la construction du document sera :
La soluzione è in
l'ultimo capitolo
.
Ce résultat reste compréhensible, mais est inélégant, parce que l'italien combine certaines de ses prépositions avec l'article défini. Un italien plus élégant formulerait :
La soluzione è nell'
ultimo capitolo
.
Sans connaître le texte qui apparaît à la place de <xref linkend="The_Secret" endterm="final"/>, le traducteur en italien ne peut pas savoir s'il doit laisser la préposition in
en l'état ou laquelle des sept combinaisons possibles avec l'article défini utiliser : nel
, nei
, nello
, nell'
, negli
, nella
ou nelle
.
En plus, notez que la préposition combinée et l'article pose aussi le problème de savoir si le mot doit être placé dans le texte autour de <xref>
ou dans le <titleabbrev>
. Quelle que soit la solution retenue, elle posera des problèmes quand endterm
apparaîtra dans un contexte grammatical différent, car toutes les propositions de la langue italienne ne se combinent pas avec l'article défini de cette façon.
Compte tenu des problèmes que endterm
présente pour la traduction, Publican rejette cet attribut.
Allow the XML and XSLT processing to access the network. Defaults off.
Répertoire pour les fichiers source de la marque.
Surcharge le chemin vers le répertoire Common_Config
Surcharge le chemin vers le répertoire Common_Content
Utiliser un fichier de configuration non standard
Afficher un message d'aide
Désactiver la colorisation ANSI de la journalisation.
Désactiver toute journalisation.
$
publican add_revisionAjouter une entrée dans l'historique des révisions
Date à utiliser pour une révision.
adresse électronique à utiliser pour la révision.
prénom à utiliser pour la révision
Langue dans laquelle le XML sera écrit
Une entrée à ajouter pour la révision. Peut être précisée plusieurs fois.
Numéro à utiliser pour la révision
nom de famille à utiliser pour la révision.
$
publican buildTransformer XML en d'autres formats (pdf, html, html-single, drupal-book, etc)
Cette balise indique à Publican que les données traitées font partie d'une collection distribuée. Note : ne pas utiliser distributed_set en ligne de commande. Publican utilise cette balise lorsqu'il s'appelle lui-même pour le traitement des collections distribuées. C'est la seule façon d'utiliser cette balise de manière sûre.
Imbrique l'objet TOC du site Web dans le HTML créé
Liste, avec une virgule comme séparateur, des formats, par exemple : html,pdf,html-single,html-desktop,txt,epub
Liste, avec une virgule comme séparateur, des langues, par exemple : en-US,de-DE,all
Ne pas lancer la validation de DTD
désigne l'outil à utiliser pour la création du PDF. Les options valides sont wkhtmltopdf ou fop.
Répertoire des fichiers à publier. Par défaut « publish »
Paramétrer le contenu à construire pour publication
Show fuzzy translation entries in output. Defaults off.
Répertoire pour les fichiers source de publican.
$
publican cleanSupprimer tous fichiers et répertoires temporaires
Répertoire des fichiers à publier. Par défaut « publish »
$
publican clean_idsExécuter clean_ids pour le XML source
$
publican clean_setSupprimer les copies locales des collections d'ouvrages distantes
$
publican copy_web_brandCopier le contenu Web installé d'une estampille sur un autre site
L'estampille à utiliser
Fichier de configuration du site Web à utiliser lors de la copie du contenu entre sites.
Fichier de configuration du site Web à utiliser ou à créer.
$
publican createCréer un nouvel ouvrage, ensemble ou article
L'estampille à utiliser
La version du DTD Dockbook à utiliser.
L'édition de l'ouvrage, de l'article ou de la collection
Langue dans laquelle le XML sera écrit
Le nom de l'ouvrage, de l'article, de la collection ou de la marque
Le nom du produit
Le type (ouvrage, article ou collection)
La version du produit
$
publican create_brandCréer une nouvelle marque
Langue dans laquelle le XML sera écrit
Le nom de l'ouvrage, de l'article, de la collection ou de la marque
$
publican create_siteCréer un nouveau site Web à l'emplacement indiqué
Surcharge le fichier base de données par défaut.
Langue dans laquelle le XML sera écrit
Fichier de configuration du site Web à utiliser ou à créer.
Remplace le chemin du modèle par défaut.
Remplace le chemin vers la TOC par défaut.
$
publican help_configAfficher un message d'aide pour le fichier de configuration
$
publican install_bookInstaller un ouvrage sur un site Web.
Langue dans laquelle le XML sera écrit
Fichier de configuration du site Web à utiliser ou à créer.
$
publican install_brandInstaller une marque à l'emplacement indiqué
/chemin/vers/emplacement/installation
Répertoire des fichiers à publier. Par défaut « publish »
Installer le contenu Web pour une marque.
$
publican lang_statsrapport des statistiques PO
Langue dans laquelle le XML sera écrit
$
publican migrate_siteMigrate a website DataBase from Publican < 3 to Publican 3.
Fichier de configuration du site Web à utiliser ou à créer.
$
publican packageEmpaquetage d'une langue pour livraison
Construire le RPM binaire au lancement de l'empaquetage
Pousser le SRPM dans brew
Créer un paquet de bureau au lieu d'un paquet Web
Langue dans laquelle le XML sera écrit
Répertoire des fichiers à publier. Par défaut « publish »
Utiliser une construction à partir de zéro au lieu d'une reprise
Créer un paquet sans numéro de version dans le nom
En attente de la fin de construction à l'aide de brew
$
publican print_bannedAfficher une liste des balises DocBook interdites
$
publican print_knownAfficher une liste des balises DocBook QA
$
publican print_treeAfficher l'arborescence des xi:includes
$
publican print_unusedAfficher une liste des fichiers XML inutilisés
$
publican print_unused_imagesAfficher la liste des fichiers Image non utilisés
$
publican remove_bookSupprimer un ouvrage d'un site Web.
Langue dans laquelle le XML sera écrit
Fichier de configuration du site Web à utiliser ou à créer.
$
publican renameRenommer un ouvrage Publican
Le nom de l'ouvrage, de l'article, de la collection ou de la marque
Le nom du produit
La version du produit
$
publican reportAfficher un rapport de lisibilité pour le texte source
$
publican site_statsRapporter le contenu du site Web
Fichier de configuration du site Web à utiliser ou à créer.
$
publican trans_dropInstantané de langue source à utiliser dans la traduction.
$
publican update_dbAjouter ou supprimer des entrées dans la base de données. Utilisé pour le traitement d'ouvrages partiellement construits, de même que lors de la construction de paquets.
Résumé pour un ouvrage
Ajouter une entrée de base de données
Langue sur laquelle cette traduction se fonde.
Le numéro de version de l'ouvrage installé.
Supprimer une entrée de la base de données
Liste, avec une virgule comme séparateur, des formats, par exemple : html,pdf,html-single,html-desktop,txt,epub
Langue dans laquelle le XML sera écrit
Le nom de l'ouvrage, de l'article, de la collection ou de la marque
étiquette du nom pour un ouvrage
Le nom du produit
étiquette produit pour un ouvrage
Fichier de configuration du site Web à utiliser ou à créer.
Ordre de tri d'un ouvrage
Sous-titre d'un ouvrage
La version du produit
étiquette version pour un ouvrage
$
publican update_poMise à jour des fichiers PO
adresse électronique à utiliser pour la révision.
prénom à utiliser pour la révision
Liste, avec une virgule comme séparateur, des langues, par exemple : en-US,de-DE,all
Utiliser msgmerge de gettext pour la fusion POT/PO
Conserver les msgid précédents quand des correspondances approximatives sont détectées dans les mises à jour des PO.
nom de famille à utiliser pour la révision.
$
publican update_potMise à jour des fichiers POT
$
publican update_siteMise à jour des modèles de site existants.
Fichier de configuration du site Web à utiliser ou à créer.
$
publican zt_pullTélécharger des traductions de Zanata.
$
publican zt_pushTéléverser des traductions dans Zanata.
These are set in the books or brands configuration files.
Architecture à filtrer en sortie.
filtre de public à utiliser pour la sortie.
Une liste, avec une espace comme séparateur, des livres utilisés dans cet ensemble distant.
L'estampille à utiliser lors de la construction de ce paquet.
The default value for this parameter is: common
La distribution de brew à utiliser pour construire le RPM bureau autonome.
The default value for this parameter is: docs-5E
This field is deprecated and will be removed from Publican in the future.
Afficher les éléments « bridgehead » dans les TM ?
The default value for this parameter is: 0
Pour HTML, le premier paragraphe doit-il être sur la même page que son parent ?
The default value for this parameter is: 0
Pour HTML, quel est le plus grand niveau d'imbrication des découpages de paragraphes dans leurs pages ?
The default value for this parameter is: 4
Chemin vers les fichiers jar pour FOP.
The default value for this parameter is: /usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar
Chemin vers le contenu Publican
The default value for this parameter is: /usr/share/publican
Chemin vers les contenus communs de Publican
The default value for this parameter is: /usr/share/publican/Common_Content
Conditions pour l'élagage du XML avant transformation.
Le contenu est-il confidentiel ?
The default value for this parameter is: 0
Le texte utilisé pour indiquer que le contenu est confidentiel.
The default value for this parameter is: CONFIDENTIAL
filtre de conformité à utiliser pour la sortie
Afficher des messages supplémentaires ?
The default value for this parameter is: 0
URL de l'équipe de documentation du paquet. Utilisé pour l'URL en haut à droite du HTML.
The default value for this parameter is: https://fedorahosted.org/publican
Name of this document. Fetched from title tag in xml_lang/TYPE_Info.xml if not set in cfg file.
This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$
This field is not supported for: brand.
Le nom de l'auteur à afficher dans la page d'ouvrage Drupal. Il doit être un nom d'utilisateur Drupal valide.
The default value for this parameter is: Publican
The directory where the image should be stored in drupal server.
The default value for this parameter is: /sites/default/files/documentation/
The menu where we can find the book.
The default value for this parameter is: user-guide
Remplace le nom de l'ouvrage affiché dans le menu Drupal
Le format à utiliser pour une sortie sur ordinateur de bureau.
The default value for this parameter is: html-desktop
Space-separated list of packages the desktop RPM obsoletes.
Space-separated list of packages the desktop RPM requires.
Version du DTD DocBook sur laquelle ce projet se fonde.
The default value for this parameter is: 4.5
ID du greffon Eclipse. Par défaut, « $product.$docname »
Nom du greffon Eclipse. Par défaut, « $product.$docname »
Eclipse plugin provider. Defaults to "Publican-v4.2.2"
Répertoire où sont situées les images.
The default value for this parameter is: extras
Crée une table des matières jusqu'à la profondeur de subdivision donnée.
The default value for this parameter is: 0
Langues à remplacer par xml_lang quel que soit l'état de la traduction.
Répertoire où sont situées les images.
The default value for this parameter is: images
Remplace le fichier Info par défaut.
filtre de langue pour la sortie.
Licence utilisée par ce paquet.
The default value for this parameter is: GFDL
Le nom des fichiers XML et ENT principaux pour l'ouvrage, sans langue ni extension. Extrait de docname si pas défini.
Liste, avec point-virgule comme séparateur, des catégories de menu pour le paquet bureau.
filtre de SE pour la sortie.
Le système d'exploitation pour lequel les paquets sont construits
La police à utiliser pour le corps du texte dans des PDF.
The default value for this parameter is: Liberation Sans
La police monospace à utiliser pour du texte dans des PDF.
The default value for this parameter is: Liberation Mono
URL du produit. Utilisé en haut à gauche des HTML.
The default value for this parameter is: https://fedorahosted.org/publican
Produits concernés par ce paquet. Extrait de la balise productname dans xml_lang/TYPE_Info.xml
This parameter is constrained with the following regular expression: ^[0-9a-zA-Z_\-\.\+]+$
This field is not supported for: brand.
Dépôt d'extraction des ouvrages distants de la collection.
Par défaut, l'historique de révision est trié dans l'ordre décroissant. Définissez cette valeur à « asc » ou « ascending » pour inverser l'ordre de tri.
Remplace le fichier Revision_History par défaut.
filtre « revision » pour la sortie.
filtre « revisionflag » pour la sortie.
filtre « role » pour la sortie.
Type de dépôt dans lequel des ouvrages faisant partie d'une collection distribuée sont stockés. Types pris en charge : SVN, GIT.
filtre « sécurity » pour la sortie.
Afficher les « remark » dans la sortie traitée
The default value for this parameter is: 0
Remplace le poids de tri par défaut. Valeur par défaut : 50.
URL pour retrouver l'archive tar des fichiers source. Utilisée dans les fichiers spec RPM.
filtre « status » pour la sortie.
Répertoire à utiliser pour la construction.
The default value for this parameter is: tmp
Profondeur de subdivision à incorporer dans la table des matières principale.
The default value for this parameter is: 2
Choisir le générateur de format à utiliser lors de la création de la sortie txt
The default value for this parameter is: default
This parameter is constrained with the following regular expression: ^(links{1}|tables{1}|default)$
Type du contenu de ce paquet. Pris en charge : set, book, article, brand
The default value for this parameter is: Book
filtre « userlevel » pour la sortie.
filtre « vendor » pour la sortie.
Version de ce paquet. Extraite de la balise productnumber de xml_lang/TYPE_Info.xml
This parameter is constrained with the following regular expression: ^[0-9][^\p{IsSpace}]*$
La distribution de brew à utiliser pour construire le RPM Web.
The default value for this parameter is: docs-5E
Une liste, avec la virgule comme séparateur, des formats à utiliser pour les paquets Web.
The default value for this parameter is: html,html-single,pdf,epub
Ceci est une page d'accueil pour un site Web créé par Publican, et non pour un ouvrage standard.
web_home is deprecated and will be removed from Publican in the future. Use "web_type: home" instead.
Ceci est le nom d'hôte pour un site Web créé par Publican, utilisé pour les recherches et le Sitemap. Assurez-vous d'avoir inclus le chemin complet dans l'arbre du document. Par ex. si vos documents sont dans le répertoire docs : http://www.example.com/docs
web_host is deprecated and will be removed from Publican in the future. Use "host" in the web site configuration file instead.
Remplace l'étiquette de menu du nom de l'ouvrage, niveau bas, sur un site Web Publican.
Paquets à déclarer obsolètes dans le RPM Web.
Remplace l'étiquette de menu du produit, niveau haut, sur un site Web Publican.
Remplace la forme de recherche par défaut d'un site Web Publican. Par défaut, elle utilise une recherche Google et effectue la recherche sur le site si web_host est défini.
web_search is deprecated and will be removed from Publican in the future. Use "search" in the web site configuration file instead.
Ceci est une page spéciale pour un site Web créé par Publican, et non pour un ouvrage standard. Les types valides sont home, product et version.
This parameter is constrained with the following regular expression: ^(home|product|version)$
Remplace l'étiquette de menu de la version, niveau médian, sur un site Web Publican. Pour cacher cet élément de menu, définissez sa valeur à UNUSED.
Options supplémentaires à passer à « wkhtmltopdf ». Ex : wkhtmltopdf_opts: "-O landscape -s A3"
filtre « wordsize » pour la sortie.
Langue dans laquelle le XML est rédigé.
The default value for this parameter is: en-US
These are set in the brands configuration files.
Une liste, avec la virgule comme séparateur, d'attributs XML non permis dans le source.
Une liste, avec la virgule comme séparateur, de balises XML non permises dans le source.
La marque de base à utiliser pour cette estampille.
The default value for this parameter is: common
Surcharge le type du Document Type. Doit être une chaîne complète.
surcharge l'URI du Document Type. Doit être une chaîne complète.
Option d'estampille pour désactiver l'imbrication de la table des matières de navigation dans les paquets Web
Chemin complet pour le fichier de configuration du site publican pour les sites non standard de RPM.
Chemin d'installation pour les sites Web de RPM non standards.
Nom du paquet de site pour sites Web avec RPM non standard. Requis pour s'assurer que le site est installé.
These are set in the sites configuration file.
The name of the SQLite database file for your site, with the filename extension .db
Output extra messages when running publican.
The default value for this parameter is: 0
The default language for this website. Tables of contents for languages other than the default language will link to documents in the default language when translations are not available.
The default value for this parameter is: en-US
Dump the publican database to an XML file.
The name of the file to dump the publican database to.
The default value for this parameter is: /var/www/html/DUMP.xml
HTML to inject in to the footer of every page on the website.
The default value for this parameter is:
The web host, may be a full URI or a relative path.
The default value for this parameter is: /docs
Stop publican from automatically rebuilding teh web site everytime a book is installed, updated or removed.
The default value for this parameter is: 0
The HTML to inject in as the site serach.
The default value for this parameter is: Google site search
Title used for all site navigation pages.
The default value for this parameter is: Documentation
Full path to the template directory.
The default value for this parameter is: /usr/share/publican/templates
The source file to use for JavaScript functionality.
The default value for this parameter is: default.js
The path to the directory in which to create the top-level index.html file.
Template to use for generagting the web style 1 toc file.
The default value for this parameter is: toc
This field is deprecated and will be removed from Publican in the future.
Publican supports mutliple base styles for websites, this picks one.
The default value for this parameter is: 1
This parameter is constrained with the following regular expression: [1-2]
This field is deprecated and will be removed from Publican in the future.
Zip up the dump file after dumping it
The default value for this parameter is: 0
Le fichier de vidage d'un site Web créé par Publican contient un certain nombre de renseignements de base sur la configuration du site, ainsi que des informations sur chaque document publié. Ce sont :
<host>
l'URL de la racine du site de documentation, tel que défini par le paramètre host
du fichier de configuration du site.
<def_lang>
la langue par défaut de la documentation sur le site Web, telle que définie par le paramètre def_lang
dans le fichier de configuration du site.
Chaque document, dans chacune des langues, dans chaque format dispose d'un enregistrement distinct. Ces enregistrements contiennent les données suivantes :
<name>
l'intitulé du document, créé à partir de la balise <title>
extraite d'un des fichiers Book_Info.xml
, Article_Info.xml
ou Set_Info.xml
, sauf si cet intitulé a été surchargé par le paramètre docname
dans le fichier publican.cfg
. Toute espace dans l'intitulé est remplacée par un souligné.
<ID>
un numéro identifiant unique pour ce document, dans ce format et dans cette langue.
<abstract>
un bref résumé du contenu du document, créé à partir du contenu de la balise <abstract>
de l'un des fichiers Book_Info.xml
, Article_Info.xml
ou Set_Info.xml
. Publican utilise le même contenu pour créer la section %description
du fichier spec quand il empaquette le document. Si <abstract>
est traduit, ce champ contient le texte traduit.
<format>
le format dans lequel le document a été produit — html
pour un html à plusieurs pages, html-single
pour un html à page unique, pdf
pour un PDF et epub
pour EPUB.
<language>
le code de la langue du document. Voyez l'Annexe F, Codification des langues pour plus d'informations à propos des codes de langues en XML.
<name_label>
le nom du document tel qu'il apparaît dans la table des matières du site. Cette étiquette peut être définie avec le paramètre web_name_label
dans le fichier publican.cfg
du document. Autrement, le champ reste vide pour un document dans sa langue d'origine ou utilise l'intitulé traduit pour un document traduit. Toute espace dans l'étiquette du nom est remplacée par un souligné.
<product>
le produit que le document décrit, valeur créée à partir de la balise <productname>
de l'un des fichiers Book_Info.xml
, Article_Info.xml
ou Set_Info.xml
, sauf si elle a été écrasée par le paramètre product
du fichier publican.cfg
. Toute espace dans le nom du produit est remplacée par un souligné.
<product_label>
le nom du produit tel qu'il apparaît dans la table des matières du site. Cette étiquette peut être définie à l'aide du paramètre web_product_label
du fichier publican.cfg
du document. Autrement, le champ reste vide pour un document dans sa langue d'origine ou bien utilise le titre traduit pour un document traduit. Toute espace dans le nom est remplacée par un souligné.
Si l'étiquette du produit est définie à la valeur UNUSED
, aucune en-tête pour ce produit n'apparaît dans les tables des matières du site Web.
<subtitle>
une description sur une ligne du contenu du document, créée à partir de la balise <subtitle>
de l'un des fichiers Book_Info.xml
, Article_Info.xml
ou Set_Info.xml
. Publican utilise le même contenu pour générer la section Summary
du fichier spec quand il empaquette le document. Si <subtitle>
est traduit, ce champ contient le texte traduit.
<update_date>
La date la plus récente de l'installation du document sur le site, au format YYYY-MM-DD.
<version>
la version du produit que le document décrit (et non la version du document lui-même), définie à partir de la balise <productnumber>
de l'un des fichiers Book_Info.xml
, Article_Info.xml
ou Set_Info.xml
, sauf à être surchargée par le paramètre version
dans le fichier publican.cfg
.
<version_label>
la version du produit telle qu'elle apparaît dans la table des matières du site. Cette étiquette peut être définie à l'aide du paramètre web_version_label
dans le fichier publican.cfg
du document.
Si l'étiquette de la version est définie à la valeur UNUSED
, aucune en-tête pour cette version du produit n'apparaît dans la table des matières du site Web.
Exemple D.1. Exemple d'enregistrements d'un fichier DUMP.xml
Ces deux enregistrements d'un fichier DUMP.xml
sont relatifs au même ouvrage, le Red Hat Enterprise Linux 5 Installation Guide (Guide d'installation de Red Hat Enterprise Linux 5), mais avec deux formats différents et deux langues différentes — une version PDF en anglais et une version HTML à plusieurs pages en français.
<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>
À l'aide des champs suivants, vous pouvez recomposer l'URL de tout document sur le site :
<host>
<name>
<format>
<language>
<product>
<version>
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Par exemple, http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
<host>
/<language>
/<product>
/<version>
/<format>
/<name>
/index.html
Par exemple, 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
Par exemple, 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
Par exemple, http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub
Notez que les champs <product_label>
, <version_label>
et <name_label>
n'ont aucun sens pour des URL, même quand ces champs ont été supprimés dans les tables des matières par l'emploi de la valeur UNUSED
.
La seule partie de la balise de langue XML qui soit obligatoire dans Publican est le descripteur de langue. Toutefois, Publican a été conçu en supposant que vous préciserez, selon la coutume, le descripteur de région pour l'identification de la langue. Dans de nombreuses langues, l'orthographe et le vocabulaire varient de façon significative d'une région à l'autre. Si vous ne précisez pas le type régional de la langue dans lequel le document est rédigé ou dans lequel il est traduit, vous pourriez obtenir des résultats imprévisibles quand vous construirez le document avec Publican.
Le système de codage utilisé pour identifier les langues dans la norme XML n'est pas le seul utilisé dans le monde aujourd'hui. Néanmoins, comme l'application Publican s'attache à respecter la norme XML, ce sont les seuls pris en charge par Publican. En particulier, notez que les codes utilisés dans les outils GNU (reconnaissables par l'utilisation de soulignés et du symbole @
(arobas) pour séparer les éléments — par exemple, en_GB
ou sr_RS@latin
) ne respectent pas la norme XML et, donc, ne fonctionnent pas avec Publican.
Publican is an XML publication tool and therefore is designed to use the language codes — or tags — that the World Wide Web Consortium (W3C) designated in the XML specification.[5] These codes are defined in the Internet Engineering Task Force (IETF) document BCP 47: Tags for Identifying Languages.[6]
Les codes de langues sont formés de un ou plusieurs descripteurs, séparés les uns des autres par un tiret. Dans l'ordre d'apparition dans un code de langue, ces descripteurs sont :
langue-écriture-région-variante
BCP 47 also allows for considerable customization of language tags for special purposes through the use of extension subtags and private-use subtags. Extension subtags allow for finer-tuning of existing subtags, but must be registered with the IETF (none are currently registered). Private-use subtags are introduced by x-
and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).[7] Although Publican will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form language-region
. A brief description of subtags follows:
The language subtag comprises two or more lower-case letters and is the only mandatory part of the language tag. For most widely spoken languages, the language subtag is a two-letter code identical with the language codes specified in ISO 639-1, [8] for example, zh
(Chinese), hi
(Hindi), es
(Spanish), and en
(English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,[9] for example, bal
(Balochi), apk
(Kiowa Apache), and tpi
(Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or ISO 639-2 equivalent, such as subtags for the constructed languages qya
(Quenya) and tlh
(Klingon), and for the occult language i-enochian
(Enochian). This last example also illustrates a small number of language subtags grandfathered into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
RFC 5646: Tags for Identifying Languages[10] issued in September 2009 allows for extended language subtags to follow the language subtag. Extended language subtags are three-letter codes that represent languages that share a close relationship with a language already represented by a language subtag. For example, yue
represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: zh-yue
. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
The script subtag comprises four letters — the first one in upper case, the other three in lower case — and defines a writing system. These codes are identical with the four-letter codes specified in ISO 15924.[11] The script subtag is used to identify languages that are commonly written with more than one writing system; the subtag is omitted when it adds no distinguishing value to the language tag overall. For example, sr-Latn
represents Serbian written with the Latin alphabet and sr-Cyrl
represents Serbian written with the Cyrillic alphabet; az-Arab
represents Azerbaijani written in Arabic script and az-Cyrl
represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as fr-Latn
, because French is not commonly written in any script other than the Latin alphabet anywhere in the world.
The region subtag comprises either two upper-case letters (for regions that conform to national boundaries) or three digits (for other areas, such as trans-national regions). The two-letter subtags are identical with those from ISO 3166-1[12], for example, AT
(Austria), TZ
(Tanzania), and VE
(Venezuela). The three-digit region subtags are based on those in UN M.49, [13] for example, 015
(Northern Africa), 061
(Polynesia), and 419
(Latin America and the Caribbean).
Les descripteurs de variantes identifient des variantes reconnues et bien définies d'une langue ou d'une écriture ; il peuvent comporter des majuscules, des minuscules et des chiffres. Les descripteurs de variantes débutant par une lettre doivent comporter au moins cinq caractères, et ceux commençant par un chiffre quatre caractères. La plupart des descripteurs de variantes ne peuvent s'utiliser que combinés avec des descripteurs donnés ou des combinaisons de descripteurs. Les descripteurs de variantes ne correspondent à aucune norme ; ils résultent d'un enregistrement séparé auprès de l'IETF par une personne ou un groupe d'intérêt.
Dans le cadre des normes actuelles, des dialectes de plusieurs langues sont désignés par des descripteurs de variantes, par exemple, nedis
désigne le nadiza (également connu comme natisone), un dialecte slovène. Ce descripteur doit être utilisé conjointement avec le descripteur du slovène, donc : sl-nedis
. En septembre 2009, l'IETF a émis une « Request for Comments (RFC) », qui (entre autres choses) propose que les dialectes soient représentés par des descripteurs d'extension attachés au descripteur de langue[14].
La plupart des descripteurs de variantes marquent une orthographe particulière, résultant le plus souvent d'une réforme de l'orthographe officielle ou d'un travail significatif de documentation de la langue. Voici quelques exemples (avec les descripteurs de langue requis) : fr-1606nicot
(français documenté par Jean Nicot en 1606), de-1901
(orthographe allemande codifiée selon la 2e Conférence orthographique de 1901) et be-1959acad
(biélorusse codifié selon la Commission orthographique de 1959).
Finalement, certains descripteurs de variantes marquent une variante particulière d'un système d'écriture ou une translittération. Par exemple, zh-Latn-wadegile
désigne le chinois écrit avec l'alphabet latin, selon le système de développé par Thomas Wade et Herbert Giles ; ja-Latn-hepburn
est le japonais écrit avec l'alphabet latin avec le système de translittération de James Curtis Hepburn.
Publican prend en charge les langues suivantes :
ar-SA — arabe
as-IN — assamais
ast-ES — asturien
bg-BG — bulgare
bn-IN — bengali (Inde)
bs-BA — bosnien
ca-ES — catalan
cs-CZ — tchèque
da-DK — danois
de-CH — allemand (Suisse)
de-DE — allemand (Allemagne)
el-GR — grec
es-ES — espagnol
fa-IR — persan
fi-FI — finnois
fr-FR — français
gu-IN — gujarati
he-IL — hébreu
hi-IN — hindi
hr-HR — croate
hu-HU — hongrois
id-ID — indonesien
is-IS — islandais
it-IT — italien
ja-JP — japonais
kn-IN — kannada
ko-KR — coréen
lv-LV — lituanien
ml-IN — malayalam
mr-IN — marathi
nb-NO — norvégien (orthographe Bokmål)
nl-NL — néerlandais
or-IN — oriya
pa-IN — pendjabi
pl-PL — polonais
pt-BR — Portugais (Brésil)
pt-PT — Portugais (Portugal)
ru-RU — russe
si-LK — cingalais
sk-SK — slovaque
sr-Cyrl-RS — serbe (écriture cyrillique)
sr-Latn-RS — serbe (écriture latine)
sv-SE — suédois
ta-IN — tamoul
te-IN — télougou
th-TH — thaï
uk-UA — ukrainien
zh-CN — chinois (République populaire de Chine, implicitement écriture Han simplifiée)
zh-TW — chinois (République de Chine, implicitement écriture Han traditionnelle)
Historique des versions | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Version 4.2-0.6 | Thu Apr 30 2015 | ||||||||||
| |||||||||||
Version 4.2-0.5 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Version 4.2-0.4 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Version 4.2-0.3 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Version 4.2-0.2 | Fri Oct 3 2014 | ||||||||||
| |||||||||||
Version 4.2-0.1 | Mon Sep 29 2014 | ||||||||||
| |||||||||||
Version 4.2-0 | Mon May 12 2014 | ||||||||||
| |||||||||||
Version 4.0-5.1 | Tue May 6 2014 | ||||||||||
| |||||||||||
Version 4.0-5 | Thu Mar 27 2014 | ||||||||||
| |||||||||||
Version 4.0-4 | Mon Nov 25 2013 | ||||||||||
| |||||||||||
Version 4.0-3 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Version 4.0-2 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Version 4.0-1 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
Version 3.2-1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Version 3.2-0 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
Version 3.1-0 | Tue Jan 8 2013 | ||||||||||
| |||||||||||
Version 3.0-0 | Mon Feb 20 2012 | ||||||||||
| |||||||||||
Version 2.7-1 | Tue Sep 6 2011 | ||||||||||
| |||||||||||
Version 2.6-1 | Mon Jul 18 2011 | ||||||||||
| |||||||||||
Version 2.4-1 | Wed Dec 1 2010 | ||||||||||
| |||||||||||
Version 2.3-0 | Mon Oct 25 2010 | ||||||||||
| |||||||||||
Version 2.3-0 | Tue Oct 5 2010 | ||||||||||
| |||||||||||
Version 2.2-0 | Thu Aug 19 2010 | ||||||||||
| |||||||||||
Version 2.1-1 | Fri Jul 16 2010 | ||||||||||
| |||||||||||
Version 1.6-1 | Mon May 24 2010 | ||||||||||
| |||||||||||
Version 1.6-0 | Fri May 7 2010 | ||||||||||
| |||||||||||
Version 1.5-0 | Fri Feb 26 2010 | ||||||||||
| |||||||||||
Version 1.4-0 | Wed Feb 17 2010 | ||||||||||
| |||||||||||
Version 1.3-0 | Mon Dec 7 2009 | ||||||||||
| |||||||||||
Version 1.2-0 | Fri Nov 27 2009 | ||||||||||
| |||||||||||
Version 1.1-1 | Thu Nov 26 2009 | ||||||||||
| |||||||||||
Version 1.1-0 | Thu Oct 22 2009 | ||||||||||
| |||||||||||
Version 1.0-0 | Tue Oct 13 2009 | ||||||||||
| |||||||||||
Version 0.5-0 | Thu Dec 18 2008 | ||||||||||
| |||||||||||
Version 0.4-0 | Tue Nov 25 2008 | ||||||||||
| |||||||||||
Version 0.3-0 | Fri Oct 10 2008 | ||||||||||
| |||||||||||
Version 0.2-0 | Fri Sep 05 2008 | ||||||||||
| |||||||||||
Version 0.1-1 | Fri Jun 06 2008 | ||||||||||
| |||||||||||
Version 0.1-0 | Fri May 16 2008 | ||||||||||
| |||||||||||
Version 0.0-0 | Thu Dec 13 2007 | ||||||||||
|