Guide utilisateur

Publication d'ouvrages, articles, papiers et ensembles en plusieurs tomes avec XML Docbook

Don Domingo

Red Hat
Services ingénierie des contenus

Zac Dover

Red Hat
Services ingénierie des contenus

Sven Dowdeit

Directives d'installation pour Debian et pour Docker 

Norman Dunbar

Directives d'installation pour OpenSUSE 

Brian Forté

Red Hat
Services ingénierie des contenus

Rüdiger Landmann

Red Hat
Services ingénierie des contenus

Rebecca Newton

Red Hat
Services ingénierie des contenus

Joshua Oakes

Red Hat
Services ingénierie des contenus

Joshua Wulf

Red Hat
Services ingénierie des contenus

Jeff Fearn

Revue de détail, brouillons bruts et problèmes persistants 
Red Hat, Engineering Operations Logo

Josef Hruška

Vérification des exemples en tchèque dans « Entités et traduction » 
Fedora
Projet adaptations locales

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.


Préface

1. Conventions d'écriture

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.

1.1. Conventions typographiques

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 et dir 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 SystèmePréférencesSouris à partir de la barre du menu principal pour lancer les Préférences de la souris. À partir de l'onglet Boutons, cliquez sur la case à cocher Pour gaucher puis cliquez sur Fermer 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).

Pour insérer un caractère spécial dans un fichier gedit, choisissez ApplicationsAccessoiresTable des caractères depuis la barre du menu principal. Ensuite, choisissez RechercheTrouver… depuis la barre du menu Table des caractères, saisissez le nom du caractère dans le champ Recherche puis cliquez sur Suivant. 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 Copier. Vous pouvez désormais revenir à votre document et choisir ModifierColler 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.

1.2. Conventions pour citations mises en avant

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"));
   }
}

1.3. Admonitions

Enfin, nous utilisons trois styles visuels pour attirer l'attention sur des informations qui auraient pu être normalement négligées :

Note

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.

Astuce

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.

Important

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.

Attention

Un avertissement ne devrait pas être ignoré. Ignorer des avertissements risque fortement d'entrainer des pertes de données.

Avertissement

Un avertissement ne devrait pas être ignoré. Ignorer des avertissements risque fortement d'entrainer des pertes de données.

2. Vos commentaires sont importants !

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.

Introduction

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.

1. This section is for testing the output and doesn't ship in the production docs

1.1. Testing BZ #1092351 Code Switcher

PerlC++
#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World!\n";
#include <iostream>

int main()
{
  std::cout << "Hello World!"; &lies;
}

1.2. Testing BZ #1088051 Code Popper

[Show All][Hide]$ apt-get search libxslt
gambas3-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

 

1.3. Testing BZ #1112899 Callouts and BZ #1101050 Entities in CDATA

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;   
    }
  }
1

Establishes the connection with the messaging broker.

2

Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.

3

Creates a receiver that reads from the given address.

4

Creates a sender that sends to the given address.

5

Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

6

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.

7

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 
1

column_name (required): the name of the column holding the collection index values.

2

base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array.

1.4. Testing BZ #752021 Cross-Browser embed external video

1.5. Testing BZ #1110611 A line break is automatically inserted after cdata in code.

Is there a newline inserted after this CDATA?

1.6. Testing BZ #1117561 CDATA tags

=, >, >=, <, <=, <>

!=

<>

1.7. Testing BZ #1135827 Single line comment being highlighted in a callout.

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
  }

}
1

The ServiceRegistry class is an example class implementing the task business logic.

2

The completeWorkItem() call completes the work item execution.

1.8. Testing BZ #1168765 programlisting no longer support language attribute.

<?xml version="1.0" encoding="UTF-8"?><test></test>

Chapitre 1. Installation de Publican

1.1. Systèmes d'exploitation Linux

Important — Disponibilité dans les dépôts

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.

1.1.1. Fedora & Red Hat Enterprise Linux 6

  1. Ouvrez un terminal.

  2. Basculez sur l'utilisateur administrateur : su -

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

1.1.2. Ubuntu

  1. Ouvrez un terminal.

  2. Exécutez la commande suivante pour installer le paquet publican :

    $ sudo apt-get install publican

1.1.3. Debian

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.

  1. Ouvrez un terminal.

  2. Devenez administrateur : su -

  3. Pour installer le paquet publican, lancez la commande :

    $ apt-get install publican
  4. Pour déterminer la version de publican installée, exécutez :

    $ publican -v
    version=2.8
Important — Installation des paquets les plus récents avec « Apt-Pinning »

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 :

  1. Ouvrez un terminal.

  2. Devenez administrateur : su -

  3. 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
  4. Ajoutez la ligne ci-après à la fin du fichier :

    #### testing  #########
    deb http://ftp.us.debian.org/debian testing main contrib non-free
  5. Sauvegardez le fichier et fermez le logiciel de traitement de texte.

  6. 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
  7. 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
  8. Sauvegardez le fichier et fermez le logiciel de traitement de texte.

  9. Lancez la commande suivante pour mettre à jour la liste des paquets disponibles pour votre ordinateur :

    $ apt-get update
  10. 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 :

$ publican
Warning: 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.
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 :

  1. [Show All][Hide]$ apt-get search libxslt
    gambas3-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
    (et à nouveau la même chose pour libxml2)

  2. puis en mettant à jour ces paquets pour le test.

    $ apt-get -t testing upgrade libxml2 libxslt1.1

1.1.4. OpenSuse 12

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.

  1. Ouvrir une session de terminal.

  2. 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
    Note

    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.

  3. 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
    
  4. 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 ./
    
  5. 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
  6. 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.

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

    Note

    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
    
    Note

    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.

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

  9. 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
    Note

    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.

1.1.5. Conteneur Docker

Note

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.

  1. Ouvrez un terminal.

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

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

  4. Maintenant vous pouvez vous servir de publican conformément à la documentation du produit :

    $ publican --version 
    version=3.2.1

1.1.6. Running publican from a GIT checkout

It is possible to run publican from a GIT checkout, without installing it, if the dependencies are installed.

  1. To checkout the source from GIT open a terminal.

  2. Exécutez la commande suivante pour installer le paquet publican :

    $ cd PATH TO PLACE SOURCE
    $ git clone git://git.fedorahosted.org/publican.git publican
  3. 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

1.2. Systèmes d'exploitation Windows

  1. Download the Publican installer from https://fedorahosted.org/releases/p/u/publican/.

  2. Naviguez jusqu'au le dossier dans lequel vous avez téléchargé Publican-Installer-version.exe.

  3. Double-cliquez sur le fichier Publican-Installer-version.exe.

  4. 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 J'accepte de chacun, sinon, cliquez sur le bouton Annuler.

  5. 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 Suivant pour poursuivre.

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

  7. Une fois la destination choisie, cliquez sur Installer.

    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 Détails.

  8. Une fois le processus achevé, l'installeur vous notifie le message Terminé.

    Cliquez sur Fermer pour quitter l'installeur.

1.3. OSX Lion

  1. Installez Xcode à partir du dépôt Mac App.

    Note

    La taille de Xcode est d'environ 4 Gio. Attendez-vous à devoir patienter. Mais il contient des choses dont vous avez besoin.

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

  3. Ouvrez un terminal.

  4. Installez les dépendances pour Publican, disponibles en tant que ports :

    $sudo port install docbook-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
  5. 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
  6. Installez FOP si vous souhaitez travailler avec des PDF :

    $ sudo port install fop
    $ echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
  7. 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 clone git://git.fedorahosted.org/publican.git
  8. Changez de répertoire :

    $ cd publican/publican
  9. 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
  10. 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

  1. $ publican create --name=testbook
  2. $ cd testbook
  3. $ publican build --formats=html --langs=en-US
  4. 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

  1. 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
  2. Soit vérifiez le SVN de votre estampille, soit obtenez une estampille pré-construite auprès d'un ami.

    1. The SVN location for the brands supplied by Red Hat is http://svn.fedorahosted.org/svn/publican

    2. Si vous utilisez une estampille pré-construite, procédez à son extraction si nécessaire.

  3. Si vous vous êtes procuré l'estampille à partir du SVN, construisez-la.

    $ cd publican/publican-jboss
    $ publican build --formats=xml --langs=all --publish
  4. 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.

Chapitre 2. Valeurs par défaut pour Publican

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

  • email

  • formats

  • lang

  • langs

Note

Ce fichier est totalement différent de publican.cfg utilisé pour construire un ouvrage. Il n'accepte pas les mêmes paramètres.

2.1. Exemples de valeurs par défaut pour Publican

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 build
Setting 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"

Chapitre 3. Commandes de Publican

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 Menu de démarrage 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_action

action 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_action

Certaines options_commande affectent la sortie des actions, par exemple, indiquer si Publican doit utiliser des couleurs ANSI dans sa sortie.

Chapitre 4. Création d'un document

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

4.1. Fichiers dans le répertoire de l'ouvrage

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

4.1.1. Le fichier publican.cfg

Note — Personnaliser une sortie

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

À utiliser avec précaution

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.

arch au niveau nœud racine

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.

Références croisées et l'attribut arch

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

chunk_section_depth: 0

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, …

chunk_section_depth: 1

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 …

chunk_section_depth: 2

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 …

chunk_section_depth: 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 …

chunk_section_depth: 4 (défaut)

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.

Nœuds racine et balisage conditionnel

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.

Références croisées et balises conditionnelles

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.

Un DTD différent peut ralentir la construction

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.

Note

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.

Note

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.

Note

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

generate_section_toc_level: 0 (défaut)

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.

generate_section_toc_level: 1

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 …

generate_section_toc_level: 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

toc_section_depth: 0

Publican crée une table des matières principale ne comportant que les chapitres.

toc_section_depth: 1

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 …

toc_section_depth: 2 (défaut)

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.

Important — Abandon de 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"

Aide à partir de la ligne de commande

Lancez la commande $ publican help_config dans le répertoire racine d'un ouvrage pour un résumé à propos de ces paramètres.

4.1.2. Book_Info.xml

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.

Paquets autres que RPM

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

Caractères permis

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.

Caractères permis

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.

Caractères autorisés

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.

Caractères autorisés

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.

Caractères autorisés

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.

4.1.2.1. Paquets RPM, éditions, impressions et versions

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.

4.1.3. Author_Group.xml

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

4.1.4. Chapter.xml

Articles et chapitres

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.

Note

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.

4.1.5. Nom_document.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.

Important

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.

4.1.6. Nom_document.ent

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>


4.1.6.1. Entités et traductions

Être particulièrement précautionneux avec les entités

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

CasUtilisationForme
Nominatifle sujet du verbeFedora
Génitifindique la possessionFedory
Accusatifcomplément d'objet directFedoru
Datifcomplément d'objet indirectFedoře
Vocatifappel direct du sujetFedoro
Locatifrelatif à un emplacementFedoře
Instrumentalrelatif à une méthodeFedorou

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.

4.1.7. Revision_History.xml

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.

4.2. Ajout d'images

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.

Emplacement des fichiers images

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.

4.3. Ajout d'exemples de code

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 (&amp; and &lt; 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/ :

  1. créer le répertoire « extras »

    $ mkdir en-US/extras
  2. copier le fichier de code dans le répertoire « extras »

    $ cp ~/samples/foo.c en-US/extras/.
  3. 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>
  4. 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/.

4.4. Ajout de fichiers

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

4.5. Renommer un document

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_titre

modifie 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_produit

modifie 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_version

modifie 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

4.6. Traduction d'un document

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 :

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

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

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

    Supprimez les fichiers XML inutilisés

    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.

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

    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
    Supprimez les fichiers POT inutilisés

    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.

  5. Traduisez les chaînes contenues dans les fichiers PO.

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

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

4.6.1. Groupe traducteur

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.

4.6.2. Traduction des index et des glossaires

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>"

4.7. Construction d'un document

Note — Personnalisation de la sortie

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 :

  1. 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 ».

  2. 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
  3. 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
  4. 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=langues

construit l'ouvrage dans les formats HTML multi-pages, HTML page unique et PDF.

4.7.1. Construction d'un document sans validation

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.

4.8. Empaquetage d'un document

Paquets autres que RPM

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.

Note — Personnalisation de la sortie

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.

4.8.1. Types de paquets RPM

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.

4.8.1.1. Paquets RPM source et paquets RPM binaires

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

4.8.1.2. Paquets pour ordinateur de bureau et paquets 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 Outils systèmeDocumentation 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.

4.8.1.3. Entrées de menu de bureau pour documents

Par défaut, les paquets RPM des documents Publican pour bureau apparaissent sur le bureau GNOME dans le menu Outils systèmeDocumentation. Quand des utilisateurs ont un grand nombre de documents installés sur le système, ce menu devient vraiment encombré et difficile à explorer. La documentation pour les divers produits, quelquefois en plusieurs langues, sont emmêlés, ajoutant à la confusion.

Pour regrouper la documentation pour des produits donnés dans un sous-menu séparé dans le menu GNOME Outils systèmeDocumentation, il faut :

  • créer et distribuer un paquet de menu bureau créant le nouveau sous-menu,

  • définir la catégorie du menu dans le document et, facultativement, faire en sorte que le paquet documentation requière le paquet de menu bureau.

Notez que le menu Documentation ne groupe pas des entrées dans un sous-menu avant que deux documents ou plus appartenant à ce sous-menu n'aient été installés. Le premier document apparaît dans le menu Outils systèmeDocumentation.

4.8.1.3.1. Création d'un paquet menu de bureau

Un paquet menu de bureau consiste en :

  • un fichier d'entrée bureau (.directory) fournissant les métadonnées à propos de ce nouveau sous-menu,

  • un fichier menu de bureau (.menu) qui définit la position du nouveau sous-menu à l'intérieur du menu Documentation.

La structure du fichier .directory pour une documentation créée avec Publican comprend :

  • l'en-tête du groupe [Desktop Entry]

  • le paramètre Name définissant le nom du sous-menu que vous souhaitez mettre en place dans le menu Documentation,

  • facultativement, la précision de l'adaptation locale pour le paramètre Name, avec le format Name[code_langue]code_langue est le code de la langue au format glibc, et non au format XML utilisé par Publican pour les codes langue,

  • le paramètre Comment pour définir une description du nouveau sous-menu,

  • facultativement, la précision de l'adaptation locale pour le paramètre Comment, avec le format Comment[code_langue]code_langue est un code langue au format glibc, et non au format XML utilisé par Publican pour les codes langue,

  • le paramètre Type, égal à Directory.

  • et le paramètre Encoding égal à UTF-8.

Exemple 4.5. Exemple de fichier .directory

Le fichier suivant, menu-example.directory illustre la structure d'un fichier entrée de bureau.

[Desktop Entry]
Name=Example
Name[fr]=Exemple
Name[it]=Esempio
Comment=Example Documentation menu
Comment[fr]=Exemple d'une menu de documentation
Comment[it]=Esempio di un menù di documentazione
Type=Directory
Encoding=UTF-8

Le fichier entrée de bureau est placé dans /usr/share/desktop-directories/.

For a full description of how desktop entries work, refer to the Desktop Entry Specification, available from http://standards.freedesktop.org/entry-spec/latest/

Un fichier menu de bureau est un fichier XML qui contient :

  • un document type de déclaration pour la définition du menu de bureau de freedesktop.org :

    <!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
    "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
  • un élément racine, <Menu>, contenant :

    • un élément <Name> de contenu Documentation

    • un autre élément <Menu> qui, à son tour, contient :

      • un élément <Name> avec le contenu Documentation (exactement comme l'élément racine).

      • un élément <Directory> dont le contenu est le nom du fichier d'entrée de bureau qui vient d'être créé, par exemple :

        <Directory>menu-example.directory</Directory>
      • un élément <Includes> avec le contenu X-nom_catégorie, où nom_catégorie est un identifiant des documents à regrouper sous cette entrée de menu. Par exemple :

        <Includes>X-Example-Docs</Includes>

Exemple 4.6. Exemple de fichier .menu

Le fichier suivant, menu-example.menu, illustre la structure d'un fichier de menu de bureau.

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
	<Name>Documentation</Name>
	<Menu>
		<Name>Documentation</Name>
		<Menu>
			<Name>Example</Name>
			<Directory>menu-example.directory</Directory>
			<Include>
				<Category>X-Example-Docs</Category>
			</Include>
		</Menu>
	</Menu> 
</Menu> 

Le fichier de menu de bureau est placé dans /etc/xdg/menus/settings-merged/

For a full description of how desktop menus work, refer to the Desktop Menu Specification, available from http://standards.freedesktop.org/desktop-menu-spec/latest/

4.8.1.3.2. Définition de la catégorie d'un menu de bureau

Pour placer un document dans un sous-menu de Outils systèmeDocumentation, définissez le paramètre menu_category dans le fichier publican.cfg de façon à ce qu'il corresponde au contenu de l'élément <Includes> du fichier menu de bureau associé. Par exemple, voyez un fichier menu de bureau contenant l'élément :

<Includes>X-Example-Docs</Includes>

Pour placer un document dans le sous-menu défini par le fichier menu du bureau, le fichier publican.cfg du document doit comporter :

menu_category: X-Example-Docs
Important

Publican traitera la chaîne dans « menu_category » et remplacera __LANG__ par la langue actuelle. Ceci permet la personnalisation des menus en fonction de la langue.

menu_category: X-Example-Docs-__LANG__

Notez que vous pouvez incorporer ce paramètre dans le fichier defaults.cfg ou dans le fichier overrides.cfg d'une estampille de façon à ce que tous les fichiers avec une estampille donnée soient regroupés automatiquement dans le sous-menu sans que vous ayez à définir le paramètre menu_category dans chaque document.

Si vous incorporez les fichiers du menu et des entrées bureau dans un paquet RPM, vous pouvez construire des paquets RPM de documentation requérant le paquet menu de bureau. Avec cet ensemble de dépendances, le paquet menu de bureau est automatiquement placé sur les systèmes des utilisateurs quand ils installent un paquet de documentation ; il est ainsi assuré que la documentation apparaîtra dans le sous-menu créé pour le projet. Définissez la dépendance avec le paramètre dt_requires dans le fichier publican.cfg du document. Par exemple, si vous voulez livrer un paquet menu de bureau nommé foodocs-menu, écrivez :

dt_requires: foodocs-menu

Notez que vous pouvez inclure ce paramètre dans le fichier defaults.cfg ou dans le fichier overrides.cfg de façon à ce que tout document construit avec cette estampille réclame le même paquet menu de bureau.

4.8.2. La commande $ 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 langue

définit la langue dans laquelle la documentation sera empaquetée.

Traductions incomplètes

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.

Omission du numéro de version du logiciel

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.

4.8.2.1. La commande $ publican package — exemples d'utilisation

Voici des exemples illustrant quelques options courantes pour le Guide de configuration de Foomaster 9, 2e édition, révision 6.

$ publican package --lang=cs-CZ

produit 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-CZ

produit 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-CZ

produit à 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-CZ

produit 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-CZ

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

4.9. Balisage conditionnel

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

Nœuds racine et balisage conditionnel

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.

Références croisées et balises conditionnelles

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

4.9.1. Balisage conditionnel et traduction

N'utiliser le balisage conditionnel qu'avec de grandes précautions

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.

4.10. Logiciels en pré-parution et brouillons de documentation

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.

4.10.1. Marquage d'un logiciel en pré-parution

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 :

  1. 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>
    
    
  2. 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.

Important

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.

4.10.2. Marquage d'un brouillon de documentation

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!

4.10.3. Marquage d'un brouillon de documentation pour un logiciel en pré-parution

Pour marquer proprement une documentation inachevée pour un logiciel en pré-parution, effectuez les deux procédures de marquage ci-dessus.

4.10.4. Denoting changed content New section

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"

added

This is how an element that has been added to a new revision is marked-up.

changed

This is how an element that has been changed in a new revision is marked-up.

deleted

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.

Chapitre 5. Estampillage

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

5.1. Installation d'un estampillage

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 :

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

  2. Placez-vous dans le répertoire dans lequel vous avez créé ou décompressé l'estampille :

    $ cd publican-estampille

    estampille désigne son nom.

  3. Construisez l'estampille :

    $ publican build --formats xml --langs all --publish
  4. Installez-la :

    $ sudo publican install_brand --path chemin

    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

MarqueLicence des fichiers « Common Content »Licence par défaut pour les documentsPaquetCommentaire
common CC0 1.0 GFDL Version 1.2 publicanLicence compatible avec la GPL. Aucune option.
RedHat CC-BY-SA 3.0 CC-BY-SA 3.0publican-redhat
FedoraCC-BY-SA 3.0CC-BY-SA 3.0publican-fedora
JBossCC-BY-SA 3.0CC-BY-SA 3.0publican-jbossAucune option.
oVirt OPL 1.0 OPL 1.0publican-ovirtAucune option.
GIMP GFDL Version 1.2 GFDL Version 1.2publican-gimpCorrespond à la licence de la documentation GIMP existante.
GenomeOPL 1.0OPL 1.0publican-genomeAucune 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 ».

5.2. Création d'une estampille

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

5.3. Fichiers dans le répertoire de l'estampille

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

5.3.1. Le fichier publican.cfg

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.

5.3.2. Les fichiers defaults.cfg et overrides.cfg

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.

5.3.3. Fichier publican-estampille.spec

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.

5.3.4. README

Le fichier README contient une courte description du contenu du paquet de l'estampille.

5.3.5. COPYING

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.

5.3.6. « Common Content » d'une estampille

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

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

5.3.7. Le sous-répertoire css

Le sous-répertoire css ne contient que le fichier overrides.css.

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

5.3.8. Le sous-répertoire 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 ».

5.3.9. L'option brand_dir

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

Important

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.

5.4. Empaquetage d'une estampille

Paquets autres que RPM

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.

Chapitre 6. Utilisation des collections

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.

6.1. Ensembles autonomes

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

  1. 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
    
    
  2. À 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.

    $ cd My_Set/en-US
    $ mkdir Book_A Book_B
  3. 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>
  4. Suivez un processus identique pour Book_B, situé dans le répertoire books/My_Set/en-US/Book_B.

  5. 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
    
    
  6. Pour rendre votre ensemble XML valide, modifiez :

    1. 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>
      
    2. 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.

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

6.2. Ensembles distribués

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.

Important

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

  1. 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
    
    
  2. 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.

  3. 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
    
    
  4. 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>
    
  5. Testez l'ensemble en exécutant la commande publican build --formats=test --langs=en-US.

    Important

    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.

Chapitre 7. Construction d'un site Web avec Publican

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.

7.1. Construction d'un site Web à la main

7.1.1. Création d'une structure de site Web

Pour construire la structure du site Web :

  1. 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
  2. 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.

  3. 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 :

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

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

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

      Important — le paramètre search n'est pas validé

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

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

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

    6. Facultativement, définissez le style Web avec le paramètre web_style.

      web_style: 1

      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)

      web_style: 2

      Le site Web comporte une barre de navigation de type « émietté » en haut de la documentation.

      Important

      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.

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

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

  4. 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
  5. Construisez et installez chaque estampille, y compris l'estampille common de Publican.

    1. Placez-vous dans le répertoire qui contient les sources de l'estampille.

      $ cd brandsrc_dir
    2. Construisez l'estampille :

      $ publican build --formats=xml --langs=all --publish
    3. Installez l'estampille sur votre site Web.

      $ publican install_brand --web --path=path_to_site_root_dir

      Effectuez ces étapes pour chacune des estampilles.

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

7.1.2. Création, installation et mise à jour de la page d'accueil

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:

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

  2. Placez-vous dans le répertoire de l'article :

    $ cd nom_page

    Par exemple :

    $ cd Home_Page
  3. 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.

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

  5. 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>
  6. 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.

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

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

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

7.1.3. Création, installation et mise à jour des pages du produit et des pages des versions

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:

  1. 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
  2. Placez-vous dans le répertoire de l'article :

    $ cd nom_page

    Par exemple :

    $ cd FooMaster
  3. 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.

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

  5. 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>
  6. 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.

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

7.1.4. Installation, mise à jour et suppression de documents

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.

7.2. Construction d'un site Web avec des paquets RPM

7.2.1. Création de la structure du site Web

Attention — cette procédure remplace des fichiers

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.

  1. Connectez-vous au serveur Web.

  2. Installez Publican. Par exemple, sur un serveur avec Fedora comme système d'exploitation, exécutez :

    $ sudo yum install publican publican-common-web
  3. 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 :

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

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

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

      Important — le paramètre search n'est pas validé

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

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

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

    6. Facultativement, définissez le style Web avec le paramètre web_style.

      web_style: 1

      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)

      web_style: 2

      Le site Web comporte une barre de navigation de type « émietté » en haut de la documentation.

      Important

      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.

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

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

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

7.2.2. Création, installation et mise à jour de la page d'accueil

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.

  1. 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 ».

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

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

7.2.3. Création, installation et mise à jour des pages du produit et des pages des versions

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.

  1. 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 ».

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

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

7.2.4. Installation, mise à jour et suppression de documents

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.

7.3. Remise du Sitemap aux moteurs de recherche

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.

7.3.1. Soumission du fichier Sitemap à Google.

Procédure 7.1. Pour soumettre le fichier Sitemap à Google :

  1. Inscrivez-vous pour obtenir un compte Google à l'adresse Google Webmaster Tools. Si vous en possédez déjà un, vous pouvez l'utiliser.

  2. Ouvrez une session dans le compte « Google Webmaster Tools » (Outils Google pour webmestres) à l'URL : http://www.google.com/webmasters/tools/home.

  3. Tout d'abord, il faut certifier que vous êtes bien le propriétaire du site Publican. Cliquez sur le bouton Ajouter un site.

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

  5. Suivez les instructions affichées et téléversez, à la racine des documents de votre site Web, le fichier HTML fourni par Google.

  6. 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 Vérifier.

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

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

  9. Vous êtes amené à la page de soumission du fichier Sitemap. Cliquez sur le bouton Soumettre un Sitemap.

  10. 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 Soumettre le Sitemap. 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.

7.3.2. Soumission d'un fichier Sitemap à Bing.

Procédure 7.2. Pour soumettre un fichier Sitemap à Bing :

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

  2. Ouvrez une session dans le compte « Bing Webmaster Tools » (Outils Google pour webmestres) à l'URL : http://www.bing.com/toolbox/webmaster/.

  3. Cliquez sur le bouton Ajouter un site.

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

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

  6. 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 Vérifier.

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

  8. Sélectionnez l'onglet Indexer.

  9. Sélectionnez Sitemaps, puis Ajouter une source.

  10. La boîte de dialogue Ajouter une source s'affiche. Entrez l'URL de votre fichier Sitemap et cliquez sur Soumettre. 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.

Chapitre 8. Importer un ouvrage dans Drupal

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.

8.1. Comment construire un fichier CSV pour 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.

Important — Utiliser le système de contrôle de version

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.

8.2. Le fichier publican.cfg

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.

Important — Définir un auteur

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

Important — Définir le bloc de menu

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/ ».

8.3. Guide d'importation dans Drupal

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 case, puis cliquez sur le bouton Enregistrer la configuration pour activer le module Node Import.

testing longdesc
Important — Activer les modules du cœur de Drupal

Vous devez également activer les modules du cœur de Drupal suivants :

  • Book

  • Menu

  • Path

Autorisation d'installation de modules

Veuillez consulter votre administrateur réseau si vous n'avez pas l'autorisation d'installer un module dans Drupal.

8.3.1. Comment ajouter un bloc menu ?

Vous pouvez définir le menu que l'ouvrage affichera dans Drupal. Si le bloc de menu indiqué n'existe pas, Drupal envoie tout contenu importé sur la première liaison. Donc, si vous souhaitez lister votre ouvrage dans un bloc de menu, assurez-vous d'en avoir créé un avant d'importer l'ouvrage. Pour ajouter un nouveau bloc de menu, connectez-vous simplement sur votre site Drupal et allez à Administrer -> Menus -> Ajouter un menu .

  • Nom du menu — le nom unique du menu. Cette valeur sert à définir le paramètre drupal_menu_block dans publican.cfg.

  • Titre — le titre du menu. Il s'affichera en tête du bloc de menu.

8.3.2. Paramétrage pour l'importation d'un nœud

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

      Important — Propriété du fichier

      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.

8.3.3. Comment importer un ouvrage ?

Procédure 8.1. Pour importer un ouvrage dans Drupal :

  1. Parcourir les étapes précisées dans la Section 8.1, « Comment construire un fichier CSV pour importation dans Drupal ? ».

  2. Téléverser le fichier CSV dans le répertoire d'importation du serveur Drupal,

  3. 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 ».

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

  5. Cliquer sur Importer maintenant 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 !

  6. Un lien vers l'ouvrage est maintenant affiché dans le bloc de menu défini.

8.3.4. Comment mettre à jour un ouvrage ?

Refaites simplement les étapes de la Section 8.3.3, « Comment importer un ouvrage ? » pour mettre à jour l'ouvrage.

Attention — Découpage en sections

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.

Chapitre 9. Questions fréquemment posées

Q :

Comment ajouter une langue à mon ouvrage ?

R :

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.

Q :

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 ?

R :

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

Q :

Comment mettre à jour tous les fichiers po ?

R :

Exécutez la commande $ publican update_po --langs=all.

Q :

Où puis-je obtenir une liste complète des options de construction de Publican ?

R :

Exécutez la commande $ publican build --help.

Q :

Où puis-je obtenir une liste complète des paramètres pouvant être définis dans publican.cfg ?

R :

Exécutez la commande $ publican help_config dans un répertoire contenant n'importe quel document Publican.

Q :

Où sont situés les fichiers courants de Publican ?

R :

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.

Q :

Est-il possible d'incorporer des fichiers quelconques dans les archives tar et les paquets RPM ?

R :

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.

Important

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.

Q :

Pourquoi Publican donne-t-il des avertissements à propos de balises inconnues ?

R :

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

Q :

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 ?

R :

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.

Q :

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 ?

R :

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.

Q :

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 ?

R :

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.

Q :

Les précédentes version de Publican supprimaient les balises <para> vides. Publican fait-il toujours cela ?

R :

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.

Q :

Qu'est-il arrivé au vérificateur d'orthographe ?

R :

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


Q :

Pourquoi la balise <segmentedlist> ne fonctionne pas lors de la construction des PDF ?

R :

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.

Q :

Qu'est-il arrivé aux couleurs des images dans ce PDF ?

R :

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.

Q :

Quand je construis le document, j'obtiens une erreur ‘langage non défini’ — qu'est-ce qui n'est pas correct ?

R :

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.

Q :

Comment puis-je activer l'auto-complétion automatique bash sur la ligne de commande pour Publican ?

R :

Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:

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

  2. Ajoutez au fichier ~/.bashrc :

    # Utiliser l'auto-complémentation bash, si disponible
    if [ -f /etc/bash_completion ]; then
            . /etc/bash_completion
    fi
    
  3. Redémarrez le terminal ou bien exécutez source ~/.bashrc.

Q :

Pourquoi ai-je des difficultés quand je construis de gros ouvrages ?

R :

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.

Q :

Pourquoi Jeff appelle-t-il Isaac ‘Ivan’ ?

R :

Parce que Jeff a la mémoire qui flanche !

Éléments et attributs rejetés

Pris en charge, non pris en charge et rejetés

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.

A.1. Discouraged elements

<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 :

A

Apple — an apple is…

G

Grapesgrapes are…

O

Orange — an orange is…

P

Peach — a peach is…

se présente ainsi en espagnol :

A

Manzana — la manzana es…

G

Uva — la uva es…

O

Naranja — la naranja es…

P

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.

A.2. Attributs rejetés

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

Résumé des commandes

B.1. Options de commande

--allow_network

Allow the XML and XSLT processing to access the network. Defaults off.

--brand_dir=s

Répertoire pour les fichiers source de la marque.

--common_config=s

Surcharge le chemin vers le répertoire Common_Config

--common_content=s

Surcharge le chemin vers le répertoire Common_Content

--config=s

Utiliser un fichier de configuration non standard

--help

Afficher un message d'aide

--nocolours

Désactiver la colorisation ANSI de la journalisation.

--quiet

Désactiver toute journalisation.

B.2. Command actions

$ publican add_revision

Ajouter une entrée dans l'historique des révisions

--date=DATE

Date à utiliser pour une révision.

--email=E-MAIL

adresse électronique à utiliser pour la révision.

--firstname=PRÉNOM

prénom à utiliser pour la révision

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--member=MEMBRE

Une entrée à ajouter pour la révision. Peut être précisée plusieurs fois.

--revnumber=NUMÉRO_RÉVISION

Numéro à utiliser pour la révision

--surname=NOM_FAMILLE

nom de famille à utiliser pour la révision.

$ publican build

Transformer XML en d'autres formats (pdf, html, html-single, drupal-book, etc)

--distributed_set

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.

--embedtoc

Imbrique l'objet TOC du site Web dans le HTML créé

--formats=FORMATS

Liste, avec une virgule comme séparateur, des formats, par exemple : html,pdf,html-single,html-desktop,txt,epub

--langs=LANGUES

Liste, avec une virgule comme séparateur, des langues, par exemple : en-US,de-DE,all

--novalid

Ne pas lancer la validation de DTD

--pdftool=PDFTOOL

désigne l'outil à utiliser pour la création du PDF. Les options valides sont wkhtmltopdf ou fop.

--pub_dir=RÉPERTOIRE_SOURCE

Répertoire des fichiers à publier. Par défaut « publish »

--publish

Paramétrer le contenu à construire pour publication

--showfuzzy

Show fuzzy translation entries in output. Defaults off.

--src_dir=SRC_DIR

Répertoire pour les fichiers source de publican.

$ publican clean

Supprimer tous fichiers et répertoires temporaires

--pub_dir=RÉPERTOIRE_SOURCE

Répertoire des fichiers à publier. Par défaut « publish »

$ publican clean_ids

Exécuter clean_ids pour le XML source

$ publican clean_set

Supprimer les copies locales des collections d'ouvrages distantes

$ publican copy_web_brand

Copier le contenu Web installé d'une estampille sur un autre site

--brand=BRAND

L'estampille à utiliser

--old_site_config=OLD_SITE_CONFIG

Fichier de configuration du site Web à utiliser lors de la copie du contenu entre sites.

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican create

Créer un nouvel ouvrage, ensemble ou article

--brand=BRAND

L'estampille à utiliser

--dtdver=DTDVER

La version du DTD Dockbook à utiliser.

--edition=EDITION

L'édition de l'ouvrage, de l'article ou de la collection

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--name=NAME

Le nom de l'ouvrage, de l'article, de la collection ou de la marque

--product=PRODUCT

Le nom du produit

--type=TYPE

Le type (ouvrage, article ou collection)

--version=VERSION

La version du produit

$ publican create_brand

Créer une nouvelle marque

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--name=NAME

Le nom de l'ouvrage, de l'article, de la collection ou de la marque

$ publican create_site

Créer un nouveau site Web à l'emplacement indiqué

--db_file=DB_FILE

Surcharge le fichier base de données par défaut.

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

--tmpl_path=TMPL_PATH

Remplace le chemin du modèle par défaut.

--toc_path=TOC_PATH

Remplace le chemin vers la TOC par défaut.

$ publican help_config

Afficher un message d'aide pour le fichier de configuration

$ publican install_book

Installer un ouvrage sur un site Web.

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican install_brand

Installer une marque à l'emplacement indiqué

--path=PATH

/chemin/vers/emplacement/installation

--pub_dir=RÉPERTOIRE_SOURCE

Répertoire des fichiers à publier. Par défaut « publish »

--web

Installer le contenu Web pour une marque.

$ publican lang_stats

rapport des statistiques PO

--lang=LANGUE

Langue dans laquelle le XML sera écrit

$ publican migrate_site

Migrate a website DataBase from Publican < 3 to Publican 3.

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican package

Empaquetage d'une langue pour livraison

--binary

Construire le RPM binaire au lancement de l'empaquetage

--brew

Pousser le SRPM dans brew

--desktop

Créer un paquet de bureau au lieu d'un paquet Web

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--pub_dir=RÉPERTOIRE_SOURCE

Répertoire des fichiers à publier. Par défaut « publish »

--scratch

Utiliser une construction à partir de zéro au lieu d'une reprise

--short_sighted

Créer un paquet sans numéro de version dans le nom

--wait

En attente de la fin de construction à l'aide de brew

Afficher une liste des balises DocBook interdites

Afficher une liste des balises DocBook QA

Afficher l'arborescence des xi:includes

Afficher une liste des fichiers XML inutilisés

Afficher la liste des fichiers Image non utilisés

$ publican remove_book

Supprimer un ouvrage d'un site Web.

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican rename

Renommer un ouvrage Publican

--name=NAME

Le nom de l'ouvrage, de l'article, de la collection ou de la marque

--product=PRODUCT

Le nom du produit

--version=VERSION

La version du produit

$ publican report

Afficher un rapport de lisibilité pour le texte source

$ publican site_stats

Rapporter le contenu du site Web

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican trans_drop

Instantané de langue source à utiliser dans la traduction.

$ publican update_db

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

--abstract=ABSTRACT

Résumé pour un ouvrage

--add

Ajouter une entrée de base de données

--book_src_lang=BOOK_SRC_LANG

Langue sur laquelle cette traduction se fonde.

--book_version=BOOK_VERSION

Le numéro de version de l'ouvrage installé.

--del

Supprimer une entrée de la base de données

--formats=FORMATS

Liste, avec une virgule comme séparateur, des formats, par exemple : html,pdf,html-single,html-desktop,txt,epub

--lang=LANGUE

Langue dans laquelle le XML sera écrit

--name=NAME

Le nom de l'ouvrage, de l'article, de la collection ou de la marque

--name_label=NAME_LABEL

étiquette du nom pour un ouvrage

--product=PRODUCT

Le nom du produit

--product_label=PRODUCT_LABEL

étiquette produit pour un ouvrage

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

--sort_order=SORT_ORDER

Ordre de tri d'un ouvrage

--subtitle=SUBTITLE

Sous-titre d'un ouvrage

--version=VERSION

La version du produit

--version_label=VERSION_LABEL

étiquette version pour un ouvrage

$ publican update_po

Mise à jour des fichiers PO

--email=E-MAIL

adresse électronique à utiliser pour la révision.

--firstname=PRÉNOM

prénom à utiliser pour la révision

--langs=LANGUES

Liste, avec une virgule comme séparateur, des langues, par exemple : en-US,de-DE,all

--msgmerge

Utiliser msgmerge de gettext pour la fusion POT/PO

--previous

Conserver les msgid précédents quand des correspondances approximatives sont détectées dans les mises à jour des PO.

--surname=NOM_FAMILLE

nom de famille à utiliser pour la révision.

$ publican update_pot

Mise à jour des fichiers POT

$ publican update_site

Mise à jour des modèles de site existants.

--site_config=SITE_CONFIG

Fichier de configuration du site Web à utiliser ou à créer.

$ publican zt_pull

Télécharger des traductions de Zanata.

$ publican zt_push

Téléverser des traductions dans Zanata.

Configuration summary

C.1. General options

These are set in the books or brands configuration files.

arch

Architecture à filtrer en sortie.

Public visé

filtre de public à utiliser pour la sortie.

books

Une liste, avec une espace comme séparateur, des livres utilisés dans cet ensemble distant.

brand

L'estampille à utiliser lors de la construction de ce paquet.

The default value for this parameter is: common

brew_dist

La distribution de brew à utiliser pour construire le RPM bureau autonome.

The default value for this parameter is: docs-5E

Avertissement

This field is deprecated and will be removed from Publican in the future.

bridgehead_in_toc

Afficher les éléments « bridgehead » dans les TM ?

The default value for this parameter is: 0

chunk_first

Pour HTML, le premier paragraphe doit-il être sur la même page que son parent ?

The default value for this parameter is: 0

chunk_section_depth

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

classpath

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

common_config

Chemin vers le contenu Publican

The default value for this parameter is: /usr/share/publican

common_content

Chemin vers les contenus communs de Publican

The default value for this parameter is: /usr/share/publican/Common_Content

condition

Conditions pour l'élagage du XML avant transformation.

confidential

Le contenu est-il confidentiel ?

The default value for this parameter is: 0

confidential_text

Le texte utilisé pour indiquer que le contenu est confidentiel.

The default value for this parameter is: CONFIDENTIAL

conformance

filtre de conformité à utiliser pour la sortie

debug

Afficher des messages supplémentaires ?

The default value for this parameter is: 0

doc_url

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

docname

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_\-\.\+]+$

Astuce

This field is not supported for: brand.

drupal_author

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

drupal_image_path

The directory where the image should be stored in drupal server.

The default value for this parameter is: /sites/default/files/documentation/

drupal_menu_block

The menu where we can find the book.

The default value for this parameter is: user-guide

drupal_menu_title

Remplace le nom de l'ouvrage affiché dans le menu Drupal

dt_format

Le format à utiliser pour une sortie sur ordinateur de bureau.

The default value for this parameter is: html-desktop

dt_obsoletes

Space-separated list of packages the desktop RPM obsoletes.

dt_requires

Space-separated list of packages the desktop RPM requires.

dtdver

Version du DTD DocBook sur laquelle ce projet se fonde.

The default value for this parameter is: 4.5

ec_id

ID du greffon Eclipse. Par défaut, « $product.$docname »

ec_name

Nom du greffon Eclipse. Par défaut, « $product.$docname »

ec_provider

Eclipse plugin provider. Defaults to "Publican-v4.2.2"

extras_dir

Répertoire où sont situées les images.

The default value for this parameter is: extras

generate_section_toc_level

Crée une table des matières jusqu'à la profondeur de subdivision donnée.

The default value for this parameter is: 0

ignored_translations

Langues à remplacer par xml_lang quel que soit l'état de la traduction.

img_dir

Répertoire où sont situées les images.

The default value for this parameter is: images

info_file

Remplace le fichier Info par défaut.

lang

filtre de langue pour la sortie.

license

Licence utilisée par ce paquet.

The default value for this parameter is: GFDL

mainfile

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.

OS

filtre de SE pour la sortie.

os_ver

Le système d'exploitation pour lequel les paquets sont construits

pdf_body_font

La police à utiliser pour le corps du texte dans des PDF.

The default value for this parameter is: Liberation Sans

pdf_mono_font

La police monospace à utiliser pour du texte dans des PDF.

The default value for this parameter is: Liberation Mono

prod_url

URL du produit. Utilisé en haut à gauche des HTML.

The default value for this parameter is: https://fedorahosted.org/publican

produit

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_\-\.\+]+$

Astuce

This field is not supported for: brand.

repo

Dépôt d'extraction des ouvrages distants de la collection.

rev_dir

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.

rev_file

Remplace le fichier Revision_History par défaut.

Version

filtre « revision » pour la sortie.

revisionflag

filtre « revisionflag » pour la sortie.

role

filtre « role » pour la sortie.

scm

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.

security

filtre « sécurity » pour la sortie.

show_remarks

Afficher les « remark » dans la sortie traitée

The default value for this parameter is: 0

sort_order

Remplace le poids de tri par défaut. Valeur par défaut : 50.

src_url

URL pour retrouver l'archive tar des fichiers source. Utilisée dans les fichiers spec RPM.

status

filtre « status » pour la sortie.

tmp_dir

Répertoire à utiliser pour la construction.

The default value for this parameter is: tmp

toc_section_depth

Profondeur de subdivision à incorporer dans la table des matières principale.

The default value for this parameter is: 2

txt_formater

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

Type du contenu de ce paquet. Pris en charge : set, book, article, brand

The default value for this parameter is: Book

userlevel

filtre « userlevel » pour la sortie.

vendor

filtre « vendor » pour la sortie.

version

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}]*$

web_brew_dist

La distribution de brew à utiliser pour construire le RPM Web.

The default value for this parameter is: docs-5E

web_formats

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

web_home

Ceci est une page d'accueil pour un site Web créé par Publican, et non pour un ouvrage standard.

Avertissement

web_home is deprecated and will be removed from Publican in the future. Use "web_type: home" instead.

web_host

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

Avertissement

web_host is deprecated and will be removed from Publican in the future. Use "host" in the web site configuration file instead.

web_name_label

Remplace l'étiquette de menu du nom de l'ouvrage, niveau bas, sur un site Web Publican.

web_obsoletes

Paquets à déclarer obsolètes dans le RPM Web.

web_product_label

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.

Avertissement

web_search is deprecated and will be removed from Publican in the future. Use "search" in the web site configuration file instead.

web_type

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)$

web_version_label

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.

wkhtmltopdf_opts

Options supplémentaires à passer à « wkhtmltopdf ». Ex : wkhtmltopdf_opts: "-O landscape -s A3"

wordsize

filtre « wordsize » pour la sortie.

xml_lang

Langue dans laquelle le XML est rédigé.

The default value for this parameter is: en-US

C.2. Brand options

These are set in the brands configuration files.

banned_attrs

Une liste, avec la virgule comme séparateur, d'attributs XML non permis dans le source.

banned_tags

Une liste, avec la virgule comme séparateur, de balises XML non permises dans le source.

base_brand

La marque de base à utiliser pour cette estampille.

The default value for this parameter is: common

dtd_type

Surcharge le type du Document Type. Doit être une chaîne complète.

dtd_uri

surcharge l'URI du Document Type. Doit être une chaîne complète.

no_embedtoc

Option d'estampille pour désactiver l'imbrication de la table des matières de navigation dans les paquets Web

web_cfg

Chemin complet pour le fichier de configuration du site publican pour les sites non standard de RPM.

web_dir

Chemin d'installation pour les sites Web de RPM non standards.

web_req

Nom du paquet de site pour sites Web avec RPM non standard. Requis pour s'assurer que le site est installé.

C.3. Site options

These are set in the sites configuration file.

db_file

The name of the SQLite database file for your site, with the filename extension .db

debug

Output extra messages when running publican.

The default value for this parameter is: 0

def_lang

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

Dump the publican database to an XML file.

dump_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:

host

The web host, may be a full URI or a relative path.

The default value for this parameter is: /docs

manual_toc_update

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

Title used for all site navigation pages.

The default value for this parameter is: Documentation

tmpl_path

Full path to the template directory.

The default value for this parameter is: /usr/share/publican/templates

toc_js

The source file to use for JavaScript functionality.

The default value for this parameter is: default.js

toc_path

The path to the directory in which to create the top-level index.html file.

toc_type

Template to use for generagting the web style 1 toc file.

The default value for this parameter is: toc

Avertissement

This field is deprecated and will be removed from Publican in the future.

web_style

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]

Avertissement

This field is deprecated and will be removed from Publican in the future.

zip_dump

Zip up the dump file after dumping it

The default value for this parameter is: 0

Contenu du fichier de vidage d'un site Web

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>

D.1. Recomposer des URL à l'aide du fichier de vidage

À l'aide des champs suivants, vous pouvez recomposer l'URL de tout document sur le site :

  • <host>

  • <name>

  • <format>

  • <language>

  • <product>

  • <version>

HTML sur plusieurs pages

<host>/<language>/<product>/<version>/<format>/<name>/index.html

Par exemple, http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html

HTML sur une seule page

<host>/<language>/<product>/<version>/<format>/<name>/index.html

Par exemple, http://docs.fedoraproject.org/en-US/Fedora/14/html-single/Accessibility_Guide/index.html

PDF

<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

EPUB

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

Exemple de fichier spec pour paquet de menu de bureau

Le fichier spec suivant est un exemple de la façon dont vous pouvez empaqueter, dans un RPM pour expédition, un fichier d'entrée sur bureau (.directory) et un fichier de menu de bureau (.menu). Reportez-vous à la Section 4.8.1.3, « Entrées de menu de bureau pour documents » pour la structure de ces fichiers.

Cet exemple suppose qu'un fichier entrée de bureau nommé menu-example.directory, un fichier menu de bureau nommé menu-example.menu et un fichier à lire nommé README sont situés dans un répertoire nommé menu-example-0 et archivés dans menu-example-0.tgz.

La construction achevée, un paquet nommé menu-example a été produit.

Name:		menu-example
Version:	0
Release:	8%{?dist}.t1
Summary:	Example of how to do a documentation menu package
Group:		Development/Tools
License:	GPLv2+
URL:		http://engineering.redhat.com
Source0:	%{name}-%{version}.tgz
BuildRoot:	%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildArch:      noarch

%description
Example of how to do a documentation menu package

%prep
%setup -q

%build

%install
rm -rf %{buildroot}
mkdir -p $RPM_BUILD_ROOT%{_datadir}/desktop-directories
mkdir -p $RPM_BUILD_ROOT/etc/xdg/menus/settings-merged

install -m644 menu-example.directory $RPM_BUILD_ROOT%{_datadir}/desktop-directories/menu-example.directory
install -m644 menu-example.menu $RPM_BUILD_ROOT%{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

%{_fixperms} $RPM_BUILD_ROOT/*

%clean
rm -rf %{buildroot}

%files
%defattr(-,root,root,-)
%doc README
%{_datadir}/desktop-directories/menu-example.directory
%config(noreplace) %{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu

%changelog
* Tue Nov 23 2010 Jeff Fearn <jfearn@redhat.com> 0-8
- Creation

Codification des langues

Descripteurs de région

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.

Autres codifications de langues

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:

Descripteur de langue

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.

Descripteurs de langue étendus

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.

Descripteur d'écriture

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.

Descripteur de région

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

Descripteurs de variantes

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)

Annexe G. Revision History

Historique des versions
Version 4.2-0.6Thu Apr 30 2015Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0.5Fri Oct 3 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0.4Fri Oct 3 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0.3Fri Oct 3 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0.2Fri Oct 3 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0.1Mon Sep 29 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.2-0
Version 4.2-0Mon May 12 2014Jeff Fearn
Convert to DocBook 5
Update a lot of content
Version 4.0-5.1Tue May 6 2014Jeff Fearn
Fichiers de traduction synchronisés avec les sources XML 4.0-5
Version 4.0-5Thu Mar 27 2014Rüdiger Landmann
Corrections des directives de construction d'un site Web
Version 4.0-4Mon Nov 25 2013Rüdiger Landmann
Amélioration des directives pour la traduction BZ#1021287
Document à propos de l'utilisation du triage pour index et glossaires
Version 4.0-3Thu Nov 14 2013Norman Joost
Clarifier l'emploi des chemins relatifs dans les instructions d'estampillage - BZ#1028815
Version 4.0-2Thu Nov 14 2013Norman Dunbar
Correction des directives d'installation sur OpenSUSE - BZ#1000534
Version 4.0-1Thu Nov 14 2013Svein Dowdeit
Mise à jour des directives d'installation sur Debian - BZ#1013934
Ajout des directives d'installation sur Docker - BZ#1015943
Version 3.2-1Thu Jul 11 2013Zac Dover
Ajout des invites de commandes - BZ#880456
Entourer de guillemets droits les listes des formats Web - BZ#839141
Remplacement du lien cassé vers la page des greffons kate sur CPAN - BZ#973461
Mise à jour des directives à propos des sites Web - BZ#979224
Version 3.2-0Thu Jul 11 2013Jeff Fearn
Publican 3.0
Option de configuration de document de site « toc_js »
Option de construction de document --pdftool
Option de construction de document
Version 3.1-0Tue Jan 8 2013Norman Dunbar
Ajout du paragraphe concernant l'installation de Publican sur OpenSuse 12
Version 3.0-0Mon Feb 20 2012Jeff Fearn
Publican 3.0
Version 2.7-1Tue Sep 6 2011Rebecca Newton
Amélioration de la documentation pour l'utilisation d'une <collection> autonome
Version 2.6-1Mon Jul 18 2011Rüdiger Landmann
Documentation du nouveau paramètre manual_toc_update -- BZ#719573
Documentation de la nouvelle action update_db -- BZ#661948
Documentation de la nouvelle action rename -- BZ#694698
Documentation du nouveau paramètre mainfile -- BZ#688585
Incorporation d'un avertissement à propos des fichiers de configuration multiples pour des ouvrages soumis à des conditions -- BZ#657132
Correction d'un exemple de commande cassé -- BZ#663211
Incorporation des correctifs de relecture de Luigi Votta BZ#657576, BZ#663399
Version 2.4-1Wed Dec 1 2010Rüdiger Landmann
Incorporation des correctifs de relecture de Luigi Votta BZ#657576
Documentation de l'absence des PDF dans les langues réputées cassées
Documentation du paramètre web_formats
Documentation sur la personnalisation des menus Bureau
Documentation de site_overrides.css
Version 2.3-0Mon Oct 25 2010Rüdiger Landmann
Documentation sur les fichiers des vidages de sites Web
Documentation de la commande bump
Mise à jour sur le comportement selon la largeur de l'image
Version 2.3-0Tue Oct 5 2010Rüdiger Landmann
Mise à jour de lang_stats pour incorporer plusieurs langues
Corrections de détails pour web_logo.png BZ#638153
Correction de la liste des caractères utilisables dans les noms de produits et les intitulés de documents
Documentation du nouveau paramètre web_type et déplacement des paramètres web_host et web_search dans le fichier de configuration du site
Description des catalogues OPDS
Documentation des pages produit et version
Documentation de la page du manuel dans le format sortie
Documentation du paramètre bridgehead_in_toc
Correction -- def_langs est un paramètre de configuration de site, et non un paramètre du fichier de configuration de la page d'accueil
Version 2.2-0Thu Aug 19 2010Rüdiger Landmann
Développement avec incorporation d'exemples de code BZ#604255
Préciser clean_ids BZ#612819
Documentation de --novalid BZ#616142
Version 2.1-1Fri Jul 16 2010Rüdiger Landmann
Correction et clarification des instructions de site Web BZ#614259
Clarification à propos de l'utilisation de Product-Version-Id pour l'empaquetage
Version 1.6-1Mon May 24 2010Rüdiger Landmann
Mise à jour des instructions d'installation sur Ubuntu
Version 1.6-0Fri May 7 2010Rüdiger Landmann
Révision de la nomenclature des actions et des options
Documentation des actions print_known, print_banned et print_unused
Correction et développement de la documentation à propos de l'installation d'une charte graphique pour une marque de fabrique
Documentation des paramètres max_image_width et confidential_text
Documentation du format de greffon d'aide pour Eclipse et des paramètres de prise en charge
Version 1.5-0Fri Feb 26 2010Rüdiger Landmann
Documentation de l'option --config
Version 1.4-0Wed Feb 17 2010Jeff Fearn
Suppression de la référence obsolète au chemin vers les fichiers du catalogue DocBook. BZ#565498.
Documentation des options CVS
Version 1.3-0Mon Dec 7 2009Rüdiger Landmann
Ajout d'une entrée vers les FAQ à propos des erreurs concernant la mise en valeur du code
Ajout d'une section à propos des formats valides.
Mise à jour de la liste des auteurs.
Instructions d'installation spécifiques pour Ubuntu ; ajout des instructions d'installation pour Debian. BZ#542711
Métadonnées dans le fichier Book_Info.xml
Version 1.2-0Fri Nov 27 2009Jeff Fearn
Documentation de l'action lang_stats. BZ#540696.
Version 1.1-1Thu Nov 26 2009Jeff Fearn
Correction de documents erronés à propos des conditions d'utilisation. BZ#540691
Version 1.1-0Thu Oct 22 2009Rüdiger Landmann
Correction de diverses erreurs mineures et nettoyage général
Version 1.0-0Tue Oct 13 2009Rüdiger Landmann
Mise à jour pour Publican 1.0
Version 0.5-0Thu Dec 18 2008Jeff Fearn
Ajout d'une annexe à propos des paramètres du Makefile
Ajout d'une entrée dans les FAQ concernant l'espace du tas Java.
Version 0.4-0Tue Nov 25 2008Brian Forté
Ajout de la section « Pré-parution et brouillon de documentation ».
Version 0.3-0Fri Oct 10 2008Don Domingo
Ajout de la section « Marquage conditionnel »
Version 0.2-0Fri Sep 05 2008Brian Forté
Édition générale et mises à jour relatives à la parution 0.36 de Publican. Également, ajout d'un nouveau paragraphe dans le chapitre 3.3.
Version 0.1-1Fri Jun 06 2008Murray McAllister
Mise à jour des marques de fabrique pour noter l'ajout de oVirt et GIMP
Version 0.1-0Fri May 16 2008Jeff Fearn
Mise à jour des FAQ
Version 0.0-0Thu Dec 13 2007Murray McAllister
Parution du contenu initial