2 This is the README file for the Emacs Muse.
4 The terms "the Emacs Muse", "Emacs Muse", and "Muse" are used
5 interchangeably throughout this document to refer to this software.
10 Emacs Muse is an authoring and publishing environment for Emacs. It
11 simplifies the process of writings documents and publishing them to
12 various output formats.
14 Emacs Muse consists of two main parts: an enhanced text-mode for
15 authoring documents and navigating within Muse projects, and a set of
16 publishing styles for generating different kinds of output.
21 The directory structure is as follows.
23 contrib :: Files that are not a part of Muse proper, but are useful
24 enough to be bundled with Muse.
26 examples :: Example configuration files for use with Muse, a
27 publishable quickstart guide, and miscellaneous helper
30 experimental :: Source code that is not yet considered stable.
32 lisp :: Muse source code.
34 scripts :: Scripts that are used when compiling Muse and publishing
35 the QuickStart document; they might prove useful if you
36 want to automate the building of Muse documents.
38 texi :: The manual (muse.texi) and any supplemental sections.
46 You need either Emacs (21.1 or greater), XEmacs (21.4 or greater), or
47 SXEmacs (warning: Muse has not been tested with SXEmacs). The current
48 maintainer recommend using Emacs.
53 This is an optional step, since Emacs Lisp source code does not
54 necessarily have to be byte-compiled. It will yield a speed increase,
57 A working copy of Emacs or XEmacs is needed in order to compile the
58 Emacs Muse. By default, the program that is installed with the name
61 If you want to use the `xemacs' binary to perform the compilation, you
62 would need to edit `Makefile.defs' in the top-level directory as
63 follows. You can put either a full path to an Emacs or XEmacs binary
64 or just the command name, as long as it is in the PATH.
67 SITEFLAG = -no-site-file
69 Running `make' should compile the Muse source files in the `lisp'
75 Muse may be installed into your file hierarchy by doing the following.
77 Edit the `Makefile.defs' file so that ELISPDIR points to where you
78 want the source and compiled Muse files to be installed and INFODIR
79 indicates where to put the Muse manual. Of course, you will want to
80 edit EMACS and SITEFLAG as shown in the Compilation section if you are
83 If you are installing Muse on a Debian or Ubuntu system, you might
84 want to change the value of INSTALLINFO as specified in
87 If you wish to install Muse to different locations than the defaults
88 specify, edit `Makefile.defs' accordingly.
90 Run `make' as a normal user.
92 Run `make install' as the root user if you have chosen installation
93 locations that require this.
98 Two things need to happen in order for Muse to be usable with your
99 version of Emacs or XEmacs.
101 1. The location of the Muse directory needs to be added to the load
102 path so that your variant of Emacs can find it.
104 2. You need to load whichever Muse files you wish to make use of.
106 A quick example that accomplishes both of these follows.
108 ;; Add this to your .emacs or .xemacs/init.el file.
109 (setq load-path (add-to-list 'load-path "/path/to/muse"))
111 (require 'muse-publish)
112 (require 'muse-html) ;; and so on
117 The Muse manual may be generated by running `make doc'.
119 It will produce two files: an Info file called `muse.info' and an HTML
120 document called `muse.html'. Both of these will be created in the
123 This manual is also available online in several forms.
125 - PDF: http://www.mwolson.org/static/doc/muse.pdf
126 - HTML (single file): http://www.mwolson.org/static/doc/muse.html
127 - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
132 Type "make examples" to generate a quickstart guide for Muse. An HTML
133 document called QuickStart.html, an Info document called
134 QuickStart.info, and a PDF file called QuickStart.pdf will be created
135 in the `examples' directory.
137 If you do not have a working LaTeX installation with the proper fonts,
138 the PDF file will not be successfully generated.
140 To see the document that is interpreted in order to generate these
141 files, take a look at `examples/QuickStart.muse'.
143 To view the generated Info document from within Emacs, try the
146 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
148 Further Documentation
149 =====================
151 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
152 more information on bugs, unimplemented features, and user-contributed
155 The current maintainer's webpage for Muse is at
156 http://www.mwolson.org/projects/EmacsMuse.html.
158 A mailing list for Muse and some related software exists; consult
159 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
160 on joining it or viewing its contents.
165 Emacs Muse is free software; you can redistribute it and/or modify it
166 under the terms of the GNU General Public License as published by the
167 Free Software Foundation; either version 2, or (at your option) any
170 Emacs Muse is distributed in the hope that it will be useful, but
171 WITHOUT ANY WARRANTY; without even the implied warranty of
172 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
173 General Public License for more details.
175 You should have received a copy of the GNU General Public License
176 along with Emacs Muse; see the file COPYING. If not, write to the
177 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
178 Boston, MA 02110-1301, USA.
180 The Muse manual is available under the terms of the GNU Free
181 Documentation License, Version 1.2 or any later version published by
182 the Free Software Foundation; with no Invariant Sections, and with the
183 Front-Cover texts and Back-Cover Texts as specified in the manual. A
184 copy of the license is included in the section entitled "GNU Free
185 Documentation License" in the Muse manual. All Emacs Lisp code
186 contained in the manual may be used, distributed, and modified without