This manual is for Emacs Muse version 3.02.93 (3.03 RC3).
Copyright © 2004, 2005, 2006 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License.
--- The Detailed Node Listing ---
How to Get Muse Releases and Development Changes
Rules for Using Markup
Publishing Various Types of Documents
Integrating Muse and pyblosxom.cgi
Making your own publishing styles
Common functionality shared by styles
This document describes Muse, which was written by John Wiegley and is now maintained by Michael Olson. Several versions of it are available on-line.
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.
This idea is not in any way new. Numerous systems exist – even one other for Emacs itself (Bhl Mode). What Muse adds to the picture is a more 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.
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 and Ubuntu users can get Muse via apt-get. The muse-el
package is available both at Michael Olson's APT repository and the
official Debian and Ubuntu repositories. 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://www.mwolson.org/debian/ ./
Alternatively, you can download the latest release from http://www.mwolson.org/static/dist/muse/ .
Choose the development version if you want to live on the bleeding edge of Muse development or try out new features before release.
The Arch revision control system allows you to retrieve previous versions and select specific features and bug fixes. If you would like to contribute to Muse development, it is highly recommended that you use Arch, but this is not a requirement.
If you are new to Arch, you might find this tutorial helpful: http://www.mwolson.org/projects/ArchTutorial.html.
Downloading the Muse module with Arch and staying up-to-date involves the following steps.
tla register-archive -f http://www.mwolson.org/archives/2005
# Download Muse into the muse directory.
tla get mwolson@gnu.org--2005/muse--main--1.0 muse
# Change to the source directory you are interested in.
cd muse/
# Display the summary of changes
tla missing --summary
cd muse
tla replay
There are other ways to interact with the Muse archive.
The latest development snapshot will be kept up-to-date since it is updated at the same time as the Arch repository.
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. It will yield a speed increase, though.
A working copy of Emacs or XEmacs is needed in order to compile the 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 would need to edit Makefile.defs in the top-level directory 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
Running make should compile the Muse source files in the
lisp directory.
Muse may be installed into your file hierarchy by doing the following.
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. Of course, 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.
Run make install as the root user if you have chosen installation
locations that require this.
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)
Once loaded, the command M-x muse-publish-this-file will publish an input document to any available style. If you enable muse-mode within a buffer, by typing M-x muse-mode, this command will be bound to C-c C-t.
If the currently opened file is part of a defined project in
muse-project-alist, it may be published using C-c C-p.
You should also type M-x customize-group, and give the name `muse'. Each of the options has its own documentation.
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 creations of "projects". Here is a sample project, to be defined in your .emacs file.
(require 'muse-project)
(setq muse-project-alist
'(("website" ; my various writings
("~/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]]'.
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)
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.
This is a summary of keystrokes available in every Muse buffer.
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.
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.
- bullet item one
- bullet item two
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
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.
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://www.mwolson.org/projects/EmacsMuse.html][here]]', or at `[[http://www.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.
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://www.mwolson.org/.
[[http://www.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, which is the only Muse tag supported in a style's header and footer text. With the <lisp> tag, you may generated 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.
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.
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.
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.
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 "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.
<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 "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.
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 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. Eventually it is hoped that a blosxom.cgi plugin and script will be found/written.
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.
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.
You will need to call the muse-book-publish-project function in
order to publish this style. An example of this may be found in John
Wiegley's configuration file at examples/johnw/muse-johnw.el.
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 used to generate DocBook XML files.
docbookmuse-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-markup-specialsmuse-docbook-encoding-defaultmuse-docbook-charset-defaultmuse-docbook-encoding-map.
muse-docbook-encoding-mapThis 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.
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 using XHTML, make sure to close the <link> tag
properly.
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-markup-specialsmuse-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-html-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-html-encoding-map.
muse-html-encoding-defaultmuse-html-encoding-mapThe 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.
journal-htmljournal-xhtmljournal-latexjournal-pdfjournal-book-latexjournal-book-pdfjournal-rdfjournal-rssmuse-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-templatemuse-journal-latex-sectionmuse-journal-latex-subsectionmuse-journal-latex-markup-tagsSee muse-publish-markup-tags, for more information.
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-templatemuse-journal-rdf-summarize-entriesmuse-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-templatemuse-journal-rss-enclosure-types-alistThis is an alist that maps file extension to content type.
Useful for podcasting.
muse-journal-rss-summarize-entriesMany RSS subscribers find this annoying.
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 TeX installation. For Debian and Ubuntu, this can be accomplished by installing the “tetex-bin” and “tetex-extra” packages. TeX fonts are also a must.
latexpdflatexcjkpdfcjkmuse-latex-extensionmuse-latex-pdf-extensionmuse-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-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-latexcjk-encoding-mapmuse-latexcjk-encoding-defaultThis will be used if no special characters are found.
muse-latex-markup-specials-exampleWith the default interpretation of <example> regions, no
specials need to be escaped.
muse-latex-markup-specials-documentmuse-latex-markup-specials-literalmuse-latex-markup-specials-urlmuse-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
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-specialsAn 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.
tagcommentanchorexplicit 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.
emdash2-wide dash
headingOutline-mode style headings.
enddotsThese are ellipses with a dot at end.
dotsEllipses.
ruleHorizontal rule or section separator.
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.
quoteBlockquotes.
versetablelinkurlemailMarkup 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.
email-addrArgument 1: email address. Argument 2: email address.
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-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
muse-define-style to create a new style.
(muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
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.
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.
(muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
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.
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-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 © 1989, 1991 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 licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software—to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
one line to give the program's name and a brief idea of what it does.
Copyright (C) yyyy name of author
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items—whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.