2 This is the README file for Emacs Muse.
4 The terms "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 etc :: Miscellaneous files like the emacs-wiki migration guide, the
24 list of ideas for the future, and a RelaxNG schema for Muse XML.
26 contrib :: Files that are not a part of Muse proper, but are useful
27 enough to be bundled with Muse.
29 examples :: Example configuration files for use with Muse, a
30 publishable quickstart guide, and miscellaneous helper stuff.
32 experimental :: Source code that is not yet considered stable.
34 lisp :: Muse source code.
36 scripts :: Scripts that are used when compiling Muse and publishing
37 the QuickStart document; they might prove useful if you want to
38 automate the building of Muse documents.
40 texi :: The manual (muse.texi) and any supplemental sections.
48 You need either Emacs (21.1 or greater), XEmacs (21.4 or greater), or
49 SXEmacs (warning: Muse has not been tested with SXEmacs). The current
50 maintainer recommends using Emacs.
55 This is an optional step, since Emacs Lisp source code does not
56 necessarily have to be byte-compiled. It may yield a slight speed
59 A working copy of Emacs or XEmacs is needed in order to compile the
60 Emacs Muse. By default, the program that is installed with the name
63 If you want to use the `xemacs' binary to perform the compilation, you
64 must copy `Makefile.defs.default' to `Makefile.defs' in the top-level
65 directory, and then edit `Makefile.defs' as follows. You can put
66 either a full path to an Emacs or XEmacs binary or just the command
67 name, as long as it is in the PATH. Depending on your setup, changes
68 to the PREFIX, ELISPDIR, and/or INFODIR variables may also need to be
72 SITEFLAG = -no-site-file
73 # Edit the section as necessary
74 install_info = install-info --section "XEmacs 21.4" $(1).info \
77 Running `make' in the top-level directory should compile the Muse
78 source files in the `lisp' directory, and generate an autoloads
79 file in `lisp/muse-autoloads.el'.
84 Muse may be installed into your file hierarchy by doing the following.
86 Copy `Makefile.defs.default' to `Makefile.defs' in the top-level
87 directory, if you haven't done so already. Then edit the
88 `Makefile.defs' file so that ELISPDIR points to where you want the
89 source and compiled Muse files to be installed and INFODIR indicates
90 where to put the Muse manual. As mentioned earlier, you will want to
91 edit EMACS and SITEFLAG as shown in the Compilation section if you are
94 If you are installing Muse on a Debian or Ubuntu system, you might
95 want to change the value of INSTALLINFO as specified in
98 If you wish to install Muse to different locations than the defaults
99 specify, edit `Makefile.defs' accordingly.
101 Run `make' as a normal user, if you haven't done so already.
103 Run `make install' as the root user if you have chosen installation
104 locations that require this.
109 Two things need to happen in order for Muse to be usable with your
110 version of Emacs or XEmacs.
112 1. The location of the Muse directory needs to be added to the load
113 path so that your variant of Emacs can find it.
115 2. You need to load whichever Muse files you wish to make use of.
117 A quick example that accomplishes both of these follows.
119 ;; Add this to your .emacs or .xemacs/init.el file.
120 (setq load-path (add-to-list 'load-path "/path/to/muse"))
122 (require 'muse-publish)
123 (require 'muse-html) ;; and so on
128 The Muse manual may be generated by running `make doc'.
130 It will produce two files: an Info file called `muse.info' and an HTML
131 document called `muse.html'. Both of these will be created in the
134 This manual is also available online in several forms.
136 - PDF: http://mwolson.org/static/doc/muse.pdf
137 - HTML (single file): http://mwolson.org/static/doc/muse.html
138 - HTML (multiple files): http://mwolson.org/static/doc/muse/
143 Type "make examples" to generate a quickstart guide for Muse. An HTML
144 document called QuickStart.html, an Info document called
145 QuickStart.info, and a PDF file called QuickStart.pdf will be created
146 in the `examples' directory.
148 If you do not have a working LaTeX installation with the proper fonts,
149 the PDF file will not be successfully generated.
151 To see the document that is interpreted in order to generate these
152 files, take a look at `examples/QuickStart.muse'.
154 To view the generated Info document from within Emacs, try the
157 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
159 Further Documentation
160 =====================
162 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
163 more information on bugs, unimplemented features, and user-contributed
166 The current maintainer's webpage for Muse is at
167 http://mwolson.org/projects/EmacsMuse.html.
169 If you wish to participate in the development of Muse, or track the
170 latest development changes, please read the `Development' section of
171 the Muse manual (in the `Obtaining Muse' chapter) for instructions.
176 Mailing lists for Muse exist.
179 Low-traffic list for Muse-related announcements.
181 You can join this mailing list (muse-el-announce@gna.org)
182 using the subscription form at
183 http://mail.gna.org/listinfo/muse-el-announce/.
185 This mailing list is also available via Gmane (http://gmane.org/).
187 gmane.emacs.muse.announce.
190 Discussion, bugfixes, suggestions, tips, and the like for Muse.
191 This mailing list also includes the content of muse-el-announce.
193 You can join this mailing list (muse-el-discuss@gna.org)
194 using the subscription form at
195 http://mail.gna.org/listinfo/muse-el-discuss/.
197 This mailing list is also available via Gmane with the identifier
198 gmane.emacs.muse.general.
201 Log messages for commits made to Muse.
203 You can join this mailing list (muse-el-logs@gna.org) using
204 the subscription form at
205 http://mail.gna.org/listinfo/muse-el-logs/.
207 This mailing list is also available via Gmane with the identifier
208 gmane.emacs.muse.scm.
211 Generated bug reports for Emacs Muse. If you use our bug-tracker at
212 https://gna.org/bugs/?group=muse-el, the bug reports will be sent to
213 this list automatically.
215 You can join this mailing list (muse-el-commits@gna.org) using
216 the subscription form at
217 http://mail.gna.org/listinfo/muse-el-commits/.
219 This mailing list is also available via Gmane with the identifier
220 gmane.emacs.muse.cvs.
225 Emacs Muse is free software; you can redistribute it and/or modify it
226 under the terms of the GNU General Public License as published by the
227 Free Software Foundation; either version 3, or (at your option) any
230 Emacs Muse is distributed in the hope that it will be useful, but
231 WITHOUT ANY WARRANTY; without even the implied warranty of
232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
233 General Public License for more details.
235 You should have received a copy of the GNU General Public License
236 along with Emacs Muse; see the file COPYING. If not, write to the
237 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
238 Boston, MA 02110-1301, USA.
240 The Muse manual is available under the terms of the GNU Free
241 Documentation License, Version 1.2 or any later version published by
242 the Free Software Foundation; with no Invariant Sections, and with the
243 Front-Cover texts and Back-Cover Texts as specified in the manual. A
244 copy of the license is included in the section entitled "GNU Free
245 Documentation License" in the Muse manual. All Emacs Lisp code
246 contained in the manual may be used, distributed, and modified without
249 The PNG images included in the examples/ directory may be used,
250 distributed, and modified without restriction.
252 The contents of the contrib/blosxom and contrib/pyblosxom directories
253 are available under the terms of other licenses. Please consult the
254 header of each file for the appropriate license text.