Cette section décrit comme être au point pour écrire vos propres documents LDP. Récupérer et configurer les outils, prendre contact avec le LDP en général, et partager vos connaissances avec tous les utilisateurs de Linux.
Si vous êtes un nouvel auteur au sein du LDP, et que vous voulez prendre en main un HOWTO (ou un Mini-HOWTO) non maintenu ou en écrire un vous même, contactez le coordinateur du LDP à l'adresse ldp-discuss@lists.linuxdoc.org. Cela lui permet de savoir qui travaille sur quel document. Tous les HOWTO envoyés devront être au format SGML (basés sur la DTD LinuxDoc ou DocBook). Les mini-HOWTO pourront être aux formats SGML ou HTML, mais seuls les documents SGML seront inclus dans les versions imprimées des HOWTO.
Il y a quelques listes de discussion auxquelles vous pouvez vous abonner pour prendre part au fonctionnement du LDP. La première est ldp-discuss@lists.linuxdoc.org, qui est le principal lieu de discussion du LDP. Pour s'abonner, il suffit d'envoyer un message avec "subscribe" dans le champ du sujet à l'adresse mailto:ldp-discuss-request@lists.linuxdoc.org. Pour se désabonner, même adresse avec "unsubscribe" dans le champ sujet du message.
Récupérez le paquetage sgmltools depuis http://www.sgmltools.org/, ou directement depuis votre distribution. Les fichiers de sgmltools.org sont le code source de l'application, vous devrez donc les compiler pour votre machine. Utiliser un paquetage pré-compilé pour votre distribution est plus facile, puisque vous n'aurez pas à le compiler et éviterez les problèmes de compilation (sauf si vous êtes un programmeur).
Les outils sgmltools sont inclus dans la distribution RedHat. Si ce n'est pas le cas, vous pouvez le télécharger depuis le site ftp de RedHat ou un des sites miroirs.
Si vous utilisez une Debian, sgmltools est également inclus en standard. Dans le cas contraire, vous pourrez utiliser apt-get pour télécharger et installer le paquetage à votre place :
# apt-get install sgml-tools
Pour plus d'informations sur le paquetage Debian, regarder à l'adresse http://www.debian.org/Packages/stable/text/sgml-tools.html
Pour la compilation des sources, la marche à suivre est :
# tar -zxvf sgmltools-x.x.x.tar.gz # cd sgmltools-x.x.x # ./configure # make # make install
Remplacez sgmltools-x.x.x par la version du paquetage que
vous utilisez. A la date où j'écris ces lignes, la version qui
supporte LinuxDoc est la 1.0.9, et celle qui supporte DocBook est
2.0.2. Ces deux versions sont disponibles sur le site web déjà vu
ci-dessus.
Une fois les outils installés, vous avez plusieurs commandes à disposition.
sgmlcheck file.sgml - Vérifie la syntaxe du document
sgml2html file.sgml - Convertit un fichier SGML en
HTML. Le fichier file.html contiendra la table des matières,
les fichiers file-x.html contiendront les sections numérotées
x.
sgml2rtf file.sgml - Convertit un fichier SGML en deux
fichiers Rich Text Format (RTF). Le fichier file.rtf
contiendra la table des matières et file-0.rtf contiendra
toutes les sections.
sgml2txt file.sgml - Convertit un fichier SGML en texte
ASCII. La table des matières et les sections sont toutes dans le fichier
file.txt.
sgml2info file.sgml - Blah SGML blah INFO, utilisé par la
commande info. Tout est contenu dans file.info.
sgml2latex file.sgml - Blah SGML blah TeX.
sgml2lyx file.sgml - SGML converti pour l'éditeur
graphique LyX. Intéressant si vous avez généré un fichier SGML et
voulez le convertir pour l'utiliser avec LyX.
Tout comme le HTML, vous pourrez écrire du SGML à la main, une fois que vous connaîtrez toutes les balises dont vous aurez besoin. Vous trouverez ici une description pour la plupart des balises, avec des exemples d'utilisations. Le code source SGML de ce document, disponible sur le site web vu dans la section Introduction, est un bon exemple pour démarrer l'apprentissage. J'essairai de donner les indications sur les interprétations des balises dans les différents formats de conversion.
Pour commencer un nouveau document, créez un nouveau fichier avec votre éditeur ASCII favori et commencez comme ça :
<!doctype linuxdoc system>
Cela précise le type de document (LinuxDoc dans notre cas) que l'interprète SGML utilisera pour la conversion vers les autres formats. Cette balise ne génère aucun texte en elle même.
Ensuite vous devez entourez le reste de votre travail entre
<article> et </article>. Cela indique le
début du contenu (ou de l'article, eh?). Si vous connaissez HTML, ces
balises sont équivalentes aux balises <html> et
</html>
La première partie du document devrait inclure des informations générales à propos du contenu. Elle est similaire aux premières pages d'un livre qui contiennent le titre de l'ouvrage, l'auteur, la date de publication, la table des matières, etc.
Le titre est indiqué entre les balises <title> et
</title>. De même on utilise <date> et
</date> pour la date.
Les deux sections qui restent sont les balises <abstract> et
</abstract> qui donnent un résumé du document, et la
balise <toc> qui indique l'emplacement de la table des
matières. Celle ci est automatiquement générée par l'interprète
SGML. Nous reviendrons sur les sections plus tard.
Maintenant, à quoi tout cela ressemble-t-il ? En regardant le début du code source de ce document, vous trouverez : (NdT : voir la version originale)
<!doctype linuxdoc system> <!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <markk> Tue Dec 14 16:17:42 1999 --> <article> <title>HOWTO HOWTO </title> <author>Mark F. Komarinski <markk@cgipc.com> </author> <date>v1.1, 14 décembre 1999 </date> <abstract>List the tools, procedures, and hints to get HOWTO authors up to speed and writing. </abstract> <toc>
Cette partie du document est utilisée pour créer la page principale que vous voyez une fois convertie au format RTF ou HTML.
Pour générer la table des matières, il vous faut de quoi la construire. Les sections de SGML sont ce que les chapitres sont aux publications traditionnelles. Il peut y avoir plusieures sections, et chaque section peut avoir des sous-sections, qui peuvent elles aussi avoir des sous-sections etc.
Démarrer la rédaction de vos documents par les sections est une bonne idée puisque cela permet de dresser la liste des sujets que vous voulez traiter. Vous pouvez alors subdiviser ces sections principales en d'autres de plus en plus petites, jusqu'à ce que vous obteniez l'information pure que vous pourrez écrire en quelques paragraphes. J'ai moi même commencé ce document en utilisant cette méthode.
Les sections fait partie des quelques balises qui n'ont pas besoin
d'être fermées. Ainsi, il n'y a pas de balise
</sect>. Vous n'avez pas besoin non plus de vous occuper
de la numérotation des sections. L'interprète SGML s'en chargera lors
de la génération vers d'autres formats.
Les sections sont amorcées par la balise
<sect>. Chaque nouvelle section commence par
<sect>. La première est numérotée 1.
Les sous-sections (comme 1.1) se créent par la balise
<sect1>. Elles commencent aussi à 1.
Les sous-sous-sections (1.1.1) se créent par la balise
<sect2> et commencent aussi à 1.
Quand l'interprète SGML arrive à la balise <toc>, il
parcourt le reste du document et construit la table des matières à
partir des balises des sections qu'il rencontre. Les sections sont
numérotées et listées dans la table des matières et, bien sûr,
utilisées dans le reste du document. Les sous-sous-sections (1.1.1)
n'apparaissent pas dans la table des matières, mais sont mises en
valeur dans le texte si c'est possible.
L'écriture de paragraphes est la même qu'en HTML. Utilisez une
balise <p> pour indiquer une nouvelle ligne, et
commencez à écrire. SGML ignore les espaces tout comme les
tabulations, les espaces multiples et les sauts de lignes. Quand SGML
rencontre une balise <p>, il commence un nouveau
paragraphe. Un document SGML correct devrait contenir les balises
</p> pour finir les paragraphes.
Vous aurez besoin de différencié des parties de texte par rapport à
d'autres. Soit le mettre en valeur, soit pour donner un nom de
commande. Le premier de ces deux cas se résout par les balises
<em> et </em>. Quant au style machine à
écrire, on utilise les balises <tt> et
</tt>.
Il existe deux types de listes sous SGML. La première est la liste numérotée, où chaque item de la liste est numéroté (comme les sections), en commençant à 1.
Le code pour cette liste est le suivant :
<enum> <item>Voici la première entrée de la liste numérotée. <item>Voici la seconde. <item>Et la troisième. </enum>
La balise <enum> indique que les entrées qui la
suivent doivent être numérotées.
L'autre type de liste est la liste à items simple, où chaque entrée à une étoile, un cercle, ou un point, ou tout autre symbole pour indiquer chaque item.
Le code de la liste ressemble à ça en SGML :
<itemize> <item>Voici la première entrée de la liste à items. <item>Voici la seconde. <item>Et la troisième. </itemize>
Comme vous le voyez, la balise <item> est la même
pour les listes numérotées et les listes à items.
Une troisième forme de liste est la liste de définition. Elle comporte un terme à définir, et la phrase de définition.
Le Projet de Documentation Linux
Standard Generalized Markup Language
Le code qui permet de créer cette liste est :
<descript> <tag>LDP</tag>Le Projet de Documentation Linux <tag>SGML</tag>Standart Generalized Markup Language </descript>
Ce n'est pas tout à fait la même syntaxe que pour les listes à
items et numérotées, mais la liste est aussi entourée par des balises
(<descrip> et </descrip>) et chaque
item qui est un mot à définir est entouré par <tag> et
</tag>. Le reste de la ligne est alors considéré comme
la définition de ce dernier.
De temps en temps, on a besoin d'afficher du texte comme on
l'écrit. Pour cela, vous pouvez utiliser les balises
<verb> et </verb> pour entourer du texte
qui doit apparaître tel quel. Les espaces, les retours à la ligne, et
tout autre caractère spécial sont préservés jusqu`à la balise
</verb>.
Ceci est du texte verbatim. Et voici un autre texte verbatim.
SGML fournit de quoi utiliser des URL (Universal Resource Locators , NdT: sortes de pointeurs vers des ressources extérieures) de tous types. Cela ne sera utilisé que par les versions HTML, mais d'autres formats pourrait également y avoir recours. La meilleure utilisation en sera faite pas HTML, mais d'autres formats, tels que PDF, pourront aussi en tirer avantages.
Les URL n'ont pas de balise de terminaison, mais toutes les
informations sont contenues dans la balise <url>
elle-même. Voici un URL qui pointe vers la page du LDP :
http://www.linuxdoc.org/. Et
voici le code pour le créer :
<url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/">
La partie url="http://www.linuxdoc.org/"
donne la destination du pointeur, et la partie
name="http://www.linuxdoc.org/" indique au
navigateur ce qu'il doit afficher en réalité. Dans ce cas, les deux
parties sont identiques, mais on pourrait créer une balise url qui
ressemblerai à ça :
<url url="http://www.linuxdoc.org/" name="LDP">
Ce qui affichera ceci dans le texte : LDP. Toutefois, un bon principe consiste à dupliquer l'URL dans la partie name. La raison est que si vous utilisez un format du type texte ou RTF, ces balises n'auront pas de significations. Le lecteur ne connaîtra pas l'URL à utiliser.
Alors que les URL sont adaptés pour faire référence aux ressources
externes à votre document, ce n'est pas le cas pour les références au
sein du texte lui-même. Pour cela, les balises <label>
et <ref> sont préférables. La balise
<label> indique un endroit dans le document auquel vous
voudrez faire référence ailleurs dans le texte, comme un signet. La
création du <label> est simple. Insérez la ligne
suivante à l'endroit voulu :
<label> id="introduction">
Vous avez alors créé un point dans le texte auquel vous pourrez vous référer en tant que "introduction". En effet, cette balise est utilisée dans le document SGML que vous lisez. Quand vous voulez pointer vers cet endroit (comme ici), vous insérez le code SGML suivant :
<ref id="introduction" name="ici">
et SGML insérera le mot "ici" dans le texte qui sera un lien vers la section indiquée par le label "introduction".
L'autre utilisation des références est l'indexation. Puisque les documents du LDP sont souvent publiés sur papier sous forme d'un grand nombre de documents, les références servent à générer un index qui apparaîtra à la fin du livre, basé sur les mots et les sujets.
Tout comme pour HTML, vous devrez interdire l'interprétation de certains caractères non alphanumériques pour éviter que SGML les voit comme du code. Voici une liste des codes utilisés. Vous en trouverez d'avantage dans le Guide de l'utilisateur de sgmltools à l'adresse http://www.sgmltools.org/guide/guide.html
"
Je vais encore chanter les louanges pour LyX. Je favorise cette application car je l'apprécie vraiment. Il donne la possibilité d'écrire en SGML avec la facilité d'un traitement de texte standard. Ce n'est pas un programme WYSIWYG, mais plutôt une application WYSIWYM (What You See Is What You Mean, NdT: Ce que vous voyez est ce que vous pensez), puisque ce que vous voyez n'est pas forcement ce que vous obtiendrez une fois que l'interpréteur SGML aura fait son travail.
Pour créer un document LinuxDoc avec LyX, téléchargez et installez
l'application. Assurez-vous d'avoir déjà installé TeX et sgmltools
(voir
Télécharger et installer les outils pour
plus d'informations à ce propos). Ensuite, lancez LyX et sélectionnez
"file->new from template...". Cliquez sur
"Templates" et
sélectionnez linuxdoctemplate.lyx et vous obtiendrez un
document de base, avec tous les en-têtes d'information qu'un document
du LDP se doit d'avoir. Modifiez les données selon vos besoins (c'est
à dire compléter les champs Titre, Auteur, Date, Abstract, etc.) en
commencez la rédaction de votre document. Le menu dans le coin en haut
à gauche vous permet de sélectionner le type du texte (standard, liste
énumérées ou à items, sections). Le point d'exclamation est utilisé
pour mettre le texte en valeur, et vous pouvez soit cliquer dessus et
commencer à taper le texte, soit sélectionner du texte et cliquer
dessus pour mettre en valeur du texte déjà écrit. D'autres
spécificités de SGML peuvent être trouvées dans le menu
Insertion. Vous pouvez insérer des URL, des références, des entrées
d'index, et d'autres types de données. Une fois votre document
terminé, vous pouvez le sauvegarder au format LyX, et l'exporter au
format LinuxDoc et obtenir ainsi un fichier avec l'extension
.sgml. sgmlcheck peut alors vérifier ce fichier, qui est prêt à être
converti vers d'autres formats.
Emacs dispose d'un mode spécial pour écrire en SGML appelé psgml. Ceux qui ont une expérience de ce mode sont invités à donner des informations à l'auteur par courrier électronique. psgml est un module majeure pour Emacs conçu pour éditer des documents SGML et XML. Il permet une coloration syntaxique et un joli affichage qui font ressortir les balises SGML, il fournit une méthode dínsertion des balises sans les taper à la main, et est capable de valider la syntaxe de votre document lors de sa rédaction. Pour les utilisateurs d'Emacs, c'est un excellent outil. Je pense qu'il permet une plus grande versatilité que tout autre éditeur de code SGML. Il fonctionne aussi bien avec DocBook, LinuxDoc et d'autres DTD. La documentation psgml est disponible à http://www.lysator.liu.se/~lenst/about_psgml/.
S'il y a d'autres outils permettant d'utiliser la DTD LinuxDoc pour générer des documents du LDP, faites le moi savoir.
Le LDP est en train de mettre un place un accès CVS pour les auteurs. Il y a, en effet, de bonnes raisons d'utiliser CVS :
Si CVS est quelque chose de nouveau pour vous, voici quelques pages web qui pourront vous aider :
D'abord, il vous faudra obtenir un compte dans le repository CVS du LDP (NdT: lieu de stockage et de dépôt des documents pour CVS). C'est souvent le répertoire racine qui est utilisé par CVS, où chaque projet (HOWTO, Mini-HOWTO, ...) dispose d'un sous-répertoire.
Vous devrez créer un mot de passe crypté et un identifiant d'utilisateur pour votre compte. Ce mot de passe vous permet d'envoyer un mot de passe crypté au groupe CVS sans qu'ils aient besoin de connaître votre mot de passe. Vous pouvez le faire par les commandes suivantes, depuis un shell bash (ou sh) :
$ echo votre_mot_de_passe | perl -e "print crypt(<>, join
'',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"n\""
(NdT: je conseille un
; echosi vous exécutez ceci depuis un shell et que la réponse ne semble pas s'afficher)
Envoyez la sortie de cette commande avec l'identifiant d'utilisateur à cvsadmin@cvslist.linuxdoc.org. Votre CVSROOT unique sera créer et vous recevrez un e-mail avec la réponse.
Quand vous obtiendrez la réponse, connectez vous sur votre CVSROOT et vérifiez que tout est configuré correctement :
$ export CVSROOT=:pserver:your_userid@cvs.linuxdoc.org:/cvsroot $ cvs -d $CVSROOT login
(Remplacez CVSROOT par ce qui vous a été indiqué dans la réponse.)
On vous demandera votre mot de passe, et vous aurez accès au repository CVS en mode lecture-écriture. Une fois que vous aurez utilisé login et obtenu accès au système, votre mot de passe est stocké dans .cvsroot et vous n'aurez plus besoin d'utiliser cvs login. Positionner CVSROOT correctement et c'est parti.
Vous pouvez obtenir le repository linuxdoc en entier avec cette commande :
$cvs get linuxdoc
Ou vous pouvez obtenir le fichier source SGML de votre propre document par :
$ cvs get linuxdoc/src/VOTRE-HOWTO.sgml $ cvs get linuxdoc/minisrc/VOTREDOC.sgml
Une liste des changements est également disponible. C'est un e-mail envoyé à chaque changement dans le repository. Remarquez que celà peut devenir une liste à très grand débit. Vous pouvez vous y abonner en envoyant un e-mail vide à commits-subscribe@cvslist.linuxdoc.org. Vous pouvez annuler votre abonnement en envoyant un e-mail vide à commits-unsubscribe@cvslist.linuxdoc.org .
L'accès CVS anonyme (en lecture seule) est disponible par :
$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Utilisez "cvs" comme mot de passe. Vous pouvez alors accèder aux modules linuxdoc comme décrit ci-dessus. Notez que les changement apparaissent sur le site cvs anonyme environ une demi-heure après le site principal.
Vous pouvez accèder au repository CVS par le web à l'adresse http://cvsweb.linuxdoc.org/index.cgi/linuxdoc.
Il existe des interfaces graphiques pour CVS, et vous en trouverz une liste sur le site http://freshmeat.net/appindex/. Cherchez CVS.
CVS reconnait une balise spéciale que vous pouvez utiliser pour insérer la date et la version automatiquement dans votre document. C'est la balise $Id$. En mettant cette balise dans la section <date> (par exemple), elle sera modifiée à chaque changement du document, permettant une incrémentation automatique de la version.
Quand vous voulez copier votre fichier modifié sur le serveur CVS,
utilisez la commande cvs ci -m "commentaires" YOUR-HOWTO.sgml. Le
paramètre -m "commentaires" n'est pas obligatoire, mais si vous ne
le mettez pas, vous serez ammené dans votre éditeur (certainement vi,
ou l'éditeur indiqué par la variable d'environnement EDITOR) et devrez
taper un commentaire à propos des changements. Si vous décidez
d'utiliser un éditeur plutôt que de spécifier le commentaire sur la
ligne de commande, il se peut qu'il faille quelques (plus de 5)
secondes pour finir ce qu'il y avait à faire et effectuer la mise à
jour.
Vous pouvez suivre toutes les discussions à propos de CVS sur la liste ldp-discuss. Pour l'instant, les soumissions LDP doivent toujours être envoyées à ldp-submit.