This manual is for Emacs Muse version 3.12.
Copyright © 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License” in this manual.(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”
This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.
All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction.
--- The Detailed Node Listing ---
How to Get Muse Releases and Development Changes
Getting Started
Creating and Managing Muse Projects
Rules for Using Markup
Publishing Various Types of Documents
Integrating Muse and pyblosxom.cgi
Making your own publishing styles
Miscellaneous add-ons, like a minor mode
This document describes Muse, which was written by John Wiegley and is now maintained by Michael Olson. Several versions of this manual are available on-line.
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 consists of two main parts: an enhanced text-mode for authoring documents and navigating within Muse projects, and a set of publishing styles for generating different kinds of output.
What makes Muse distinct from other text-publishing systems is a modular environment, with a rather simple core, in which "styles" are derived from to create new styles. Much of Muse's overall functionality is optional. For example, you can use the publisher without the major-mode, or the mode without doing any publishing; or if you don't load the Texinfo or LaTeX modules, those styles won't be available.
The Muse codebase is a departure from emacs-wiki.el version 2.44. The code has been restructured and rewritten, especially its publishing functions. The focus in this revision is on the authoring and publishing aspects, and the "wikiness" has been removed as a default behavior (available in the optional muse-wiki module). CamelCase words are no longer special by default.
One of the principal aims in the development of Muse is to make it very easy to produce good-looking, standards-compliant documents.
Choose to install a release if you want to minimize risk.
Errors are corrected in development first. User-visible changes will be announced on the muse-el-discuss@gna.org mailing list. See Getting Help and Reporting Bugs.
Debian users can get Muse via apt-get. The muse-el package is
available both at Michael Olson's APT repository and the official Debian
repository. To make use of the former, add the following line to your
/etc/apt/sources.list file and run apt-get install muse.
deb http://mwolson.org/debian/ ./
Ubuntu users can also get Muse via apt-get. The muse-el package
is available both at Michael Olson's APT repository and the official
Ubuntu repository. To make use of the former, add the following line to
your /etc/apt/sources.list file and run apt-get install
muse.
deb http://mwolson.org/ubuntu/ ./
The reason for making separate Debian and Ubuntu packages is that this manual is under the GFDL, and Debian will not allow it to be distributed in its main repository. Ubuntu, on the other hand, permits this manual to be included with the muse-el package.
Alternatively, you can download the latest release from http://download.gna.org/muse-el/ .
Choose the development version if you want to live on the bleeding edge of Muse development or try out new features before release.
The git version control system allows you to keep up-to-date with the latest changes to the development version of Muse. It also allows you to contribute changes (via commits, if you are have developer access to the repository, or via patches, otherwise). If you would like to contribute to Muse development, it is highly recommended that you use git.
If you are new to git, you might find this tutorial helpful: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html.
Downloading the Muse module with git and staying up-to-date involves the following steps.
If you have developer access to Muse, do:
git clone ssh://repo.or.cz/srv/git/muse-el.git muse
otherwise, do:
git clone git://repo.or.cz/muse-el.git muse
If you are behind a restrictive firewall, and do not have developer access, then do the following instead:
git clone http://repo.or.cz/r/muse-el.git muse
# Change to the source directory you are interested in.
cd muse
# Fetch new changes from the repository, but don't apply them yet
git fetch origin
# Display log messages for the new changes
git log HEAD..origin
“origin” is git's name for the location where you originally got Muse from. You can change this location at any time by editing the .git/config file in the directory where the Muse source was placed.
cd muse
git pull origin
git will show how many files changed, and will provide a visual display for how many lines were changed in each file.
There are other ways to interact with the Muse repository.
The latest development snapshot can lag behind the git repo by as much as 20 minutes, but never more than that.
If you want commit access to the shared Muse repository, then register an account at http://repo.or.cz (be sure to add an SSH key), and contact the current maintainer at mwolson@gnu.org. It would be best to send some patches to the muse-el-discuss@gna.org mailing list first, so that he knows that you know what you are doing. See Getting Help and Reporting Bugs, for instructions on subscribing to the mailing list.
You must also be willing to sign a copyright assignment for your changes to Muse, since Muse is a GNU project. The current maintainer will assist you in this process if you contact him.
For information on committing changes to Muse and performing development, please consult http://emacswiki.org/cgi-bin/wiki/MuseDevelopment.
Muse may be compiled and installed on your machine.
This is an optional step, since Emacs Lisp source code does not necessarily have to be byte-compiled. Byte-compilation may yield a very slight speed increase.
A working copy of Emacs or XEmacs is needed in order to compile Emacs Muse. By default, the program that is installed with the name emacs will be used.
If you want to use the xemacs binary to perform the compilation, you must copy Makefile.defs.default to Makefile.defs in the top-level directory, and then edit Makefile.defs as follows. You can put either a full path to an Emacs or XEmacs binary or just the command name, as long as it is in the PATH.
EMACS = xemacs
SITEFLAG = -no-site-file
# Edit the section as necessary
install_info = install-info --section "XEmacs 21.4" $(1).info \
$(INFODIR)/dir || :
Running make in the top-level directory should compile the Muse
source files in the lisp directory, and generate an autoloads
file in lisp/muse-autoloads.el.
Muse may be installed into your file hierarchy by doing the following.
Copy Makefile.defs.default to Makefile.defs in the top-level directory, if you haven't done so already. Then edit the Makefile.defs file so that ELISPDIR points to where you want the source and compiled Muse files to be installed and INFODIR indicates where to put the Muse manual. You may use a combination of DESTDIR and PREFIX to further determine where the installed files should be placed. As mentioned earlier, you will want to edit EMACS and SITEFLAG as shown in the Compilation section if you are using XEmacs.
If you are installing Muse on a Debian or Ubuntu system, you might want to change the value of INSTALLINFO as specified in Makefile.defs.
If you wish to install Muse to different locations than the defaults specify, edit Makefile.defs accordingly.
Run make as a normal user, if you haven't done so already.
Run make install as the root user if you have chosen installation
locations that require root permissions.
For those used to installing software packages, there will be a
muse package available in the Emacs Lisp Package Archive
(abbreviated “ELPA”) as of the 3.10 release of Muse. This package
will be compiled and installed automatically in a user-specific
location. For more information on ELPA, see
http://tromey.com/elpa/.
To use Muse, add the directory containing its files to your
load-path variable, in your .emacs file. Then, load in
the authoring mode, and the styles you wish to publish to. An example
follows.
(add-to-list 'load-path "<path to Muse>")
(require 'muse-mode) ; load authoring mode
(require 'muse-html) ; load publishing styles I use
(require 'muse-latex)
(require 'muse-texinfo)
(require 'muse-docbook)
(require 'muse-project) ; publish files in projects
An easy way of seeing which settings are available and changing settings is to use the Muse customization interface. To do this, type M-x customize-group muse RET. Each of the options has its own documentation. Options are grouped logically according to what effect they have.
Muse Mode should automatically be activated when you visit a file with a “.muse” extension. One such file is QuickStart.muse, which is available in the examples directory of the Muse distribution. You can tell that Muse Mode has been activated by checking for the text “Muse” in your mode line. If Muse Mode has not been activated, you may activate it by type M-x muse-mode RET.
You will notice that Muse files are highlighted very simply. Links are colored blue, headings are large and bold text, and <example> tags are colored in grey.
There are several different ways to edit things like links, which hide the underlying Muse markup. One way is to toggle font-locking off by hitting C-c C-l, which is also M-x font-lock-mode, make changes, and then hit C-c C-l again to toggle font-locking back on. Another way is just to move into the text and edit it. Markup can also be removed by normal deletion methods, though some side effects might require a second deletion.
For the particular case of editing links, it is easiest to move to the link and do C-c C-e, which is also M-x muse-edit-link-at-point. This prompts you for the link and its description, using the previous contents of the link as initial values. A link to another Muse file may be created by hitting C-c TAB l. A link to a URL may be created by hitting C-c TAB u. Links may be followed by hitting RET on them.
If you want to add a new list item, this may by accomplished by hitting M-RET. This will put a dash and some spaces on the screen. The dash is the Muse markup that indicates a list item. It is also possible to created “nested” lists with this command, by adjusting the number of spaces in front of the dashes. If you have lists with long lines, you can move to a list item and hit M-q to wrap it onto multiple lines.
The command M-x muse-project-publish-this-file will publish the current document to any available publishing style (a publishing style is an output format, like HTML or Docbook), placing the output in the current directory. If you are in Muse Mode, this command will be bound to C-c C-t. If the file has been published recently, and its contents have not changed, running C-c C-t again will not publish the file. To force publishing in this case, do C-u C-c C-t.
If you have set up projects and are visiting a file that is part of a project, then C-c C-t will restrict the output formats to those which are used by the project, and will automatically publish to the output directory defined by the project. If you want to publish to a different directory or use a different format, then use C-c M-C-t, which is also M-x muse-publish-this-file.
If the currently opened file is part of a defined project in
muse-project-alist, it (and the rest of the changed files in a
project) may be published using C-c C-p.
By default, Muse expects all project files to have the file extension .muse. Files without this extension will not be associated with Muse mode and will not be considered part of any project, even if they are within a project directory.
If you don't want to use .muse, you can customize the extension
by setting the value of muse-file-extension.
If you don't want to use any extension at all, and want Muse to autodetect project files based on their location, then add the following to your Muse settings file.
(setq muse-file-extension nil
muse-mode-auto-p t)
Note that if you chose to have muse-file-extension set to
nil, you may have trouble if your .emacs file or other
init scripts attempt to visit a Muse file. (A very common example of
this is if you use Planner with Muse and run (plan) from your
.emacs.) If you wish to visit Muse files from your
.emacs, be sure to also add the following additional code before
any such visits happen:
(add-hook 'find-file-hooks 'muse-mode-maybe)
Often you will want to publish all the files within a directory to a particular set of output styles automatically. To support, Muse allows for the creation of "projects".
Here is a sample project, which may be defined in your .emacs file.
(setq muse-project-alist
'(("Website" ("~/Pages" :default "index")
(:base "html" :path "~/public_html")
(:base "pdf" :path "~/public_html/pdf"))))
The above defines a project named "website", whose files are located in the directory ~/Pages. The default page to visit is index. When this project is published, each page will be output as HTML to the directory ~/public_html, and as PDF to the directory ~/public_html/pdf. Within any project page, you may create a link to other pages using the syntax ‘[[pagename]]’.
If you would like to include only some files from a directory in a Muse project, you may use a regexp in place of ~/Pages in the example.
It is possible to specify multiple projects. Here is an example of three projects: a generic website, a projects area, and a day-planner (the day-planner part requires Planner Mode—see http://wjsullivan.net/PlannerMode.html to get it).
(setq muse-project-alist
'(("Website" ("~/Pages" :default "index")
(:base "html" :path "~/public_html"))
(("Projects" ("~/Projects" :default "index")
(:base "xhtml"
:path "~/public_html/projects"
:exclude "/TopSecret")
(:base "pdf"
:path "~/public_html/projects/pdf"
:exclude "/TopSecret")))
("Plans" ("~/Plans"
:default "TaskPool"
:major-mode planner-mode
:visit-link planner-visit-link)
(:base "planner-xhtml"
:path "~/public_html/plans"))))
The :major-mode attribute specifies which major to use when visiting files in this directory.
The :visit-link attribute specifies the function to call when visiting links.
The :exclude attribute has a regexp that matches files to never publish.
If you want to publish a directory and all of its subdirectories, Muse provides two convenience functions that together generate the proper rules for you. Note that we use the backtick to begin this muse-project-alist definition, rather than a single quote.
(setq muse-project-alist
`(("Website" ("~/Pages" :default "index")
(:base "html" :path "~/public_html"))
("Blog" (,@(muse-project-alist-dirs "~/Blog")
:default "index")
;; Publish this directory and its subdirectories. Arguments
;; are as follows. The above `muse-project-alist-dirs' part
;; is also needed.
;; 1. Source directory
;; 2. Output directory
;; 3. Publishing style
;; remainder: Other things to put in every generated style
,@(muse-project-alist-styles "~/Blog"
"~/public_html/blog"
"blosxom"))))
The muse-project-alist-dirs function takes a directory and
returns it and all of its subdirectories in a list.
The muse-project-alist-styles function is explained by the
comments above.
The “blosxom” text is the name of another publishing style, much like
“html”. See Blosxom, for further information about it. You can
use any publishing style you like for the third argument to
muse-project-alist-styles.
This is a listing of all of the various options (or, more accurately:
attributes) that may be specified in muse-project-alist.
Each muse-project-alist entry looks like this:
(PROJECT-NAME (SOURCES)
OUTPUTS)
We refer to these names below.
“Attributes”, which compose SOURCES and OUTPUTS, are a pair of values. The first value is a keyword, like :default. The second part is the value associated with that keyword, such as the text “index”. If you are familiar with Emacs Lisp property lists, the concept is similar to that, except that in the SOURCES section, single directories can be interspersed with two-value attributes.
This is a string that indicates the name of the project. It is primarily used for publishing interwiki links with the muse-wiki.el module.
This part of a muse-project-alist entry consists of two-value attributes, and also directory names. If you are publishing a book, the order of directories and attributes is significant.
The minimal content for the sources section is a list of directories.
muse-mode.
(VAR1 VALUE1 VAR2 VALUE2 ...)
muse-visit-link-default. The arguments for that function should
be (1) the link and (2) whether to visit the link in a new window.
This part of a muse-project-alist entry is composed of lists of attributes. Each list is called an “output style”.
The minimal content for an output style is a :base attribute and a :path attribute.
It is also used by the muse-journal module to create the RSS or
RDF output.
This is a summary of keystrokes available in every Muse buffer.
Call this after changing muse-project-alist.
A Muse document uses special, contextual markup rules to determine how to format the output result. For example, if a paragraph is indented, Muse assumes it should be quoted.
There are not too many markup rules, and all of them strive to be as simple as possible so that you can focus on document creation, rather than formatting.
Paragraphs in Muse must be separated by a blank line.
A line that begins with six or more columns of whitespace (either tabs or spaces) indicates a centered paragraph. Alternatively, you can use the <center> tag to surround regions that are to be published as centered paragraphs.
But if a line begins with whitespace, though less than six columns, it indicates a quoted paragraph. Alternatively, you can use the <quote> tag to surround regions that are to be published as quoted paragraphs.
The <example> tag is used for examples, where whitespace should be preserved, the text rendered in monospace, and any characters special to the output style escaped.
There is also the <literal> tag, which causes a marked block to be entirely left alone. This can be used for inserting a hand-coded HTML blocks into HTML output, for example.
If you want some text to only be inserted when publishing to a particular publishing style, use the style attribute for the <literal> tag. An example follows.
<literal style="latex">
A LaTeX-based style was used in the publishing of this document.
</literal>
This will leave the region alone if the current publishing style is
“latex” or based on “latex”, such as “pdf”, and delete the region
otherwise. It is also possible to leave the text alone only for one
particular style, rather than its derivations, by adding
exact="t" to the tag.
If you need a line break, then use the ‘<br>’ tag. Most of the time this tag is unnecessary, because Muse will automatically detect paragraphs by means of blank lines. If you want to preserve newlines in several lines of text, then use verse markup instead (see Verse).
A heading becomes a chapter or section in printed output – depending on the style. To indicate a heading, start a new paragraph with one or more asterices, followed by a space and the heading title. Then begin another paragraph to enter the text for that section.
All levels of headings will be published. Most publishing styles only distinguish the between the first 4 levels, however.
* First level
** Second level
*** Third level
**** Fourth level
Directives are lines beginning with the ‘#’ character that come before any paragraphs or sections in the document. Directives are of the form “#directive content of directive”. You can use any combination of uppercase and lowercase letters for directives, even if the directive is not in the list below.
The muse-publishing-directive function may be used in header and
footer text to access directives. For example, to access the
#title directive, use (muse-publishing-directive "title").
The following is a list of directives that Muse uses.
#authorIf this is not specified, Muse will attempt to figure it out from the
user-full-name variable.
#dateThis is used by publishing styles that are able to embed the date information.
#descThis is used by the journal publishing style to embed information
inside of an RSS/RDF feed.
#titleIf this is not specified, the name of the file is used.
To emphasize text, surround it with certain specially recognized characters.
*emphasis*
**strong emphasis**
***very strong emphasis***
_underlined_
=verbatim and monospace=
While editing a Muse document in Muse mode, these forms of emphasis will be highlighted in a WYSIWYG manner. Each of these forms may span multiple lines.
Verbatim text will be colored as gray by default. To change this,
customize muse-verbatim-face.
You can also use the <code> tag to indicate verbatim and monospace text. This is handy for regions that have an “=” in them.
A footnote reference is simply a number in square brackets. To define the footnote, place this definition at the bottom of your file. ‘footnote-mode’ can be used to greatly facilitate the creation of these kinds of footnotes.
Footnotes are defined by the same number in brackets occurring at the beginning of a line. Use footnote-mode's C-c ! a command, to very easily insert footnotes while typing. Use C-x C-x to return to the point of insertion.
Poetry requires that whitespace be preserved, but without resorting to monospace. To indicate this, use the following markup, reminiscent of email quotations.
> A line of Emacs verse;
> forgive its being so terse.
You can also use the <verse> tag, if you prefer.
<verse>
A line of Emacs verse;
forgive its being so terse.
</verse>
Multiple stanzas may be included in one set of <verse> tags, as follows.
<verse>
A line of Emacs verse;
forgive its being so terse.
In terms of terse verse,
you could do worse.
</verse>
Lists are given using special characters at the beginning of a line. Whitespace must occur before bullets or numbered items, to distinguish from the possibility of those characters occurring in a real sentence.
These are rendered as a bullet list.
Normal text.
- bullet item one
- bullet item two
Normal text.
1. Enum item one
2. Enum item two
Term1 ::
This is a first definition
And it has two lines;
no, make that three.
Term2 :: This is a second definition
It is possible to nest lists of the same or different kinds. The “level” of the list is determined by the amount of initial whitespace.
Normal text.
- Level 1, bullet item one
1. Level 2, enum item one
2. Level 2, enum item two
- Level 1, bullet item two
1. Level 2, enum item three
2. Level 2, enum item four
term :: definition
If you want to break up a line within any list type, just put one blank line between the end of the previous line and the beginning of the next line, using the same amount of initial indentation.
- bullet item 1, line 1
bullet item 1, line 2
1. Enum line 1
Enum line 2
- bullet item 2, line 1
bullet item 2, line 2
Only very simple tables are supported. The syntax is as follows.
Double bars || Separate header fields
Single bars | Separate body fields
Here are more | body fields
Triple bars ||| Separate footer fields
Some publishing styles require header fields to come first, then footer fields, and then the body fields. You can use any order for these sections that you like, and Muse will re-order them for you at publish-time.
If you wish to disable table generation for one Muse file, add the directive ‘#disable-tables t’ to the top of the file.
It is possible to publish very basic Orgtbl-mode style tables.
| org | style | table |
|------+-------+-------|
| one | | one |
| two | two | |
| | three | three |
|------+-------+-------|
| more | stuff | |
If you are used to the way that Org Mode publishes these tables, then customize `muse-html-table-attributes' to the following, in order to get a similar kind of output.
border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
table.el style tables are also supported, as long as table.el itself supports outputting tables for a particular publishing style. At the time of this writing, the “html”, “latex”, and “docbook” styles are supported by table.el. Styles derived from these styles will also work.
+---+-----+---+
| | one | 1 |
+---+-----+---+
| b | two | |
+---+-----+---+
| c | | 3 |
+---+-----+---+
A hyperlink can reference a URL, or another page within a Muse project. In addition, descriptive text can be specified, which should be displayed rather than the link text in output styles that supports link descriptions. The syntax is as follows.
[[link target][link description]]
[[link target without description]]
Thus, the current maintainer's homepage for Muse can be found ‘[[http://mwolson.org/projects/EmacsMuse.html][here]]’, or at ‘[[http://mwolson.org/projects/EmacsMuse.html]]’.
A URL or email address encountered in the input text is published as a hyperlink. These kind of links are called implicit links because they are not separated from the rest of the Muse document in any way.
Some characters in URLs will prevent Muse from recognizing them as implicit links. If you want to link to a URL containing spaces or any of the characters “][,"'`()<>^”, you will have to make the link explicit. The punctuation characters “.,;:” are also not recognized as part of a URL when they appear at its end. For information on how to make an explicit link, see Hyperlinks and email addresses with descriptions.
If the muse-wiki module is loaded, another form of implicit link will be made available. WikiNames, which are typed in CamelCase, are highlighted and published as links, provided that the file they refer to exists.
Customization of WikiName recognition may be accomplished by editing the
muse-wiki-wikiword-regexp option and subsequently running
(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup).
If you use the Customize interface, the latter will be done
automatically.
The muse-wiki module also allows for InterWiki links. These
are similar to WikiWords, but they specify both the project and page of
a file. The names of your project entries in muse-project-alist
will be used as InterWiki names by default. Several examples follow.
Blog::DocumentingMuse
Projects#EmacsMuse
Website
In the first case, the interwiki delimiter is ‘::’, ‘Blog’ is the project name, and ‘DocumentingMuse’ is the page name. In the second example, ‘#’ is the interwiki delimiter. If the name of a project occurs by itself in text, like the third case, it will be colorized and published as a link to the default page of the given project.
Customization of interwiki links may be accomplished by editing the
muse-wiki-interwiki-alist option.
It is also possible to link to an anchor in an interwiki document. This is called a “three-part link”. Examples of this follow.
Blog::DocumentingMuse#anchor1
Projects#EmacsMuse#anchor2
Links to images may be used in either the target or the description, or both. Thus, the following code will publish as a clickable image that points to http://mwolson.org/.
[[http://mwolson.org/][/static/logos/site-logo.png]]
Normally, images in the link part will be inlined.
If you want these images to be published as links instead, place the text “URL:” immediately in front of the link text. An example follows.
[[URL:http://mwolson.org/static/logos/site-logo.png]]
If a link to a locally-available image is encountered in the link description, Muse mode will attempt to display it if your version of Emacs permits this.
This behavior may be toggled with C-c C-i, or disabled permanently
by setting the muse-colors-inline-images option to nil.
The method for finding images may be altered by customizing the
muse-colors-inline-image-method option. One useful value for
this option is muse-colors-use-publishing-directory, which tells
Muse mode to look in the directory where the current file will be
published. The default is to look in the current directory. Relative
paths like ‘../pics/’ should work for either setting.
Eventually, it is hoped that Muse will be able to copy images from the a
“source” directory to a publishing directory by customizing
muse-project-alist, but this has not been implemented yet.
The following example will display correctly and publish correctly if a PNG file called TestLogo.png exists in the ../pics/ directory. If text is on the same line as the picture, it will remain so in the output.
[[../myimage.png]]
If you want to add a caption to an image, use the following syntax. This will center the image (if the output format supports it) and add a centered caption below the picture. Formats that do not support centering the image will instead leave it against the left margin.
[[../pics/mycat.png][My cat Dexter]]
Images with captions may only occur in their own paragraphs, with no text on the same line. Otherwise, the published output will not be syntactically correct.
Four or more dashes indicate a horizontal rule. Be sure to put blank lines around it, or it will be considered part of the proceeding or following paragraph!
If you begin a line with "#anchor" – where "anchor" can be any word that doesn't contain whitespace – it defines an anchor at that point into the document. This point can be referenced using "page#anchor" as the target in a Muse link.
Arbitrary kinds of markup can be achieved using the <lisp> tag. With the <lisp> tag, you may generate whatever output text you wish. The inserted output will get marked up if the <lisp> tag appears within the main text of the document.
<lisp>(concat "This form gets " "inserted")</lisp>
Note that you should not use the insert command within a set of
<lisp> tags, since the return value from the <lisp>
tags will be automatically inserted into the document.
It is also possible to treat the output as if it were surrounded by the <example>, <src>, or <verse> tags, by specifying “example”, “src”, or “verse” as the markup attribute of the <lisp> tag.
<lisp markup="example">
(concat "Insert" " me")
</lisp>
Other languages also have tags that cause source code to be evaluated. See Tag Summary, for details.
Here is an example of what citations look like in a Muse document.
#bibsource REFDB
* Title
** Subtitle
Some text before <cite>Miller1999</cite> and after the citation.
This is an author-only citation <cite type="author">Miller1999</cite>.
And this is a year-only citation <cite type="year">Miller1999</cite>.
Finally, this is a multi-head citation
<cite>Miller1999,Andrews2005</cite>.
The #bibsource directive defines the source of the
bibliographies. The following sources are possible.
Citations are encoded as <cite> elements which enclose the
citation keys as they are defined in the bibliography file or database.
In multi-head citations, the citation keys have to be separated by
colons or semicolons. The latex and docbook styles
translate these to the proper separator automatically.
The <cite> elements take an optional “type” attribute that defines how the citation is rendered. If the attribute is missing, you'll get a regular citation according to the bibliography style, e.g.” (Miller et al., 1999)”. If the attribute is set to "author", only the name of the author(s) will be rendered. Accordingly, "year" will cause the year to be printed. This is useful to create citations like this:
Miller et al. had already shown in a previous publication (1999) that
this is not going to work.
Remember that refdb-mode (the Emacs interface to RefDB) can retrieve
references by simply marking the citation key and running the
refdb-getref-by-field-on-region command. Later versions of
refdb-mode will also allow to insert references as Muse citations
(which is already implemented for DocBook, TEI, and LaTeX documents).
You may have noticed that there is no element to indicate the position
of the bibliography. The latter is always created at a valid position
close to the end of the document. The functions
muse-docbook-bibliography and muse-latex-bibliography are
called in the header or footer to generate this content, so it is
possible to change the exact position.
Use the following syntax to indicate a comment. Comments will not be published.
; Comment text goes here.
That is, only a semi-colon at the beginning of a line, followed by a literal space, will cause that line to be treated as a comment.
You can alternatively surround the region with the <comment> tag.
If you wish the comment to be published, but just commented out using the comment syntax of the output format, then set muse-publish-comments-p to non-nil.
Muse has several built-in tags that may prove useful during publishing. See muse-publish-markup-tags, to see how to customize the tags that Muse uses, as well as make your own tags.
Only a small subset of these tags are available in header and footer
text. The muse-publish-markup-header-footer-tags option lists
the tags that are allowed in headers and footers.
If a tag takes arguments, it will look like this, where “tagname” is the name of the tag.
<tagname arg1="string1" arg2="string2">
If you want the tag to look like it came straight from an XHTML document, you can alternatively do the following.
<tagname arg1="string1" arg2="string2" />
If a tag surrounds some text, it will look like this.
<tagname>Some text</tagname>
If a tag surrounds a large region, it will look like this.
<tagname>
Some text.
Some more text.
</tagname>
This is the complete list of tags that Muse accepts, including those that were mentioned in previous sections.
Muse will automatically detect paragraphs when publishing by means of
blank lines, so this tag is usually unnecessary.
This takes the argument type, which indicates the type of citation. The valid types are "author" and "year". If this argument is omitted, include both author and year in the citation.
The bibliography to use for the citation may be specified by the #bibsource directive.
See Citations, for additional information.
If publishing to a different format, do nothing extra to the text.
The “markup” argument controls how this section is marked up.
If it is omitted, publish the region with the normal Muse rules.
If "nil", do not mark up the region at all, but prevent Muse from further interpreting it.
If "example", treat the region as if it was surrounded by the <example> tag.
If "src", treat the included text as if it was surrounded by the <src> tag. You should also specify the “lang” attribute if doing this.
If "verse", treat the region as if it was surrounded by the <verse> tag, to preserve newlines.
Otherwise, it should be the name of a function to call, with the buffer
narrowed to the region.
By default, only 2 levels of headings will be included in the generated
Table of Contents. To change this globally, customize the
muse-publish-contents-depth option. To change this only for the
current tag, use the “depth” argument.
If the “style” argument is provided, include it with the published
<div> tag. Likewise for the “id” argument.
<include file="included_file">
The “markup” argument controls how this section is marked up.
If it is omitted, publish the included text with the normal Muse rules.
If "nil", do not mark up the included text at all.
If "example", treat the included text as if it was surrounded by the <example> tag.
If "src", treat the included text as if it was surrounded by the <src> tag. You should also specify the “lang” attribute if doing this.
If "verse", treat the included text as if it was surrounded by the <verse> tag, to preserve newlines.
Otherwise, it should be the name of a function to call after inserting
the file with the buffer narrowed to the section inserted.
insert. All text properties are removed from the
resulting text.
This tag takes the “markup” argument. See the description of
<command> for details.
This is useful for marking up regions in headers and footers. One example that comes to mind is generating a published index of all of the files in the current project by doing the following.
<markup><lisp>(muse-index-as-string t t)</lisp></markup>
This tag takes the “markup” argument. See the description of
<command> for details.
This tag takes the “markup” argument. See the description of
<command> for details.
This tag takes the “markup” argument. See the description of
<command> for details.
Muse will look for a function named lang-mode, where lang is the value of the “lang” attribute.
This tag requires htmlize 1.34 or later in order to work. If this is
not satisfied, or the current publishing style is not HTML-based, Muse
will publish the region like an <example> tag.
This tag was used often in previous versions of Muse because they did
not support whole-document escaping of specials. Now, it will only be
needed for other tags, and perhaps footnotes as well.
One of the principle features of Muse is the ability to publish a simple input text to a variety of different output styles. Muse also makes it easy to create new styles, or derive from an existing style.
The Blosxom publishing style publishes a tree of categorised files to a mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi. In other words, each blog entry corresponds with one file.
You will need to have pyblosxom.cgi or blosxom.cgi installed on a machine that you have upload access to.
The major difficulty in both of these programs is specifying the date of the entries. Both programs rely on the file modification time rather than any data contained in the entries themselves. A plugin is needed in order for these programs to be able to get the correct date.
There are two different ways of accomplishing this in pyblosxom. The
first way involves gathering the timestamps (as specified by the
#date directive) into one file and then sending that file along
with published entries to the webserver.
The second will read each file at render time and parse the
#postdate directive. Muse will translate the #date
directive into #postdate at publish time, so you don't have to do
any extra work.
The following additional components are required in order to make the date of blog entries display as something sensible.
These 2 things are provided for pyblosxom.cgi in the contrib/pyblosxom subdirectory. getstamps.py provides the former service, while hardcodedates.py provides the latter service.
Here is a sample listing from my timestamps file, which maps each file to a date. This can really be in any format, as long as your date-gathering script and your plugin can both understand it.
2005-04-01-14-16 personal/paper_cranes
2005-03-21 personal/spring_break_over
2004-10-24 personal/finished_free_culture
The script contrib/pyblosxom/make-blog demonstrates how to call getstamps.py. Note that you will need to set the current directory to where your Muse files are, execute getstamps.py, and then move the generated timestamps file to your publishing directory.
Alternately, the pyblosxom metadate plugin may be used. On the plus
side, there is no need to run a script to gather the date. On the
downside, each entry is read twice rather than once when the page is
rendered. Set the value of muse-blosxom-use-metadate to non-nil
to enable adding a #postdate directive to all published files.
You can do this by:
M-x customize-variable RET muse-blosxom-use-metadate RET
With the metadate plugin installed in pyblosxom, the date set in this directive will be used instead of the file's modification time. The plugin is included with Muse at contrib/pyblosxom/metadate.py.
It is also possible to use Blosxom, which is written in Perl, to serve blog entries that were published with Muse. The steps are as follows.
Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
longer `#date yyyy-mm-dd-hh-mm', a title (using the #title
directive), plus whatever normal content is desired.
The date directive is not used directly by pyblosxom.cgi or this program. You need to have the two additional items from the former section to make use of this feature.
There is a function called muse-blosxom-new-entry that will
automate the process of making a new blog entry. To make use of it, do
the following.
muse-blosxom-base-directory to the location that your
blog entries are stored.
muse-blosxom-new-entry function to a key sequence. I
use the following code to assign this function to C-c p l'.
(global-set-key "\C-cpl" 'muse-blosxom-new-entry)
The following styles and options are available in the Blosxom publishing style.
blosxom-htmlblosxom-xhtmlmuse-blosxom-extensionmuse-blosxom-headerThis may be text or a filename.
muse-blosxom-footerThis may be text or a filename.
muse-blosxom-base-directorymuse-blosxom-new-entry.
This is the top-level directory where your blog entries may be found locally.
This publishing style is used to output “books” in LaTeX or PDF format.
Each page will become a separate chapter in the book, unless the style keyword :nochapters is used, in which case they are all run together as if one giant chapter.
One way of publishing a book is to make a project for it, add the
project to muse-project-alist, and use the book-pdf style
with a very specific :include value to specify some page whose
contents will be checked for the values of #title and
#date, and whose name will be used in the output file. Then to
publish the book, visit the aforementioned page and use C-c C-t or
C-c C-p to trigger the publishing process. An example
muse-project-alist for this method follows.
(setq muse-project-alist
'(("MyNotes" (:nochapters t ; do automatically add chapters
:book-chapter "Computer Science"
"~/Notes/cs"
:book-chapter "Mathematics"
"~/Notes/math"
:book-chapter "Emacs"
"~/Notes/emacs"
:book-end t ; the rest will not be placed in the book
"~/Notes" ; so we can find the notes-anthology page
"~/Notes/private"
:force-publish ("index")
:default "index")
(:base "book-pdf"
:include "/notes-anthology[^/]*$"
:path "~/public_html/notes")
;; other publishing styles for each directory go here,
;; if desired
)))
In this example, there would be a file called ~/Notes/notes-anthology.muse, which would contain just the following. The resulting book would be published to ~/public_html/notes/notes-anthology.pdf.
#title My Technology Ramblings
Another way is to call the muse-book-publish-project function
manually, with a custom project entry. An example of this may be found
in John Wiegley's configuration file at
examples/johnw/muse-init.el, in the muse-publish-my-books
function.
book-latexbook-pdfmuse-book-before-publish-hookmuse-book-after-publish-hookmuse-book-latex-headerThis may be text or a filename.
muse-book-latex-footerThis may be text or a filename.
This publishing style is capable of producing ConTeXt or PDF documents.
If you wish to publish PDF documents based on ConTeXt, you will need to have it installed. For Debian and Ubuntu, this can be accomplished by installing the “texlive” package.
contextcontext-pdfcontext-slidesHere is an example of a slide.
* First Slide
[[Some-sort-of-cute-image.png]]
** A subheading
- A bullet point.
- Another bullet point.
* Second Slide
... and so on
context-slides-pdfmuse-context-extensionmuse-context-pdf-extensionmuse-context-pdf-programmuse-context-pdf-cruftmuse-context-headerThis may be text or a filename.
muse-context-footerThis may be text or a filename.
muse-context-markup-regexpsFor more on the structure of this list,
See muse-publish-markup-regexps.
muse-context-markup-functionsFor more on the structure of this list,
See muse-publish-markup-functions.
muse-context-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-context-slides-headerAny of the predefined modules, which are available in the tex/context/base directory, can be used by writing a "module" directive at the top of the Muse file; if no such directive is provided, module pre-01 is used. Alternatively, you can use your own style ("mystyle", in this example) by replacing "\usemodule[]" with "\input mystyle".
This may be text or a filename.
muse-context-slides-markup-stringsmuse-context-markup-specials-documentmuse-context-markup-specials-exampleWith the default interpretation of <example> regions, no
specials need to be escaped.
muse-context-markup-specials-literalmuse-context-markup-specials-urlmuse-context-markup-specials-imagemuse-context-permit-contents-tagMost of the time, it is best to have a table of contents on the first page, with a new page immediately following. To make this work with documents published in both HTML and ConTeXt, we need to ignore the <contents> tag.
If you don't agree with this, then set this option to non-nil, and it will do what you expect.
This publishing style is used to generate DocBook XML files.
docbookThis publishing style uses the same options for markup up special characters as the “xml” publishing style. See XML, for details.
muse-docbook-extensionmuse-docbook-headerThis may be text or a filename.
muse-docbook-footerThis may be text or a filename.
muse-docbook-markup-regexpsmuse-docbook-markup-functionsmuse-docbook-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-docbook-encoding-defaultmuse-docbook-charset-defaultmuse-xml-encoding-map.
This publishing style is capable of producing HTML or XHTML documents.
htmlxhtmlIf an HTML option does not have a corresponding XHTML option, it will be used for both of these publishing styles.
These publishing styles use the same options for markup up special characters as the “xml” publishing style. See XML, for details.
muse-html-extensionmuse-xhtml-extensionmuse-html-style-sheetThis is used in muse-html-header. You can put raw CSS in here or
a <link> tag to an external stylesheet. This text may contain
<lisp> markup tags.
If you are publishing to XHTML, then customize the
muse-xhtml-style-sheet option instead.
muse-xhtml-style-sheetThis is used in muse-xhtml-header. You can put raw CSS in here
or a <link> tag to an external stylesheet. This text may
contain <lisp> markup tags.
muse-html-headerThis may be text or a filename.
muse-html-footerThis may be text or a filename.
muse-xhtml-headerThis may be text or a filename.
muse-xhtml-footerThis may be text or a filename.
muse-html-anchor-on-wordThis allows you to select them in a browser (i.e. for pasting), but has
the side-effect of marking up headers in multiple colors if your header
style is different from your link style.
muse-html-table-attributesIf you want to make more-complicated tables in HTML, surround the HTML
with the literal tag, so that it does not get escaped.
muse-html-markup-regexpsmuse-html-markup-functionsmuse-html-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-xhtml-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-html-markup-tagsmuse-html-meta-http-equivmuse-html-meta-content-typeIf you are striving for XHTML 1.1 compliance, you may want to change
this to “application/xhtml+xml”.
muse-html-meta-content-encodingIf set to the symbol 'detect, use muse-xml-encoding-map to try
and determine the HTML charset from emacs's coding. If set to a string,
this string will be used to force a particular charset.
muse-html-charset-defaultmuse-xml-encoding-map.
muse-html-encoding-defaultIkiwiki is a wiki compiler (http://ikiwiki.info/). Emacs Muse can be used as a source format for Ikiwiki pages with the plugin IkiWiki::Plugin::muse.
The lisp/muse-ikiwiki.el file provides publishing functions and
styles for Ikiwiki. The plugin for Ikiwiki to recognize Muse files is
provided by the examples/ikiwiki/muse file. Two sample init
files are available in the examples/ikiwiki directory. Configure
your ikiwiki.setup file so that the muse_init variable
has the location of your Muse init file.
If you are using CGI, The directory examples/ikiwiki/IkiWiki must be copied to the same directory as the CGI script that Ikiwiki generates. When publishing your wiki, the PERL5LIB environment variable must contain the path to the examples/ikiwiki/IkiWiki directory.
ikiwikimuse-ikiwiki-headerThis may be text or a filename.
muse-ikiwiki-footerThis may be text or a filename.
muse-colors-evaluate-lisp-tagsThe actual contents of the buffer are not changed, only the
displayed text.
muse-html-src-allowed-modest,
permit the <src> tag to colorize any mode.
If a list of mode names, such as '("html" "latex"), and the lang
argument to <src> is not in the list, then use fundamental mode
instead.
muse-publish-enable-dangerous-tagsThis is useful to set to nil when the file to publish is coming
from an untrusted source.
The module facilitates the keeping and publication of a journal. When publishing to HTML, it assumes the form of a web log, or blog.
The input format for each entry is as follows.
* 20040317: Title of entry
text for the entry.
<qotd>
"You know who you are. It comes down to a simple gut check: You
either love what you do or you don't. Period." -- P. Bronson
</qotd>
The "qotd", or Quote of the Day, is entirely optional. When generated to HTML, this entry is rendered as the following.
<div class="entry">
<div class="entry-qotd">
<h3>Quote of the Day:</h3>
<p>"You know who you are. It comes down to a simple gut
check: You either love what you do or you don't. Period."
-- P. Bronson</p>
</div>
<div class="entry-body">
<div class="entry-head">
<div class="entry-date">
<span class="date">March 17, 2004</span>
</div>
<div class="entry-title">
<h2>Title of entry</h2>
</div>
</div>
<div class="entry-text">
<p>Text for the entry.</p>
</div>
</div>
</div>
The plurality of "div" tags makes it possible to display the entries in any form you wish, using a CSS style.
Also, an .RDF file can be generated from your journal by publishing it with the "rdf" style. It uses the first two sentences of the first paragraph of each entry as its "description", and auto-generates tags for linking to the various entries.
If you wish to publish an RDF or RSS feed, it is important to include
the :base-url attribute in your muse-project-alist entry
for your Journal projects. An example follows.
(setq muse-project-alist
'(("Journal" ("~/Journal/"
:default "journal")
(:base "journal-rss"
:base-url "http://example.org/journal/"
:path "~/public_html/journal"))))