#author John Wiegley et Michael Olson (traduction Jean Magnan de Bornier)
#title Premiers pas avec Emacs-Muse


<contents>


Emacs-Muse est un environnement d'écriture et de publication pour Emacs.
Il simplifie le processus d'écriture et de publication de documents sous
divers formats.

Muse consiste en deux parties principales: un mode d'édition de texte pour
un écriture de documents et la navigation à l'intérieur des projets Muse, 
et un ensemble de styles de publication pour créer différentes sortes de
produits finals.



* Ce document
Ce document fournit un exemple de marquage de texte par Muse
et fonctionne aussi comme une initiation à Muse.

Pour visualiser à quoi qu'il ressemblera publié, saisissez =make
examples=. Vous obtiendrez alors un document info, un document HTML, et un
document PDF (à condition qu'une distribution de LaTeX soit installée avec
les fontes nécessaires).
 
* Pour commencer 

Pour utiliser Muse, on ajoutera le répertoire contenant les fichiers muse à la
variable =load-path= de votre fichier =.emacs= . Ensuite on charge le =muse-mode= et les styles dans lesquels on souhaite publier. Par exemple :
 
<example>
(add-to-list 'load-path "<chemin où est Muse>")

(require 'muse-mode)     ; chargement du mode écriture

(require 'muse-html)     ; chargement des styles de publication qu'on utilise
(require 'muse-latex)
(require 'muse-texinfo)
(require 'muse-docbook)

(require 'muse-project)  ; publication par projets
</example>

Une fois que ceci aura été chargé, la commande =M-x muse-publish-this-file=
publiera le document saisi dans n'importe quel des styles disponibles. Si
vous validez =muse-mode= à l'intérieur d'un tampon (buffer), en tapant =M-x
muse-mode=, cette commande sera accessible avec =C-c C-t=.

* Création d'un projet Muse 
On veut souvent publier de manière automatique tous les fichiers d'un
certain dossier avec un ensemble particulier de styles. Muse permet pour
cela la création de «projets». Voici un exemple de projet à définir dans
votre fichier =.emacs= :

<example>
(setq muse-project-alist
      '(("website" ("~/Pages" :default "index")
         (:base "html" :path "~/public_html")
         (:base "pdf" :path "~/public_html/pdf"))))
</example>

Par les lignes ci-dessus en définit un projet nommé "website", dont les
fichiers se trouvent dans le dossier =~/Pages=.  La page à visiter par
défaut est =index=. Quand ce projet sera publié, chaque page sortira en
format HTML dans le dossier =~/public_html=, et comme PDF dans le dossier
=~/public_html/pdf=.  Dans une page appartenant à un projet, vous pouvez
créer un lien à d'autres pages en utilisant la syntaxe =[[nom_de_la_page]]=.

* Règles de marquage 

Un document Muse utilise des règles spéciales de marquage contextuel pour
déterminer comment formater le résultat final. Par exemple, si un
paragraphe est indenté, Muse suppose qu'il doit être mis en citation.

Il n'y a pas énormément de règles de marquage, et on a essayé qu'elles
soient aussi simples que possible pour que l'utilisateur puisse se
concentrer sur la création de son document plutôt que sur sa mise en
forme.  

** Paragraphes

Dans Muse on sépare les paragraphes par une ligne blanche.

Par exemple, le texte de cette section est saisi comme ceci: 
<example>
Dans Muse on sépare les paragraphes par une ligne blanche.

Par exemple, le texte de cette section est saisi comme ceci: 
</example>

** Paragraphes centrés et citations 

Une ligne qui commence par six ou plus colonnes ou espaces (qu'il s'agisse
de tabulations ou d'espace) indique un paragraphe centré.


                           Ceci est centré

   Mais quand une ligne commence par une espace de moins de six colonnes,
   cela indique un paragraphe de citation.
 
** En-têtes 

Un en-tête devient le titre d'un chapitre ou d'une section dans le document
final -- en fonction du style. Pour indiquer un en-tête, on commence un
nouveau paragraphe par un, deux ou trois astérisques, suivi d'une espace
et du titre. Puis on commence un autre paragraphe pour saisir le texte
de cette section.

<example>
* Premier niveau

** Second niveau

*** Troisième niveau
</example>

** Lignes horizontales

Quatre tirets ou plus indiquent une ligne horizontale. Attention à ne pas
oublier de les entourer de lignes blanches, faute de quoi ils seraient
considérés comme appartenant au paragraphe précédent ou suivant!

-----

Le séparateur ci-dessus a été produit en saisissant ceci :
<example>
-----
</example>

** Emphase ou magnification du texte

Pour mettre l'emphase sur du texte, on l'entoure de certains caractères
spécifiques :

<example>
*emphase*

**emphase forte**

***emphase très forte***

_soulignage_

=verbatim et monospace =
</example>

La liste ci-dessus apparaîtra comme ceci :

<verse>
*emphase*

**emphase forte**

***emphase très forte***

_soulignage_

=verbatim et monospace =
</verse>

** Insérer des notes de bas de page

Une note de bas de page sera appelée simplement par le nombre entre les
parenthèses carrées <verbatim>[1]</verbatim>.[1]. Pour saisir la note,
placer son texte à la fin de votre fichier.  =footnote-mode= peut être
utilisé pour faciliter grandement la création de ce type de note.

 <example>
 Footnotes:

 [1] Des notes de bas de page sont identifiées par le même nombre entre
 des parenthèses carrées en début de ligne. On peut utiliser la commande
 C-c ! a du footnote-mode pour insérer des notes de bas de page en
 saisissant du texte.  C-x C-x permet de revenir au point d'insertion.

</example>

** Les vers

Pour la poésie il faut que les espaces soient conservées, sans pour autant
utiliser le monospace. Pour indiquer cela, on utilise le marquage suivant,
qui rappelle les citations dans le courrier électronique :

<example>
>           HERNANI, *faisant un pas*
>                                             Sire,
> La chose est toute simple,et l'on peut vous la dire.
> Nous gravions la sentence au mur de Balthazar.
>           *Il tire un poignard et l'agite*
> Nous rendions à César ce qu'on doit à César.
>           DON CARLOS
> Bien!
>           *À don Ruy Gomez*
>       Vous traître, Silva!
>           DON RUY GOMEZ
>                            Lequel de nous deux, Sire?

</example>

Le paragraphe ci-dessus apparaîtra ainsi:

>           HERNANI, *faisant un pas*
>                                             Sire,
> La chose est toute simple,et l'on peut vous la dire.
> Nous gravions la sentence au mur de Balthazar.
>           *Il tire un poignard et l'agite*
> Nous rendions à César ce qu'on doit à César.
>           DON CARLOS
> Bien!
>           *À don Ruy Gomez*
>       Vous traître, Silva!
>           DON RUY GOMEZ
>                            Lequel de nous deux, Sire?


(Victor Hugo: **Hernani**, IV, 4)


On peut aussi utiliser le délimiteur =<literal><verse></literal>= si on préfère :

<example>
<verse>
           HERNANI, *faisant un pas*
                                             Sire,
 La chose est toute simple,et l'on peut vous la dire.
 Nous gravions la sentence au mur de Balthazar.
           *Il tire un poignard et l'agite*
 Nous rendions à César ce qu'on doit à César.
           DON CARLOS
 Bien!
           *À don Ruy Gomez*
       Vous traître, Silva!
           DON RUY GOMEZ
                            Lequel de nous deux, Sire?
</verse>
</example>

** Paragraphes sous forme littérale

Le délimiteur =<literal><example></literal>= est utilisé pour des exemples,
quand on doit conserver les espaces, avec texte en monospace et où les
caractères spéciaux ne doivent pas être interprétés .

Il y a aussi le délimiteur =<literal><literal></literal>= qui fait qu'un
bloc marqué sera laissé entièrement de côté. On peut utiliser cela
pour insérer des blocs de code HTML quand le format final est le HTML.

Si l'on veut qu'une partie de texte ne soit insérée que quand on publie
dans un format particulier on peut utiliser l'attribut =style= du délimiteur
=<literal><literal></literal>=. Voici quelques exemples.

<example>
Vous lisez la version 
<literal style="html">HTML</literal>
<literal style="pdf">PDF</literal>
<literal style="info">Info</literal>
de ce document.
</example>

Produit ceci:

Vous lisez la version 
<literal style="html">HTML</literal>
<literal style="pdf">PDF</literal>
<literal style="info">Info</literal>
de ce document.

<example>
<literal style="context">
ConTeXt a été utilisé pour publier ce document.
</literal>
</example>

Produit:

<literal style="context">
ConTeXt  a été utilisé pour publier ce document.
</literal>

** Listes

Les listes seront obtenues en utilisant des caractères spéciaux en début
de ligne. Une espace doit être insérée avant les éléments d'une liste
numérotée ou non, pour éviter la confusion avec l'utilisation habituelle
de ces caractères.

Les types de listes reconnus sont les suivants:

<example>
  -premier élément d'une liste non numérotée
  -deuxième élément d'une liste non numérotée

  1. premier élément d'une énumeration
  2. deuxième élément d'une énumeration

Terme1 :: Description d'un premier élément

Terme2 :: Description d'un deuxième élément
</example>

Ces listes apparaîtront ainsi:

Liste non numérotée:

  -premier élément d'une liste non numérotée
  -deuxième élément d'une liste non numérotée

Énumération:

  1. premier élément d'une énumeration
  2. deuxième élément d'une énumeration

Définition:

Terme1 :: Description d'un premier élément

Terme2 :: Description d'un deuxième élément


Les listes peuvent être imbriquées l'une dans l'autre. Le niveau de l'imbrication est indiqué par la quantité d'espace en tête de ligne. 

<example>
 - Premier niveau, élément non numéroté 1
   1. Deuxième niveau, élément numéroté 1
   2. Deuxième niveau, élément numéroté 2
 - Premier niveau, élément non numéroté 2
</example>

Ce qui apparaîtra ainsi :

 - Premier niveau, élément non numéroté 1
   1. Deuxième niveau, élément numéroté 1
   2. Deuxième niveau, élément numéroté 2
 - Premier niveau, élément non numéroté 2
 
** Tableaux

Muse peut traiter des tableaux simples. La syntaxe est la suivante : 
<example>
  Double barre verticale  || Séparation des champs d'en-tête 

  Barre verticale unique   | Séparation des champs du corps du tableau 
  D'autres                 | Éléments du corps

  Triple barre verticale ||| Séparation des champs du pied du tableau 
</example>

Ce qui sera rendu ainsi[2]:

 Double barre verticale  || Séparation des champs d'en-tête 

  Barre verticale unique  | Séparation des champs du corps du tableau 
  D'autres                | Élément du corps
  Triple barre verticale||| Séparation des champs du pied du tableau 

On peut aussi présenter les tableaux comme ceci :

<example>
| Barre verticale unique | Séparation des champs du corps du tableau |
| D'autres               | Élément du corps                          |
 </example>

Ce qui sera rendu ainsi : 


| Barre verticale unique | Séparation des champs du corps du tableau |
| D'autres               | Élément du corps                          |

  

Pour ceux qui sont familiers avec les tableaux dans le style Org-mode, des
variantes simples (sans colonnes groupées ni formules autogénérées) seront
prises en compte correctement.  De même, les tableaux du style table.el
seront publiés à condition que le format de publication soit connu de
table.el.

** Balises et liens délimités

#exemple Si vous commencez une ligne par "#balise" -- où "balise"
peut-être n'importe quel mot ne contenant pas d'espace -- cela définit une
balise à ce point du document. Ce point pourra ensuite être référencé en
utilisant "page# balise" comme un cible dans un lien Muse (voir plus bas).

Cliquer [[#exemple][ici]] pour revenir au paragraphe précédent.

** URLs et adresses électroniques

Une URL ou une adresse e-mail rencontrée dans le texte est publiée comme un
lien hypertexte si le style utilisé pour la publication le permet. Par
exemple, la dernière version de Muse peut être téléchargée à l'adresse
http://download.gna.org/muse-el et du courrier peut être envoyé à
mwolson@gnu.org.

** Images

Si une URL a comme extension celle d'un format d'image connu, elle sera
affichée si possible. Pour créer un lien à une image plutôt que de
l'afficher, mettre le texte "URL:" immédiatement devant le lien.

Voici un exemple d'image affichée :

<example>
Produit avec [[muse-made-with.png]] Emacs Muse.
</example>

Ce sera publié ainsi :

Produit avec [[muse-made-with.png]] Emacs Muse.

Voici un exemple d'image avec légende :

<example>
[[emacs-muse.png][Muse, l'outil de publication (d'un sous-ensemble) des grands penseurs]]
</example>

Qui sera publié ainsi :

[[emacs-muse.png][Muse, l'outil de publication (d'un sous-ensemble) des grands penseurs]]

Ce qui suit sera publié uniquement sous forme de lien.

<example>
Le logo Muse: [[URL:http://mwolson.org/static/logos/emacs-muse.png]].
</example>

Le logo Muse: [[URL:http://mwolson.org/static/logos/emacs-muse.png]].

** Liens

Un hyperlien peut référencer une URL, ou une autre page à l'intérieur
d'un projet Muse.  De plus, un texte descriptif peut être spécifié, il
sera affiché plutôt que le lien pour les styles qui acceptent les
descriptions de lien. La syntaxe est la suivante : 

<example>
[[lien cible][description]] [[lien cible sans description]] 
</example>

Donc le texte:

<example>
Muse peut être téléchargé[[http://download.gna.org/muse-el/][ici]], ou ici :
[[http://download.gna.org/muse-el/]].
</example>

Sera publié comme ceci :

Muse peut être téléchargé [[http://download.gna.org/muse-el/][ici]], ou ici :
[[http://download.gna.org/muse-el/]].

** Code source

Si htmlize.el (version 1.34 ou postérieure) est installé sur votre machine,
il est possible de publier du HTML colorisé pour le code source de tout
mode majeur supporté par Emacs en utilisant le délimiteur
=<literal><src></literal>=.  Si le style de publication n'est pas le HTML,
le texte entre les délimiteurs est traité comme s'il y avait un délimiteur
=<literal><example></literal>=.

Voici un exemple de code C.  Muse cheche l'élément =lang= et lui ajoute
="-mode"= pour déterminer quel mode majeur doit être utilisé pour la
colorisation du code.

<example>
<src lang="c">
#include <stdlib.h>

char *unused;

int main (int argc, char *argv[])
{
    puts("Hello, world!\n");
}
</src>
</example>

Voici le résultat colorisé. Son apparence peut varier si vous avez
configuré certaines faces.

<src lang="c">
#include <stdlib.h>

char *unused;

int main (int argc, char *argv[3])
{
    puts("Hello, world!\n");
}
</src>

** Lisp, Perl, Ruby, Python, ou Shell embarqué

Des types de marquage arbitraires peuvent être réalisés grâce au délimiteur
=<literal><lisp></literal>=, le seul des délimiteurs Muse supporté dans
le texte d'en-tête ou de bas de page d'un style. Avec le
délimiteur =<literal><lisp></literal>=, on peut générer n'importe quel texte
final.  Le produit du code sera marqué si le délimiteur
=<literal><lisp></literal>= apparaît dans le corps du texte.

<example>
<lisp>(concat "Cette forme sera " "inserée")</lisp>
</example>

Ce code sera rendu ainsi: 


<lisp>(concat "Cette forme sera " "inserée")</lisp>


On peut aussi traiter le résultat comme s'il était à l'intérieur d'un des
délimiteurs =<literal><example></literal>=, =<literal><src></literal>=, ou
=<literal><verse></literal>= , en spécifiant ="example"=, ="src"=, ou
="verse"= comme attribut =markup= du délimiteur.

Par exemple:

<example>
<lisp markup="example">
(concat "Inserez" " moi")
</lisp>
</example>

Le résultat est:

<lisp markup="example">
(concat "Inserez" " moi")
</lisp>


Cet attribut =markup=  peut aussi être passé aux délimiteurs
=<literal><perl></literal>=, =<literal><ruby></literal>=,
=<literal><python></literal>=, and =<literal><command></literal>= ,
qui interprètent respectivement les codes Perl, Ruby, Python, Shell.

* Styles de publication

Une des caractéristiques majeures de Muse est sa capacité à publier un
simple texte de départ dans une variété de styles à l'arrivée.  Muse
permet aussi facilement de créer de nouveaux styles, ou d'en dériver à
partir de ceux qui existent.

** Dériver à partir d'un style existant

Pour créer un nouveau style à partir d'un style existant, on utilise la fonction =muse-derive-style=:

<example>
(muse-derive-style NOM-DÉRIVÉ NOM-DE-BASE PARAMÈTRES-DU-STYLE)
</example>

Le nom dérivé est une chaîne de caractères définissant le nouveau style, comme
"mon-html".  Le nom de base doit identifier une style existant, comme
"html" -- si on a chargé =muse-html=.  Les paramètres de style sont les
mêmes que ceux qu'on utilise pour créer un style, et ils remplacent les
définitions présentes dans le style de base.

Le plus souvent, cela sera utile pour définir un en-tête, un pied de page,
une feuille de style, pour un projet particulier. En voici un exemple.

<example>
(setq ma-feuille-de-style
      (concat "<link rel=\"stylesheet\" type=\"text/css\""
              " charset=\"utf-8\" media=\"all\""
              " href=\"/different.css\" />"))

(muse-derive-style "mon-xhtml" "xhtml"
                   :header "~/.emacs.d/muse/different-header.html"
                   :footer "~/.emacs.d/muse/different-footer.html"
                   :style-sheet ma-feuille-de-style)
</example>

De nombreux paramètres supportent d'être ainsi remplacés
partiellement. Par exemple:
avec =:functions=, si une function de markup n'est pas trouvée dans la liste
de fonctions du style
dérivé, c'est la fonction du style de base qui sera appelée.

Si un paramètre prend le nom d'une fonction, alors si non-nil est retourné
par cette fonction, aucun autre processus ne sera appelé. Si la
fonction retourne nil, tout autre fonction dans le style de base sera appelée.

** Créer un nouveau style

Pour créer un nouveau style, utiliser =muse-define-style=:

<example>
(muse-define-style NOM PARAMETRES-DE-STYLE)
</example>

Quand on veut créer un nouveau style, le mieux est d'examiner d'abord le code
source d'autres styles, pour avoir une idée de ce qui est nécessaire.
Chaque format de sortie devrait avoir un fichier propre, contenant tous
les styles ayant la même base. Par exemple, les styles =latex=,
=latex-slides=, =pdf= et =latex-slides-pdf= sont tous inclus dans le fichier =muse-latex.el=.

Si vous désirez être l'auteur de documents avec copyright pour la Free
Software Foundation (nous vous aiderons dans cette démarche), les auteurs
de Muse pourraient être intéressés à inclure votre travail dans les
versions futures de Muse.

* Licence

Ce document "premiers pas" peut être redistribué et/ou modifié selon les
termes de la GNU General Public License telle que publiée par la Free
Software Foundation; la version 2, ou (suivant votre choix) toute version
postérieure.


Footnotes: 
[1] Ceci est une note.

[2] Les trois barres verticales pour le bas de tableau ne sont pas
    fonctionnelles dans les styles =latex= ou =context= et leurs dérivés.

[3] Une autre note, non référencée