--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/HACKING Mon Dec 26 19:21:22 2005 -0500
@@ -0,0 +1,140 @@
+On Mon, Apr 23, 2001 at 11:57:49PM +0200, Jean-Luc et Anna-Maria Donnadieu wrote:
+> > Je fais tout à partir du XML à la place: il y a plus de souplesse ainsi
+> > et j'ai jamais trop apprécié les logiciels de transformations
+> > tex->html... c'est généralement du bizounage pas très solide.
+> >
+> > Pour information (attention, je deviens technique là), voici un peu
+> > l'arbre de transformations:
+> >
+> > XML+DSL -->{jade}--> HTML -->{HTML2TEXT}--> Text
+> > | +-> {html2ps} --> PS
+> > +-> TeX --> {jadetex} --> DVI -->{dvips} --> PS
+> > | +-> PDF -->{ps2pdf}--> PS
+> > +-> RTF
+> >
+> > Ça demande toutefois pas mal de matériels installés:
+> > ...
+> > apt-get install task-sgml make w3m xfig gs
+> > ...
+>
+> Je me suis mis a la debian, et je vais essayer d'utiliser jade. Mais
+> j'ai du mal a debuter. J'ai telecharge les sources des arpeges, j'ai
+> tape make, et j'ai tout un tas de formats qui ont ete generes, c'est
+> super !
+> Maintenant, j'ai du pain sur la planche pour comprendre le
+> fonctionnement ;-)
+
+Tout est dans le fichier Makefile.rules qui peut-être pratiquement
+utilisé comme tel pour un autre projet similaire. Tu y trouveras les
+lignes de commandes nécessaire pour faire les transfo. Avec le schéma
+ci-dessus, tu devrais être capable de t'y retrouver... Et rappelle-toi,
+man et /usr/share/doc/package sont tes amis!
+
+L'autre partie de la magie est dans les fichiers .dsl et dans le
+répertoire dtd. Voici une petite description de chacun:
+
+print.dsl: Fichier DSSSL contenant les instructions pour formatter
+les éléments XML dans une version imprimable (TeX, PS, PDF). C'est du
+scheme principalement, avec quelques primitives supplémentaires. Ca
+vaut la peine de lire la doc fourni dans le paquet
+docbook-stylesheets-doc pour s'y retrouver un peu. Il donne un bon
+exemple sur comment ajouter un formattage spécial lorsqu'on ajoute un
+élément à Docbook (en l'occurence les éléments complist et comp).
+
+html.dsl: Meme chose que print.dsl, mais comme le html est une forme de
+SGML (comme le XML), c'est plus des instructions de transformations
+(transformer un <emphasize>...</emphasize> en <em>...</em>). Le
+principe est donc un peu différent. Même paquet pour la doc.
+
+arpeges.dtd: Fichier principal qui se contente d'inclure les autres DTD
+(Document Type Description). C'est ça qui va définir qu'est-ce qui est
+permis et qu'est-ce qui l'est pas.
+
+comp.dtd: Ajout des éléments complist et comp à docbook. Un bon
+exemple de comment augmenter docbook avec ces propres définitions. Le
+paquet docbook-doc donne plus d'infos là-dessus, ainsi que Docbook, the
+definitive guide chez O'Really (aussi disponible sur le net sur
+www.docbook.org!). Le livre est une excellente référence.
+
+struct.dtd: Définition des fichiers des Arpèges. Dans la version
+courante, tu retrouveras une inclusion conditionnelle: c'est la version
+simplifié des arpèges, dans laquelle de nombreux fichiers sont exclus
+(simplement en les faisant pointer vers /dev/null). Note que tu peux
+définir deux fois la même entité mais seule la PREMIÈRE définition (pas
+de redéfinition possible!) est prise en compte (ce qui permet de faire
+un parser en une seule passe)... C'est pourquoi l'ordre d'inclusion est
+très important.
+
+terms.dtd: Définition d'abbréviations. En fait, très peu sont des
+abbréviations... Ce sont plus des termes que je veux garder afin de les
+retrouver plus facilement s'il change. J'ai mis quelques abrégés connus
+(&mj; => meneur du jeu) mais l'expérience m'a montré qu'à la longue,
+c'était bon d'éviter d'en faire trop et que c'était plus facilement
+lisible ainsi. De plus, avec un éditeur comme Emacs et le mode PSGML,
+c'est pas plus long à écrire. La touche miracle? Ctrl-/ qui complète
+un mot à partir des mots déjà écrit. Par exemple, si tu as déjà écrit
+une fois &Competence;, tu n'as qu'à faire &Com<CTRL-/> et il va te
+trouver la première occurence d'un mot qui commence par &Com... Si c'est
+pas le bon, C-/ à nouveau et tu passes au suivant. Chouette, n'est-ce
+pas. Si tu préfères Vim, dans le mode d'insertion, c'est C-N (en mode
+insertion) qui fait un truc semblable. ':help completion' pour les
+autres raccourcis.
+
+Le reste, c'est du SGML bien standard, du texte.
+Toutefois, j'avoue sans humilité que les Arpèges sont un exemple
+intéressant des capacités des Arpèges.
+
+> Connais-tu une bonne adresse pour trouver de la doc ?
+
+Pour le XML, XMLfr.org est excellent et contient beaucoup de tutoriels
+en français. Par contre, ça parle beaucoup des XPath, XSL et tout le
+reste, dont les outils sont encore plutôt bêta (et principalement en
+Java en plus; très lourd pour ma machine donc). Même chose pour
+www.xml.org et www.w3.org. Le paquet wdg-html-reference contient
+plusieurs des documents (standards) qu'on retrouve sur le site de
+w3.org. Mais c'est un peu lourd parfois comme lecture. À utiliser plus
+comme référence.
+
+J'utilise présentement du DSSSL pour les Arpèges qui est du Scheme avec
+des primitives pour l'impression. Le site de Normand Walsh
+(www.nwalsh.com) et celui de James Clark (www.jclark.com) contiennent
+beaucoup d'infos et tutoriel à ce niveau mais la spec elle-même est peu
+digestible. Si tu as le courage et que tu es prêt à faire des
+tentatives, Norman Walsh a déjà un docbook-stylesheets en XSL ainsi que
+des instructions à ce sujet sur son site. D'excellents livres à ce
+sujet ainsi que sur le XML. J'ai bien apprécié the XML companion ainsi
+que the XSL companion chez Addison Wesley. Ce dernier peut aussi
+fournir une bonne introduction au modèle de mise-en-page utiliser pour
+le DSSSL (et les CSS) puisque c'est pratiquement le même avec des
+primitives presque identiques. Il y'a aussi the XML Blackbook chez
+Coriolis qui semble aussi bien fourni.
+
+Finalement, il y a aussi le site de openjade.sourceforge.net. Je n'ai
+toutefois pas encore essayé ce dernier mais les dernières nouvelles (qui
+sont quand même assez vieille) indiqué l'introduction de quelques
+incompabilité avec jade standard... c'est donc à tes risques.
+
+>
+> Jean-Luc
+
+
+Bonne chance! Moi, il me reste juste à mettre tout ça dans un fichier
+HACKING pour ne pas avoir à le réécrire la prochaine fois ;) A+ et
+bienvenue sur Debian...
+
+En passant, si tu as upgradé sur woody, un petit package bien cool et
+pratique pour faire le ménage: debfoster... ça ajoute le petit rien qui
+manquait à apt pour en faire mon package tool de rêve. C'est d'ailleurs
+probablement recompilable sur potato (dépendance sur libc seulement)...
+Faudrait que j'y vois. http://packages.debian.org/debfoster pour plus
+d'infos.
+
+Fabien
+
+--
+-------------------------------* *-------------------------
+Fabien Niñoles / / fabien@tzone.org
+Chevalier Servant de Sa Dame / / C15D FE9E BB35 F596 127F
+Veneur Gris par la Clef / / BF7D 8F1F DFC9 BCE0 9436
+Développeur pour Debian / / http://www.tzone.org/~fabien
+--------------------------* *------------------------------