muse-latex: Render <example> correctly in slides.
[muse-el.git] / README
blob8386278b6bd6c864988acee7d1775474a711b4a6
1                                                           -*- Text -*-
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.
7 Synopsis
8 ========
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.
18 Directory contents
19 ==================
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.
42 Getting started
43 ===============
45 Prerequisites
46 -------------
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.
52 Compilation
53 -----------
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
57 increase, however.
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
61 `emacs' will be used.
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.
69 EMACS    = xemacs
70 SITEFLAG = -no-site-file
71 # Edit the section as necessary
72 install_info = install-info --section "XEmacs 21.4" $(1).info \
73         $(INFODIR)/dir || :
75 Running `make' in the top-level directory should compile the Muse
76 source files in the `lisp' directory, and generate an autoloads
77 file in `lisp/muse-autoloads.el'.
79 Installation
80 ------------
82 Muse may be installed into your file hierarchy by doing the following.
84 Copy `Makefile.defs.default' to `Makefile.defs' in the top-level
85 directory, if you haven't done so already.  Then edit the
86 `Makefile.defs' file so that ELISPDIR points to where you want the
87 source and compiled Muse files to be installed and INFODIR indicates
88 where to put the Muse manual.  You may use a combination of DESTDIR
89 and PREFIX to further determine where the installed files should be
90 placed.  As mentioned earlier, you will want to edit EMACS and
91 SITEFLAG as shown in the Compilation section if you are using XEmacs.
93 If you are installing Muse on a Debian or Ubuntu system, you might
94 want to change the value of INSTALLINFO as specified in
95 `Makefile.defs'.
97 If you wish to install Muse to different locations than the defaults
98 specify, edit `Makefile.defs' accordingly.
100 Run `make' as a normal user, if you haven't done so already.
102 Run `make install' as the root user if you have chosen installation
103 locations that require this.
105 Insinuation
106 -----------
108 Two things need to happen in order for Muse to be usable with your
109 version of Emacs or XEmacs.
111  1. The location of the Muse directory needs to be added to the load
112     path so that your variant of Emacs can find it.
114  2. You need to load whichever Muse files you wish to make use of.
116 A quick example that accomplishes both of these follows.
118 ;; Add this to your .emacs or .xemacs/init.el file.
119 (setq load-path (add-to-list 'load-path "/path/to/muse"))
120 (require 'muse-mode)
121 (require 'muse-publish)
122 (require 'muse-html)  ;; and so on
124 Documentation
125 -------------
127 The Muse manual may be generated by running `make doc'.
129 It will produce two files: an Info file called `muse.info' and an HTML
130 document called `muse.html'.  Both of these will be created in the
131 `texi' directory.
133 This manual is also available online in several forms.
135  - PDF: http://mwolson.org/static/doc/muse.pdf
136  - HTML (single file): http://mwolson.org/static/doc/muse.html
137  - HTML (multiple files): http://mwolson.org/static/doc/muse/
139 QuickStart
140 ----------
142 Type "make examples" to generate a quickstart guide for Muse.  An HTML
143 document called QuickStart.html, an Info document called
144 QuickStart.info, and a PDF file called QuickStart.pdf will be created
145 in the `examples' directory.
147 If you do not have a working LaTeX installation with the proper fonts,
148 the PDF file will not be successfully generated.
150 To see the document that is interpreted in order to generate these
151 files, take a look at `examples/QuickStart.muse'.
153 To view the generated Info document from within Emacs, try the
154 following.
156 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
158 Further Documentation
159 =====================
161 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
162 more information on bugs, unimplemented features, and user-contributed
163 tweaks.
165 The current maintainer's webpage for Muse is at
166 http://mwolson.org/projects/EmacsMuse.html.
168 If you wish to participate in the development of Muse, or track the
169 latest development changes, please read the `Development' section of
170 the Muse manual (in the `Obtaining Muse' chapter) for instructions.
172 Mailing Lists
173 =============
175 Mailing lists for Muse exist.
177 muse-el-announce ::
178   Low-traffic list for Muse-related announcements.
180   You can join this mailing list (muse-el-announce@gna.org)
181   using the subscription form at
182   http://mail.gna.org/listinfo/muse-el-announce/.
184   This mailing list is also available via Gmane (http://gmane.org/).
185   The group is called
186   gmane.emacs.muse.announce.
188 muse-el-discuss ::
189   Discussion, bugfixes, suggestions, tips, and the like for Muse.
190   This mailing list also includes the content of muse-el-announce.
192   You can join this mailing list (muse-el-discuss@gna.org)
193   using the subscription form at
194   http://mail.gna.org/listinfo/muse-el-discuss/.
196   This mailing list is also available via Gmane with the identifier
197   gmane.emacs.muse.general.
199 muse-el-logs ::
200   Log messages for commits made to Muse.
202   You can join this mailing list (muse-el-logs@gna.org) using
203   the subscription form at
204   http://mail.gna.org/listinfo/muse-el-logs/.
206   This mailing list is also available via Gmane with the identifier
207   gmane.emacs.muse.scm.
209 muse-el-commits ::
210   Generated bug reports for Emacs Muse.  If you use our bug-tracker at
211   https://gna.org/bugs/?group=muse-el, the bug reports will be sent to
212   this list automatically.
214   You can join this mailing list (muse-el-commits@gna.org) using
215   the subscription form at
216   http://mail.gna.org/listinfo/muse-el-commits/.
218   This mailing list is also available via Gmane with the identifier
219   gmane.emacs.muse.cvs.
221 License
222 =======
224 Emacs Muse is free software; you can redistribute it and/or modify it
225 under the terms of the GNU General Public License as published by the
226 Free Software Foundation; either version 3, or (at your option) any
227 later version.
229 Emacs Muse is distributed in the hope that it will be useful, but
230 WITHOUT ANY WARRANTY; without even the implied warranty of
231 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
232 General Public License for more details.
234 You should have received a copy of the GNU General Public License
235 along with Emacs Muse; see the file COPYING.  If not, write to the
236 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
237 Boston, MA 02110-1301, USA.
239 The Muse manual is available under the terms of the GNU Free
240 Documentation License, Version 1.2 or any later version published by
241 the Free Software Foundation; with no Invariant Sections, and with the
242 Front-Cover texts and Back-Cover Texts as specified in the manual.  A
243 copy of the license is included in the section entitled "GNU Free
244 Documentation License" in the Muse manual.  All Emacs Lisp code
245 contained in the manual may be used, distributed, and modified without
246 restriction.
248 The PNG images included in the examples/ directory may be used,
249 distributed, and modified without restriction.
251 The contents of the contrib/blosxom and contrib/pyblosxom directories
252 are available under the terms of other licenses.  Please consult the
253 header of each file for the appropriate license text.