Introduction

Généralités sur le SGML

La norme SGML, ou langage normalisé de balisage généralisé ([8879]), a été créée par un groupe de recherche de l'ISO afin de faciliter les échanges de documents électroniques.

Il s'agit d'un méta-langage, un moyen de description d'une langue. Il définit des méthodes de représentation logique de textes électroniques indépendantes du système ou de la machine utilisée. Cette notation de balisage (étiquetage) permet la structuration de textes et facilite leur analyse en rendant explicite ce qui est implicite ou supposé. Toutes les conventions de notations de ce format sont décrites dans une grammaire formelle appelée DTD car une telle langue doit spécifier ce qui est autorisé, obligatoire et de quelle manière elle peut se distinguer du texte.

Le type de document

SGML soulève la notion de Définition du Type de Document (DTD). Le type d'un document est défini selon ses parties constituantes et leur structure. On peut définir un rapport comme étant un document comportant nécessairement un titre, un nom d'auteur suivis d'un résumé et une suite de paragraphes. Un document n'ayant pas de titre ou un document ayant une suite de paragraphes terminé par un résumé ne sera pas considéré comme étant un rapport.

Indépendance des données

Un des premiers buts de SGML est la transportabilité d'un document. Celui-ci ne doit perdre aucune information en changeant d'environnement système ou en passant d'un logiciel à un autre.

La séparation de la forme et du contenu

SGML est un format de description sémantique de texte. La description sémantique sépare clairement la forme du document de son contenu. SGML ne détermine pas la manière dont un document sera affiché ou imprimé, mais plutôt sa structure. En effet, l'utilisateur de SGML manipule un balisage pour décrire des parties de texte (par exemple pour indiquer qu'un mot est le nom d'une personne). La production d'un document imprimable ou consultable sur un écran est effectuée par un processus de compilation faisant intervenir des feuilles de style. Ces feuilles de style conditionnent l'aspect visuel final du document.

Concepts de SGML

La DTD

Le modèle de contenu d'un élément est le premier type de règles de construction donnant la structure d'un document SGML. Il représente une partie de la Définition du Type de Document (DTD). Lors de la création d'une DTD, il faut trouver un équilibre entre la définition de règles de construction simples et la complexité du texte. Il ne faut pas oublier que toute DTD est une interprétation du texte. Un texte peut être interprété par plusieurs DTDs.

Les éléments

La séparation entre le contenu textuel et la description de la structure du document est assuré par le biais d'une syntaxe particulière. SGML définit la notion d'élément, qui permettent de marquer et de structurer une partie du texte. Ces éléments sont nommés et possèdent une certaine signification. Ils sont compris entre les caractères « < » et « > ». Par exemple, l'élément article est représenté par la chaîne de caractères:

Exemple 1. Élément SGML

<article>

Les éléments SGML sont souvent utilisés par paires de deux éléments: un élément ouvrant et un élément fermant (un élément fermant est placé entre les caractères « < » et « > » et il est préfixé par un caractère « / », par exemple </article>). Le texte compris entre ces deux éléments est « contenu » par l'élément (nous dirons qu'il est compris dans le contexte de l'élement). Tous les éléments ne sont cependant pas nécessairement organisés par paires.

La DTD d'un document spécifie dans quel contexte chacun des éléments est valide. Ainsi, dans le cas d'AlcoveBook un élément appendix n'est valable que dans un contexte article, book ou part. De même, la DTD spécifie les éléments obligatoires dans un certain contexte. Par exemple, un élément listitem est obligatoire dans un contexte itemizedlist.

Astuce : Les éléments étant organisés de manière hiérarchique, nous suggérons d'utiliser la convention d'indentation suivante:

  • pour chaque niveau d'inclusion d'élément, indenter de deux caractères vers la droite ;

  • dans le cas d'un contenu non textuel, passer une ligne après chaque élément ouvrant et avant chaque élément fermant ;

  • les éléments comportant du contenu textuel ne doivent pas comporter d'espace ni de saut de ligne entre les éléments et le contenu.

Exemple 2. Exemple de mauvaise indentation

<section><title>Introduction</title>
<para>
        De tous temps, les hommes ont cherché à écrire des
introductions bateau.
</para>
</section>
	      

Exemple 3. Exemple d'indentation correcte

<section>
  <title>Introduction</title>
  <para>De tous temps, les hommes ont cherché à écrire des
    introductions bateau.</para>
</section>
	      

Les attributs

Les éléments peuvent posséder des attributs étendant leur signification. Par exemple, des attributs permettant d'identifier un élément (identificateur) ou de spécifier un de ses paramètres (la langue par exemple). Les attributs sont des données nommées et typées. Ils sont syntaxiquement compris dans un élément et sont de la forme « nom="valeur" ». Par exemple:

Exemple 4. Exemple de paramètre

<article lang="fr">

Les entités

Les entités SGML sont des chaînes de caractères nommées et interpolées lors de la transformation du document SGML en un produit publiable. On distingue plusieurs types d'entités, dont les entités « générales internes » et les « entités générales externes. »

Les entités générales internes font référence à un texte défini dans le document et interpolé à la transformation (comme c'est le cas pour une variable dans un langage de programmation).

Les entités générales externes font référence à un texte défini dans un fichier externe au document et sont interpolées par le contenu de ce fichier à la transformation. Cette technique permet d'insérer du contenu externe dans un document SGML, par exemple pour segmenter un document en chapitres.

Une entité est précédée d'un caractère « & » et terminée par un caractère « ; ». Par exemple:

Exemple 5. Exemple d'entité

&nbsp;

Le contenu textuel

Le contenu textuel est possible uniquement dans certains contextes. Ainsi, chaque élément d'un document SGML permet de contenir soit uniquement du contenu textuel, soit uniquement des éléments, soit les deux. Dans le cas d'AlcoveBook, les éléments pouvant contenir du texte sont par exemple para, title, constant, etc.

AlcoveBook ignore les espaces multiples et les transforme en un espace unique. De même, les sauts de ligne uniques sont ignorés. C'est aussi le cas des sauts de ligne. En revanche, nous recommandons de ne pas utiliser d'espaces ou de sauts de ligne superflus au début et à la fin des contextes textuels.

La spécificité d'AlcoveBook

AlcoveBook est un dérivé (subset) de DocBook. Il s'agit d'une version allégée de DocBook, conçue spécifiquement pour les besoins internes de documentation Alcôve. En tant que dérivé de DocBook, AlcoveBook est traitable directement par les outils de DocBook, mais peut fournir un document spécifique à Alcôve par les outils spécifiques AlcoveBook. Sur un système Debian GNU/Linux, le paquet à installer est le paquet alcovebook-sgml, disponible dans la source APT interne potato-alcove.