This manual is for Emacs Muse version 3.20.
Copyright © 2004, 2005, 2006, 2007, 2008, 2009, 2010 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-defaultNote: Support for Ikiwiki is not yet complete. Use at your own risk.
Ikiwiki is a wiki compiler (http://ikiwiki.info/). Emacs Muse can (not yet) 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 contrib/ikiwiki/IkiWiki/Plugin/muse.pm 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 contrib/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 contrib/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"))))
journal-htmljournal-xhtmljournal-latexjournal-pdfjournal-book-latexjournal-book-pdfjournal-rdfjournal-rssjournal-rss-entryjournal-rss and journal-rdf for
publishing individual entries.
muse-journal-heading-regexpParen group 1 is the ISO date, group 2 is the optional category, and
group 3 is the optional heading for the entry.
muse-journal-date-formatmuse-journal-html-heading-regexpParen group 1 is the ISO date, group 2 is the optional category, and
group 3 is the optional heading for the entry.
muse-journal-html-entry-templateThis may be text or a filename.
muse-journal-latex-sectionmuse-journal-latex-subsectionmuse-journal-markup-tagsSee muse-publish-markup-tags, for more information.
This is used by journal-latex and its related styles, as well as
the journal-rss-entry style, which both journal-rdf and
journal-rss use.
muse-journal-rdf-extensionmuse-journal-rdf-base-urlmuse-journal-rdf-headerThis may be text or a filename.
muse-journal-rdf-footerThis may be text or a filename.
muse-journal-rdf-date-formatmuse-journal-rdf-entry-templateThis may be text or a filename.
muse-journal-rdf-summarize-entriesThe default is nil, because this annoys some subscribers.
muse-journal-rss-heading-regexpParen group 1 is the ISO date, group 2 is the optional category,
and group 3 is the optional heading for the entry.
muse-journal-rss-extensionmuse-journal-rss-base-urlmuse-journal-rss-headerThis may be text or a filename.
muse-journal-rss-footerThis may be text or a filename.
muse-journal-rss-date-formatmuse-journal-rss-entry-templateThis may be text or a filename.
muse-journal-rss-enclosure-types-alistThis is an alist that maps file extension to content type.
Useful for podcasting.
muse-journal-rss-summarize-entriesThe default is nil, because this annoys some subscribers.
muse-journal-rss-markup-regexpsFor more information on the structure of this list,
See muse-publish-markup-regexps.
muse-journal-rss-markup-functionsFor more on the structure of this list, See muse-publish-markup-functions.
This publishing style is capable of producing LaTeX or PDF documents.
If you wish to publish PDF documents, you will need to have a good LaTeX installation. For Debian and Ubuntu, this can be accomplished by installing the “tetex-bin” and “tetex-extra” packages. TeX fonts are also a must.
If your LaTeX installation has the file grffile.sty, which may be found in the texlive-latex-recommended package for Debian and Ubuntu, then consider using it by adding the following to your header file. This allows spaces in filenames to work.
\usepackage{grffile}
latexpdflatexcjkpdfcjkslidesHere is an example of a slide.
<slide title="First Slide">
Everything between the slide tags composes this slide.
[[Some-sort-of-cute-image.png]]
- A bullet point.
- Another bullet point.
</slide>
slides-pdflecture-notesThis can also use the <slide> tag.
lecture-notes-pdfmuse-latex-extensionmuse-latex-pdf-extensionmuse-latex-pdf-browserThis should be a format string.
muse-latex-pdf-programmuse-latex-pdf-cruftmuse-latex-headerThis may be text or a filename.
muse-latex-footerThis may be text or a filename.
muse-latexcjk-headerThis may be text or a filename.
muse-latexcjk-footerThis may be text or a filename.
muse-latex-slides-headerThis may be text or a filename.
You must have the Beamer extension for LaTeX installed for this to work.
muse-latex-lecture-notes-headerThis may be text or a filename.
You must have the Beamer extension for LaTeX installed for this to work.
muse-latex-markup-regexpsFor more on the structure of this list,
See muse-publish-markup-regexps.
muse-latex-markup-functionsFor more on the structure of this list,
See muse-publish-markup-functions.
muse-latex-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-latex-slides-markup-tagsmuse-latexcjk-encoding-mapmuse-latexcjk-encoding-defaultThis will be used if no special characters are found.
muse-latex-markup-specials-documentmuse-latex-markup-specials-exampleWith the default interpretation of <example> regions, no
specials need to be escaped.
muse-latex-markup-specials-literalmuse-latex-markup-specials-urlmuse-latex-markup-specials-imagemuse-latex-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 LaTeX, 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.
The muse-poem module makes it easy to attractively publish and
reference poems in the following format, using the "memoir" module for
LaTeX publishing. It will also markup poems for every other output
style, though none are nearly as pretty.
Title
Body of poem
Annotations, history, notes, etc.
Once a poem is written in this format, just publish it to PDF using the
poem-pdf style. To make an inlined reference to a poem that
you've written – for example, from a blog page – there is a "poem" tag
defined by this module.
<poem title="name.of.poem.page">
Let's assume the template above was called name.of.poem.page; then the above tag would result in this inclusion.
** Title
> Body of poem
John Wiegley uses this module for publishing all of the poems on his website, which are at http://www.newartisans.com/johnw/poems.html.
poem-latexpoem-pdfchapbook-latexchapbook-pdfmuse-poem-latex-headerThis may be text or a filename.
muse-poem-latex-footerThis may be text or a filename.
muse-poem-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-chapbook-latex-headerThis may be text or a filename.
muse-chapbook-latex-footerThis may be text or a filename.
muse-poem-chapbook-stringsThese cover the most basic kinds of markup, the handling of which differs little between the various styles.
Rules for publishing a Muse file as a Texinfo article.
texiinfoinfo-pdfmuse-texinfo-process-nativelymuse-texinfo-extensionmuse-texinfo-info-extensionmuse-texinfo-pdf-extensionmuse-texinfo-headerThis may be text or a filename.
It may contain <lisp> markup tags.
muse-texinfo-footerThis may be text or a filename.
It may contain <lisp> markup tags.
muse-texinfo-markup-regexpsFor more on the structure of this list,
See muse-publish-markup-regexps.
muse-texinfo-markup-functionsFor more on the structure of this list,
See muse-publish-markup-functions.
muse-texinfo-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-texinfo-markup-specialsmuse-texinfo-markup-specialsMuse is capable of publishing XML documents, with the help of the muse-xml.el module.
A RelaxNG schema is available as part of the Muse distribution in the etc/muse.rnc file.
xmlmuse-xml-encoding-mapmuse-xml-markup-specialsmuse-xml-markup-specials-url-extraThese are extra characters that are escaped within URLs.
muse-xml-extensionmuse-xml-headerThis may be text or a filename.
muse-xml-footerThis may be text or a filename.
muse-xml-markup-regexpsFor more on the structure of this list,
See muse-publish-markup-regexps.
muse-xml-markup-functionsFor more on the structure of this list,
See muse-publish-markup-functions.
muse-xml-markup-stringsThese cover the most basic kinds of markup, the handling of which
differs little between the various styles.
muse-xml-encoding-defaultThis will be used if no special characters are found.
muse-xml-charset-defaultmuse-xml-encoding-map.
An alist of style types to custom functions for that kind of text.
This is used by publishing styles to attempt to minimize the amount of custom regexps that each has to define. muse-publish provides rules for the most common types of markup.
Each member of the list is of the following form.
(SYMBOL FUNCTION)
muse-publish-markup-regexps maps regexps to these symbols.
List of markup rules for publishing a page with Muse.
The rules given in this variable are invoked first, followed by whatever rules are specified by the current style.
Each member of the list is either a function, or a list of the following form.
(REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
If it is not a string, but a function, it will be called to determine what the replacement text should be (it must return a string). If it is a symbol, the value of that symbol should be a string.
The replacements are done in order, one rule at a time. Writing the regular expressions can be a tricky business. Note that case is never ignored. `case-fold-search' is always bound to nil while processing the markup rules.
This is the order that the publishing rules are consulted, by default.
This may be changed by customizing muse-publish-markup-regexps.
trailing and leading whitespacedirectiveThis is only recognized at the beginning of a file.
commenttagcommentexplicit linksDon't actually publish them here, just add a special no-emphasis text
property.
wordThis function is responsible for marking up emphasis and escaping some
specials.
headingOutline-mode style headings.
enddotsThese are ellipses with a dot at end.
dotsEllipses.
ruleHorizontal rule or section separator.
no-break-spacePrevent lines from being split before or after these characters.
line-breakBreak a line at point.
fn-sepBeginning of footnotes section.
footnoteFootnote definition or reference. If at beginning of line, it is a
definition.
listNumbered list, item list, or term definition list.
table-eltableMuse tables or orgtbl-mode style tables.
quoteBlockquotes.
emdash2-wide dash
verseanchorlinkurlemailMarkup strings are strings used for marking up text for a particular style.
These cover the most basic kinds of markup, the handling of which differs little between the various styles.
image-with-descArgument 1: image without extension. Argument 2: image extension.
Argument 3: description.
imageArgument 1: image without extension. Argument 2: image extension.
image-linkArgument 1: link. Argument 2: image without extension.
Argument 3: image extension.
anchor-refArgument 1: anchor name. Argument 2: description if one exists, or the
original link otherwise.
urlArgument 1: URL.
linkArgument 1: link. Argument 2: description if one exists, or the
original link otherwise.
link-and-anchorArgument 1: link. Argument 2: anchor name.
Argument 3: description if one exists, or the original link otherwise.
Argument 4: link without an extension.
email-addrArgument 1: email address. Argument 2: email address.
anchorArgument 1: name of anchor.
emdashArgument 1: Initial whitespace. Argument 2: Terminating whitespace.
comment-begincomment-endruleno-break-spacefootnotefootnote-endfootnotemarkArgument 1: number of this footnote.
footnotemark-endfootnotetextArgument 1: number of this footnote.
footnotetext-endfn-sepdotsenddotspartpart-endchapterchapter-endsectionArgument 1: level of section; always 1.
section-endArgument 1: level of section; always 1.
subsectionArgument 1: level of section; always 2.
subsection-endArgument 1: level of section; always 2.
subsubsectionArgument 1: level of section; always 3.
subsubsection-endArgument 1: level of section; always 3.
section-otherArgument 1: level of section.
section-other-endArgument 1: level of section.
begin-underlineend-underlinebegin-literalend-literalbegin-emphend-emphbegin-more-emphend-more-emphbegin-most-emphend-most-emphbegin-verseverse-spacebegin-verse-lineempty-verse-linebegin-last-stanza-lineend-last-stanza-lineend-versebegin-exampleend-examplebegin-centerend-centerbegin-quoteend-quotebegin-quote-itemend-quote-itembegin-uliend-ulibegin-uli-itemend-uli-itembegin-oliend-olibegin-oli-itemend-oli-itembegin-dlend-dlbegin-dl-itemend-dl-itembegin-ddtend-ddtbegin-ddeend-ddebegin-tableend-tablebegin-table-groupend-table-groupbegin-table-rowend-table-rowbegin-table-entryend-table-entryA list of tag specifications, for specially marking up text.
XML-style tags are the best way to add custom markup to Muse. This is easily accomplished by customizing this list of markup tags.
For each entry, the name of the tag is given, whether it expects a closing tag and/or an optional set of attributes, whether it is nestable, and a function that performs whatever action is desired within the delimited region.
The tags themselves are deleted during publishing, before the function is called. The function is called with three arguments, the beginning and end of the region surrounded by the tags. If properties are allowed, they are passed as a third argument in the form of an alist. The `end' argument to the function is always a marker.
Point is always at the beginning of the region within the tags, when the function is called. Wherever point is when the function finishes is where tag markup will resume.
These tag rules are processed once at the beginning of markup, and once at the end, to catch any tags which may have been inserted in-between.
Style elements are tags that define a style. Use either
muse-define-style or muse-derive-style
(see Deriving Styles) to create a new style.
For example, PDF publishing generates a LaTeX file first, then a PDF
from that LaTeX file.
These cover the most basic kinds of markup, the handling of which
differs little between the various styles.
This is used to set extra parameters that direct the publishing process.
This is used to fix the order of table elements (header, footer, body)
in XML-ish styles.
This is used for generating the table of contents as well as setting the
file coding system.
This is used for generating second-stage documents like PDF files from just-published LaTeX files.
The function must accept three arguments: the name of the muse source
file, the name of the just-published file, and the name of the
second-stage target file. The name of the second-stage target file is
the same as that of the just-published file if no second-stage
publishing is required.
This may be a variable, text, or a filename. It is inserted at the
beginning of a file, after evaluating the publishing markup.
This may be a variable, text, or a filename. It is inserted at the end
of a file, after evaluating the publishing markup.
This may be a variable or text. It is used in the header of HTML and
XHTML based publishing styles.
To create a new style from an existing one, use muse-derive-style
as follows. This is a good way to fix something you don't like about a
particular publishing style, or to personalize it.
The derived name is a string defining the new style, such as "my-html". The base name must identify an existing style, such as "html" – if you have loaded muse-html. The style parameters are the same as those used to create a style, except that they override whatever definitions exist in the base style. However, some definitions only partially override. The following parameters support partial overriding.
See Style Elements, for a complete list of all parameters.
muse-list-edit-minor-mode is meant to be used with other major
modes, such as Message (for composing email) and debian-changelog-mode
(for editing debian/changelog files).
It implements practically perfect support for editing and filling lists. It can even handle nested lists. In addition to Muse-specific list items ("-", numbers, definition lists, footnotes), it can also handle items that begin with "*" or "+". Filling list items behaves in the same way that it does in Muse, regardless of whether filladapt is also enabled, which is the primary reason to use this tool.
To use it, add “(require 'muse-mode)” to your Emacs customization file
and add the function turn-on-muse-list-edit-minor-mode to any
mode hooks where you wish to enable this minor mode.
muse-list-edit-minor-mode uses the following keybindings.
This is a global minor mode for editing files with lists. It is meant to be used with other major modes, and not with Muse mode.
Interactively, with no prefix argument, toggle the mode. With universal prefix arg turn mode on. With zero or negative arg turn mode off.
This minor mode provides the Muse keybindings for editing lists, and support for filling lists properly.
It recognizes not only Muse-style lists, which use the "-" character or numbers, but also lists that use asterisks or plus signs. This should make the minor mode generally useful.
Definition lists and footnotes are also recognized.
Note that list items may omit leading spaces, for compatibility with modes that set
left-margin, such asdebian-changelog-mode.
After you have read this guide, if you still have questions about Muse, or if you have bugs to report, there are several places you can go.
You can join this mailing list (muse-el-announce@gna.org)
using the subscription form at
http://mail.gna.org/listinfo/muse-el-announce/. This
mailing list is also available via Gmane (http://gmane.org/). The
group is called ‘gmane.emacs.muse.announce’.
You can join this mailing list (muse-el-discuss@gna.org)
using the subscription form at
http://mail.gna.org/listinfo/muse-el-discuss/. This mailing
list is also available via Gmane with the identifier
‘gmane.emacs.muse.general’.
You can join this mailing list (muse-el-logs@gna.org) using
the subscription form at
http://mail.gna.org/listinfo/muse-el-logs/. This mailing list
is also available via Gmane with the identifier
‘gmane.emacs.muse.scm’.
You can join this mailing list (muse-el-commits@gna.org) using
the subscription form at
http://mail.gna.org/listinfo/muse-el-commits/. This mailing list
is also available via Gmane with the identifier
‘gmane.emacs.muse.cvs’.
You can join this mailing list (muse-el-internationalization@gna.org) using the subscription form at http://mail.gna.org/listinfo/internationalization/. This mailing list is also available via Gmane with the identifier ‘gmane.emacs.muse.internationalization’.
Most of those who frequent the emacs-wiki mailing list continued to use emacs-wiki, mainly because Planner hasn't been ported over to it.
As of 2004-12-01, Michael Olson became the maintainer of Muse, as per John Wiegley's request.
The first draft of this document was taken from the emacs-wiki texinfo manual. Michael Olson adapted it for Muse and added most of its content.
John Sullivan did a majority of the work on the emacs-wiki texinfo manual.
While Sacha Chua maintained emacs-wiki, she worked quite a bit on the emacs-wiki texinfo manual.
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft,” which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document,” below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you.” You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque.”
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements,” “Dedications,” “Endorsements,” or “History.”) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History,” Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled “History” in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the “History” section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications,”
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section Entitled “Endorsements.” Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled “Endorsements”
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements,” provided it contains nothing but endorsements of your Modified Version by various parties–for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements,” and any sections Entitled “Dedications.” You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements,” “Dedications,” or “History,” the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
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, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License.''
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with the
Front-Cover Texts being list, and with the Back-Cover Texts being
list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
muse-define-style: Style Elementsmuse-derive-style: Deriving Stylesmuse-list-edit-minor-mode: Muse List Edit Minor Modeturn-off-muse-list-edit-minor-mode: Muse List Edit Minor Modeturn-on-muse-list-edit-minor-mode: Muse List Edit Minor Mode