Emacs-muse

From Wiki
Revision as of 19:34, 31 August 2007 by Jean (talk | contribs) (New page: 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 outpu...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 for details.

It can be used to prepare, to some extent, ConTeXt documents. The greatest benefit of using Muse are that editing content (raw text, mathematics, graphics) is done in a text editor with a very small amount of code, and 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 [1] 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 <site> 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

<site>bibtex key</site>

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):

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

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

BEWARE In the preceding paragraph the string "site" should red as "cite"; but writing this string surrounded with "<" and ">" produces unexpected results here. Please think of making the correction.

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")

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.