diff --git a/fr_FR.ISO8859-1/articles/committers-guide/Makefile b/fr_FR.ISO8859-1/articles/committers-guide/Makefile index 0d3f683af0..72c1d9b8c9 100644 --- a/fr_FR.ISO8859-1/articles/committers-guide/Makefile +++ b/fr_FR.ISO8859-1/articles/committers-guide/Makefile @@ -1,20 +1,20 @@ # # The FreeBSD Documentation Project # The FreeBSD French Documentation Project # -# $Id: Makefile,v 1.1 2000-05-25 16:27:48 gioria Exp $ +# $FreeBSD$ # Original revision: 1.4 # DOC?= article FORMATS?= html INSTALL_COMPRESSED?=gz INSTALL_ONLY_COMPRESSED?= SRCS= article.sgml DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/fr_FR.ISO8859-1/books/fdp-primer/Makefile b/fr_FR.ISO8859-1/books/fdp-primer/Makefile index c0e962b1db..e052115a8b 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/Makefile +++ b/fr_FR.ISO8859-1/books/fdp-primer/Makefile @@ -1,47 +1,47 @@ # # The FreeBSD Documentation Project # The FreeBSD French Documentation Project # # Compilation de l'Introduction au Projet de Documentation de FreeBSD # -# $Id: Makefile,v 1.1 2000-06-12 15:46:26 gioria Exp $ +# $FreeBSD$ # Original revision: 1.6 # MAINTAINER=nik@FreeBSD.ORG DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # # SRCS lists the individual SGML files that make up the document. Changes # to any of these files will force a rebuild # # SGML content SRCS= book.sgml SRCS+= overview/chapter.sgml SRCS+= psgml-mode/chapter.sgml SRCS+= see-also/chapter.sgml SRCS+= sgml-markup/chapter.sgml SRCS+= sgml-primer/chapter.sgml SRCS+= stylesheets/chapter.sgml SRCS+= the-faq/chapter.sgml SRCS+= the-handbook/chapter.sgml SRCS+= the-website/chapter.sgml SRCS+= tools/chapter.sgml SRCS+= translations/chapter.sgml SRCS+= writing-style/chapter.sgml # Entities SRCS+= chapters.ent SRCS+= ../handbook/mailing-lists.ent SRCS+= ../../../en_US.ISO_8859-1/books/handbook/authors.ent DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/fr_FR.ISO8859-1/books/fdp-primer/book.sgml b/fr_FR.ISO8859-1/books/fdp-primer/book.sgml index 38dbc8c38c..c251c1e636 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/book.sgml +++ b/fr_FR.ISO8859-1/books/fdp-primer/book.sgml @@ -1,303 +1,303 @@ %man; %urls; %bookinfo; %translators; %chapters; %authors; %mailing-lists; ]> Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants Nik Clayton
nik@FreeBSD.ORG
 1998 1999 Nik Clayton - $Date: 2000-06-12 15:46:26 $ + $Date: 2000-11-10 12:30:58 $ - $Id: book.sgml,v 1.1 2000-06-12 15:46:26 gioria Exp $ + $Id: book.sgml,v 1.2 2000-11-10 12:30:58 kuriyama Exp $ La redistribution et l'utilisation du code source (SGML), et compilé (HTML, PostScript, etc.), modifiés ou non, sont soumises aux conditions suivantes : Le code source (SGML DocBook) distribué doit conserver le copyright ci-dessus, la présente liste de conditions et l'avertissement qui la suit, sans modifications, en tête de ce fichier. Le code source distribué sous forme compilé (transformation vers d'autres DTDs, conversion en PDF, PostScript, RTF et autres formats) doit faire apparaître dans la documentation et/ou les autres composants distribués, le copyright ci-dessus, la présente liste de conditions et l'avertissement qui la suit. CE DOCUMENT EST FOURNI PAR NIK CLAYTON “TEL QUEL” ET AUCUNE GARANTIE EXPRESSE OU IMPLICITE, Y COMPRIS, MAIS NON LIMITÉE, GARANTIES IMPLICITES DE COMMERCIABILITÉ ET D'ADÉQUATION À UN BUT PARTICULIER N'EST DONNÉE. EN AUCUN CAS NIK CLAYTON NE SAURAIT ÊTRE TENU RESPONSABLE DES DOMMAGES DIRECTS, INDIRECTS, ACCIDENTELS, SPÉCIAUX, EXEMPLAIRES OU CONSÉQUENTS (Y COMPRIS, MAIS SANS LIMITATION, LA FOURNITURE DE BIENS ET SERVICES ANNEXES  DÉFAUT D'UTILISABILITÉ, PERTE DE DONNÉES OU DE PROFITS ; OU INTERRUPTION DE TRAVAIL) QUELLE QU'EN SOIT LA CAUSE ET SELON TOUTE DÉFINITION DE RESPONSABILITÉ, SOIT PAR CONTRAT, RESPONSABILITÉ STRICTE, OU PRÉJUDICE (Y COMPRIS NÉGLIGENCE OU AUTRES) IMPUTABLES D'UNE FAÇON OU D'UNE AUTRE À L'UTILISATION DE CE DOCUMENT, MÊME APRES AVOIR ÉTÉ AVISÉ DE LA POSSIBILITÉ DE TELS DOMMAGES. Merci de votre participation au Projet de Documentation de FreeBSD. Votre contribution est très utile. Cette introduction décrit tout ce que vous devez savoir pour commencer à participer au projet de documentation de FreeBSD, des outils et logiciels que vous utiliserez (indispensables et facultatifs) à la philosophie sous-jacente au Projet de Documentation. Ce document est en cours de rédaction et n'est pas terminé. Les sections inachevées sont indiquées par un astérisque - * - qui précède leur nom. &trans.a.haby; Préface Invites de l'interpréteur de commandes La table ci-dessous donne les invites par défaut du système pour un utilisateur normal et pour le super-utilisateur. Elles sont utilisées dans les exemples pour indiquer quel utilisateur doit appliquer l'exemple. Utilisateur Invite Utilisateur normal &prompt.user; root &prompt.root; Conventions Typographiques La table ci-dessous décrit les conventions typographiques utilisées dans le présent ouvrage. Signification Exemples Noms de commandes, fichiers et répertoires. Affichage à l'écran de l'ordinateur. Modifiez votre fichier .login.Utilisez ls -a pour avoir la liste de tous les fichiers.Vous avez reçu du courrier. Ce que vous tapez, par opposition à ce que l'ordinateur affiche. &prompt.user; su Password: Références aux pages de manuel Utilisez su 1 pour changer de nom d'utilisateur. Noms d'utilisateurs et de groupes Seul root peut le faire. Mise en valeur Vous devez le faire. Variables sur la ligne de commande ; à remplacer par le nom ou la valeur effectif. Pour supprimer un fichier, tapez rm nom_du_fichier. Variables d'environnement $HOME est votre répertoire utilisateur. Notes, avertissements et exemples Dans le cours du texte, il peut y avoir des notes, des avertissements et des exemples. Les notes apparaissent comme ceci, et contiennent des informations que vous devriez prendre en considération, parce qu'elles peuvent avoir une incidence sur ce que vous faites. Les avertissements apparaissent comme ceci, et vous préviennent de problèmes potentiels si vous n'appliquez pas ces instructions. Des dégats peuvent être causés à votre matériel, ou ne pas être physiques, suppression inopinée de fichiers importants par exemple. Un exemple d'exemple Les exemples apparaissent comme ceci, et sont généralement des exemples que vous devriez tester ou qui vous montrent quels doivent être les résultats d'une opération donnée. Remerciements Mes remerciements à Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn et Christopher Maden, qui ont pris le temps de lire les premières versions de ce document et ont apporté de nombreux commentaires et critiques utiles. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; &chap.the-faq; &chap.the-handbook; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; diff --git a/fr_FR.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/fr_FR.ISO8859-1/books/fdp-primer/overview/chapter.sgml index 81cbc4421e..bb2316cc55 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ b/fr_FR.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,187 +1,187 @@ Introduction Bienvenue au Projet de Documentation de FreeBSD. Une documentation de bonne qualité est un facteur important de succès pour FreeBSD, et le Projet de Documentation de FreeBSD - “The FreeBSD Documentation Project” -  est la source d'une grande part de cette documentation. Votre participation est importante. L'objectif principal de ce document est d'expliquer clairement comment est organisé le FDP, comment écrire et soumettre de la documentation au FDP et comment utiliser les outils disponibles pour produire de la documentation. La participation de chacun au FDP est bienvenue. Il n'y a pas de cotisation minimum, pas de quota de documentation à produire par mois. Il vous suffit de vous inscrire sur la &a.doc;. Après avoir lu ce document, vous : Saurez quelles sont les documentations maintenues par le FDP. Serez capable de lire et comprendre le code SGML source des documentations maintenues par le FDP. Serez capable de modifier la documentation. Saurez comment soumettre vos modifications pour qu'elles soient revues et incorporées à la documentation de FreeBSD. Le jeu de documentations de FreeBSD Le FDP a la responsabilité de quatre catégories de documents. Les pages de manuel Les pages de manuel système en anglais ne sont pas rédigées par le FDP, puisqu'elles font partie du système de base. Le FDP, néanmoins, peut (et a) récrit des pages de manuel existantes pour les clarifier ou corriger des inexactitudes. Les équipes de traductions sont responsables de la traduction des pages de manuel dans les différentes langues. Ces traductions sont archivées par le FDP. FAQ L'objectif de la FAQ est de répondre (sous forme de courtes questions/réponses) aux questions qui sont posées, ou devraient être posées, sur les différentes listes de diffusion et forums de discussion consacrées à FreeBSD. Son format n'autorise pas de réponses longues et exhaustives. Manuel de référence - “Handbook” Le Manuel cherche à être la ressource en ligne exhaustive et de référence pour les utilisateurs de FreeBSD. Le site Web C'est le point de présence central de FreeBSD sur le World Wide Web, dont le site principal est http://www.freebsd.org/ et qui a de nombreux sites miroirs dans le monde. Pour beaucoup de gens, ce site est leur première rencontre avec FreeBSD. Ces quatres catégories de documentation sont disponibles dans les archives CVS de FreeBSD. Ce qui signifie que les modifications et les notifications sont accessibles à tous, et que chacun peut utiliser un programme comme CVSup ou CTM pour maintenir à jour son propre exemplaire local. En plus de ces documents, de nombreuses personnes ont écrit des guides ou réalisé des sites Web se rapportant à FreeBSD. Certains sont aussi archivés dans l'arborescence CVS (quand l'auteur a donné son accord). Dans d'autre cas, l'auteur a choisi de conserver ses documentations en dehors des archives FreeBSD. Le FDP essaie de donner le maximum de liens possible sur ces documents. Avant de commencer Ce document fait l'hypothèse que vous savez déjà : Vous procurer et tenir à jour une copie locale de la documentation. Soit en maintenant une copie locale des archives CVS de FreeBSD (avec CVS, CVSup ou CTM), ou en vous servant de CVSup pour ne télécharger que la version extraite - courante. Comment télécharger et installer de nouveaux logiciels en vous servant soit du catalogue des logiciels de FreeBSD soit de &man.pkg.add.1;. diff --git a/fr_FR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/fr_FR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml index 29422c6417..77184dc686 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/fr_FR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -1,1645 +1,1645 @@ Introduction à SGML La majorité des documentations du FDP utilisent SGML. Ce chapitre vous explique ce que cela signifie exactement, comment lire et comprendre le source de la documentation et décrit la façon d'utiliser le SGML que vous recontrerez dans la documentation. Des parties de cette section se sont inspirées du livre de Mark Galassi, “Get Going With DocBook”. Introduction Il était autrefois facile de travailler sur des documents électroniques. Vous n'aviez normalement à connaître que le jeu de caractères utilisé (ASCII, EBCDIC, ou l'un des nombreux autres) et c'était à peu près tout. Le texte était du texte, et vous voyiez vraiment ce que vous obteniez. Pas de sophistication, pas de formatage, pas d'intelligence. Cela devint inévitablement insuffisant. Une fois que vous avez du texte qu'une machine peut lire, vous vous attendez à ce que la machine puisse l'utiliser et le manipuler intelligemment. Vous aimeriez pouvoir préciser que certaines phrases sont accentuées, y ajouter un glossaire ou des hyper-liens. Vous voulez que les noms de fichiers apparaissent en police “machine à écrire” à l'écran et en italique à l'impression, et tout un tas d'autres options de présentation encore. Il fut un temps où l'on pensait que l'Intelligence Artificielle (IA) rendrait cela facile. Votre ordinateur pourrait lire le document et identifier les phrases clés, les noms de fichiers, le texte que l'utilisateur devait taper, et d'autres encore. Malheureusement, la réalité est un peu différente, et il faut aider nos ordinateurs à manipuler intelligemment notre texte. Plus précisement, il faut les aider à indentifier ce qui est quoi. Vous et moi, à la vue de :
Pour effacer /tmp/foo, utilisez &man.rm.1; : &prompt.user; rm /tmp/foo
distinguons facilement ce qui est nom de fichier, commande à taper, référence aux pages de manuel, et ainsi de suite. Mais l'ordinateur lui ne le peut pas. Pour cela, Nous avons besoin des marques. Le “marquage” est communément qualifié de “valeur ajoutée” ou “coût augmenté”. Le terme prend ces deux sens quand il s'applique au texte. La marquage est du texte en supplément dans le document, distinct par un moyen ou un autre du contenu du document, de façon à ce que les programmes qui traitent le document puisse le lire et l'utiliser pour prendre des décisions. Les éditeurs peuvent masquer le marquage à l'utilisateur, de façon à ce qu'il ne soit pas perturbé par ces marques. L'information supplémentaire donnée avec les marques ajoute de la valeur au document. Le marquage doit habituellement être manuel - après tout, si les ordinateurs pouvait analyser suffisamment le texte pour ajouter les marques, il n'y en aurait alors en fait pas besoin. Cela augment le coût du document. L'exemple précédent est codé comme suit dans le présent document : Pour effacer /tmp/foo, utilisez &man.rm.1;. rm /tmp/foo]]> Comme vous pouvez le constater, le marquage est clairement séparé du contenu. Bien évidemment, si vous devez utiliser des marques, vous devrez définir ce que les marques veulent dire et comment elles doivent être traitées. Il vous faudra un language de marquage auquel vous référer pour marquer vos documents. Un seul language de marquage peut bien sûr ne pas suffire. Les besoins de marquage d'une documentation technique diffèrent énormément de ceux de recettes de cuisines. ces derniers seront à leur tour différents de ceux d'un language de marquage pour de la poésie. Vous avez en fait besoin d'un language qui vous permette de définir ces autres languages de marquage. Un méta-language de marquage. C'est exactement ce qu'est Standard Generalised Markup Language (SGML) - Language de Marquage Standard Généralisé. De nombreux languages de marquage sont écrits en SGML, dont les deux languages les plus utilisés par le FDP, HTML et DocBook. Chaque définition d'un language s'appelle plus exactement une Document Type Definition (DTD) - Définition de Type de Document. La DTD définit les noms des éléments utilisables, leur ordre d'apparition (et leur hiérarchie) et les informations qui s'y rapportent. Une DTD est parfois désignée comme une application de SGML. Une DTD est une spécification complète de tous les éléments autorisés, de l'ordre dans lequel ils doivent être utilisés, quels sont ceux qui sont obligatoires, quels sont ceux qui sont facultatifs, et ainsi de suite. Il est alors possible d'écrire un analyseur qui lise et la DTD et le document qui prétend s'y conformer. L'analyseur peut alors vérifier si tous les éléments requis sont bien présents dans l'ordre voulu dans le document et s'il y a des erreurs dans le marquage. On appelle habituellement cela valider le document. Ce traitement ne valide uniquement que le choix des éléments, leur ordre, et ainsi de suite, se conforme à ce que définit la DTD. Il ne vérifie pas que vous avez utilisé les marques appropriées au document. Si vous marquez tous les noms de fichiers de votre document comme des noms de fonctions, l'analyseur ne le signalera pas comme une erreur (en supposant, bien sûr, que votre DTD définisse des éléments pour les noms de fichiers et de fonctions et qu'ils aient le droit d'apparaître aux mêmes endroits). Il est probable que vos contributions au Projet de Documentation consiste en documents marqués soit en HTML soit en DocBook, plutôt qu'en modifications aux DTDs. Pour cette raison, cet ouvrage n'abordera pas la façon d'écrire une DTD. Eléments, marques et attributs Toutes les DTDs écrites en HTML ont des caractéristiques communes. Ce n'est guère surprenant comme le montre inévitablement la philosophie qui sous-tend SGML. Une des manifestations les plus visibles de cette philosophie est la caractérisation en contenu et éléments. Votre documentation (que ce soit une seule page Web ou un ouvrage volumineux) est vue comme étant un contenu. Ce contenu est alors divisé (et ensuite subdivisé) en éléments. L'objectif de l'ajout de marques est de nommer et de définir le début et la fin de ces éléments pour traitement ultérieur. Considérez par exemple un livre type. Au plus haut niveau, ce livre lui-même est un élément. Cet élément “livre” contient évidemment des chapitres, qui peuvent aussi être légitimement considérés comme des éléments. Chaque chapitre contiendra à son tour des éléments, tels que des paragraphes, des citations et de notes de bas de page. Chaque paragraphe peut lui-même contenir encore des éléments, pour identifier le texte parlé par exemple, ou les noms des personnages de l'histoire. Vous pouvez si vous le voulez voir cela comme un “morcelement” du contenu. A la racine, vous avez un morceau, le livre. Un niveau en dessous, vous avez plus de morceaux, les chapitres individuels. Ils sont à leur tour morcelés en pargraphes, notes de bas de page, noms des personnages, et ainsi de suite. Remarquez que vous pouvez différencier les éléments sans utiliser la terminologie SGML. C'est vraiment immédiat. Vous pouvez le faire avec un surligneur et un livre imprimé, en utilisant des couleurs différentes pour chaque type d'élément. Nous n'avons bien sûr pas de surligneur électronique, il nous faut donc un autre moyen d'indiquer à quel élément appartient chaque morceau du contenu. Dans les languages écrits avec SGML ,(HTML, DocBook, et al.), cela se fait avec des marques. Une marque sert à dire où commence et où finit un élément. La marque ne fait pas partie de l'élément lui-même. Comme chaque DTD est habituellement écrite pour marquer des types d'informations spécifiques, chacune reconnaîtra des éléments différents, et aura donc des noms différents pour les marques. Pour un élément appelé nom-de-l'élément, la marque de début sera normalement <nom-de-l'élément>. La marque de fin correspondante sera </nom-de-l'élément>. Utiliser un élément (marques de début et de fin) HTML dispose d'un élément pour indiquer que le contenu inclus est un paragraphe, appelé p. Cet élément a une marque de début et une de fin. C'est un paragraphe. Il commence avec la marque de début pour l'élément 'p', et se terminera avec la marque de fin pour l'élément 'p'

C'est un autre paragraphe. Mais il est beaucoup plus court.

]]> Tous les éléments n'ont pas besoin d'une marque de fin. Certains n'ont pas de contenu. En HTML, par exemple, vous pouvez indiquer que vous voulez avoir une ligne horizontal dans votre document. Cette ligne n'a bien sûr aucun contenu, vous n'avez donc besoin que de la marque de début pour cet élément. Utiliser un élément (marque de début uniquement) HTML dispose d'un élément pour inclure une ligne horizontale, appelé hr. C'est un élément sans contenu, il n'a donc qu'une marque de début. C'est un paragraphe.

C'est un autre paragraphe. Une ligne horizontale le sépare du précédent.

]]> Si ce n'était pas encore clair, les éléments peuvent contenir d'autres éléments. Dans l'exemple du livre plus haut, ce livre contenait tous les chapitres, qui à leur tour contenaient tous les paragraphes, et ainsi de suite. Eléments dans des éléments ; <sgmltag>em</sgmltag> C'est un paragraphe simple où certains mots ont été mis en valeur.

]]> La DTD définira les règles qui disent quels éléments peuvent être inclus dans quels autres éléments, et ce qu'ils peuvent précisement contenir. Les gens confondent souvent marques et éléments comme si c'étaient des termes interchangeables. Ce n'est pas le cas. Un élément est une partie de la structure d'un document. Un élément a un début et une fin. Les marques définissent où commence et où finit le document. Quand le présent document (ou quelqu'un d'autre qui connait le SGML) parle de la marque “the <p> tag”, cela se rapporte au texte composé des trois caractères <, p et >. Mais la phrase “l'élément <p>” désigne tout l'élément. Cette distinction est très subtile. Mais gardez la à l'esprit. Les éléments peuvent avoir des attributs. Un attribut a un nom et une valeur, et sert à donner des informations supplémentaires concernant l'élément. Ce peuvent être des informations qui précisent comment l'élément doit être formaté, ou un identifiant unique pour cette occurrence de l'élément, ou autre chose encore. Les attributs d'un élément sont donnés dans la marque de début de l'élément et ont la forme nom-de-l'attribut="valeur-de-l'attribut". Dans les versions récentes d'HTML, l'élément p a un attribut appelé align, qui suggère un alignement (justification) du paragraphe au programme affichant l'HTML. L'attribut align peut prendre l'une des quatre valeurs prédéfinies, left, center, right et justify. Si l'attribut n'est pas précise, la valeur par défaut est left. Utiliser un élément avec un attribut L'attribut align est superflus pour ce paragraphe, puisque 'left' est la valeur par défaut.

Ce paragraphe sera peut-être centré.

]]> Certains attributs ne prennent que des valeurs prédéfinies, comme left ou justify. D'autres peuvent prendre les valeurs que vous voulez. Si vous avez besoin de quotes (") dans un attribut, mettez la valeur de l'attribut entre simples quotes. Simples quotes dans un attribut Je suis à droite !

]]> Vous n'avez pas toujours besoin de mettre la valeur de l'attribut entre simples quotes. Les régles à ce sujet sont cependant subtiles, et il est beaucoup plus simple de toujours mettre entre simples quotes les valeurs des attributs. A faire… Pour tester les exemples donnés dans ce document, vous devrez installer des logiciels sur votre système et vérifiez qu'une variable d'environnement est correctement définie. Téléchargez et installez textproc/docproj du catalogue des logiciels portés de FreeBSD. C'est un méta-port qui doit télécharger et installer tous les programmes et fichiers utilisés par le Projet de Documentation. Ajoutez les lignes pour définir SGML_CATALOG_FILES à vos procédures d'initialisation de l'interpréteur de commandes. <filename>.profile</filename>, pour les utilisateurs de &man.sh.1; et &man.bash.1; SGML_ROOT=/usr/local/share/sgml SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES <filename>.login</filename>, pour les utilisateurs de &man.csh.1; et &man.tcsh.1; setenv SGML_ROOT /usr/local/share/sgml setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES Déconnectez-vous et reconnectez-vous ensuite, ou exécutez ces commandes pour définir la variable d'environnement. Créez un fichier exemple.sgml, où vous mettrez : Exemple de fichier HTML

C'est un paragraphe avec du texte.

C'est encore un paragraphe avec du texte.

Ce paragraphe sera peut-être justifié à droite.

]]> Essayez de le valider avec un analyseur syntaxique SGML. L'analyseur syntaxique &man.nsgmls.1; fait partie de textproc/docproj. &man.nsgmls.1; lit normalement un document marqué en utilisant une DTD SGML et génère l'Element Structure Information Set (ESIS) - Informations sur la Structuration en Eléments - mais cela ne nous concerne pas pour le moment. Néanmoins, avec le paramètre , &man.nsgmls.1; ne génère rien mais affiche simplement les messages d'erreurs éventuels. C'est utile pour vérifier si votre document est correct ou non. Utilisez &man.nsgmls.1; pour vérifier si votre document est valide : &prompt.user; nsgmls -s example.sgml Vous constaterez que &man.nsgmls.1; n'affiche rien. Cela signifie qu'il a validé votre document. Voyez ce qui ce passe si vous oubliez un élément requis. Supprimez les marques title et /title et relancer la validation. &prompt.user; nsgmls -s example.sgml nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished Les messages d'erreur de &man.nsgmls.1; sont structurés en colonnes séparés par des deux-points ou des points-virgules. Colonne Signification 1 Nom du programme qui a généré l'erreur. Ce sera toujours nsgmls. 2 Nom du fichier où se trouve l'erreur. 3 Numéro de la ligne où se trouve l'erreur. 4 Numéro de la colonne où se trouve l'erreur. 5 Une lettre donnant le type de message d'erreur. I pour un message d'information, W pour un message d'avertissement, E pour un message d'erreur et X pour les références croisées. (Ce n'est cependant pas toujours la cinquième colonne. nsgmls -sv affiche nsgmls:I: SP version "1.3" - selon la version installée. Comme vous pouvez le constater, c'est un message d'information.) Vous voyez donc que nous avons dans notre exemple des messages d'erreurs. 6 Le texte du message d'erreur. Vous aurez plus d'informations sur les erreurs de &man.nsgmls.1; dans la Unofficial 'Kindler, Gentler HTML Validator' FAQ. Ne pas mettre les marques title a généré 2 erreurs différentes. La première erreur indique que l'analyseur SGML a rencontré un contenu (ici, des caractères, au lieu d'une marque de début d'élément) alors qu'il attendait autre chose. Dans le cas présent, l'analyseur attendait une marque de début pour un élément valide à l'intérieur de head (title par exemple). La deuxième erreur est due au fait que les éléments head doivent contenir un élément title. &man.nsgmls.1; considère alors que l'élément n'est pas complet. La marque de fin indique donc que l'élément se termine alors qu'il n'est pas correctement renseigné. Remettez l'élément title en place. La déclaration DOCTYPE Au début de chaque document que vous rédigez, vous devez préciser le nom de la DTD à laquelle le document se conforme. Cela pour que les analyseurs syntaxiques SGML la connaissent et puissent valider le document. Cette information est habituellement donnée sur une seule ligne, dans la déclaration DOCTYPE. Voici une déclaration typique pour un document conforme à la version 4.0 de la DTD HTML : ]]> Cette ligne a plusieurs composants distincts : <! C'est l'indicateur qui dit que c'est une déclaration SGML. Cette ligne définit le type de document. DOCTYPE Précise que c'est la déclaration SGML du type de document. html Définit le premier élément qui apparaîtra dans le document. PUBLIC "-//W3C//DTD HTML 4.0//EN" Donne le Formal Public Identifier (FPI) - Identifiant Public Officiel - de la DTD à laquelle le document se conforme. PUBLIC n'appartient pas au FPI, mais indique au processeur SGML comment trouver la DTD référencée par le FPI. Les autres façons de dire à l'analyseur SGML comment trouver la DTD sont données plus loin. > Retour au document. <foreignphrase>Formal Public Identifiers (FPIs)</foreignphrase> - Identifiants Publics Officiels Vous n'avez pas besoin de connaître ce qui suit, mais ce n'est n'est pas inutile, et cela peut vous aider à résoudre des problèmes, si votre processeur SGML ne trouve pas la DTD que vous utilisez. Les FPIs doivent respecter une syntaxe précise. La voici : "Propriétaire//Mot-Clé Description//Langue" Propriétaire Indique qui détient le FPI. Si la chaîne de caractères commence par “ISO”, c'est un FPI ISO. Par exemple, le FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" donne ISO 8879:1986 comme propriétaire du jeu d'entités pour les lettres grecques. ISO 8879:1986 est le numéro ISO du standard SGML. Sinon, cette chaîne sera de la forme -//Propriétaire ou +//Propriétaire (remarquez que la seule différence est le + ou - du début). Si la chaîne commence par un -, c'est que le propriétaire n'est pas enregistré, il l'est si elle commence par un +. L'ISO 9070:1991 définit comment sont générés les noms enregistrés ; ils peuvent dériver du numéro d'une publication ISO, d'un code ISBN ou d'un code d'organisation affecté selon l'ISO 6523. De plus, il pourrait y avoir une autorité d'enregistrement pour l'affectation de ces noms. Le conseil ISO a délégué cela à l'American National Standards Institute (ANSI) - Institut National Américain des Standards. Comme le Projet FreeBSD n'est pas enregistré, la chaîne utilisée est -//FreeBSD. Comme vous pouvez vous en rendre compte, le W3C n'est pas non plus un propriétaire enregistré. Mot-Clé Il y a plusieurs mots-clés qui définissent le type d'information dans le fichier. Les mots-clés les plus courants sont : DTD, ELEMENT, ENTITIES et TEXT. DTD ne sert que pour les DTD, ELEMENT sert habituellement pour les extraits de DTD qui ne contiennent que des entités ou des déclarations d'éléments. TEXT sert pour le contenu SGML (texte et marques). Description La description que vous souhaitez donner du contenu du fichier. Cela peut inclure des numéros de version et n'importe quel texte court qui ait un sens et soit unique au système SGML. Langue C'est une code ISO de deux caractères qui identifie la langue utilisée dans le fichier. Pour l'anglais, c'est EN. Fichiers <filename>catalog</filename> Si vous avez utilisé la syntaxe décrite plus haut et essayé d'utiliser un processeur SGML pour traiter votre document, il aura besoin de convertir le FPI en un nom de fichier sur votre ordinateur qui décrive la DTD. Vous pouvez pour cela vous servir d'un fichier catalogue (habituellement appelé catalog). Il contient des lignes qui donnent les correspondances entre FPIs et noms de fichiers. Par exemple, s'il y a la ligne : PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" le processeur SGML cherchera la DTD dans le fichier strict.dtd du sous-répertoire 4.0 où se trouve le fichier catalog qui comporte cette ligne. Jettez un oeil au fichier /usr/local/share/sgml/html/catalog. C'est le fichier catalogue pour les DTDs HTML qui ont été installées par le logiciel porté textproc/docproj. <envar>SGML_CATALOG_FILES</envar> Pour trouver un fichier catalog, votre processeur SGML doit savoir où chercher. La plupart d'entre eux ont des paramètres de leur ligne de commande pour donner le chemin d'accès à un ou plusieurs catalogues. Vous pouvez par ailleurs définir SGML_CATALOG_FILES pour désigner ces fichiers. Cette variable d'environnement doit contenir une liste de fichiers catalogues (donnés par leurs chemins d'accès complets) séparés par des points-virgules. Habituellement, vous incluerez les fichiers suivants : /usr/local/share/sgml/docbook/catalog /usr/local/share/sgml/html/catalog /usr/local/share/sgml/iso8879/catalog /usr/local/share/sgml/jade/catalog Alternatives aux FPIs Au lieu d'utiliser un FPI pour préciser la DTD utilisée (et donc le fichier qui contient la DTD), il est possible de donner explicitement le nom du fichier. La syntaxe pour le faire est légèrement différente : ]]> Le mot-clé SYSTEM indique que le processeur SGML doit localiser le fichier d'une façon qui dépend du système. Cela signifie habituellement (mais pas toujours) que la DTD sera définie par un nom de fichier. Il est préférable d'utiliser des FPIs pour des raisons de portabilité. Vous ne voulez pas livrer un exemplaire de la DTD avec votre document, et si vous avez utilisé l'identifiant SYSTEM, il faudra que chacun ait ses DTDs aux mêmes endroits. Revenir au SGML On a dit plus haut dans cette introduction que le SGML n'était utilisé que pour écrire les DTDs. Ce n'est pas tout à fait vrai. Il y a des éléments de la syntaxe SGML que vous voudrez pouvoir utiliser dans vos documents. Par exemple, vous pouvez y inclure des commentaires, qui seront ignorés par les analyseurs. Les commentaires sont inclus en utilisant une syntaxe SGML. D'autres utilisations du SGML dans les documents seront mentionnées plus loin. Il vous faut évidemment un moyen d'indiquer au processeur SGML que ce qui va suivre n'est pas constitué d'éléments du document, mais est du SGML que le processeur doit prendre en compte. Ces sections sont marqués avec <! ... > dans votre document. Tout ce qui se trouve entre ces délimiteurs est du code SGML comme on en trouve dans les DTDs. Comme vous venez peut-être de vous en rendre compte, la déclaration DOCTYPE est un exemple de syntaxe SGML que vous devez inclure dans votre document… Commentaires &sgml.todo; Les commentaires suivent une syntaxe SGML et ne sont normalement autorisés que dans une DTD. Cependant comme la le montre, il est possible d'inclure du SGML dans vos documents. Les délimiteurs pour les commentaires SGML sont constitués de la chaîne de caractères “--”. Une première occurence ouvre le commentaire, et la seconde le ferme. Commentaire SGML générique ]]> Utilisez 2 tirets Vous aurez un problème avec les versions PostScript et PDF de ce document. Les exemples précédents n'auront probablement qu'un simple tiret, - après <! et avant >. Il faut utiliser deux -, et non un seul. Les versions PostScript et PDF ont converti les deux - de l'original en un seul double tiret plus professionnel, et déformé l'exemple au passage. Les versions HTML, texte et RTF de ce document ne sont pas sujettes à ce problème. ]]> Si vous avez déjà utilisé HTML auparavant, on vous a peut-être donné des règles différentes pour les commentaires. En particulier, vous pensez peut-être qu'ils commencent par <!-- et ne se terminent qu'avec -->. Ce n'est pas le cas. Les analyseurs syntaxiques de nombreux navigateurs sont défectueux et acceptent cette syntaxe. Ceux qu'utilisent le Projet de Documentation sont plus rigoureux et rejetteront les documents qui comportent cette erreur. Commentaires SGML erronnés ]]> L'analyseur SGML traitera cela comme s'il trouvait : <!CE N'EST PAS EN COMMENTAIRE> Ce qui n'est pas du SGML valide et donnera des messages d'erreur source de confusion. ]]> Comme l'exemple le suggère, ne mettez pas de commentaires de ce type. ]]> C'est une (légèrement) meilleure idée, mais c'est toute de même une source de confusion potentielle pour les débutants en SGML. A faire… Ajoutez des commentaires à exemple.sgml et validez vos modifications avec &man.nsgmls.1; Ajoutez des commentaires incorrects à exemple.sgml, pour voir quels messages d'erreur produit alors &man.nsgmls.1;. Entités Les entités fournissent un mécanisme pour désigner des parties d'un contenu. Lorsque l'analyseur SGML traite votre document, il remplace les entités qu'il rencontre par le contenu de ces entités. C'est un bon moyen pour avoir du texte réutilisable et facile à modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML, un fichier marqué dans un autre. Il y a deux sortes d'entités SGML qui s'utilisent dans des situations différentes : les entités générales et les entités paramètres. Entités Générales Vous ne pouvez pas employer les entités générales dans un contexte SGML (bien que ce soit là que vous les définissiez). Elles ne peuvent être utilisées que dans votre document. Comparez cela au cas des entités paramètres. Chaque entité générale a un nom. Quand vous voulez y faire référence (et donc inclure le texte qu'elle contient dans votre document), vous mettez &nom-de-l'entité;. Supposons par exemple que vous ayez une entité appelée version.courante qui contienne le numéro de version courante de votre produit. Vous pourriez écrire : La version courante de notre produit est la &version.courante;.]]> Quand le numéro de version change, il vous suffit de modifier la définition de l'entité générale et de recompiler votre document. Vous pouvez aussi vous servir d'entités générales pour représenter des caractères que vous ne pouvez pas inclure autrement dans un document SGML. < et &, par exemple, ne doivent normalement pas apparaître dans un document SGML. Quand l'analyseur SGML rencontre un symbole <, il suppose qu'il précède une marque (de début ou de fin), et quand il rencontre un symbole &, il suppose que le texte qui le suit est le nom d'une entité. Heureusement, il y a deux entités générales, &lt; et &amp; pour le cas où vous auriez besoin d'inclure l'un ou l'autre de ces symboles. Une entité générale ne peut être définie que dans un contexte SGML. On le fait habituellement immédiatement après la déclaration DOCTYPE. Définition d'entités générales ]>]]> Remarquez que la déclaration DOCTYPE est suivie d'un crochet ouvrant à la fin de la première ligne. Les deux entités sont définies aux deux lignes suivantes, avant le crochet fermant. La déclaration DOCTYPE se termine ensuite. Les crochets sont nécessaires pour dire que nous ajoutons un complément à la DTD mentionnée par la déclaration DOCTYPE. Entités paramètres Comme les entités générales, les entités paramètres servent à nommer des parties réutilisables du texte. Cependant, alors que les entités générales peuvent être utilisées dans le corps du document, les entités paramètres ne peuvent être employées que dans un contexte SGML. Les entités paramètres sont définies de la même manière que les entités générales. Sinon qu'au lieu de vous servir de &inomd-de-l'entité; pour y faire référence, vous utiliserez %nom-de-l'entité; Les entités Paramètres employent le symbole Pourcent. . Leur définition comporte aussi un % entre le mot-clé ENTITY et le nom de l'entité. Définition d'entités paramètres ]>]]> Cela ne paraît peut être pas très utile. On verra pourtant que ça l'est. A faire… Définissez un entité générale dans exemple.sgml. ]> Exemple de fichier HTML

C'est un paragraphe avec du texte.

C'est encore un paragraphe avec du texte.

Ce paragraphe sera peut-être justifié à droite

La version courante de ce document est : &version;

]]> Validez le document avec &man.nsgmls.1; Chargez exemple.sgml avec votre navigateur (vous devrez peut-être le recopier dans exemple.html pour que votre navigateur le reconnaisse comme un document HTML). A moins que votre navigateur ne soit très évolué, il ne remplacera pas la référence &version; à l'entité par le numéro de version. Les analyseurs de la plupart des navigateurs sont élémentaires et ne gèrent pas correctement le SGMLC'est tout à fait dommage. Imaginez les problèmes et bricolages (comme les Server Side Includes) que cela éviterait.. La solution est de normaliser votre document avec un outil de normalisation du SGML. Ce type d'outil lit un document SGML valide et le transforme en un autre document SGML tout aussi valide. En particulier, il y remplace les références aux entités par leur contenu. Vous pouvez le faire avec &man.sgmlnorm.1;. &prompt.user; sgmlnorm exemple.sgml > exemple.html exemple.html doit maintenant contenir une version normalisée (i.e., où les références aux entités ont été remplacées par leur contenu) de votre document, prête à être affichée par votre navigateur. Si vous jetez un oeil au résultat de &man.sgmlnorm.1;, vous verrez qu'il ne comporte pas de déclaration DOCTYPE au début. Pour qu'elle y soit, utilisez l'option  : &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Utiliser les entités pour inclure des fichiers Les entités (générales et paramètres) sont particulièrement utiles pour inclure un fichier dans un autre. Utiliser les entités générales pour inclure des fichiers Supposons que le contenu d'un livre SGML soit découpé en fichiers, à raison d'un fichier par chapitre, appelés chaptitre1.sgml, chapitre2.sgml, et ainsi de suite, et que le fichier livre.sgml inclue ces chapitres. Pour que vos entités aient pour valeur le contenu de ces fichiers, vous les déclarerez avec le mot-clé SYSTEM. Cela indique à l'analyseur SGML qu'il doit utiliser le contenu du fichier mentionné comme valeur de l'entité. Utiliser les entités générales pour inclure des fichiers ]> &chapitre.1; &chapitre.2; &chapitre.3; ]]> Quand vous vous servez d'entités générales pour inclure d'autres fichiers dans un document, les fichiers inclus (chapitre1.sgml, chapitre2.sgml, et ainsi de suite) ne doivent pas commencer par une déclaration DOCTYPE. Ce serait une erreur de syntaxe. Utiliser les entités paramètres pour inclure des fichiers Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML. Quand aurez-vous besoin d'inclure un fichier dans un contexte SGML ? Vous pouvez vous en servir pour être sûr de pouvoir réutiliser vos entités générales. Supposons que votre document comporte de nombreux chapitres, et que vous réutilisiez ces chapitres dans deux livres différents, chacun organisant ces chapitres de façon différente. Vous pourriez donner la liste des entités en tête de chaque livre, mais cela pourrait rapidement devenit fastidieux à gérer. Mettez, au lieu de cela, les définitions des entités générales dans un fichier, et utilisez une entité paramètre pour inclure ce fichier dans votre document. Utiliser les entités paramètres pour inclure des fichiers Mettez d'abord les définitions de vos entités dans un fichier séparé, appelé chapitres.ent. Voici ce qu'il contiendra : ]]> Créez maintenant une entité paramètre qui fasse référence au contenu de ce fichier. Utilisez ensuite cette entité pour inclure le fichier dans votre document, vous pourrez alors y utiliser les entités générales. Ce que vous faites de la même façon que précédemment : %chapitres; ]> &chapitre.1; &chapitre.2; &chapitre.3; ]]> A faire… Utiliser les entités générales pour inclure des fichiers Créez trois fichiers, para1.sgml, para2.sgml et para3.sgml. Mettez-y quelque chose qui ressemble à ceci : C'est le premier paragraphe.

]]> Modifiez exemple.sgml de la façon suivante : ]> Exemple de fichier HTML

La version courante de ce document est : &version;

¶1; ¶2; ¶3; ]]> Générez exemple.html en normalisant exemple.sgml. &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.sgml ont bien été inclus dans exemple.html. Utiliser les entités paramètres pour inclure des fichiers Vous devez d'abord avoir mis en pratique l'exemple précédent. Modifiez comme ceci exemple.sgml : %entites; ]> Exemple de fichier HTML

La version courant de ce document est : &version;

¶1; ¶2; ¶3; ]]> Créez un nouveau fichier, entites.sgml, qui contienne : ]]> Générez exemple.html en normalisant exemple.sgml. &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.sgml ont bien été inclus dans example.html. Sections marquées SGML fournit un mécanisme pour définir quelles parties d'un document doivent être traitées de façon particulière. On appelle cela des “sections marquées”. Structure d'une section marquée <![ MOT-CLE [ Contenu de la section marquée ]]> Comme vous pouviez vous y attendre, une section marquée est une fonctionnalité SGML et commence donc par <!. Le premier crochet ouvrant délimite la section marquée. Le MOT-CLE définit comment cette section marquée doit être traitée par l'analyseur. Le second crochet ouvrant indique que le contenu de la section marquée commence là. La section marquée se termine par deux crochets fermants, puis un > pour indiquer que l'on quitte le contexte SGML et que l'on revient au document. Mots-clés pour les sections marquées <literal>CDATA</literal>, <literal>RCDATA</literal> Ces deux mots-clés définissent des sections marquées comme modèle de contenu et vous permettent de modifier sa valeur par défaut. Quand un analyseur SGML traite un docuemnt, il mémorise ce que l'on appelle le “modèle de contenu”. En bref, le modèle de contenu décrit ce que l'analyseur doit s'attendre à trouver comme contenu, et ce qu'il doit en faire quand il le rencontre. Les deux modèles de contenu que vous trouverez certainement les plus utiles sont CDATA et RCDATA. CDATA signifie “Character Data” - données caractères. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères, et uniquement des caractères. Les symboles < et & perdent alors leur signification particulière et sont traités comme de simples caractères. RCDATA signifie “Références à des entités et données caractères”. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères et des entités. < perd sa signification particulière, mais & est toujours compris comme le début d'une entité générale. C'est particulièrement utile si vous incluez du texte qui contient de nombreux caractères < et &. Vous pourriez bien sûr contrôler que dans votre texte tous les < sont écrits &lt; et tous les & &amp;, il peut être plus facile de marquer la section comme ne contenant que des “CDATA”. Quand SGML rencontre l'instruction correspondante, il ignorera les symboles < et & qui apparaîtront dans le contenu. Utiliser une section marquée CDATA <para>Voici un exemple de la façon dont vous pourriez inclure un texte comportant de nombreux &lt; et &amp;. L'exemple lui-même est en HTML. Le texte qui l'encadre (<para> et <programlisting>) est du DocBook.</para> <programlisting> <![ CDATA [ Cet exemple vous montre quelques éléments de HTML. Comme les caractères < et > y sont si fréquemment utilisés, il est plus facile de marquer tout l'exemple comme CDATA plutôt que de se servir des entités à la place de ces caractères dans tout le texte.

  • C'est un élément de liste
  • C'est un second élément de liste
  • C'est un troisième élément de liste

C'est la fin de l'exemple.

]]> ]]> </programlisting> Si vous consultez le source de ce document, vous verrez qu'il utilise constamment cette technique. <literal>INCLUDE</literal> et <literal>IGNORE</literal> Si le mot-clé est INCLUDE, alors le contenu de la section marquée sera pris en compte. Si le mot-clé est IGNORE, alors la section marquée sera ignorée. Il n'apparaîtra pas dans les sorties. Utiliser <literal>INCLUDE</literal> et <literal>IGNORE</literal> dans les sections marquées <![ INCLUDE [ Ce texte sera traité et inclus. ]]> <![ IGNORE [ Ce texte ne sera pas traité ou inclus. ]]> En soi, cela ne sert pas à grand-chose. Si vous vouliez supprimer du texte de votre document, vous auriez pu l'enlever ou le mettre en commentaires. Cela devient plus utile quand vous comprenez que vous pouvez vous servir des entités paramètres pour contrôler ces sections. Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML, et une section marquée est un contexte SGML. Si par exemple, vous générez une version imprimée et une version électronique de votre document, vous pourriez vouloir inclure dans la version électronique un contenu supplémentaire qui ne devra pas apparaître dans la version imprimée. Créez une entité paramètre et donnez lui comme contenu INCLUDE. Rédigez votre document en utilisant des sections marquées pour délimiter le contenu qui ne doit apparaître que dans la version électronique. Dans ces sections marquées, servez-vous de l'entité paramètre au lieu du mot-clé. Lorsque vous voulez générer la version électronique, changez la valeur de l'entité paramètre en IGNORE et retraitez le document. Utiliser une entité paramètre pour contrôler une section marquée <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % version.electronique "INCLUDE"> ]]> ... <![ %version.electronique [ Ce texte ne doit apparaître que dans la version électronique du document. ]]> Pour générer la version imprimée, changez la définition de l'entité en : <!ENTiTY % version.electronique "IGNORE"> A la seconde passe sur le document, les sections marquées qui utilisent %version.electronique comme mot-clé seront ignorées. A faire… Créez un nouveau fichier, section.sgml, qui contienne : <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % text.output "INCLUDE"> ]> <html> <head> <title>Exemple d'utilisation des sections marquées</title> </head> <body> <p>Ce paragraphe <![ CDATA [contient de nombreux caractères < (< < < < <) il est donc plus facile de l'inclure dans une section marquée CDATA ]]></p> <![ IGNORE [ <p>Ce paragraphe n'apparaîtra jamais dans les sorties.</p> ]]> <![ [ <p>Ce paragraphe apparaîtra peut-être dans les sorties.</p> <p>Cela dépend de l'entité paramètre .</p> ]]> </body> </html> Normalisez le fichier avec &man.sgmlnorm.1; et examinez le résultat. Notez quels paragraphes ont été conservés et quels paragraphes ont été supprimés, et ce qu'est devenu le contenu des sections marquées CDATA. Modifiez la définition de l'entité sortie.texte de INCLUDE en IGNORE. Normalisez de nouveau le fichier et regardez ce qui a changé dans le résultat. Conclusion Ici se termine cette introduction à SGML. Pour des raisons de place et de complexité, de nombreux points ont été survolés (voire omis). Les sections qui précédent décrivent néanmoins suffisamment d'éléments du SGML pour vous permettre de comprendre comment est organisée la documentation du FDP. diff --git a/fr_FR.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/fr_FR.ISO8859-1/books/fdp-primer/tools/chapter.sgml index 378957ec2b..29b6d1e45a 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/tools/chapter.sgml +++ b/fr_FR.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -1,301 +1,301 @@ Outils Le FDP utilise un certain nombre de logiciels pour faciliter la gestion de la documentation de FreeBSD, la convertir en différents formats, et ainsi de suite. Vous devrez vous-même vous servir de ces outils, si vous travaillez à la documentation de FreeBSD. Tous ces outils existent sous forme de logiciels portés ou pré-compilés pour FreeBSD, ce qui vous simplifie beaucoup la tâche de leur installation. Vous devrez les installer avant de mettre en pratique les exemples donnés dans les chapitres suivants. Ces chapitres vous expliquent comment vous servir de ces outils. Utilisez <filename>textproc/docproj</filename> si possible Vous pouvez gagner beaucoup de temps si vous les installez avec textproc/docproj. C'est un méta-port qui ne contient pas lui-même de logiciels. Au lieu de cela, il dépend de l'installation correcte de divers autres logiciels portés. Son installation devrait télécharger et installer automatiquement tous les paquetages listés dans ce chapitre dont vous aurez besoin, s'ils n'existent pas déjà sur votre système. L'un des paquetages dont vous aurez peut-être besoin est le jeu de macro-instructions JadeTeX. Celui-ci, à son tour, a besoin que TeX soit installé. TeX est un paquetage volumineux, dont vous n'aurez besoin que si vous voulez générer les versions PostScript et PDF. Pour économiser du temps et de l'espace disque, vous pouvez préciser si vous voulez ou non installer JadeTeX (et donc TeX). Faites soit : &prompt.root; make JADETEX=yes install ou : &prompt.root; make JADETEX=no install selon le cas. Outils indispensables Logiciels Vous aurez besoin de ces programmes avant de pouvoir utilement travailler sur la documentation de FreeBSD. Ils font tous partie de textproc/docproj. SP (textproc/sp) Une série d'applications, dont un analyseur syntaxique SGML et un outil de normalisation du source SGML. Jade (textproc/jade) Une implémentation des DSSSL. Cela sert à convertir des documents marqués vers d'autres formats, dont HTML et TeX. Tidy (www/tidy) Un formateur HTML, qui sert à remettre en forme le code HTML généré automatiquement pour qu'il soit plus lisible. Lynx (www/lynx-current) Navigateur WWW en mode texte, &man.lynx.1; peut aussi convertir des fichiers HTML en fichiers texte. DTDs et Entités Ce sont les DTDs et jeux d'entités utilisés par le FDP. Il faut les installer avant de pouvoir travailler à la documentation. DTD HTML (textproc/html) HTML est le langage principal du World Wide Web, il est utilisé constamment par le site Web de FreeBSD. DTD LinuxDoc (textproc/linuxdoc) Une partie de la documentation de FreeBSD est marquée avec LinuxDoc. Le FDP migre activement de LinuxDoc à DocBook. DTD DocBook (textproc/docbook) DocBook est conçu pour le marquage de documentation technique et le FDP est en cours de migration de LinuxDoc à DocBook. A la date de rédaction de cette documentation, celle-ci et le Manuel de Référence de FreeBSD sont au format DocBook. Entités ISO 8879 (textproc/iso8879) 19 de jeux de caractères ISO 8879:1986 utilisés par de nombreuses DTDs. Cela comprend des symboles mathématiques nommés, les caractères “latins” supplémentaires (accents, signes diacritiques et ainsi de suite) et les lettres grecques. Feuilles de style Les feuilles de style sont utilisées pour convertir et formater la documentation pour l'affichage à l'écran, l'impression, et ainsi de suite. Les Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) Les Modular DocBook Stylesheets sont utilisées pour convertir la documentation marqué en DocBook aux autres formats, comme HTML ou RTF. Outils facultatifs Il n'est pas obligatoire d'installer les outils qui suivent. Si vous le faites cependant, vous trouverez peut-être plus facile de travailler à la documentation et ils vous donneront plus de possibilité de choix du format de sortie. Logiciels JadeTeX et teTeX (print/jadetex et print/teTeX) Jade et teTeX servent à convertir les documents DocBook en DVI, Postscript et PDF. Il faut pour cela les macro-instructions JadeTeX. Si vous n'avez pas l'intention de convertir votre documentation à l'un de ces formats (i.e., HTML, texte et RTF vous suffisent), il n'est pas nécessaire d'installer JadeTeX et teTeX. Cela vous fera gagner du temps et de l'espace disque, teTeX, en effet occupe plus de 30 Mo. Si vous choisissez d'installer JadeTeX et teTeX, vous devrez configurer teTeX après avoir installé JadeTeX. print/jadetex/pkg/MESSAGE vous donnera des instructions détaillées sur la façon de procéder. Emacs ou xemacs (editors/emacs ou editors/xemacs) Ces deux éditeurs ont un mode spécialisé pour travailler sur des documents marqués conformément à une DTD SGML. Cela vous permet d'avoir moins de choses à saisir et limite la possibilité d'erreurs. Vous n'êtes pas obligé de les utiliser, n'importe quel éditeur peut servir avec des documents marqués. Mais vous trouverez peut-être qu'ils vous permettent d'être plus efficace. Si quelqu'un a d'autres outils utiles pour manipuler des documents SGML, merci de transmettre l'information à Nik Clayton (nik@freebsd.org), de façon à ce qu'il les ajoute à cette liste. diff --git a/fr_FR.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/fr_FR.ISO8859-1/books/fdp-primer/translations/chapter.sgml index ed8537589c..362a736305 100644 --- a/fr_FR.ISO8859-1/books/fdp-primer/translations/chapter.sgml +++ b/fr_FR.ISO8859-1/books/fdp-primer/translations/chapter.sgml @@ -1,497 +1,497 @@ Traductions Ceci est la Foire aux Questions pour les gens qui traduisent la documentation de FreeBSD (FAQ, Manuel de Référence, guides, pages de manuel et autres) en différentes langues. Elle est très largement basée sur la FAQ du Projet Allemand de Documentation de FreeBSD, rédigée à l'origine par Frank Grnder elwood@mc5sys.in-berlin.de et traduite en Anglais par Bernd Warken bwarken@mayn.de. Nik Clayton nik@FreeBSD.org maintient cette FAQ. Pourquoi une FAQ ? De plus en plus de gens s'adressent à la &a.doc; et se proposent de traduire en d'autres langues la documentation de FreeBSD. Le but de cette FAQ est de répondre à leurs questions de façon à ce qu'ils puissent commencer le plus rapidement possible à traduire la documentation. Que signfient i18n et l10n ? i18n veut dire internationalisation et l10n localisation. Ce ne sont que des abréviations commodes. i18n se lit “i” suivi de 18 lettres, suivies d'un “n”. De la même façon, l10n se lit “l” suivi de 10 lettres, suivies d'un “n”. Y-a-t-il une liste de diffusion pour les traducteurs ? Oui, freebsd-translate@ngo.org.uk. Inscrivez-vous en envoyant un message à freebsd-translate-request@ngo.org.uk avec le mot subscribe dans le texte du message. Vous recevrez une réponse vous demandant de confirmer votre inscription (de la même façon que pour les listes de FreeBSD sur FreeBSD.org). La langue de base sur la liste est l'Anglais, mais les messages en d'autres langues sont acceptés. La liste n'est pas modérée, mais vous devez vous y être inscrit avant d'y adresser des messages. La liste est archivée, mais il n'est pas actuellement possible d'y faire des recherches. Vous aurez en retour des explications sur la façon d'accéder aux archives en envoyant le message help à majordomo@ngo.org.uk. Il est prévue que la liste de diffusion soit transférée sur FreeBSD.org et devienne donc officielle dans un avenir proche. A-t-on besoin de nouveaux traducteurs ? Oui. Plus il y a de gens qui travaillent aux traductions, plus vite elles sont réalisées, et synchronisées avec les modifications de la version anglaise. Il n'est pas nécessaire que vous soyez traducteur professionnel pour pouvoir contribuer. Quelle langue faut-il que je connaisse ? Dans l'idéal, il faudrait que vous ayez une bonne connaissance de l'anglais écrit et bien sûr, il faut que vous pratiquiez couramment la langue dans laquelle vous traduisez. L'anglais n'est pas strictement indispensable. Vous pourriez par exemple effectuez une traduction en Hongrois, à partir de la traduction espagnole de la FAQ. Quels logiciels faut-il que je connaisse ? Il est fortement recommandé que vous teniez à jour une copie locale des archives CVS de FreeBSD (au moins de la documentation), soit à l'aide de CTM, soit en utilisant CVSup. Le chapitre “Se synchroniser avec la version -current de FreeBSD” du Manuel de Référence vous explique comment utiliser ces logiciels. Il faudra que vous soyiez à l'aise avec CVS. Cela vous permettra de suivre les modifications apportées entre les différentes versions des fichiers qui constituent la documentation. [A Faire -- écrire un mode d'emploi qui explique comment utiliser CVSup pour ne récupérer que la documentation, et voir ce qui a évolué entre deux versions données] Comment savoir qui d'autre traduit la documentation dans la même langue ? La page des traductions du Projet de Documentation liste les traductions en cours déjà connues. S'il y a déjà d'autres personnes qui travaillent à la traduction de documentation dans votre langue, s'il vous plaît, ne faites pas le même travail qu'eux en double. Au lieu de cela, prenez contact avec eux, pour savoir comment vous pouvez les aider. S'il la page n'indique personne qui travaille dans votre langue, envoyez un message à la &a.doc; au cas où quelqu'un aurait déjà envisagé de commencer une traduction, mais que ne ce soit pas encore signalé. Il n'y a personne d'autre qui traduise dans ma langue. Que faire ? Félicitations, vous venez juste de lancer le “Projet de Documentation dans-votre-langue de FreeBSD. Bien venu à bord. Commencez par vous assurer que vous avez bien du temps disponible. Comme vous êtes pour le moment le seul volontaire pour la traduction dans votre langue, il sera de votre responsabilité de publier votre travail et de coordonner celui d'autres personnes qui voudraient y collaborer. Envoyez un courrier électronique à la &a.doc; pour annoncer que vous allez traduire la documentation de façon à ce que la pages des traductions du Projet de Documentation puisse être tenue à jour. Il faudra vous inscrire à la liste de diffusion freebsd-translate@ngo.org.uk (comme expliqué plus haut). S'il y a déjà dans votre pays quelqu'un qui maintienne un site miroir de FreeBSD, vous devriez le contacter et voir s'il peut vous fournir un hébergement pour votre projet et, si possible, une adresse de courrier électronique et la possibilité de mettre en place une liste de diffusion. Choisissez ensuite une documentation et commencez la traduction. Il vaut mieux commencer par quelque chose de pas trop volumineux—soit la FAQ, soit l'un des guides. J'ai traduit une documentation, à qui dois-je l'envoyer ? Cela dépend. Si vous travaillez déjà au sein d'une équipe de traduction (comme l'équipe Japonaise ou l'équipe Allemande), elle aura ses propres procédures pour gérer la documentation soumise, qui seront décrites dans ses pages Web. Si vous êtes la seule personne à travailler dans une langue donnée (ou si vous êtes responsable d'un projet de traduction et voulez soumettre votre travail au Projet FreeBSD), vous devez alors l'envoyer au Projet FreeBSD (voir la question suivante). Je suis la seule personne à traduire dans cette langue, comment soumettre mes traductions ? ou Nous sommes une équipe de traduction et voulons soumettre les traductions de nos membres ? Commencez par vérifier que vos traductions sont correctement structurées. C'est-à-dire qu'elles doivent s'intégrer à l'arborescence des documentations existantes et compiler sans problèmes. La documentation de FreeBSD est actuellement archivée dans les répertoires en dessous de doc/. Les sous-répertoires de celui-ci prennent le nom codifiant la langue dans laquelle les documentations sont écrites, selon la norme ISO639 (/usr/share/misc/iso639, pour les versions de FreeBSD postérieures au 20 Janvier 1999). S'il ya a différentes codifications pour votre langue (le Chinois,par exemple), il y aura au niveau en-dessous plusieurs sous-répertoires, un pour chacun des formats de codage que vous aurez fournis. Vous aurez enfin des sous-répertoires pour chaque document. Une éventuelle traduction en Suédois ressemblerait par exemple à ce qui suit : doc/ sv/ Makefile FAQ/ Makefile *.sgml sv est le code ISO639 pour le Suédois. Remarquez les deux Makefiles, qui servent à compiler la documentation. Il n'y a qu'une seule façon de coder le Suédois, il n'y a donc pas de niveau intermédiaire entre les répertoires sv et FAQCette organisation va radicalement changer très bientôt. Suivez ce qui ce dit sur la &a.doc; pour plus d'information.. Utilisez &man.tar.1; et &man.gzip.1; pour compresser votre documentation, et envoyez-la au projet. &prompt.user; cd doc &prompt.user; tar cf swedish-docs.tar sv &prompt.user; gzip -9 swedish-docs.tar Mettez swedish-docs.tar.gz quelque part. Si vous ne disposez pas d'espace sur le Web (votre fournisseur d'accès n'en met peut-être pas à votre disposition), vous pouvez envoyer un courrier électronique à &a.nik;, pour vous mettre d'accord sur une date pour les lui envoyer par courrier. De quelque façon que vous procédiez, il faudra que vous utilisez &man.send-pr.1; pour envoyer un rapport signalant que vous avez soumis de la documentation. Il serait très utile que d'autres puissent relire votre traduction d'abord, parce qu'il y a peu de chances que la personne qui l'intégrera connaisse bien votre langue. Quelqu'un (probablement le Responsbale du Projet de Documentation, &a.nik; actuellement), récupérera votre traduction et s'assurera qu'elle compile. En particulier, les points suivants seront examinés : Tous vos fichiers utilisent-ils de chaînes RCS (comme “ID”). make all fonctionne-t-il correctement dans le répertoire sv. make install fonctionne-t-il correctement. S'il y a des problèmes, la personne qui examine votre soumission vous en fera part pour que vous essayiez de les régler. S'il n'y a pas de problèmes, votre traduction sera intégrée aussi vite que possible. Puis-je inclure dans mon texte des considérations propres à la langue ou au pays ? Nous préférerions que vous ne le fassiez pas. Supposons par exemple que vous traduisiez le Manuel de Référence en Coréen et que vous vouliez inclure une section sur les revendeurs en Corée dans votre Manuel. Il n'y a pas vraiment de raison pour que cette information ne soit pas aussi présente dans la version anglaise (ou allemande, espagnole, …). Il se peut qu'un anglophone ait besoin d'un exemplaire de FreeBSD alors qu'il se trouve en Corée. Cela permet aussi de mettre en avant la pénétration de FreeBSD dans le monde entier, ce qui n'est pas une mauvaise chose. Si vous avez des informations propres à un pays donné, soumettez-les d'abord sous forme de modifications à la version anglaise du Manuel de Référence (avec &man.send-pr.1;) et traduisez-les ensuite dans votre langue dans le Manuel de Référence dans cette langue. Merci. Comment faut-il coder les caractères propres à une langue ? Dans les documentations, les caractères Non-ASCII doivent apparaître sous forme d'entités SGML. Brièvement, celles-ci sont constituées d'une perluette (&), du nom de l'entité, et d'un point-virgule (;). Les noms des entités sont définis par la norme ISO8879, que vous trouverez dans le catalogue des logiciels portés, sous textproc/iso8879. Voici quelques examples : &eacute; é “e” accent aigu minuscule &Eacute; É “e” accent aigu majuscule &uuml; ü “u” tréma minuscule Après installation du logiciel porté “iso8879”, le fichier /usr/local/share/sgml/iso8879 en donne la liste complète. Comment doit-on s'adresser au lecteur ? Dans les documents anglais, le “you” est employé, il n'y a qu'une seule forme, à l'inverse d'autres langues. Si vous traduisez dans une langue qui dispose de plusieurs formes, utilisez celle que l'on emploie habituellement dans les documentations techniques. En cas de doute, servez-vous d'une forme de politesse courante. Y'a-t-il des informations supplémentaires à inclure dans les traductions ? Oui. Les en-têtes de la version anglaise du document ressembleront à ceci : ]]> La forme exacte peut changer, mais elles comporteront toujours la ligne “Id” et la phrase The FreeBSD Documentation Project. Vos traductions doivent comporter leur propre ligne “Id” et FreeBSD Documentation Project doit être remplacé par The FreeBSD Langue Documentation Project. Vous devrez aussi ajouter une troisième ligne qui donne la version anglaise d'origine sur laquelle est basée la traduction. Donc, la version espagnole du présent fichier commencerait par : ]]> diff --git a/fr_FR.ISO_8859-1/articles/committers-guide/Makefile b/fr_FR.ISO_8859-1/articles/committers-guide/Makefile index 0d3f683af0..72c1d9b8c9 100644 --- a/fr_FR.ISO_8859-1/articles/committers-guide/Makefile +++ b/fr_FR.ISO_8859-1/articles/committers-guide/Makefile @@ -1,20 +1,20 @@ # # The FreeBSD Documentation Project # The FreeBSD French Documentation Project # -# $Id: Makefile,v 1.1 2000-05-25 16:27:48 gioria Exp $ +# $FreeBSD$ # Original revision: 1.4 # DOC?= article FORMATS?= html INSTALL_COMPRESSED?=gz INSTALL_ONLY_COMPRESSED?= SRCS= article.sgml DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/Makefile b/fr_FR.ISO_8859-1/books/fdp-primer/Makefile index c0e962b1db..e052115a8b 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/Makefile +++ b/fr_FR.ISO_8859-1/books/fdp-primer/Makefile @@ -1,47 +1,47 @@ # # The FreeBSD Documentation Project # The FreeBSD French Documentation Project # # Compilation de l'Introduction au Projet de Documentation de FreeBSD # -# $Id: Makefile,v 1.1 2000-06-12 15:46:26 gioria Exp $ +# $FreeBSD$ # Original revision: 1.6 # MAINTAINER=nik@FreeBSD.ORG DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # # SRCS lists the individual SGML files that make up the document. Changes # to any of these files will force a rebuild # # SGML content SRCS= book.sgml SRCS+= overview/chapter.sgml SRCS+= psgml-mode/chapter.sgml SRCS+= see-also/chapter.sgml SRCS+= sgml-markup/chapter.sgml SRCS+= sgml-primer/chapter.sgml SRCS+= stylesheets/chapter.sgml SRCS+= the-faq/chapter.sgml SRCS+= the-handbook/chapter.sgml SRCS+= the-website/chapter.sgml SRCS+= tools/chapter.sgml SRCS+= translations/chapter.sgml SRCS+= writing-style/chapter.sgml # Entities SRCS+= chapters.ent SRCS+= ../handbook/mailing-lists.ent SRCS+= ../../../en_US.ISO_8859-1/books/handbook/authors.ent DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/book.sgml b/fr_FR.ISO_8859-1/books/fdp-primer/book.sgml index 38dbc8c38c..c251c1e636 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/book.sgml +++ b/fr_FR.ISO_8859-1/books/fdp-primer/book.sgml @@ -1,303 +1,303 @@ %man; %urls; %bookinfo; %translators; %chapters; %authors; %mailing-lists; ]> Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants Nik Clayton
nik@FreeBSD.ORG
 1998 1999 Nik Clayton - $Date: 2000-06-12 15:46:26 $ + $Date: 2000-11-10 12:30:58 $ - $Id: book.sgml,v 1.1 2000-06-12 15:46:26 gioria Exp $ + $Id: book.sgml,v 1.2 2000-11-10 12:30:58 kuriyama Exp $ La redistribution et l'utilisation du code source (SGML), et compilé (HTML, PostScript, etc.), modifiés ou non, sont soumises aux conditions suivantes : Le code source (SGML DocBook) distribué doit conserver le copyright ci-dessus, la présente liste de conditions et l'avertissement qui la suit, sans modifications, en tête de ce fichier. Le code source distribué sous forme compilé (transformation vers d'autres DTDs, conversion en PDF, PostScript, RTF et autres formats) doit faire apparaître dans la documentation et/ou les autres composants distribués, le copyright ci-dessus, la présente liste de conditions et l'avertissement qui la suit. CE DOCUMENT EST FOURNI PAR NIK CLAYTON “TEL QUEL” ET AUCUNE GARANTIE EXPRESSE OU IMPLICITE, Y COMPRIS, MAIS NON LIMITÉE, GARANTIES IMPLICITES DE COMMERCIABILITÉ ET D'ADÉQUATION À UN BUT PARTICULIER N'EST DONNÉE. EN AUCUN CAS NIK CLAYTON NE SAURAIT ÊTRE TENU RESPONSABLE DES DOMMAGES DIRECTS, INDIRECTS, ACCIDENTELS, SPÉCIAUX, EXEMPLAIRES OU CONSÉQUENTS (Y COMPRIS, MAIS SANS LIMITATION, LA FOURNITURE DE BIENS ET SERVICES ANNEXES  DÉFAUT D'UTILISABILITÉ, PERTE DE DONNÉES OU DE PROFITS ; OU INTERRUPTION DE TRAVAIL) QUELLE QU'EN SOIT LA CAUSE ET SELON TOUTE DÉFINITION DE RESPONSABILITÉ, SOIT PAR CONTRAT, RESPONSABILITÉ STRICTE, OU PRÉJUDICE (Y COMPRIS NÉGLIGENCE OU AUTRES) IMPUTABLES D'UNE FAÇON OU D'UNE AUTRE À L'UTILISATION DE CE DOCUMENT, MÊME APRES AVOIR ÉTÉ AVISÉ DE LA POSSIBILITÉ DE TELS DOMMAGES. Merci de votre participation au Projet de Documentation de FreeBSD. Votre contribution est très utile. Cette introduction décrit tout ce que vous devez savoir pour commencer à participer au projet de documentation de FreeBSD, des outils et logiciels que vous utiliserez (indispensables et facultatifs) à la philosophie sous-jacente au Projet de Documentation. Ce document est en cours de rédaction et n'est pas terminé. Les sections inachevées sont indiquées par un astérisque - * - qui précède leur nom. &trans.a.haby; Préface Invites de l'interpréteur de commandes La table ci-dessous donne les invites par défaut du système pour un utilisateur normal et pour le super-utilisateur. Elles sont utilisées dans les exemples pour indiquer quel utilisateur doit appliquer l'exemple. Utilisateur Invite Utilisateur normal &prompt.user; root &prompt.root; Conventions Typographiques La table ci-dessous décrit les conventions typographiques utilisées dans le présent ouvrage. Signification Exemples Noms de commandes, fichiers et répertoires. Affichage à l'écran de l'ordinateur. Modifiez votre fichier .login.Utilisez ls -a pour avoir la liste de tous les fichiers.Vous avez reçu du courrier. Ce que vous tapez, par opposition à ce que l'ordinateur affiche. &prompt.user; su Password: Références aux pages de manuel Utilisez su 1 pour changer de nom d'utilisateur. Noms d'utilisateurs et de groupes Seul root peut le faire. Mise en valeur Vous devez le faire. Variables sur la ligne de commande ; à remplacer par le nom ou la valeur effectif. Pour supprimer un fichier, tapez rm nom_du_fichier. Variables d'environnement $HOME est votre répertoire utilisateur. Notes, avertissements et exemples Dans le cours du texte, il peut y avoir des notes, des avertissements et des exemples. Les notes apparaissent comme ceci, et contiennent des informations que vous devriez prendre en considération, parce qu'elles peuvent avoir une incidence sur ce que vous faites. Les avertissements apparaissent comme ceci, et vous préviennent de problèmes potentiels si vous n'appliquez pas ces instructions. Des dégats peuvent être causés à votre matériel, ou ne pas être physiques, suppression inopinée de fichiers importants par exemple. Un exemple d'exemple Les exemples apparaissent comme ceci, et sont généralement des exemples que vous devriez tester ou qui vous montrent quels doivent être les résultats d'une opération donnée. Remerciements Mes remerciements à Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn et Christopher Maden, qui ont pris le temps de lire les premières versions de ce document et ont apporté de nombreux commentaires et critiques utiles. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; &chap.the-faq; &chap.the-handbook; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/overview/chapter.sgml b/fr_FR.ISO_8859-1/books/fdp-primer/overview/chapter.sgml index 81cbc4421e..bb2316cc55 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/overview/chapter.sgml +++ b/fr_FR.ISO_8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,187 +1,187 @@ Introduction Bienvenue au Projet de Documentation de FreeBSD. Une documentation de bonne qualité est un facteur important de succès pour FreeBSD, et le Projet de Documentation de FreeBSD - “The FreeBSD Documentation Project” -  est la source d'une grande part de cette documentation. Votre participation est importante. L'objectif principal de ce document est d'expliquer clairement comment est organisé le FDP, comment écrire et soumettre de la documentation au FDP et comment utiliser les outils disponibles pour produire de la documentation. La participation de chacun au FDP est bienvenue. Il n'y a pas de cotisation minimum, pas de quota de documentation à produire par mois. Il vous suffit de vous inscrire sur la &a.doc;. Après avoir lu ce document, vous : Saurez quelles sont les documentations maintenues par le FDP. Serez capable de lire et comprendre le code SGML source des documentations maintenues par le FDP. Serez capable de modifier la documentation. Saurez comment soumettre vos modifications pour qu'elles soient revues et incorporées à la documentation de FreeBSD. Le jeu de documentations de FreeBSD Le FDP a la responsabilité de quatre catégories de documents. Les pages de manuel Les pages de manuel système en anglais ne sont pas rédigées par le FDP, puisqu'elles font partie du système de base. Le FDP, néanmoins, peut (et a) récrit des pages de manuel existantes pour les clarifier ou corriger des inexactitudes. Les équipes de traductions sont responsables de la traduction des pages de manuel dans les différentes langues. Ces traductions sont archivées par le FDP. FAQ L'objectif de la FAQ est de répondre (sous forme de courtes questions/réponses) aux questions qui sont posées, ou devraient être posées, sur les différentes listes de diffusion et forums de discussion consacrées à FreeBSD. Son format n'autorise pas de réponses longues et exhaustives. Manuel de référence - “Handbook” Le Manuel cherche à être la ressource en ligne exhaustive et de référence pour les utilisateurs de FreeBSD. Le site Web C'est le point de présence central de FreeBSD sur le World Wide Web, dont le site principal est http://www.freebsd.org/ et qui a de nombreux sites miroirs dans le monde. Pour beaucoup de gens, ce site est leur première rencontre avec FreeBSD. Ces quatres catégories de documentation sont disponibles dans les archives CVS de FreeBSD. Ce qui signifie que les modifications et les notifications sont accessibles à tous, et que chacun peut utiliser un programme comme CVSup ou CTM pour maintenir à jour son propre exemplaire local. En plus de ces documents, de nombreuses personnes ont écrit des guides ou réalisé des sites Web se rapportant à FreeBSD. Certains sont aussi archivés dans l'arborescence CVS (quand l'auteur a donné son accord). Dans d'autre cas, l'auteur a choisi de conserver ses documentations en dehors des archives FreeBSD. Le FDP essaie de donner le maximum de liens possible sur ces documents. Avant de commencer Ce document fait l'hypothèse que vous savez déjà : Vous procurer et tenir à jour une copie locale de la documentation. Soit en maintenant une copie locale des archives CVS de FreeBSD (avec CVS, CVSup ou CTM), ou en vous servant de CVSup pour ne télécharger que la version extraite - courante. Comment télécharger et installer de nouveaux logiciels en vous servant soit du catalogue des logiciels de FreeBSD soit de &man.pkg.add.1;. diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/fr_FR.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml index 29422c6417..77184dc686 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/fr_FR.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -1,1645 +1,1645 @@ Introduction à SGML La majorité des documentations du FDP utilisent SGML. Ce chapitre vous explique ce que cela signifie exactement, comment lire et comprendre le source de la documentation et décrit la façon d'utiliser le SGML que vous recontrerez dans la documentation. Des parties de cette section se sont inspirées du livre de Mark Galassi, “Get Going With DocBook”. Introduction Il était autrefois facile de travailler sur des documents électroniques. Vous n'aviez normalement à connaître que le jeu de caractères utilisé (ASCII, EBCDIC, ou l'un des nombreux autres) et c'était à peu près tout. Le texte était du texte, et vous voyiez vraiment ce que vous obteniez. Pas de sophistication, pas de formatage, pas d'intelligence. Cela devint inévitablement insuffisant. Une fois que vous avez du texte qu'une machine peut lire, vous vous attendez à ce que la machine puisse l'utiliser et le manipuler intelligemment. Vous aimeriez pouvoir préciser que certaines phrases sont accentuées, y ajouter un glossaire ou des hyper-liens. Vous voulez que les noms de fichiers apparaissent en police “machine à écrire” à l'écran et en italique à l'impression, et tout un tas d'autres options de présentation encore. Il fut un temps où l'on pensait que l'Intelligence Artificielle (IA) rendrait cela facile. Votre ordinateur pourrait lire le document et identifier les phrases clés, les noms de fichiers, le texte que l'utilisateur devait taper, et d'autres encore. Malheureusement, la réalité est un peu différente, et il faut aider nos ordinateurs à manipuler intelligemment notre texte. Plus précisement, il faut les aider à indentifier ce qui est quoi. Vous et moi, à la vue de :
Pour effacer /tmp/foo, utilisez &man.rm.1; : &prompt.user; rm /tmp/foo
distinguons facilement ce qui est nom de fichier, commande à taper, référence aux pages de manuel, et ainsi de suite. Mais l'ordinateur lui ne le peut pas. Pour cela, Nous avons besoin des marques. Le “marquage” est communément qualifié de “valeur ajoutée” ou “coût augmenté”. Le terme prend ces deux sens quand il s'applique au texte. La marquage est du texte en supplément dans le document, distinct par un moyen ou un autre du contenu du document, de façon à ce que les programmes qui traitent le document puisse le lire et l'utiliser pour prendre des décisions. Les éditeurs peuvent masquer le marquage à l'utilisateur, de façon à ce qu'il ne soit pas perturbé par ces marques. L'information supplémentaire donnée avec les marques ajoute de la valeur au document. Le marquage doit habituellement être manuel - après tout, si les ordinateurs pouvait analyser suffisamment le texte pour ajouter les marques, il n'y en aurait alors en fait pas besoin. Cela augment le coût du document. L'exemple précédent est codé comme suit dans le présent document : Pour effacer /tmp/foo, utilisez &man.rm.1;. rm /tmp/foo]]> Comme vous pouvez le constater, le marquage est clairement séparé du contenu. Bien évidemment, si vous devez utiliser des marques, vous devrez définir ce que les marques veulent dire et comment elles doivent être traitées. Il vous faudra un language de marquage auquel vous référer pour marquer vos documents. Un seul language de marquage peut bien sûr ne pas suffire. Les besoins de marquage d'une documentation technique diffèrent énormément de ceux de recettes de cuisines. ces derniers seront à leur tour différents de ceux d'un language de marquage pour de la poésie. Vous avez en fait besoin d'un language qui vous permette de définir ces autres languages de marquage. Un méta-language de marquage. C'est exactement ce qu'est Standard Generalised Markup Language (SGML) - Language de Marquage Standard Généralisé. De nombreux languages de marquage sont écrits en SGML, dont les deux languages les plus utilisés par le FDP, HTML et DocBook. Chaque définition d'un language s'appelle plus exactement une Document Type Definition (DTD) - Définition de Type de Document. La DTD définit les noms des éléments utilisables, leur ordre d'apparition (et leur hiérarchie) et les informations qui s'y rapportent. Une DTD est parfois désignée comme une application de SGML. Une DTD est une spécification complète de tous les éléments autorisés, de l'ordre dans lequel ils doivent être utilisés, quels sont ceux qui sont obligatoires, quels sont ceux qui sont facultatifs, et ainsi de suite. Il est alors possible d'écrire un analyseur qui lise et la DTD et le document qui prétend s'y conformer. L'analyseur peut alors vérifier si tous les éléments requis sont bien présents dans l'ordre voulu dans le document et s'il y a des erreurs dans le marquage. On appelle habituellement cela valider le document. Ce traitement ne valide uniquement que le choix des éléments, leur ordre, et ainsi de suite, se conforme à ce que définit la DTD. Il ne vérifie pas que vous avez utilisé les marques appropriées au document. Si vous marquez tous les noms de fichiers de votre document comme des noms de fonctions, l'analyseur ne le signalera pas comme une erreur (en supposant, bien sûr, que votre DTD définisse des éléments pour les noms de fichiers et de fonctions et qu'ils aient le droit d'apparaître aux mêmes endroits). Il est probable que vos contributions au Projet de Documentation consiste en documents marqués soit en HTML soit en DocBook, plutôt qu'en modifications aux DTDs. Pour cette raison, cet ouvrage n'abordera pas la façon d'écrire une DTD. Eléments, marques et attributs Toutes les DTDs écrites en HTML ont des caractéristiques communes. Ce n'est guère surprenant comme le montre inévitablement la philosophie qui sous-tend SGML. Une des manifestations les plus visibles de cette philosophie est la caractérisation en contenu et éléments. Votre documentation (que ce soit une seule page Web ou un ouvrage volumineux) est vue comme étant un contenu. Ce contenu est alors divisé (et ensuite subdivisé) en éléments. L'objectif de l'ajout de marques est de nommer et de définir le début et la fin de ces éléments pour traitement ultérieur. Considérez par exemple un livre type. Au plus haut niveau, ce livre lui-même est un élément. Cet élément “livre” contient évidemment des chapitres, qui peuvent aussi être légitimement considérés comme des éléments. Chaque chapitre contiendra à son tour des éléments, tels que des paragraphes, des citations et de notes de bas de page. Chaque paragraphe peut lui-même contenir encore des éléments, pour identifier le texte parlé par exemple, ou les noms des personnages de l'histoire. Vous pouvez si vous le voulez voir cela comme un “morcelement” du contenu. A la racine, vous avez un morceau, le livre. Un niveau en dessous, vous avez plus de morceaux, les chapitres individuels. Ils sont à leur tour morcelés en pargraphes, notes de bas de page, noms des personnages, et ainsi de suite. Remarquez que vous pouvez différencier les éléments sans utiliser la terminologie SGML. C'est vraiment immédiat. Vous pouvez le faire avec un surligneur et un livre imprimé, en utilisant des couleurs différentes pour chaque type d'élément. Nous n'avons bien sûr pas de surligneur électronique, il nous faut donc un autre moyen d'indiquer à quel élément appartient chaque morceau du contenu. Dans les languages écrits avec SGML ,(HTML, DocBook, et al.), cela se fait avec des marques. Une marque sert à dire où commence et où finit un élément. La marque ne fait pas partie de l'élément lui-même. Comme chaque DTD est habituellement écrite pour marquer des types d'informations spécifiques, chacune reconnaîtra des éléments différents, et aura donc des noms différents pour les marques. Pour un élément appelé nom-de-l'élément, la marque de début sera normalement <nom-de-l'élément>. La marque de fin correspondante sera </nom-de-l'élément>. Utiliser un élément (marques de début et de fin) HTML dispose d'un élément pour indiquer que le contenu inclus est un paragraphe, appelé p. Cet élément a une marque de début et une de fin. C'est un paragraphe. Il commence avec la marque de début pour l'élément 'p', et se terminera avec la marque de fin pour l'élément 'p'

C'est un autre paragraphe. Mais il est beaucoup plus court.

]]> Tous les éléments n'ont pas besoin d'une marque de fin. Certains n'ont pas de contenu. En HTML, par exemple, vous pouvez indiquer que vous voulez avoir une ligne horizontal dans votre document. Cette ligne n'a bien sûr aucun contenu, vous n'avez donc besoin que de la marque de début pour cet élément. Utiliser un élément (marque de début uniquement) HTML dispose d'un élément pour inclure une ligne horizontale, appelé hr. C'est un élément sans contenu, il n'a donc qu'une marque de début. C'est un paragraphe.

C'est un autre paragraphe. Une ligne horizontale le sépare du précédent.

]]> Si ce n'était pas encore clair, les éléments peuvent contenir d'autres éléments. Dans l'exemple du livre plus haut, ce livre contenait tous les chapitres, qui à leur tour contenaient tous les paragraphes, et ainsi de suite. Eléments dans des éléments ; <sgmltag>em</sgmltag> C'est un paragraphe simple où certains mots ont été mis en valeur.

]]> La DTD définira les règles qui disent quels éléments peuvent être inclus dans quels autres éléments, et ce qu'ils peuvent précisement contenir. Les gens confondent souvent marques et éléments comme si c'étaient des termes interchangeables. Ce n'est pas le cas. Un élément est une partie de la structure d'un document. Un élément a un début et une fin. Les marques définissent où commence et où finit le document. Quand le présent document (ou quelqu'un d'autre qui connait le SGML) parle de la marque “the <p> tag”, cela se rapporte au texte composé des trois caractères <, p et >. Mais la phrase “l'élément <p>” désigne tout l'élément. Cette distinction est très subtile. Mais gardez la à l'esprit. Les éléments peuvent avoir des attributs. Un attribut a un nom et une valeur, et sert à donner des informations supplémentaires concernant l'élément. Ce peuvent être des informations qui précisent comment l'élément doit être formaté, ou un identifiant unique pour cette occurrence de l'élément, ou autre chose encore. Les attributs d'un élément sont donnés dans la marque de début de l'élément et ont la forme nom-de-l'attribut="valeur-de-l'attribut". Dans les versions récentes d'HTML, l'élément p a un attribut appelé align, qui suggère un alignement (justification) du paragraphe au programme affichant l'HTML. L'attribut align peut prendre l'une des quatre valeurs prédéfinies, left, center, right et justify. Si l'attribut n'est pas précise, la valeur par défaut est left. Utiliser un élément avec un attribut L'attribut align est superflus pour ce paragraphe, puisque 'left' est la valeur par défaut.

Ce paragraphe sera peut-être centré.

]]> Certains attributs ne prennent que des valeurs prédéfinies, comme left ou justify. D'autres peuvent prendre les valeurs que vous voulez. Si vous avez besoin de quotes (") dans un attribut, mettez la valeur de l'attribut entre simples quotes. Simples quotes dans un attribut Je suis à droite !

]]> Vous n'avez pas toujours besoin de mettre la valeur de l'attribut entre simples quotes. Les régles à ce sujet sont cependant subtiles, et il est beaucoup plus simple de toujours mettre entre simples quotes les valeurs des attributs. A faire… Pour tester les exemples donnés dans ce document, vous devrez installer des logiciels sur votre système et vérifiez qu'une variable d'environnement est correctement définie. Téléchargez et installez textproc/docproj du catalogue des logiciels portés de FreeBSD. C'est un méta-port qui doit télécharger et installer tous les programmes et fichiers utilisés par le Projet de Documentation. Ajoutez les lignes pour définir SGML_CATALOG_FILES à vos procédures d'initialisation de l'interpréteur de commandes. <filename>.profile</filename>, pour les utilisateurs de &man.sh.1; et &man.bash.1; SGML_ROOT=/usr/local/share/sgml SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES <filename>.login</filename>, pour les utilisateurs de &man.csh.1; et &man.tcsh.1; setenv SGML_ROOT /usr/local/share/sgml setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES Déconnectez-vous et reconnectez-vous ensuite, ou exécutez ces commandes pour définir la variable d'environnement. Créez un fichier exemple.sgml, où vous mettrez : Exemple de fichier HTML

C'est un paragraphe avec du texte.

C'est encore un paragraphe avec du texte.

Ce paragraphe sera peut-être justifié à droite.

]]> Essayez de le valider avec un analyseur syntaxique SGML. L'analyseur syntaxique &man.nsgmls.1; fait partie de textproc/docproj. &man.nsgmls.1; lit normalement un document marqué en utilisant une DTD SGML et génère l'Element Structure Information Set (ESIS) - Informations sur la Structuration en Eléments - mais cela ne nous concerne pas pour le moment. Néanmoins, avec le paramètre , &man.nsgmls.1; ne génère rien mais affiche simplement les messages d'erreurs éventuels. C'est utile pour vérifier si votre document est correct ou non. Utilisez &man.nsgmls.1; pour vérifier si votre document est valide : &prompt.user; nsgmls -s example.sgml Vous constaterez que &man.nsgmls.1; n'affiche rien. Cela signifie qu'il a validé votre document. Voyez ce qui ce passe si vous oubliez un élément requis. Supprimez les marques title et /title et relancer la validation. &prompt.user; nsgmls -s example.sgml nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished Les messages d'erreur de &man.nsgmls.1; sont structurés en colonnes séparés par des deux-points ou des points-virgules. Colonne Signification 1 Nom du programme qui a généré l'erreur. Ce sera toujours nsgmls. 2 Nom du fichier où se trouve l'erreur. 3 Numéro de la ligne où se trouve l'erreur. 4 Numéro de la colonne où se trouve l'erreur. 5 Une lettre donnant le type de message d'erreur. I pour un message d'information, W pour un message d'avertissement, E pour un message d'erreur et X pour les références croisées. (Ce n'est cependant pas toujours la cinquième colonne. nsgmls -sv affiche nsgmls:I: SP version "1.3" - selon la version installée. Comme vous pouvez le constater, c'est un message d'information.) Vous voyez donc que nous avons dans notre exemple des messages d'erreurs. 6 Le texte du message d'erreur. Vous aurez plus d'informations sur les erreurs de &man.nsgmls.1; dans la Unofficial 'Kindler, Gentler HTML Validator' FAQ. Ne pas mettre les marques title a généré 2 erreurs différentes. La première erreur indique que l'analyseur SGML a rencontré un contenu (ici, des caractères, au lieu d'une marque de début d'élément) alors qu'il attendait autre chose. Dans le cas présent, l'analyseur attendait une marque de début pour un élément valide à l'intérieur de head (title par exemple). La deuxième erreur est due au fait que les éléments head doivent contenir un élément title. &man.nsgmls.1; considère alors que l'élément n'est pas complet. La marque de fin indique donc que l'élément se termine alors qu'il n'est pas correctement renseigné. Remettez l'élément title en place. La déclaration DOCTYPE Au début de chaque document que vous rédigez, vous devez préciser le nom de la DTD à laquelle le document se conforme. Cela pour que les analyseurs syntaxiques SGML la connaissent et puissent valider le document. Cette information est habituellement donnée sur une seule ligne, dans la déclaration DOCTYPE. Voici une déclaration typique pour un document conforme à la version 4.0 de la DTD HTML : ]]> Cette ligne a plusieurs composants distincts : <! C'est l'indicateur qui dit que c'est une déclaration SGML. Cette ligne définit le type de document. DOCTYPE Précise que c'est la déclaration SGML du type de document. html Définit le premier élément qui apparaîtra dans le document. PUBLIC "-//W3C//DTD HTML 4.0//EN" Donne le Formal Public Identifier (FPI) - Identifiant Public Officiel - de la DTD à laquelle le document se conforme. PUBLIC n'appartient pas au FPI, mais indique au processeur SGML comment trouver la DTD référencée par le FPI. Les autres façons de dire à l'analyseur SGML comment trouver la DTD sont données plus loin. > Retour au document. <foreignphrase>Formal Public Identifiers (FPIs)</foreignphrase> - Identifiants Publics Officiels Vous n'avez pas besoin de connaître ce qui suit, mais ce n'est n'est pas inutile, et cela peut vous aider à résoudre des problèmes, si votre processeur SGML ne trouve pas la DTD que vous utilisez. Les FPIs doivent respecter une syntaxe précise. La voici : "Propriétaire//Mot-Clé Description//Langue" Propriétaire Indique qui détient le FPI. Si la chaîne de caractères commence par “ISO”, c'est un FPI ISO. Par exemple, le FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" donne ISO 8879:1986 comme propriétaire du jeu d'entités pour les lettres grecques. ISO 8879:1986 est le numéro ISO du standard SGML. Sinon, cette chaîne sera de la forme -//Propriétaire ou +//Propriétaire (remarquez que la seule différence est le + ou - du début). Si la chaîne commence par un -, c'est que le propriétaire n'est pas enregistré, il l'est si elle commence par un +. L'ISO 9070:1991 définit comment sont générés les noms enregistrés ; ils peuvent dériver du numéro d'une publication ISO, d'un code ISBN ou d'un code d'organisation affecté selon l'ISO 6523. De plus, il pourrait y avoir une autorité d'enregistrement pour l'affectation de ces noms. Le conseil ISO a délégué cela à l'American National Standards Institute (ANSI) - Institut National Américain des Standards. Comme le Projet FreeBSD n'est pas enregistré, la chaîne utilisée est -//FreeBSD. Comme vous pouvez vous en rendre compte, le W3C n'est pas non plus un propriétaire enregistré. Mot-Clé Il y a plusieurs mots-clés qui définissent le type d'information dans le fichier. Les mots-clés les plus courants sont : DTD, ELEMENT, ENTITIES et TEXT. DTD ne sert que pour les DTD, ELEMENT sert habituellement pour les extraits de DTD qui ne contiennent que des entités ou des déclarations d'éléments. TEXT sert pour le contenu SGML (texte et marques). Description La description que vous souhaitez donner du contenu du fichier. Cela peut inclure des numéros de version et n'importe quel texte court qui ait un sens et soit unique au système SGML. Langue C'est une code ISO de deux caractères qui identifie la langue utilisée dans le fichier. Pour l'anglais, c'est EN. Fichiers <filename>catalog</filename> Si vous avez utilisé la syntaxe décrite plus haut et essayé d'utiliser un processeur SGML pour traiter votre document, il aura besoin de convertir le FPI en un nom de fichier sur votre ordinateur qui décrive la DTD. Vous pouvez pour cela vous servir d'un fichier catalogue (habituellement appelé catalog). Il contient des lignes qui donnent les correspondances entre FPIs et noms de fichiers. Par exemple, s'il y a la ligne : PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" le processeur SGML cherchera la DTD dans le fichier strict.dtd du sous-répertoire 4.0 où se trouve le fichier catalog qui comporte cette ligne. Jettez un oeil au fichier /usr/local/share/sgml/html/catalog. C'est le fichier catalogue pour les DTDs HTML qui ont été installées par le logiciel porté textproc/docproj. <envar>SGML_CATALOG_FILES</envar> Pour trouver un fichier catalog, votre processeur SGML doit savoir où chercher. La plupart d'entre eux ont des paramètres de leur ligne de commande pour donner le chemin d'accès à un ou plusieurs catalogues. Vous pouvez par ailleurs définir SGML_CATALOG_FILES pour désigner ces fichiers. Cette variable d'environnement doit contenir une liste de fichiers catalogues (donnés par leurs chemins d'accès complets) séparés par des points-virgules. Habituellement, vous incluerez les fichiers suivants : /usr/local/share/sgml/docbook/catalog /usr/local/share/sgml/html/catalog /usr/local/share/sgml/iso8879/catalog /usr/local/share/sgml/jade/catalog Alternatives aux FPIs Au lieu d'utiliser un FPI pour préciser la DTD utilisée (et donc le fichier qui contient la DTD), il est possible de donner explicitement le nom du fichier. La syntaxe pour le faire est légèrement différente : ]]> Le mot-clé SYSTEM indique que le processeur SGML doit localiser le fichier d'une façon qui dépend du système. Cela signifie habituellement (mais pas toujours) que la DTD sera définie par un nom de fichier. Il est préférable d'utiliser des FPIs pour des raisons de portabilité. Vous ne voulez pas livrer un exemplaire de la DTD avec votre document, et si vous avez utilisé l'identifiant SYSTEM, il faudra que chacun ait ses DTDs aux mêmes endroits. Revenir au SGML On a dit plus haut dans cette introduction que le SGML n'était utilisé que pour écrire les DTDs. Ce n'est pas tout à fait vrai. Il y a des éléments de la syntaxe SGML que vous voudrez pouvoir utiliser dans vos documents. Par exemple, vous pouvez y inclure des commentaires, qui seront ignorés par les analyseurs. Les commentaires sont inclus en utilisant une syntaxe SGML. D'autres utilisations du SGML dans les documents seront mentionnées plus loin. Il vous faut évidemment un moyen d'indiquer au processeur SGML que ce qui va suivre n'est pas constitué d'éléments du document, mais est du SGML que le processeur doit prendre en compte. Ces sections sont marqués avec <! ... > dans votre document. Tout ce qui se trouve entre ces délimiteurs est du code SGML comme on en trouve dans les DTDs. Comme vous venez peut-être de vous en rendre compte, la déclaration DOCTYPE est un exemple de syntaxe SGML que vous devez inclure dans votre document… Commentaires &sgml.todo; Les commentaires suivent une syntaxe SGML et ne sont normalement autorisés que dans une DTD. Cependant comme la le montre, il est possible d'inclure du SGML dans vos documents. Les délimiteurs pour les commentaires SGML sont constitués de la chaîne de caractères “--”. Une première occurence ouvre le commentaire, et la seconde le ferme. Commentaire SGML générique ]]> Utilisez 2 tirets Vous aurez un problème avec les versions PostScript et PDF de ce document. Les exemples précédents n'auront probablement qu'un simple tiret, - après <! et avant >. Il faut utiliser deux -, et non un seul. Les versions PostScript et PDF ont converti les deux - de l'original en un seul double tiret plus professionnel, et déformé l'exemple au passage. Les versions HTML, texte et RTF de ce document ne sont pas sujettes à ce problème. ]]> Si vous avez déjà utilisé HTML auparavant, on vous a peut-être donné des règles différentes pour les commentaires. En particulier, vous pensez peut-être qu'ils commencent par <!-- et ne se terminent qu'avec -->. Ce n'est pas le cas. Les analyseurs syntaxiques de nombreux navigateurs sont défectueux et acceptent cette syntaxe. Ceux qu'utilisent le Projet de Documentation sont plus rigoureux et rejetteront les documents qui comportent cette erreur. Commentaires SGML erronnés ]]> L'analyseur SGML traitera cela comme s'il trouvait : <!CE N'EST PAS EN COMMENTAIRE> Ce qui n'est pas du SGML valide et donnera des messages d'erreur source de confusion. ]]> Comme l'exemple le suggère, ne mettez pas de commentaires de ce type. ]]> C'est une (légèrement) meilleure idée, mais c'est toute de même une source de confusion potentielle pour les débutants en SGML. A faire… Ajoutez des commentaires à exemple.sgml et validez vos modifications avec &man.nsgmls.1; Ajoutez des commentaires incorrects à exemple.sgml, pour voir quels messages d'erreur produit alors &man.nsgmls.1;. Entités Les entités fournissent un mécanisme pour désigner des parties d'un contenu. Lorsque l'analyseur SGML traite votre document, il remplace les entités qu'il rencontre par le contenu de ces entités. C'est un bon moyen pour avoir du texte réutilisable et facile à modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML, un fichier marqué dans un autre. Il y a deux sortes d'entités SGML qui s'utilisent dans des situations différentes : les entités générales et les entités paramètres. Entités Générales Vous ne pouvez pas employer les entités générales dans un contexte SGML (bien que ce soit là que vous les définissiez). Elles ne peuvent être utilisées que dans votre document. Comparez cela au cas des entités paramètres. Chaque entité générale a un nom. Quand vous voulez y faire référence (et donc inclure le texte qu'elle contient dans votre document), vous mettez &nom-de-l'entité;. Supposons par exemple que vous ayez une entité appelée version.courante qui contienne le numéro de version courante de votre produit. Vous pourriez écrire : La version courante de notre produit est la &version.courante;.]]> Quand le numéro de version change, il vous suffit de modifier la définition de l'entité générale et de recompiler votre document. Vous pouvez aussi vous servir d'entités générales pour représenter des caractères que vous ne pouvez pas inclure autrement dans un document SGML. < et &, par exemple, ne doivent normalement pas apparaître dans un document SGML. Quand l'analyseur SGML rencontre un symbole <, il suppose qu'il précède une marque (de début ou de fin), et quand il rencontre un symbole &, il suppose que le texte qui le suit est le nom d'une entité. Heureusement, il y a deux entités générales, &lt; et &amp; pour le cas où vous auriez besoin d'inclure l'un ou l'autre de ces symboles. Une entité générale ne peut être définie que dans un contexte SGML. On le fait habituellement immédiatement après la déclaration DOCTYPE. Définition d'entités générales ]>]]> Remarquez que la déclaration DOCTYPE est suivie d'un crochet ouvrant à la fin de la première ligne. Les deux entités sont définies aux deux lignes suivantes, avant le crochet fermant. La déclaration DOCTYPE se termine ensuite. Les crochets sont nécessaires pour dire que nous ajoutons un complément à la DTD mentionnée par la déclaration DOCTYPE. Entités paramètres Comme les entités générales, les entités paramètres servent à nommer des parties réutilisables du texte. Cependant, alors que les entités générales peuvent être utilisées dans le corps du document, les entités paramètres ne peuvent être employées que dans un contexte SGML. Les entités paramètres sont définies de la même manière que les entités générales. Sinon qu'au lieu de vous servir de &inomd-de-l'entité; pour y faire référence, vous utiliserez %nom-de-l'entité; Les entités Paramètres employent le symbole Pourcent. . Leur définition comporte aussi un % entre le mot-clé ENTITY et le nom de l'entité. Définition d'entités paramètres ]>]]> Cela ne paraît peut être pas très utile. On verra pourtant que ça l'est. A faire… Définissez un entité générale dans exemple.sgml. ]> Exemple de fichier HTML

C'est un paragraphe avec du texte.

C'est encore un paragraphe avec du texte.

Ce paragraphe sera peut-être justifié à droite

La version courante de ce document est : &version;

]]> Validez le document avec &man.nsgmls.1; Chargez exemple.sgml avec votre navigateur (vous devrez peut-être le recopier dans exemple.html pour que votre navigateur le reconnaisse comme un document HTML). A moins que votre navigateur ne soit très évolué, il ne remplacera pas la référence &version; à l'entité par le numéro de version. Les analyseurs de la plupart des navigateurs sont élémentaires et ne gèrent pas correctement le SGMLC'est tout à fait dommage. Imaginez les problèmes et bricolages (comme les Server Side Includes) que cela éviterait.. La solution est de normaliser votre document avec un outil de normalisation du SGML. Ce type d'outil lit un document SGML valide et le transforme en un autre document SGML tout aussi valide. En particulier, il y remplace les références aux entités par leur contenu. Vous pouvez le faire avec &man.sgmlnorm.1;. &prompt.user; sgmlnorm exemple.sgml > exemple.html exemple.html doit maintenant contenir une version normalisée (i.e., où les références aux entités ont été remplacées par leur contenu) de votre document, prête à être affichée par votre navigateur. Si vous jetez un oeil au résultat de &man.sgmlnorm.1;, vous verrez qu'il ne comporte pas de déclaration DOCTYPE au début. Pour qu'elle y soit, utilisez l'option  : &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Utiliser les entités pour inclure des fichiers Les entités (générales et paramètres) sont particulièrement utiles pour inclure un fichier dans un autre. Utiliser les entités générales pour inclure des fichiers Supposons que le contenu d'un livre SGML soit découpé en fichiers, à raison d'un fichier par chapitre, appelés chaptitre1.sgml, chapitre2.sgml, et ainsi de suite, et que le fichier livre.sgml inclue ces chapitres. Pour que vos entités aient pour valeur le contenu de ces fichiers, vous les déclarerez avec le mot-clé SYSTEM. Cela indique à l'analyseur SGML qu'il doit utiliser le contenu du fichier mentionné comme valeur de l'entité. Utiliser les entités générales pour inclure des fichiers ]> &chapitre.1; &chapitre.2; &chapitre.3; ]]> Quand vous vous servez d'entités générales pour inclure d'autres fichiers dans un document, les fichiers inclus (chapitre1.sgml, chapitre2.sgml, et ainsi de suite) ne doivent pas commencer par une déclaration DOCTYPE. Ce serait une erreur de syntaxe. Utiliser les entités paramètres pour inclure des fichiers Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML. Quand aurez-vous besoin d'inclure un fichier dans un contexte SGML ? Vous pouvez vous en servir pour être sûr de pouvoir réutiliser vos entités générales. Supposons que votre document comporte de nombreux chapitres, et que vous réutilisiez ces chapitres dans deux livres différents, chacun organisant ces chapitres de façon différente. Vous pourriez donner la liste des entités en tête de chaque livre, mais cela pourrait rapidement devenit fastidieux à gérer. Mettez, au lieu de cela, les définitions des entités générales dans un fichier, et utilisez une entité paramètre pour inclure ce fichier dans votre document. Utiliser les entités paramètres pour inclure des fichiers Mettez d'abord les définitions de vos entités dans un fichier séparé, appelé chapitres.ent. Voici ce qu'il contiendra : ]]> Créez maintenant une entité paramètre qui fasse référence au contenu de ce fichier. Utilisez ensuite cette entité pour inclure le fichier dans votre document, vous pourrez alors y utiliser les entités générales. Ce que vous faites de la même façon que précédemment : %chapitres; ]> &chapitre.1; &chapitre.2; &chapitre.3; ]]> A faire… Utiliser les entités générales pour inclure des fichiers Créez trois fichiers, para1.sgml, para2.sgml et para3.sgml. Mettez-y quelque chose qui ressemble à ceci : C'est le premier paragraphe.

]]> Modifiez exemple.sgml de la façon suivante : ]> Exemple de fichier HTML

La version courante de ce document est : &version;

¶1; ¶2; ¶3; ]]> Générez exemple.html en normalisant exemple.sgml. &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.sgml ont bien été inclus dans exemple.html. Utiliser les entités paramètres pour inclure des fichiers Vous devez d'abord avoir mis en pratique l'exemple précédent. Modifiez comme ceci exemple.sgml : %entites; ]> Exemple de fichier HTML

La version courant de ce document est : &version;

¶1; ¶2; ¶3; ]]> Créez un nouveau fichier, entites.sgml, qui contienne : ]]> Générez exemple.html en normalisant exemple.sgml. &prompt.user; sgmlnorm -d exemple.sgml > exemple.html Affichez exemple.html avec votre navigateur Web et vérifiez que les fichiers paran.sgml ont bien été inclus dans example.html. Sections marquées SGML fournit un mécanisme pour définir quelles parties d'un document doivent être traitées de façon particulière. On appelle cela des “sections marquées”. Structure d'une section marquée <![ MOT-CLE [ Contenu de la section marquée ]]> Comme vous pouviez vous y attendre, une section marquée est une fonctionnalité SGML et commence donc par <!. Le premier crochet ouvrant délimite la section marquée. Le MOT-CLE définit comment cette section marquée doit être traitée par l'analyseur. Le second crochet ouvrant indique que le contenu de la section marquée commence là. La section marquée se termine par deux crochets fermants, puis un > pour indiquer que l'on quitte le contexte SGML et que l'on revient au document. Mots-clés pour les sections marquées <literal>CDATA</literal>, <literal>RCDATA</literal> Ces deux mots-clés définissent des sections marquées comme modèle de contenu et vous permettent de modifier sa valeur par défaut. Quand un analyseur SGML traite un docuemnt, il mémorise ce que l'on appelle le “modèle de contenu”. En bref, le modèle de contenu décrit ce que l'analyseur doit s'attendre à trouver comme contenu, et ce qu'il doit en faire quand il le rencontre. Les deux modèles de contenu que vous trouverez certainement les plus utiles sont CDATA et RCDATA. CDATA signifie “Character Data” - données caractères. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères, et uniquement des caractères. Les symboles < et & perdent alors leur signification particulière et sont traités comme de simples caractères. RCDATA signifie “Références à des entités et données caractères”. Si l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend à trouver des caractères et des entités. < perd sa signification particulière, mais & est toujours compris comme le début d'une entité générale. C'est particulièrement utile si vous incluez du texte qui contient de nombreux caractères < et &. Vous pourriez bien sûr contrôler que dans votre texte tous les < sont écrits &lt; et tous les & &amp;, il peut être plus facile de marquer la section comme ne contenant que des “CDATA”. Quand SGML rencontre l'instruction correspondante, il ignorera les symboles < et & qui apparaîtront dans le contenu. Utiliser une section marquée CDATA <para>Voici un exemple de la façon dont vous pourriez inclure un texte comportant de nombreux &lt; et &amp;. L'exemple lui-même est en HTML. Le texte qui l'encadre (<para> et <programlisting>) est du DocBook.</para> <programlisting> <![ CDATA [ Cet exemple vous montre quelques éléments de HTML. Comme les caractères < et > y sont si fréquemment utilisés, il est plus facile de marquer tout l'exemple comme CDATA plutôt que de se servir des entités à la place de ces caractères dans tout le texte.

  • C'est un élément de liste
  • C'est un second élément de liste
  • C'est un troisième élément de liste

C'est la fin de l'exemple.

]]> ]]> </programlisting> Si vous consultez le source de ce document, vous verrez qu'il utilise constamment cette technique. <literal>INCLUDE</literal> et <literal>IGNORE</literal> Si le mot-clé est INCLUDE, alors le contenu de la section marquée sera pris en compte. Si le mot-clé est IGNORE, alors la section marquée sera ignorée. Il n'apparaîtra pas dans les sorties. Utiliser <literal>INCLUDE</literal> et <literal>IGNORE</literal> dans les sections marquées <![ INCLUDE [ Ce texte sera traité et inclus. ]]> <![ IGNORE [ Ce texte ne sera pas traité ou inclus. ]]> En soi, cela ne sert pas à grand-chose. Si vous vouliez supprimer du texte de votre document, vous auriez pu l'enlever ou le mettre en commentaires. Cela devient plus utile quand vous comprenez que vous pouvez vous servir des entités paramètres pour contrôler ces sections. Rappelez-vous que les entités paramètres ne peuvent être utilisées que dans un contexte SGML, et une section marquée est un contexte SGML. Si par exemple, vous générez une version imprimée et une version électronique de votre document, vous pourriez vouloir inclure dans la version électronique un contenu supplémentaire qui ne devra pas apparaître dans la version imprimée. Créez une entité paramètre et donnez lui comme contenu INCLUDE. Rédigez votre document en utilisant des sections marquées pour délimiter le contenu qui ne doit apparaître que dans la version électronique. Dans ces sections marquées, servez-vous de l'entité paramètre au lieu du mot-clé. Lorsque vous voulez générer la version électronique, changez la valeur de l'entité paramètre en IGNORE et retraitez le document. Utiliser une entité paramètre pour contrôler une section marquée <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % version.electronique "INCLUDE"> ]]> ... <![ %version.electronique [ Ce texte ne doit apparaître que dans la version électronique du document. ]]> Pour générer la version imprimée, changez la définition de l'entité en : <!ENTiTY % version.electronique "IGNORE"> A la seconde passe sur le document, les sections marquées qui utilisent %version.electronique comme mot-clé seront ignorées. A faire… Créez un nouveau fichier, section.sgml, qui contienne : <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % text.output "INCLUDE"> ]> <html> <head> <title>Exemple d'utilisation des sections marquées</title> </head> <body> <p>Ce paragraphe <![ CDATA [contient de nombreux caractères < (< < < < <) il est donc plus facile de l'inclure dans une section marquée CDATA ]]></p> <![ IGNORE [ <p>Ce paragraphe n'apparaîtra jamais dans les sorties.</p> ]]> <![ [ <p>Ce paragraphe apparaîtra peut-être dans les sorties.</p> <p>Cela dépend de l'entité paramètre .</p> ]]> </body> </html> Normalisez le fichier avec &man.sgmlnorm.1; et examinez le résultat. Notez quels paragraphes ont été conservés et quels paragraphes ont été supprimés, et ce qu'est devenu le contenu des sections marquées CDATA. Modifiez la définition de l'entité sortie.texte de INCLUDE en IGNORE. Normalisez de nouveau le fichier et regardez ce qui a changé dans le résultat. Conclusion Ici se termine cette introduction à SGML. Pour des raisons de place et de complexité, de nombreux points ont été survolés (voire omis). Les sections qui précédent décrivent néanmoins suffisamment d'éléments du SGML pour vous permettre de comprendre comment est organisée la documentation du FDP. diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/tools/chapter.sgml b/fr_FR.ISO_8859-1/books/fdp-primer/tools/chapter.sgml index 378957ec2b..29b6d1e45a 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/tools/chapter.sgml +++ b/fr_FR.ISO_8859-1/books/fdp-primer/tools/chapter.sgml @@ -1,301 +1,301 @@ Outils Le FDP utilise un certain nombre de logiciels pour faciliter la gestion de la documentation de FreeBSD, la convertir en différents formats, et ainsi de suite. Vous devrez vous-même vous servir de ces outils, si vous travaillez à la documentation de FreeBSD. Tous ces outils existent sous forme de logiciels portés ou pré-compilés pour FreeBSD, ce qui vous simplifie beaucoup la tâche de leur installation. Vous devrez les installer avant de mettre en pratique les exemples donnés dans les chapitres suivants. Ces chapitres vous expliquent comment vous servir de ces outils. Utilisez <filename>textproc/docproj</filename> si possible Vous pouvez gagner beaucoup de temps si vous les installez avec textproc/docproj. C'est un méta-port qui ne contient pas lui-même de logiciels. Au lieu de cela, il dépend de l'installation correcte de divers autres logiciels portés. Son installation devrait télécharger et installer automatiquement tous les paquetages listés dans ce chapitre dont vous aurez besoin, s'ils n'existent pas déjà sur votre système. L'un des paquetages dont vous aurez peut-être besoin est le jeu de macro-instructions JadeTeX. Celui-ci, à son tour, a besoin que TeX soit installé. TeX est un paquetage volumineux, dont vous n'aurez besoin que si vous voulez générer les versions PostScript et PDF. Pour économiser du temps et de l'espace disque, vous pouvez préciser si vous voulez ou non installer JadeTeX (et donc TeX). Faites soit : &prompt.root; make JADETEX=yes install ou : &prompt.root; make JADETEX=no install selon le cas. Outils indispensables Logiciels Vous aurez besoin de ces programmes avant de pouvoir utilement travailler sur la documentation de FreeBSD. Ils font tous partie de textproc/docproj. SP (textproc/sp) Une série d'applications, dont un analyseur syntaxique SGML et un outil de normalisation du source SGML. Jade (textproc/jade) Une implémentation des DSSSL. Cela sert à convertir des documents marqués vers d'autres formats, dont HTML et TeX. Tidy (www/tidy) Un formateur HTML, qui sert à remettre en forme le code HTML généré automatiquement pour qu'il soit plus lisible. Lynx (www/lynx-current) Navigateur WWW en mode texte, &man.lynx.1; peut aussi convertir des fichiers HTML en fichiers texte. DTDs et Entités Ce sont les DTDs et jeux d'entités utilisés par le FDP. Il faut les installer avant de pouvoir travailler à la documentation. DTD HTML (textproc/html) HTML est le langage principal du World Wide Web, il est utilisé constamment par le site Web de FreeBSD. DTD LinuxDoc (textproc/linuxdoc) Une partie de la documentation de FreeBSD est marquée avec LinuxDoc. Le FDP migre activement de LinuxDoc à DocBook. DTD DocBook (textproc/docbook) DocBook est conçu pour le marquage de documentation technique et le FDP est en cours de migration de LinuxDoc à DocBook. A la date de rédaction de cette documentation, celle-ci et le Manuel de Référence de FreeBSD sont au format DocBook. Entités ISO 8879 (textproc/iso8879) 19 de jeux de caractères ISO 8879:1986 utilisés par de nombreuses DTDs. Cela comprend des symboles mathématiques nommés, les caractères “latins” supplémentaires (accents, signes diacritiques et ainsi de suite) et les lettres grecques. Feuilles de style Les feuilles de style sont utilisées pour convertir et formater la documentation pour l'affichage à l'écran, l'impression, et ainsi de suite. Les Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) Les Modular DocBook Stylesheets sont utilisées pour convertir la documentation marqué en DocBook aux autres formats, comme HTML ou RTF. Outils facultatifs Il n'est pas obligatoire d'installer les outils qui suivent. Si vous le faites cependant, vous trouverez peut-être plus facile de travailler à la documentation et ils vous donneront plus de possibilité de choix du format de sortie. Logiciels JadeTeX et teTeX (print/jadetex et print/teTeX) Jade et teTeX servent à convertir les documents DocBook en DVI, Postscript et PDF. Il faut pour cela les macro-instructions JadeTeX. Si vous n'avez pas l'intention de convertir votre documentation à l'un de ces formats (i.e., HTML, texte et RTF vous suffisent), il n'est pas nécessaire d'installer JadeTeX et teTeX. Cela vous fera gagner du temps et de l'espace disque, teTeX, en effet occupe plus de 30 Mo. Si vous choisissez d'installer JadeTeX et teTeX, vous devrez configurer teTeX après avoir installé JadeTeX. print/jadetex/pkg/MESSAGE vous donnera des instructions détaillées sur la façon de procéder. Emacs ou xemacs (editors/emacs ou editors/xemacs) Ces deux éditeurs ont un mode spécialisé pour travailler sur des documents marqués conformément à une DTD SGML. Cela vous permet d'avoir moins de choses à saisir et limite la possibilité d'erreurs. Vous n'êtes pas obligé de les utiliser, n'importe quel éditeur peut servir avec des documents marqués. Mais vous trouverez peut-être qu'ils vous permettent d'être plus efficace. Si quelqu'un a d'autres outils utiles pour manipuler des documents SGML, merci de transmettre l'information à Nik Clayton (nik@freebsd.org), de façon à ce qu'il les ajoute à cette liste. diff --git a/fr_FR.ISO_8859-1/books/fdp-primer/translations/chapter.sgml b/fr_FR.ISO_8859-1/books/fdp-primer/translations/chapter.sgml index ed8537589c..362a736305 100644 --- a/fr_FR.ISO_8859-1/books/fdp-primer/translations/chapter.sgml +++ b/fr_FR.ISO_8859-1/books/fdp-primer/translations/chapter.sgml @@ -1,497 +1,497 @@ Traductions Ceci est la Foire aux Questions pour les gens qui traduisent la documentation de FreeBSD (FAQ, Manuel de Référence, guides, pages de manuel et autres) en différentes langues. Elle est très largement basée sur la FAQ du Projet Allemand de Documentation de FreeBSD, rédigée à l'origine par Frank Grnder elwood@mc5sys.in-berlin.de et traduite en Anglais par Bernd Warken bwarken@mayn.de. Nik Clayton nik@FreeBSD.org maintient cette FAQ. Pourquoi une FAQ ? De plus en plus de gens s'adressent à la &a.doc; et se proposent de traduire en d'autres langues la documentation de FreeBSD. Le but de cette FAQ est de répondre à leurs questions de façon à ce qu'ils puissent commencer le plus rapidement possible à traduire la documentation. Que signfient i18n et l10n ? i18n veut dire internationalisation et l10n localisation. Ce ne sont que des abréviations commodes. i18n se lit “i” suivi de 18 lettres, suivies d'un “n”. De la même façon, l10n se lit “l” suivi de 10 lettres, suivies d'un “n”. Y-a-t-il une liste de diffusion pour les traducteurs ? Oui, freebsd-translate@ngo.org.uk. Inscrivez-vous en envoyant un message à freebsd-translate-request@ngo.org.uk avec le mot subscribe dans le texte du message. Vous recevrez une réponse vous demandant de confirmer votre inscription (de la même façon que pour les listes de FreeBSD sur FreeBSD.org). La langue de base sur la liste est l'Anglais, mais les messages en d'autres langues sont acceptés. La liste n'est pas modérée, mais vous devez vous y être inscrit avant d'y adresser des messages. La liste est archivée, mais il n'est pas actuellement possible d'y faire des recherches. Vous aurez en retour des explications sur la façon d'accéder aux archives en envoyant le message help à majordomo@ngo.org.uk. Il est prévue que la liste de diffusion soit transférée sur FreeBSD.org et devienne donc officielle dans un avenir proche. A-t-on besoin de nouveaux traducteurs ? Oui. Plus il y a de gens qui travaillent aux traductions, plus vite elles sont réalisées, et synchronisées avec les modifications de la version anglaise. Il n'est pas nécessaire que vous soyez traducteur professionnel pour pouvoir contribuer. Quelle langue faut-il que je connaisse ? Dans l'idéal, il faudrait que vous ayez une bonne connaissance de l'anglais écrit et bien sûr, il faut que vous pratiquiez couramment la langue dans laquelle vous traduisez. L'anglais n'est pas strictement indispensable. Vous pourriez par exemple effectuez une traduction en Hongrois, à partir de la traduction espagnole de la FAQ. Quels logiciels faut-il que je connaisse ? Il est fortement recommandé que vous teniez à jour une copie locale des archives CVS de FreeBSD (au moins de la documentation), soit à l'aide de CTM, soit en utilisant CVSup. Le chapitre “Se synchroniser avec la version -current de FreeBSD” du Manuel de Référence vous explique comment utiliser ces logiciels. Il faudra que vous soyiez à l'aise avec CVS. Cela vous permettra de suivre les modifications apportées entre les différentes versions des fichiers qui constituent la documentation. [A Faire -- écrire un mode d'emploi qui explique comment utiliser CVSup pour ne récupérer que la documentation, et voir ce qui a évolué entre deux versions données] Comment savoir qui d'autre traduit la documentation dans la même langue ? La page des traductions du Projet de Documentation liste les traductions en cours déjà connues. S'il y a déjà d'autres personnes qui travaillent à la traduction de documentation dans votre langue, s'il vous plaît, ne faites pas le même travail qu'eux en double. Au lieu de cela, prenez contact avec eux, pour savoir comment vous pouvez les aider. S'il la page n'indique personne qui travaille dans votre langue, envoyez un message à la &a.doc; au cas où quelqu'un aurait déjà envisagé de commencer une traduction, mais que ne ce soit pas encore signalé. Il n'y a personne d'autre qui traduise dans ma langue. Que faire ? Félicitations, vous venez juste de lancer le “Projet de Documentation dans-votre-langue de FreeBSD. Bien venu à bord. Commencez par vous assurer que vous avez bien du temps disponible. Comme vous êtes pour le moment le seul volontaire pour la traduction dans votre langue, il sera de votre responsabilité de publier votre travail et de coordonner celui d'autres personnes qui voudraient y collaborer. Envoyez un courrier électronique à la &a.doc; pour annoncer que vous allez traduire la documentation de façon à ce que la pages des traductions du Projet de Documentation puisse être tenue à jour. Il faudra vous inscrire à la liste de diffusion freebsd-translate@ngo.org.uk (comme expliqué plus haut). S'il y a déjà dans votre pays quelqu'un qui maintienne un site miroir de FreeBSD, vous devriez le contacter et voir s'il peut vous fournir un hébergement pour votre projet et, si possible, une adresse de courrier électronique et la possibilité de mettre en place une liste de diffusion. Choisissez ensuite une documentation et commencez la traduction. Il vaut mieux commencer par quelque chose de pas trop volumineux—soit la FAQ, soit l'un des guides. J'ai traduit une documentation, à qui dois-je l'envoyer ? Cela dépend. Si vous travaillez déjà au sein d'une équipe de traduction (comme l'équipe Japonaise ou l'équipe Allemande), elle aura ses propres procédures pour gérer la documentation soumise, qui seront décrites dans ses pages Web. Si vous êtes la seule personne à travailler dans une langue donnée (ou si vous êtes responsable d'un projet de traduction et voulez soumettre votre travail au Projet FreeBSD), vous devez alors l'envoyer au Projet FreeBSD (voir la question suivante). Je suis la seule personne à traduire dans cette langue, comment soumettre mes traductions ? ou Nous sommes une équipe de traduction et voulons soumettre les traductions de nos membres ? Commencez par vérifier que vos traductions sont correctement structurées. C'est-à-dire qu'elles doivent s'intégrer à l'arborescence des documentations existantes et compiler sans problèmes. La documentation de FreeBSD est actuellement archivée dans les répertoires en dessous de doc/. Les sous-répertoires de celui-ci prennent le nom codifiant la langue dans laquelle les documentations sont écrites, selon la norme ISO639 (/usr/share/misc/iso639, pour les versions de FreeBSD postérieures au 20 Janvier 1999). S'il ya a différentes codifications pour votre langue (le Chinois,par exemple), il y aura au niveau en-dessous plusieurs sous-répertoires, un pour chacun des formats de codage que vous aurez fournis. Vous aurez enfin des sous-répertoires pour chaque document. Une éventuelle traduction en Suédois ressemblerait par exemple à ce qui suit : doc/ sv/ Makefile FAQ/ Makefile *.sgml sv est le code ISO639 pour le Suédois. Remarquez les deux Makefiles, qui servent à compiler la documentation. Il n'y a qu'une seule façon de coder le Suédois, il n'y a donc pas de niveau intermédiaire entre les répertoires sv et FAQCette organisation va radicalement changer très bientôt. Suivez ce qui ce dit sur la &a.doc; pour plus d'information.. Utilisez &man.tar.1; et &man.gzip.1; pour compresser votre documentation, et envoyez-la au projet. &prompt.user; cd doc &prompt.user; tar cf swedish-docs.tar sv &prompt.user; gzip -9 swedish-docs.tar Mettez swedish-docs.tar.gz quelque part. Si vous ne disposez pas d'espace sur le Web (votre fournisseur d'accès n'en met peut-être pas à votre disposition), vous pouvez envoyer un courrier électronique à &a.nik;, pour vous mettre d'accord sur une date pour les lui envoyer par courrier. De quelque façon que vous procédiez, il faudra que vous utilisez &man.send-pr.1; pour envoyer un rapport signalant que vous avez soumis de la documentation. Il serait très utile que d'autres puissent relire votre traduction d'abord, parce qu'il y a peu de chances que la personne qui l'intégrera connaisse bien votre langue. Quelqu'un (probablement le Responsbale du Projet de Documentation, &a.nik; actuellement), récupérera votre traduction et s'assurera qu'elle compile. En particulier, les points suivants seront examinés : Tous vos fichiers utilisent-ils de chaînes RCS (comme “ID”). make all fonctionne-t-il correctement dans le répertoire sv. make install fonctionne-t-il correctement. S'il y a des problèmes, la personne qui examine votre soumission vous en fera part pour que vous essayiez de les régler. S'il n'y a pas de problèmes, votre traduction sera intégrée aussi vite que possible. Puis-je inclure dans mon texte des considérations propres à la langue ou au pays ? Nous préférerions que vous ne le fassiez pas. Supposons par exemple que vous traduisiez le Manuel de Référence en Coréen et que vous vouliez inclure une section sur les revendeurs en Corée dans votre Manuel. Il n'y a pas vraiment de raison pour que cette information ne soit pas aussi présente dans la version anglaise (ou allemande, espagnole, …). Il se peut qu'un anglophone ait besoin d'un exemplaire de FreeBSD alors qu'il se trouve en Corée. Cela permet aussi de mettre en avant la pénétration de FreeBSD dans le monde entier, ce qui n'est pas une mauvaise chose. Si vous avez des informations propres à un pays donné, soumettez-les d'abord sous forme de modifications à la version anglaise du Manuel de Référence (avec &man.send-pr.1;) et traduisez-les ensuite dans votre langue dans le Manuel de Référence dans cette langue. Merci. Comment faut-il coder les caractères propres à une langue ? Dans les documentations, les caractères Non-ASCII doivent apparaître sous forme d'entités SGML. Brièvement, celles-ci sont constituées d'une perluette (&), du nom de l'entité, et d'un point-virgule (;). Les noms des entités sont définis par la norme ISO8879, que vous trouverez dans le catalogue des logiciels portés, sous textproc/iso8879. Voici quelques examples : &eacute; é “e” accent aigu minuscule &Eacute; É “e” accent aigu majuscule &uuml; ü “u” tréma minuscule Après installation du logiciel porté “iso8879”, le fichier /usr/local/share/sgml/iso8879 en donne la liste complète. Comment doit-on s'adresser au lecteur ? Dans les documents anglais, le “you” est employé, il n'y a qu'une seule forme, à l'inverse d'autres langues. Si vous traduisez dans une langue qui dispose de plusieurs formes, utilisez celle que l'on emploie habituellement dans les documentations techniques. En cas de doute, servez-vous d'une forme de politesse courante. Y'a-t-il des informations supplémentaires à inclure dans les traductions ? Oui. Les en-têtes de la version anglaise du document ressembleront à ceci : ]]> La forme exacte peut changer, mais elles comporteront toujours la ligne “Id” et la phrase The FreeBSD Documentation Project. Vos traductions doivent comporter leur propre ligne “Id” et FreeBSD Documentation Project doit être remplacé par The FreeBSD Langue Documentation Project. Vous devrez aussi ajouter une troisième ligne qui donne la version anglaise d'origine sur laquelle est basée la traduction. Donc, la version espagnole du présent fichier commencerait par : ]]>