#title Tutoriel pour emacs-muse #bibsource /home/jean/BIB/biblio.bib * Muse, qu'est-ce? [[http://www.mwolson.org/projects/EmacsMuse.html][Muse]] est, essentiellement, un système d'édition et de publication de documents pour les utilisateurs d'emacs/xemacs -- système d'édition reposant sur une structure de wiki. Son principe est le suivant: on ouvre un fichier toto.muse dans emacs, et on saisit du texte avec un minimum de formatage; une fois le fichier prêt, on pourra par des commandes très simples créer des fichiers aux formats pdf, html, xhtml, xml ou texinfo; on peut d'ailleurs demander à muse de les créer tous à la fois dans le cadre de "projets". Les quelques indications qui suivent ne prétendent pas être un manuel complet, mais permettre une rapide (?) prise en mains de cet outil extrèmement puissant qu'est Muse. ** Installation et prérequis *** GNU-Emacs Muse est constitué d'un ensemble de fichiers écrits en Elisp (emacs-lisp). Aussi dès lors qu'Emacs est installé sur une machine, Muse peut y être installé aussi; Muse n'est limité à aucune plateforme, exactement comme emacs qui fonctionne sur tous les systèmes d'exploitation disponibles. Bien sûr Muse est conçu pour être utilisé à l'intérieur de GNU-Emacs, mais en réalité les fichiers et projets Muse peuvent très bien être édités dans tout autre éditeur de texte (vim, scite, etc.) Mais les commandes de publication de Muse ne peuvent passer que par Emacs, par exemple en mode batch. Voir plus loin pour des détails. On peut récupérer Muse sur le site ci-dessus, et il peut exister en paquet pour certaines distributions Linux (il existe par exemple un paquet pour les distributions debian et gentoo). L'installation "à la main" (en dehors des propositions de votre distribution) est d'une grande simplicité. *** Autres logiciels Selon les styles qu'on voudra utiliser, d'autres logiciels peuvent évidemment être requis, même s'ils ne sont pas indispensables pour l'installation de Muse. Ainsi pour produire des fichiers LaTeX il est évident qu'une distribution de LaTeX doit être présente; il en existe d'assez nombreuses, selon la plateforme: teTeX (Linux), TeXLive (multi plateforme), MikteX ou ProTeX sous Windows. Ces paquets permettront en général aussi de publier en utilisant une autre variante de TeX comme ConTeXt. Pour publier des fichiers xml on installera docbook (toutes plateformes). Pour utiliser certaines facilités d'intégration de graphiques, Imagemagick (toutes plateformes) sera nécessaire. ** Configuration emacs pour Muse Il suffit d'écrire quelques lignes dans le fichier .emacs, par exemple: (add-to-list 'load-path "") (require 'muse-mode) ; chargement du muse-mode (require 'muse-html) ; style html (require 'muse-latex) ; style latex (require 'muse-texinfo) ; style texi (require 'muse-docbook) ; style xml, etc. (require 'muse-project) ; publication par projets Une autre manière de faire consiste à créer un fichier de configuration spécifique pour Muse, nommé par exemple muse-init.el, où seront écrits tous les détails de configuration (ils peuvent vite devenir importants) y-compris ceux décrits ci-dessus, et d'écrire uniquement dans son .emacs (bien sûr le fichier muse-init.el doit se trouver dans le "load-path" d'emacs): (require 'muse-init) Ne pas négliger aussi l'utilisation des fonctions "customize" d'emacs, qu'on peut exploiter (dans notre cas) avec M-x customize-group RET muse RET * Projets et pages muse ** Un projet muse est un ensemble de fichiers ou "pages", présents dans un même répertoire, et auxquels on attache certains "styles". Muse permet de lier une page aux autres pages du même projet, de créer des propriétés d'hypertexte. On peut ensuite publier les pages individuellement, ou tout le projet à la fois (par une seule commande). Un projet Muse se définit comme ceci dans le fichier de configuration (setq muse-project-alist '(("Site web" ("~/Pages" :default "index") (:base "html" :path "~/public_html") (:base "pdf" :path "~/public_html/pdf")))) Dans cet exemple on définit un projet qu'on appelle "Site web", qui se trouve dans le répertoire "Pages" de l'utilisateur, avec comme page par défaut "index"; les deux lignes commençant par ":base" indiquent en premier lieu le style à utiliser, puis le répertoire où Muse devra mettre les fichiers qu'il a publiés: les fichiers html dans le répertoire "public_html", et les fichiers pdf dans "public_html/pdf". Si les fichiers html (par exemple, on pourra faire la même chose pour les fichiers pdf) doivent être téléchargés sur un site lointain, on peut demander à Muse de le faire directement; il suffira de définir le projet ainsi: (setq muse-project-alist '(("Site web" ("~/Pages" :default "index") (:base "html" :path "~/public_html") (:base "pdf" :path "/ftp:@:")))) Ici est votre nom d'utilisateur, est l'adresse du serveur ftp et est le répertoire de destination dans vos pages web. Si vous avez un fichier .netrc bien rempli (nom de machine, login et mot de passe), Muse se chargera du reste! ** Une page muse est un fichier muse qui pourra être exporté sous divers formats; on peut considérer que l'ensemble des fichiers issus du fichier muse constituent, avec celui-ci, une *page*. Si on édite aux styles xml et html, les trois fichiers muse, xml et html portant le même nom (par exemple toto.muse, toto.xml et toto.html) constituent la *page toto*. L'utilisateur n'a en principe qu'à éditer le fichier toto.muse. On peut avoir des pages muse ne dépendant d'aucun projet. Pour créer un telle page, il n'y a qu'à créer un fichier avec l'extension muse: C-x C-f toto.muse; si muse-mode est chargé, on sera alors automatiquement en mode muse (on lit Muse dans la modeline). * Fichier muse: directives, marques et tags Un fichier muse contient principalement votre texte à publier. Mais il y a aussi divers éléments, qui sont les indications que vous donnez à Muse, permettant de définir des sections et sous sections, listes, etc. ** Directives Le fichier muse devra *commencer* par les directives: elles définissent des propriétés de l'ensemble de la page: titre, auteur, etc; les directives de base s'écrivent: #author #title #date #desc #bibsource Toutes ces directives ne sont pas indispensables; les trois premières ont des valeurs par défaut, puisque emacs connaît votre nom et la date courante par exemple; donc si elles n'existent pas Muse écrira pour *auteur* la valeur de "user-full-name"; la valeur par défaut de *titre* est le nom de la page. Les deux dernières ne servent que dans des cas précis. Ne pas oublier que les directives s'écrivent comme ci-dessus (en début de ligne) et en haut du fichier. L'utilisateur peut définir de nouvelles directives si nécessaire. ** Marquage du texte Voici quelques-uns des moyens pour structurer votre texte (voir le manuel pour une liste complète): *** Section Ligne commençant par une étoile suivie d'une espace puis du titre de la section; en html ou xhtml on obtiendra un titre h2. Pour une section qu'on nomme Section, on écrira donc sur une ligne: * Section Bla bla bla.. *** Sous-section Ligne commençant par deux étoiles suivies d'une espace puis du titre de la sous-section; en html ou xhtml on obtiendra un titre h3. Avec trois étoiles on obtiendra une subdivision des sous-sections, etc. Pour une sous-section et une sous-sous-section: ** Sous-section Bli bli.. *** Sous-sous-section Blo blo.. *** Liste non numérotée Une espace en début de ligne, un tiret, une autre espace suivi du texte de l'item. - Item 1.... - Item 2.... *** Liste numérotée Une espace en début de ligne, un chiffre suivi d'un point, une autre espace suivi du texte de l'item. 1. Item 1.... 2. Item 2.... *** Mise en valeur d'un ou plusieurs mots (emphasize) Pour mettre un ou plusieurs mots en valeur, l'entourer (les entourer) d'une étoile de chaque côté: Je suis *très* fâché contre toi Le mot "très" apparaîtra la plupart du temps en italique, il se distinguera du reste du texte. *** Caractères gras Pour les caractères gras on entourera la partie désirée de deux étoiles de chaque côté: Je suis très **fâché** contre toi *** Notes On peut saisir un appel de note par: [1] puis, à la fin du fichier, on écrira: [1] Texte de la note On peut pour faire cela utiliser le footnote-mode d'emacs (s'en méfier légèrement tout de même, il a quelques défauts). *** Liens hypertexte On peut se référer à divers documents, comme: - d'autres pages du même projet - des images - des url Cela se fait en utilisant les parenthèse carrées; ainsi pour renvoyer à la page "tutu" appartenant au même projet que ma page "toto", j'écrirai: [[tutu]] Je peux me référer à cette page avec un nom différent de "tutu" (par exemple le titre que cette page montrera "Au pays de Tutu"): [[tutu][Au pays de Tutu]] Dans une page html ou pdf, on pourra cliquer sur les mots "Au pays de Tutu" pour ouvrir le document en question; et dans le mode muse d'emacs, dans le fichier toto.muse, si on a activé font-lock-mode, en plaçant le curseur sur les mots "Au pays de Tutu" et en appuyant sur RET on ouvre la page tutu. Pour une url le principe est le même: dans la première parenthèse carrée, on tape l'adresse, dans la seconde, le nom qu'on lui donne: [[http://www.mwolson.org/projects/EmacsMuse.html][Muse]] Appel d'une image qui se trouve dans le même répertoire que mon fichier toto.muse: [[emacs.jpg][Emacs]] ** Les tags Les tags que Muse reconnaît consistent en une commande particulière encadrée (généralement) par commande . Il existe de nombreux tags et comportant parfois des arguments (arg1, arg2, etc.); on écrit alors pour encadrer la commande: commande Voici quelques exemples de tags (voir le manuel pour la liste complète): La région à l'intérieur du tag est publiée telle quelle, non interprétée et en monospace. Placer une table des matières à cet endroit. Pour ce tag, la partie fermante n'existe pas. Interprète le code elisp entre ouverture et fermeture du tag. Ce qui est à l'intérieur est considéré comme citation. Le code à l'intérieur doit être du code TeX de mathématiques; les dérivés de TeX (LaTeX et ConTeXt) voient donc du code mathématique standard, pour les autres styles le code est transformé en image png et affiché. Utile pour les styles qui disposent d'une gestion des citations et des bibliographies (xml, LaTeX et ConTeXt). La commande est du code pgf, Muse fabriquera le graphique correspondant dans les styles html, xml, LaTeX et ConTeXt (Ce module est disponible pour l'instant sur le présent site, il sera peut-être intégré à Muse par la suite). * Exemples approfondis ** Tag mathématique Pour saisir une formule ou même un simple nom de variable mathématique, on utilisera le tag : je veux donner la définition du logarithme népérien; j'écrirai dans Muse: ln x = \int^x_t{\frac{dt}{t}} et j'obtiendrai ln x = \int^x_t{\frac{dt}{t}} Comme on le voit, la formule mathématique est codée en TeX, **sans les délimiteurs** qu'on est habitué à écrire dans un fichier LaTeX ou ConTeXt pour saisir une formule; Muse rajoute de lui-même le délimiteur "$" au début ou la fin de la formule pour pouvoir la compiler. Quand on veut que la formule apparaisse seule en milieu de ligne (et non à l'intérieur du texte), il suffit de commencer le tag math après au moins six espaces; ce mécanisme n'existe que pour les styles dérivés de TeX (il n'aura aucun effet en html par exemple): ln x = \int^x_t{\frac{dt}{t}} ** Tag tikz Le paquet pgf pour TeX permet de réaliser des graphiques qui sont définis dans le fichier source; voici un petit exemple: \draw (0,0) node(x) [draw] {XX} (2,0) node(y) {XY} (node cs:name=x) .. controls +(1,1) and +(-1,1) .. (node cs:name=y); \draw (0,0) node(x) [draw] {XX} (2,0) node(y) {XY} (node cs:name=x) .. controls +(1,1) and +(-1,1) .. (node cs:name=y); Pour que cet exemple fonctionne il faut récupérer le fichier muse-tikz2png.el qui se trouve [[muse-tikz2png.el][ici]] et l'installer avec les autres fichiers Muse, puis le charger; il faut aussi, bien sûr que votre distribution TeX (LaTeX et/ou ConTeXt) soit assez récente et complète pour que pgf y figure. ** Tag mpo Le tag mpo est pour ceux qui préfèrent metapost; il est opérationnel avec les styles contex et dérivés, html, xml **mais pas encore avec LaTeX**. Voici un exemple de code (extrait du manuel metafun.pdf de [[http://www.pragma-ade.com/][Pragma]]) à insérer dans le fichier muse: pickup pencircle scaled 1.5mm ; draw (origin -- dir(45) -- dir(0) -- cycle) scaled sqrt(2) scaled 3cm withcolor .625red ; draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle) scaled sqrt(2) scaled 3cm shifted (4.5cm,0) withcolor .625yellow ; draw (origin -- (1,1) -- (1,0) -- cycle) scaled 3cm shifted (9cm,0) withcolor .625white ; et le résultat: pickup pencircle scaled 1.5mm ; draw (origin -- dir(45) -- dir(0) -- cycle) scaled sqrt(2) scaled 3cm withcolor .625red ; draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle) scaled sqrt(2) scaled 3cm shifted (4.5cm,0) withcolor .625yellow ; draw (origin -- (1,1) -- (1,0) -- cycle) scaled 3cm shifted (9cm,0) withcolor .625white ; Pour que cet exemple fonctionne il faut récupérer le fichier muse-pmotopng.el qui se trouve [[muse-mpotopng.el][là]] et l'installer avec les autres fichiers Muse, puis le charger; il faut aussi, bien sûr que votre distribution TeX (LaTeX et/ou ConTeXt) soit assez récente et complète pour que metapost y figure. ** L'argument caption Dans ces deux exemples, on voit l'argument "caption"; pour les styles latex et contex et dérivés, si le tag commence après six espaces au moins sur une ligne (sans autre texte avant), cela créera un float et le texte de "caption" apparaîtra sous le graphique. dans les styles html et dérivés, le texte est dans le graphique pour le tag tikz, et est oublié avec mpo. * Commandes de base de Muse Quand on édite un fichier muse, la première chose à faire est d'appeler le mode muse (si vous n'avez pas commandé à emacs de le faire automatiquement; c'est la variable muse-mode-auto-p dont la valeur de défaut est "off"). Vous disposez alors de commandes propres à ce mode dont les plus souvent utilisées sont (pour moi): `C-c C-i t, C-c TAB t (`muse-insert-tag')' Insertion d'un tag (interactive). `C-c C-i u, C-c TAB u (`muse-insert-url')' Insertion d'une URL (interactive). `C-c C-l (`font-lock-mode')' Activer ou désactiver le mode font-lock pour le buffer courant. `C-c C-p (`muse-project-publish')' Publier les pages Muse qui ont changé. `C-c C-s (`muse-search')' Recherche de texte dans tous les fichiers du projet courant. `C-c C-t (`muse-project-publish-this-file')' Publier le fichier visité. S'il y a plusieurs styles possibles emacs vous demandera le style à utiliser. Bien sûr, vous devrez regerder le manuel pour en savoir plus, mais c'est une base déjà utile. * Pour finir Il ne vous reste qu'à tester si je vous ai, ne serait-ce qu'un peu, convaincu(e); le fichier muse dont vous voyez le résultat publié en html se trouve [[tuto.muse][à cet endroit]]. Vous pouvez l'utiliser comme premier test; n'oubliez pas de retirer l'exemple du tag mpo si vous essayez de publier avec le style latex.