7. Résumé du guide des outils SGML

Par Matt Welsh. mis à jour par Greg Hankins. traduit et résumé par Jean-Daniel Dodin. Ce document est un résumé du guide d'utilisation des outils sgml, qui permettent de diffuser un même texte en plusieurs formats (html, TeX...) version des outils 0.99.0.

7.1 Introduction

Les SGML-Tools permettent d'écrire des textes et ensuite de les formater en multiples formats : groff, LaTeX, HTML, GNU info, LyX, et RTF.

Ce document

Ce document est écrit avec les outils SGML (bien sur!). Il contient tout ce qu'il faut savoir - et ce qui ne s'y trouve pas se trouve dans le guide complet (en anglais), disponible avec les outils.

Jeu de caractères ISO 8859-1

Le jeu de caractères ISO 8859-1 (latin1) peut (et doit, en français) être utilisé en texte pur, LaTeX, HTML, LyX, et RTF (GNU info peut-être un jour).

% sgml2txt -l bidule.sgml

Si j'ai bien compris, les instructions ci-dessus concernent ceux qui doivent écrire les caractères sous forme de code d'échappement dans le texte, sinon, si vous les entrez dans le texte source, ils seront automatiquement traduits quand ce sera nécessaire (utilisez la bibliothèque emacs iso-sgml.el).

7.2 Écrire avec les outils SGML

Le fichier example.sgml vous donne un exemple et un modèle. Imprimez le document pouvoir le comparer avec le source.

Concepts de base

Le source est composé de texte normal et de "balises" encadrées par < et >. Une balise indique simplement le début ou la fin d'un élément, comme une section, un paragraphe...

Par exemple, pour avoir ce texte en gras, j'ai tapé

Par exemple, pour avoir <bf>ce texte en gras</bf>,...

dans le source.

Il y a une forme abrégée :

Par exemple, pour avoir <bf/ce texte en gras/,...

La balise de fin est facultative dans certains cas, par exemple pour les sections.

Caractères spéciaux

Pour avoir dans un texte <bidule> (c'est à dire une balise bidule encadrée), Il faut taper < ce qui est une macro. J'ai donc tapé :

<tt>&lt;bidule></tt>.

Tout ce qui commence par un et commercial est en général une macro, comme % pour donner %, etc.

Les macros les plus courantes sont :

• & pour &,
• < pour <,
• > pour >,
• &etago; pour </
• $ pour $,
• # pour #,
• % pour %,
• ˜ pour ~,
• ``et '' pour guillemets simples, ou &dquot pour des doubles ". Sur un clavier français, les guillemets simples ouvrants (`) indiqués au début de cette phrase s'obtiennent en faisant alt 7 puis espace.

Environnements Verbatim et Code

L'élément verb permet de reproduire texto une partie de texte.

<verb>

Un peu de texte ordinaire

</verb>

L'environnement verb ne permet pas tout On doit faire dans l'environnement verb

• &ero; pour avoir un et commercial
• &etago; pour </,
• ne pas utiliser \end{verbatim} dans un environnement verb car c'est ainsi que LaTeX termine verbatim

L'environnement code ressemble à l'environnement verb sauf que des lignes horizontales sont ajoutées autour du texte, ainsi

Voici un exemple de code   

Vous devriez utiliser tscreen autour de verb :

<tscreen><verb>

Un peu de texte, pour voir

</verb></tscreen>

tscreen indente simplement le texte et règle la fonte de caractères sur tt.

L'environnement quote est comme tscreen, mais il ne modifie pas la fonte.

7.3 Structure générale des documents

Le préambule

<!doctype linuxdoc system>

<article>

<title>Linux Bidule HOWTO

<author>Norbert Ebersol, <tt/nob@baz.com/

<date>v1.0, 9 March 1994

<abstract>

This document describes how to use the <tt/bidule/ tools to frobnicate

bar libraries, using the <tt/xyzzy/ relinker.

</abstract>

<toc>

Sections et Paragraphes

Dans le document, les commandes suivantes sont disponibles:

• sect: Sections de premier niveau (c'est à dire 1, 2, etc.)
• sect1: Sous-sections de deuxième niveau (1.1, 1.2, etc.)
• sect2: troisième niveau
• sect3: quatrième niveau
• sect4: cinquième niveau

Après sect (ou sect1, sect2, etc.), vient le nom de la section

sect>Introduction

Le corps de la section doit commencer par <p>, ainsi :

<sect>Introduction

<p> Guide de l'utilisateur...

Pour signaler que vous avez terminé le titre. Ensuite, les paragraphes sont marqués par une ligne blanche.

Fin du premier paragraphe

Et début du suivant

Fin du document

À la fin du document, utiliser

</article>

7.4 Références croisées

Pour référencer une section,

<sect1>Introduction<label id="sec-intro">

Et s'y référer

Voir section <ref id="sec-intro" name="Introduction"> pour une introduction

Ceci remplace la balise ref par le numéro de section appelé sec-intro. L'argument name de ref est necessaire pour groff et HTML.

Par exemple, la présente section est Références croisées

Il y a aussi un élément url pour Universal Resource Locators, adresses web. Par exemple :

Vous pouvez trouver les documents HOWTO de Linux à <url url="http://sunsite.unc.edu/mdw/HOWTO/" name="The Linux HOWTO INDEX">.

L'argument url specifie l'URL elle-même. Un lien sera ajouté automatiquement. L'argument name est optionnel. Une variante est htmlurl, qui ne met en place l'URL qu'en mode html.

7.5 Fontes

Les fontes sont les mêmes que pour LaTeX, mais ne sont pas reproduites en sorties texte pur, il vaut donc mieux ne pas trop identifier de texte de cette façon. En particulier, la balise tt donne une fonte à chasse constante ''machine à écrire'', bf pour caractères gras et em pour italiques. Il vaut mieux éviter les autres, qui n'existent pas dans tous les formats.

7.6 Listes

• itemize Listes à puces comme celle-ci
• enum Listes numérotées
• descrip descriptions Chaque item dans itemize ou enum doit être marqué avec une balise item. Dans descrip la balise est particulière. Par exemple

<itemize>

<item>Premier item.

<item>Deuxième item.

</itemize>

Donne:

• Premier item.
• Deuxième item. Ou, avec enum,

<enum>

<item>Premier item.

<item>Deuxième item.

</enum>

Donne:

1. Premier item.
2. Deuxième item.

Une liste descrip est légèrement différente, et un peu laide, mais peut être utile:

<descrip>

<tag/Gnats./ Bestioles agaçantes qui se baladent dans votre ventilateur

<tag/Gnus./ Bestioles agaçantes qui se baladent dans votre processeur

</descrip>

Donne:

Gnats.

Bestioles agacantes qui se baladent dans votre ventilateur

Gnus.

Bestioles agacantes qui se baladent dans votre processeur

7.7 Vérifier la syntaxe SGML

% sgmlcheck bidule.sgml

7.8 Formater les documents SGML

Supposons que vous ayez le document bidule.sgml à formater, voici des exemples de méthode.

Texte pur sans accents

% sgml2txt bidule.sgml

Pages man, à formater avec groff -man

% sgml2txt -man bidule.sgml

Document LaTeX (fichier dvi seul)

% sgml2latex bidule.sgml

Sortie dvi, ps ou tex:

-p option:

% sgml2latex -o dvi bidule.sgml

% sgml2latex -o ps bidule.sgml

% sgml2latex -o tex bidule.sgml

Sortie imprimante (dvi + tex + toc + log)

% sgml2latex -dbidule.sgml

et ensuite

lpr bidule.dvi

Document HTML

% sgml2html -l -L french -t 2 bidule.sgml

Ceci va produire bidule.html, bidule-1.html, bidule-2.html, et ainsi de suite pour chaque section du document

Lisez bidule.html, le fichier de premier niveau avec votre navigateur, et vérifiez bien que tous les fichiers soient dans le même répertoire. Les documents HTML auront des boutons ``Previous'', ``Next'', and ``Contents'' pour la navigation. Pour avoir ces boutons en français, rajoutez -l french sur la ligne de commande.

Si vous voulez utiliser une image gif au lieu de texte pour les boutons, utilisez l'option sgml2html -img. Les fichiers gif sont dans /usr/lib/sgmltools/icons (si vous ne les trouvez pas là, regardez dans /usr/bin/sgml2*), ce sont des scripts perl et le répertoire est dans la variable $LibDir.

Document pour GNU Info

% sgml2info bidule.sgml

Documents LyX

% sgml2lyx bidule.sgml

Sorties RTF

% sgml2rtf bidule.sgml

Cela produira des sorties bidule.rtf, bidule-1.rtf, bidule-2.rtf, etc. Un fichier par section.

7.9 Informations supplémentaires

La version originale du guide contient d'autres conseils.

7.10 Utiliser LyX

LyX est un traitement de texte, sorte d'interface visuelle à LaTeX. Il a un mode sgml extrèmement efficace. Je n'utilise plus que ca !