Emacs-muse

From Wiki
Jump to navigation Jump to search

Emacs Muse (also known as "Muse" or "Emacs-Muse") is an authoring and publishing environment for Emacs. It simplifies the process of writing documents and publishing them to various output formats.

Muse is written in elisp (Emacs-lisp) so you must have emacs installed if you are to benefit of Muse's editing capacities. Then Muse has to be also present on your system (it is planned to be some day part of emacs, but right now it isn't); please visit the Muse site [[1]] for details.

It can be used to prepare, to some extent, ConTeXt documents. The greatest benefit of using Muse are :

  • Editing content (raw text, mathematics, graphics) is done in a text editor with a very small amount of code.
  • Muse will later take care of coding your content into the various outputs (or "styles") which you decide, including html, xml, texinfo, LaTeX, and ConTeXt.
  • From the same source file, Muse can output with only one command all the styles you ask (when within a "project"). Have a look at the muse

QuickStart and Manual to see how to do all this.

ConTeXt styles

For ConTeXt users, Muse has four predefined styles :

  • "context" outputs your muse file to a tex file, which of course you can further edit as such.
  • "context-pdf" outputs your muse file to a pdf file, using context.
  • "context-slides" outputs your muse file to a tex file into one of the official context presentation styles.
  • "context-slides-pdf" outputs your muse file to a pdf file into one of the official context presentation styles.

Muse files

A muse file has typically ".muse" as extension, and when muse-mode is loaded, emacs will recognize it as a muse file; you can load some minor modes as well, such as AucTeX's math mode. At the top of your muse file, you write "directives" (one by line) such as:

#author Myself

#title MyTitle

#bibsource MyBibtexFile , etc.

Then your text, with markups such as :

* Sectiontitle for a first-level title

** Subsectiontitle for a second-level title

*emphasized text* for emphasizing, etc (read the nice manual)

Math

To insert mathematic formulae, you make use of the <math> tag:

<math>\sqrt{2x}=y</math> becomes in your tex file:

 $\sqrt{2x}=y$

If the <math> tag follows six or more spaces at the beginning at a line:

     <math>\sqrt{2x}=y</math> 

it becomes in your tex file:

\startformula
\sqrt{2x}=y
\stopformula

Graphics

Muse has ways to insert external graphics; you would typically write something like this in the muse file :

[[graphic's file name][caption]]; the graphic file has to be in the present directory though.

It is also possible to write code for metafun or tikz graphics within the muse file; it goes like that:

<tikz>tikz code</tikz>,

or

<mpo>metapost/metafun code</mpo>

If you publish to html in addition to context, the code will be transformed into png graphics.


However, these two graphics tags are not (yet?) part of the official muse distribution; you would have to download the files on my site [2] and install them into your muse directory (they do no harm :-)).

Of course you can write crude context code in a muse file, with the help of the <literal> tag:

<literal style="context"> Some context code </literal> This code will be interpreted only in context styles.

Presentations

To prepare a context presentation write your muse file as usual, but sections and subsections will appear differently in the output

* Sectiontitle appears as

\Topic{Sectiontitle}

, and ** Subsectiontitle as

\page {\bf Subsectiontitle}

You can choose the presentation style you want among the "official" one (present in the base directory of your context distribution); the default style is "pre-01"; but if at the top of the muse file (that is, before your text begins) you write (e.g.):

#module pre-14,

this muse "directive" tells muse to make use of presentation style "pre-14" (remember the directive must be alone on its line).

Bibliography

Muse provides the <cite> tag to manage citations and insertion of references into a biblography. The "bibsource" directive instructs Muse which is the bibtex file to use; then inserting

<cite>bibtex key</cite>

will produce a citation of "authoryear" type, and insert the cited document in the bibliography. It is possible also to obtain "author" or "year" citations like this (respectively):

<cite type="author">bibtex key</cite>

<cite type="year">bibtex key</cite>

Publishing your file

When your muse file is prepared and saved, you can publish it with the command:

X-c X-t

Then type in emacs' modeline the style you want (e.g. context), and that's it!

Muse customization

Many functions in emacs-muse are customizable, and for use of the context styles some degree of customization will be highly useful (although not strictly necessary). Let me recall that customization within emacs is mostly done with the commands:

M-x customize-option RET <option-name> RET , and

M-x customize-group RET <group-name> RET

So you can start with "M-x customize-group RET muse-context RET" and see what can be done, upon which I want to comment briefly; here are some options you will see then and might want to modify (less interesting ones are left aside):

muse-context-pdf-program: set by default to texexec --pdf; if you prefer to use texexec --xetex or texexec --lua modify this variable accordingly.

muse-context-header: this will be put at the top of the .tex file. It is minimal, but ready for "interaction", "bibliography" and "tikz pictures". Add and remove whatever you need here; the best way in my view is to prepare a file "my-preamble.tex" where all your additions to the "header" would be written, and just add the following to muse-context-header: \input "<path-to my-preamble.tex>". So you don't have to go back to customization when you want to change something in your preamble, you just modify my-preamble.tex.

muse-context-footer: ready for bibliography (if any) at the end of your document.

muse-context-markup-specials-document: this option permits to define how some character will be rendered in your tex file; it can be useful for you, depending on your language, to make some customization. Writing mostly in french, I customized œ to be rendered as \oe, and € as \euro, for example. It also depends of how your keyboard and emacs are configured.

Your own styles

The list of avalaible styles can be easily extended to fit your own needs, as Muse allows to define derived styles; you might for example decide that muse files created in the ~/foo directory will have as preamble a specific content you wrote as ~/foo/foo-preamble.tex.

You would then define a style context-foo and another context-foo-pdf, using this code (to be put in an initialization file):

(muse-derive-style "context-foo" "context"

:header "~/foo/foo-preamble.tex")

(muse-derive-style "context-foo-pdf" "context-pdf"

:header "~/foo/foo-preamble.tex")

Exercise: how to use Thomas A. Schmitz's "taspresent" presentation module

Thomas has recently offered a very useful module with several styles for presentations. I won't describe it here but I will just let you know how I use it with muse.

Some special code has to appear in the preamble, so I have to define a special variable for muse, which I call muse-context-tas-header:

 (defvar muse-context-tas-header
"\\usemodule[taspresent][style=<lisp>(if (string-equal (muse-publishing-directive \"style\") nil) \"blueframe\" 
(muse-publishing-directive \"style\"))</lisp>,font=Pagella,size=17pt]
\\setvariables [taspresent]
              [author={<lisp>(muse-publishing-directive \"author\")</lisp>},
               title={<lisp>(muse-publishing-directive \"title\")</lisp>}]
\\starttext \n \\Maketitle \n \\page \n \\lecback \n"
)

You can see that the first line says to use the module with various options; in particular the default style is blueframe; the author and title are the ones written in the muse file. Then this "header" goes beyond the preamble as it includes the \Maketitle macro and what follows it (\lecback).

Another variable muse-context-tas-markup-strings is defined to take care of text structure (which is simple for presentations). In the taspresent module, you typically use \Slidetitle{} for a new slide; we want to use muse's first-level title, i.e. a star+space at the beginning of a line containing the title of the slide. For this I define a working variable:

(defvar muse-context-tas-markup-strings
  (nconc 
   '((section      . "\\Slidetitle  {")
 muse-context-markup-regexps)))

Now we're ready to define two new styles, which are derived respectively from the context and context-pdf styles:


(muse-derive-style "tas" "context"
		   :header 'muse-context-tas-header
                   :strings 'muse-context-tas-markup-strings)

(muse-derive-style "tas-pdf" "context-pdf"
		   :header  'muse-context-tas-header
                   :strings 'muse-context-tas-markup-strings
)

This code defines two muse styles, "tas" and "tas-pdf" (Thomas I hope you don't mind I use your initials!); as you easily guess, the former produces a tex file, while the latter produces the pdf output.

Of course this code has to be evaluated by emacs (either at its start if it is written in the .emacs file, or after that using usual elisp methods).

You may see here that this code defines a muse "style" directive, to be used if you want to use another taspresent style than blueframe. To do that, just write at the top of the muse file, after the title and author directives, eg:

#style blackblue

Of course you can modify various things, especially in the header; as for me I add \\usemodule[french] in the first defvar, so the french module is loaded.

The only small problem I have is that if I want to use the \PicHoriz or \PicVert macros I have to manipulate tex code to change the background (\picback is needed there to replace \lecback); which can de done in the muse file with the literal tag, or by editing the tex file.

But this is only a minor inconvenient compared to the advantages of preparing a presentation so easily!

For those who won't use emacs :-(

It is quite possible to use another editor to edit muse files, if you're not a friend of emacs; you can when a file has been edited with vim/kedit/scite, etc. issue a command asking emacs to publish the file in batch mode, and you can use a script for that (or a makefile); examples are given in the muse distribution.