本手册针对 Emacs Muse 3.02.92 (3.03 RC2) 版本。
Copyright © 2004, 2005, 2006 Free Software Foundation, Inc.
基于 GNU 通用公共许可证（General Public Licese）的条款任何人有权复制，发布和/或修改本文档。[翻译]：郑海永(Haiyong Zheng) zhyfly.org@gmail.com http://www.zhyfly.org/
--- 详细节点列表 ---
怎样获得 Muse 发行及开发更新
使用标记的规则
发布不同类型的文档
集成 Muse 和 pyblosxom.cgi
制作你自己的发布风格
风格共有的通用功能
本文档描述了 Muse，它由 John Wiegley 所写，现在由 Michael Olson 维护。本文档有下面几种在线版本可用。
Emacs Muse 是一个基于 Emacs 的写作和发布平台。它简化了文档编辑过程，并且可以选择多种格式进行发布。
Muse 包括两个主要部分：一个增强的 text 模式，用来编辑文档和在 Muse 工程中随意浏览文档；一组发布策略，用来产生各种不同的格式输出。
然而这种思想并不新颖，有大量类似的系统存在 ── 甚至 Emacs 本身就有另外一个（Bhl Mode）。Muse 所增色的地方是一个更加模块化的平台，带有一个相当简单的核心，在这个平台上“风格”可被派生而生成新的风格。Muse 全部的功能中大部分是可选的。比如，你可以不在 major-mode 下使用发布功能，或者在 major-mode 下但不做任何发布；又或者如果你不加载 Texinfo 或 LaTeX 模块，那么相应的那些风格就不可用。
Muse 代码基于 emacs-wiki.el 版本 2.44，但代码已经重新组织和改写，特别是那些发布函数。此次修订的重点在写作和发布方面，Wiki 部分作为其中一个默认的行为（在可选的 muse-wiki 模式中）。在默认情况下 CamelCase 词组（每个单词的第一个字母都大写，其它小写）不再特殊对待。
如果你想承担最小的风险，那么选择安装一个发行版。
错误被首先在开发中更正。用户可见的修正将公布在 muse-el-discuss@gna.org 邮件列表中。See Getting Help and Reporting Bugs。
Debian
和 Ubuntu 用户可以通过 apt-get 获得 Muse。muse-el 包在
Michael Olson 的 APT 仓库及官方 Debian 和 Ubuntu 仓库都可用。要使用 Michael Olson 的 APT
仓库，添加下面一行到你的 /etc/apt/sources.list 文件并运行
apt-get install muse。
deb http://www.mwolson.org/debian/ ./
另外，你也可以从 http://www.mwolson.org/static/dist/muse/ 下载最新的发行版。
如果你想要追求 Muse 开发的最新技术或者在发行前尝试新特色，那么选择开发版本。
Arch 修正控制系统允许你找回以前的版本，从而选择某些指定的特色和 bug 修复。如果你想帮助 Muse 开发，强烈推荐使用 Arch，但这并不是一个必要条件。
如果 Arch 对你来说是陌生的，你可能会认为下面这篇手册很有帮助： http://www.mwolson.org/projects/ArchTutorial.html。
使用 Arch 下载 Muse 模块，并参照下面步骤保持最新。
tla register-archive -f http://www.mwolson.org/archives/2005
# 下载 Muse 到 muse 目录。
tla get mwolson@gnu.org--2005/muse--main--1.0 muse
# 进入你关心的源目录。
cd muse/
# 显示更改概要。
tla missing --summary
cd muse
tla replay
与 Muse 归档交互还有一些其他的方法。
最新开发快照与 Arch 存储库同时被更新，因此它始终保持最新。
Muse 可以在你的机器上被编译并安装。
这是一个可选的步骤，因为 Emacs Lisp 源代码没有必要必须进行字节编译。但这样做可以产生速度的提升。
为了编译 Emacs Muse，一个Emacs 或 XEmacs 的工作副本是必须的。默认情况下，安装时命名为 emacs 的程序将被使用。
如果你想要使用二进制文件 xemacs 来执行编译，你需要象下面这样编辑顶层目录中的 Makefile.defs 文件。你可以输入 Emacs 或者 XEmacs 二进制文件所在的全路径，或者只要其全路径在环境变量 PATH 中就可以仅仅输入命令名。
EMACS = xemacs
SITEFLAG = -no-site-file
运行 make 就会编译 lisp 目录中的 Muse
源文件。
通过下述操作 Muse 可以被安装到你的文件层次结构中。
编辑 Makefile.defs 文件使得 ELISPDIR 指向你想要的 Muse 源文件和编译文件的安装路径， INFODIR 表示 Muse 手册的安装路径。当然，如果你使用 XEmacs 你需要如编译部分所说的那样编辑 EMACS 和 SITEFLAG。
如果你在一个 Debian 或者 Ubuntu 系统中安装 Muse，你可能需要按照文件 Makefile.defs 中的说明更改变量 INSTALLINFO 的值。
如果你想要安装 Muse 到一个非默认指定的位置，那么如前所说，编辑 Makefile.defs 文件。
然后以普通用户身份运行 make。
如果你选择的安装位置要求必须 root 用户，那么以 root 身份运行 make install。
要使用
Muse，添加包含 Muse 文件的目录到你的 load-path 变量中，它一般在你的 .emacs 文件中定义。然后，加载写作模式和你想要发布的文档风格。下面是一个例子。
(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)
一旦 Muse 模式被加载，命令 M-x muse-publish-this-file 将发布一个输入文档为任意可用的风格。如果你想在一个 buffer 中启用 muse-mode，那么输入 M-x muse-mode，它被绑定到 C-c C-t。
如果当前打开的文件属于 muse-project-alist 中一个定义的项目，那么可以使用 C-c
C-p 来发布它。
你也可以输入 M-x customize-group，然后给出名 `muse'。每一个选项都有它自己的文档。
通常你希望自动将一个目录中的所有文件发布为一组特定的输出风格，为此， Muse 允许创建“项目”。下面是一个定义在你的 .emacs 文件中的项目范例。
(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"))))
上面定义了一个名为“website”的项目，该项目所有的文件都位于目录 ~/Pages 下，默认的访问页为 index。当该项目被发布时，每一页将会以 HTML 格式输出到 ~/public_html 目录中，并以 PDF 格式输出到 ~/public_html/pdf 目录中。在项目中的任一页中，你可以使用语法 `[[pagename]]' 创建到其他页的链接。
默认情况下 Muse 要求所有的项目文件具有扩展名 .muse，不具有这个扩展名的文件将不会被关联到 Muse 模式，也将不会被看作任何项目的一部分，即使这些文件确确实实在一个项目目录中。
如果你不想使用扩展名 .muse，你可以通过设置
muse-file-extension 的值来自定义扩展名。
如果你不想使用任何扩展名，而是想要 Muse 基于项目文件位置自动探测项目文件，那么在你的 Muse 设置文件中加入下面两行。
(setq muse-file-extension nil
muse-mode-auto-p t)
如果你想要仅仅包括一个目录中的几个文件，那么你需要使用一个正则表达式代替例子中的 ~/Pages。
一个 Muse 文档使用特别的、文脉上的标记规则来决定怎样格式化输出结果。例如，如果一个段落被缩进了，Muse 就认为它应该被引用。
并没有太多的标记规则，而且所有的标记规则力争简单以便让使用者更加专注于文档创作，而不是格式。
以六个或者更多的空白字元（Tab 或者空格）开始的一行表示一个居中的段落。另外，你也可以使用 <center> 标签使得其包含的区域被发布为居中的段落。
但是如果一行以空白字元开始，但空白字元不足六个，这表示一个引用的段落。另外，你也可以使用 <quote> 标签使得起包含的区域被发布为引用的段落。
<example> 标签用于示例，其中空白应该被保留，等宽间距文本，且输出风格的任意特殊字符都被转义。
还有一个 <literal> 标签，作用是使得所标记的块全部原样输出。比如这可以用来插入一段手编的 HTML 代码到 HTML 输出。
依赖于输出风格一个标题会成为打印输出的一章或者一节。以一个或几个星号开始一个新的段落，后面跟一个空格和标题题目，来表示一个标题。然后另起一段输入这部分的正文。
所有层次的标题都将会被发布，然而，大部分发布风格仅仅会区分头四个层次。
* First level
** Second level
*** Third level
**** Fourth level
文档中全部的段落或者区段前以 `#' 开始的行是指令。指令的格式为 “#directive content of directive”。你可以使用任意大小写字母的组合作为指令，即使它没有在下面列出。
muse-publishing-directive 函数可以被用于页眉和页脚来存取指令。例如，使用
(muse-publishing-directive "title") 来存取 `#title' 指令。
#author
如果它没有被指定，Muse 将试图从变量 user-full-name 来推断它。
#date
它由那些能够嵌入日期信息的发布风格使用。
#desc
它被 journal 发布风格用来在一个 RSS/RDF 源内部嵌入信息。
#title
如果它没有被指定，那么将使用文件名作为文档题目。
*emphasis*
**strong emphasis**
***very strong emphasis***
_underlined_
=verbatim and monospace=
当在 Muse 模式下编辑一个 Muse 文档时，这些强调形式将会以一种所见即所得（WYSIWYG）的方式高亮显示。每种形式可跨越多行。
抄录（verbatim）文本默认情况下被灰色显示，定制 muse-verbatim-face 来改变它。
你也可以使用 <code> 标签来表示抄录（verbatim）和等宽（monospace）文本，这在本身含有“=”的区域中很方便。
一个脚注引用就是简单的一个在方括号中的数字，在你的文件底部放置脚注的注解来定义它。`footnote-mode' 可以被用来非常方便的生成这种脚注。
脚注由行首方括号内的相同数字所定义，在输入的时候使用 footnote-mode 的 C-c ! a 命令会很容易的插入脚注，使用 C-x C-x 便返回插入点。
诗要求空白字元被保留，但不采取等宽。为显示诗使用下面的标签，它让我们想起 email 引用的方式。
> A line of Emacs verse;
> forgive its being so terse.
你也可以使用 <verse> 标签，如果你喜欢。
<verse>
A line of Emacs verse;
forgive its being so terse.
</verse>
<verse>
A line of Emacs verse;
forgive its being so terse.
In terms of terse verse,
you could do worse.
</verse>
列表是由行首使用的特殊字符产生，在符号列表项或数字列表项前必须有一个空白字元用于区别那些字符可能确实出现在一个句子中的情况。
- 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
Double bars || Separate header fields
Single bars | Separate body fields
Here are more | body fields
Triple bars ||| Separate footer fields
一些发布风格要求首先是表头，紧跟着是表底，然后才是表体。你可以对这些部分使用你喜欢的任意顺序，Muse 在发布时将会为你重新排序。
如果你想禁用一个 Muse 文件的表格生成，添加指令 `#disable-tables t' 到文件的顶部。
一个超级链接可以引用一个 URL或者某个 Muse 项目中的其他页面。另外，描述文本可以被指定并在支持链接描述的输出风格中显示，而不是显示链接文本。
[[link target][link description]]
[[link target without description]]
因而，当前 Muse 维护者的主页可以从 `[[http://www.mwolson.org/projects/EmacsMuse.html][here]]'，或者 `[[http://www.mwolson.org/projects/EmacsMuse.html]]' 找到。
输入文本中的一个 URL 或者 email 地址被发布为一个超链接，这种链接被称做 implicit links，因为不管怎样它们与 Muse 文档的其他部分没有分离。
URL 中的一些字符会禁止 Muse 把它们当作 implicit links，如果你想要链接一个包含空格或者“][,"'`()<>^”中任一个字符的 URL，那么你必须使用 explicit links，当“.,;:”这些标点符号出现在一个 URL 的末尾时它们也不会被看做是这个 URL 的一部分。关于如何写一个 explicit link 参见 Hyperlinks and email addresses with descriptions。
如果 muse-wiki 模块被加载，另一种 implicit link 的形式就可用了。以 CamelCase 形式输入的 Wikinames 被高亮显示并发布为链接，这提供给该文件一种引用其他存在文件的方式。
通过编辑 muse-wiki-wikiword-regexp 选项接着运行
(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)
就可以完成 WikiName 认可定制。如果你使用定制界面，后面的部分会自动完成。
muse-wiki 模式也允许 InterWiki links，这与 WikiWords 很相似，但
InterWiki links 不但可以指定某个项目，而且也可以指定某个文件页面。默认情况下在 muse-project-alist
中定义的项目条目名将被用于 InterWiki 名。下面是几个例子。
Blog::DocumentingMuse
Projects#EmacsMuse
Website
第一种情况，interwiki 分隔符是 `::'，`Blog' 为项目名， `DocumentingMuse' 为页面名；第二种情况，`#' 是 interwiki 分隔符。象第三种情况这样，如果一个项目名单独出现在文本中，那么它会被加色并发布为一个指向该工程默认页面的一个链接。
通过编辑 muse-wiki-interwiki-alist 选项可以完成 interwiki links 的定制。
指向图片的链接可以被用于目标或者描述中，也可以两者都使用。所以，下面的代码会发布一个指向 http://www.mwolson.org/ 可点击的图片。
[[http://www.mwolson.org/][/static/logos/site-logo.png]]
如果在链接描述中遇到一个指向本地可用图片的链接，并且你的 Emacs 版本允许图片显示，那么 Muse 模式会试图显示它。
这个行为可以由 C-c C-i 触发，或者通过设置选项 muse-colors-inline-images
为 nil 来永久禁止此功能。
通过定制 muse-colors-inline-image-method 选项可以 Muse
改变查找图片的方式。这个选项的一个有用的值为 muse-colors-use-publishing-directory，它告诉
Muse 模式去查找当前文件将要被发布的目录。默认情况下是在当前目录下查找。对于任一设置类似 `../pic/' 这样的相对路径应该是有效的。
最后，我们希望通过定制 muse-project-alist Muse
能够从一个“源”目录复制图片到一个发布目录中，但这个功能尚未完成。
如果在 ../pics/ 目录中存在一个叫做 TestLogo.png 的文件，那么下面的这个例子将会正确显示和发布。如果文本与图片在同一行，那么在输出中也是如此。
[[../myimage.png]]
如果你想要为一幅图片添加标题，使用下面的语法。它将图片居中（如果所发布的格式支持该功能）并在图片下面添加一个居中的标题。对于那些不支持图片居中的格式将以图片紧靠左边界来代替。
[[../pics/mycat.png][My cat Dexter]]
带有标题的图片仅可以自成一段，在同一行不允许有文本。否则，发布的输出句法上是错误的。
四个或者更多的破折号（-）表示一个水平线。确保其前后都是空行，否则它将被看作是前面或后面段落的一部分。
如果你以“#anchor”开始一行 ── 其中“anchor”可以是任意不包含空白字元的单词 ── 那么它在所在位置定义了一个进入文档内部的锚。在一个 Muse 链接中使用“page#anchor”作为目标就可以引用这个锚点。
使用 <lisp> 标签可以得到任意种类的标记，它也是仅有的在一个风格的页眉和页脚文本中支持的 Muse 标签。使用 <lisp> 标签你可以生成任意你想要的输出。如果 <lisp> 标签出现在文档正文内部，那么插入的输出将会被标记出。
<lisp>(concat "This form gets " "inserted")</lisp>
注意不能在一组
<lisp> 标签中使用 insert 命令，因为这样的话 <lisp>
标签的返回值将被自动插入文档中。
; Comment text goes here.
也就是说，仅仅行首一个分号，紧跟一个文字空白，就使得这一行被当作注释了。
在发布过程中 Muse 有几个内嵌标签证明非常有用。See muse-publish-markup-tags 来了解怎样定制 Muse 使用的标签和怎样制作你自己的标签。
如果一个标签带有参数，那么它就会看起来象下面这样，其中“tagname”是标签名。
<tagname arg1="string1" arg2="string2">
如果你想要一个标签看起来更象来自一个标准的 XHTML 文档，作为选择你可以照下面这样做。
<tagname arg1="string1" arg2="string2" />
如果一个标签包围一些文本，那么它看起来象下面这样。
<tagname>Some text</tagname>
如果一个标签包围一大块区域，那么它看起来象下面这样。
<tagname>
Some text.
Some more text.
</tagname>
下面是 Muse 所采用的完整的标签列表，其中包括前面章节中所提到的那些标签。
如果发布成其他的格式，那么对文本没有任何作用。
“markup”参数控制这块区域是怎样被标记。
如果它被省略，那么使用正常的 Muse 规则发布这个区域。
如果是“nil”，那么根本不标记这个区域，但也禁止 Muse 进一步解释它。
如果是“example”，那么这个区域就象被 <example> 标签包围那样被处理。
如果是“verse”，那么这个区域就象被 <verse> 标签包围那样被处理，保留其中的新行。
否则，它应是要调用的一个函数名，带有一个被限定在这个区域的 buffer。
默认情况下生成的目录中仅仅包含一级和二级标题。定制 muse-publish-contents-depth
选项来全局地改变它。要想仅仅为当前这个标签改变，使用“depth”参数。
<include file="included_file">
“markup”参数控制这块区域是怎样被标记。
如果它被省略，那么使用正常的 Muse 规则发布被包括的文本。
如果是“nil”，那么根本不标记被包括的文本。
如果是“example”，那么被包括的文本就象被 <example> 标签包围那样被处理。
如果是“verse”，那么被包括的文本就象被 <verse> 标签包围那样被处理，保留其中的新行。
否则，它应是插入文件后要调用的一个函数名，带有一个被限定在被插入区域的 buffer。
insert。结果文本中的所有文本属性被去掉。
这个标签带有“markup”参数，参见 <command> 的描述查看细节。
这在页眉和页脚中标记区域时非常有用。记忆中的一个例子就是通过下面的操作生成一个当前项目下的所有文件的发布索引。
<markup><lisp>(muse-index-as-string t t)</lisp></markup>
这个标签带有“markup”参数，参见 <command> 的描述查看细节。
这个标签带有“markup”参数，参见 <command> 的描述查看细节。
这个标签带有“markup”参数，参见 <command> 的描述查看细节。
在前面的 Muse 版本中这个标签使用很频繁因为那些版本不支持整个文档的特殊转义。现在，这个标签仅仅为其他标签需要，或许在脚注中需要。
Muse 的一个基本特色是它能够把一个简单的输入文本发布成种种不同风格的输出。 Muse 也使得创建一个新的风格或者从一个存在的风格中派生新风格变得容易。
Blosxom 发布格式发布一个归类文件树为一个文章的镜像树，并由 blosxom.cgi 或 pyblosxom.cgi 提供服务。换句话说，每个 blog 条目与一个文件相对应。
你需要在一个你具有上传访问权限的机器上安装 pyblosxom.cgi 或 blosxom.cgi。
为了使得 blog 条目的日期能够合理的显示，下面这些额外的组件是必须的。
在 contrib/pyblosxom 子目录中为 pyblosxom.cgi 提供这两个组件。 getstamps.py 提供前面的服务，而 hardcodedates.py 提供后面的服务。最后期望找出或写出一个 blosxom.cgi 插件和脚本。
下面是在我的 timestamps 文件中的一个例子列表，其中每个文件与一个日期相对应。其实这可以是任意格式，只要你的日期聚合脚本和插件都能够解析。
2005-04-01-14-16 personal/paper_cranes
2005-03-21 personal/spring_break_over
2004-10-24 personal/finished_free_culture
contrib/pyblosxom/make-blog 脚本示范了怎样调用 getstamps.py。注意你需要设置当前目录为你的 Muse 文件所在的目录，执行 gestamps.py，然后移动生成的时间戳文件到你的发布目录中。
每一个 Blosxom 文件必须包含 `#date yyyy-mm-dd' 或者可选的长格式 `#date yyyy-mm-dd-hh-mm'，一个题目（使用 #title 指令）加上任意内容的正文。
日期指令不会直接由 pyblosxom.cgi 或者这个程序所使用。你需要有上一节中提到的那两个额外组件来使用这个特色。
有一个名为 muse-blosxom-new-entry 的函数可以使得生成一个新的 blog
条目的过程自动化。照下面所做来使用它。
muse-blosxom-base-directory 为你的 blog 条目存储的位置。
muse-blosxom-new-entry 函数到一个键序列。我使用下面的代码绑定这个函数到 C-c p
l'。 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
在 Blosxom 发布风格中下面的风格和选项可用。
muse-blosxom-extension
muse-blosxom-header
这可以是文本或者一个文件名。
muse-blosxom-footer
这可以是文本或者一个文件名。
muse-blosxom-base-directory
muse-blosxom-new-entry 使用。
这是你的 blog 条目本地能找到的顶层目录。
这个发布风格被用于输出 LaTeX 或者 PDF 格式的“书”。
如果不使用关键字 :nochapters 每一个页面将会成为书中一个独立的章，否则，它们就会象庞大的一章那样在一起。
为发布这种风格你需要调用 muse-book-publish-project 函数。在 John Wiegley 的配置文件
examples/johnw/muse-johnw.el 中可以找到这样的一个例子。
muse-book-before-publish-hook
muse-book-after-publish-hook
muse-book-latex-header
这可以是文本或者一个文件名。
muse-book-latex-footer
这可以是文本或者一个文件名。
这种发布风格被用于生成 DocBook XML 文件。
docbook
muse-docbook-extension
muse-docbook-header
这可以是文本或者一个文件名。
muse-docbook-footer
这可以是文本或者一个文件名。
muse-docbook-markup-regexps
muse-docbook-markup-functions
muse-docbook-markup-strings
这些字符串涵盖最基本的标记类，它们在各种风格之间的操作差别很小。
muse-docbook-markup-specials
muse-docb