Linux.com

Maintained by Michael Olson, Muse mode combines an easy-to-learn markup language for authoring documents with a set of styles for generating output in several formats, including:

• LaTeX, using either the standard book or article class
• Texinfo
• PDF, based on LaTeX
• HTML and XHTML
• DocBook XML
• Blosxom (a lightweight blogging tool)

Some of the uses that people have put Muse to include documentation and tutorials, Web pages, recipes and poems, blogs, and knowledge bases. Since I started using Muse last year, I've output LaTeX, HTML/XHTML, DocBook, and PDF files. After a bit of tweaking, the results have been very good.

Getting and installing Muse

You can download Muse directly from the project Web site. You can choose either a stable release or the latest development version. Once you've downloaded Muse, just extract the archive to your hard drive and add the following block of text to your .emacs file:

(add-to-list 'load-path "/home/scott/elisp/muse_latest/lisp")
(require 'muse-mode)
(require 'muse-html)
(require 'muse-latex)
(require 'muse-texinfo)
(require 'muse-docbook)
(require 'muse-book)

Once you've installed Muse, you can also byte-compile it. Byte-compiling is an Emacs process that turns Lisp files (the programming language in which Muse and other Emacs extensions are written) into code that Emacs can execute faster. I have a fairly fast laptop, so I didn't notice much of a difference between the byte-compiled and uncompiled versions of Muse, but your mileage may vary.

Change the load path to where you installed Muse, then fire up Emacs and start writing.

Using Muse markup

Muse's markup language is simple to learn. For the most part, you don't need to remember a bunch of tags, as you would with HTML or XML. Instead, Muse uses keyboard symbols to denote how text is formatted. For example, put one or more asterisks (*) before text to make it a heading. Type a space followed by a dash or a number to create a bulleted or numbered list. Surround text with one or more asterisks to set the text in bold or italics.

A Muse source document being edited in Emacs - click to enlarge

If you think the Muse markup is wiki-like, you're not far off the mark. Muse is based on Emacs wiki mode and recycles much of the markup. But Muse also expands on it with a number of additional tags.

Some of the tags are HTML- or XML-like, right down to being surrounded by angle brackets. The tag <contents>, for instance, generates a table of contents at the beginning of a document. The <example> tag sets a block of text in monospace type, and is used for code samples.

Muse also supports hyperlinks, images, and tables with wiki-like markup directives. The Muse manual has a comprehensive explanation of all the supported markup.

Publishing files

Once you've written and marked up a document, you can publish it. Save your document and then type Esc-x muse-publish-this-file and press Enter. (Alternatively, you can publish a file that's elsewhere on your hard drive using the muse-publish-file command.)

You'll be prompted for the type of output you want to create. If you don't remember the available publishing styles, press the Tab key to view a list of them. Type the name of the style you want to use -- for example, pdf. Emacs will prompt you for the directory in which you want to output the file. You can press Enter to use the directory in which you saved your source file, or you can type the path to a different one.

Once you've done that, Emacs will publish your document. The speed of publishing depends on the size of your source file and the output format you choose. I've output 30-page PDF files in just a few seconds; HTML and XHTML files take even less time.

Customizing your output

One aspect of Muse that I don't like is that it uses the standard LaTeX article and book classes to generate LaTeX and PDF files. Visually, I don't find either appealing. But that's easy to change; you can switch to just about any LaTeX document class.

To make changes, edit the files muse-latex.el and muse-book.el. Find the entries \\documentclass{article} and \\documentclass{book} and change the document classes to whatever you like. I'm partial to replacing the article class with the hitec, refart, or paper classes. For the book class, good replacements are the memoir and scrbook classes.

Bear in mind that if you've byte-compiled the Muse files, you'll need to byte-compile muse-latex.el and muse-book.el again before your changes take effect.

The HTML and XHTML that Muse outputs is surprisingly compliant with Web standards. The XHTML output embeds a Cascading Style Sheet in the file. The styles are simple and functional, but they might not be what you're looking for. You can change them by adding the muse-htmlstyle-sheet option to the header of your document, and then adding your stylesheet information, as documented in the Muse manual.

Conclusion

If you do any sort of writing, Emacs Muse is a great way to not only author your work but publish it as well. The markup used is easy to learn, and you have many options for converting your source documents into a usable format.

If you don't think that Muse can be used for creating "professional" documents, think again. I've used it to publish several reports and a couple of short manuals for various clients -- as well as this article!

Scott Nesbitt is a writer based in Toronto, Canada, who thinks that he's found the writing tool he's always been looking for in Emacs Muse.

Share    Print    Comments