README

   1                                                           -*- Text -*-
   2 This is the README file for Emacs Muse.
   3
   4 The terms "Emacs Muse", and "Muse" are used interchangeably throughout
   5 this document to refer to this software.
   6
   7 Synopsis
   8 ========
   9
  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.
  13
  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.
  17
  18 Directory contents
  19 ==================
  20
  21 The directory structure is as follows.
  22
  23 contrib :: Files that are not a part of Muse proper, but are useful
  24            enough to be bundled with Muse.
  25
  26 examples :: Example configuration files for use with Muse, a
  27             publishable quickstart guide, and miscellaneous helper
  28             stuff.
  29
  30 experimental :: Source code that is not yet considered stable.
  31
  32 lisp :: Muse source code.
  33
  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.
  37
  38 texi :: The manual (muse.texi) and any supplemental sections.
  39
  40 Getting started
  41 ===============
  42
  43 Prerequisites
  44 -------------
  45
  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.
  49
  50 Compilation
  51 -----------
  52
  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,
  55 though.
  56
  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
  59 `emacs' will be used.
  60
  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.
  65
  66 EMACS    = xemacs
  67 SITEFLAG = -no-site-file
  68
  69 Running `make' should compile the Muse source files in the `lisp'
  70 directory.
  71
  72 Installation
  73 ------------
  74
  75 Muse may be installed into your file hierarchy by doing the following.
  76
  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
  81 using XEmacs.
  82
  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
  85 `Makefile.defs'.
  86
  87 If you wish to install Muse to different locations than the defaults
  88 specify, edit `Makefile.defs' accordingly.
  89
  90 Run `make' as a normal user.
  91
  92 Run `make install' as the root user if you have chosen installation
  93 locations that require this.
  94
  95 Insinuation
  96 -----------
  97
  98 Two things need to happen in order for Muse to be usable with your
  99 version of Emacs or XEmacs.
 100
 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.
 103
 104  2. You need to load whichever Muse files you wish to make use of.
 105
 106 A quick example that accomplishes both of these follows.
 107
 108 ;; Add this to your .emacs or .xemacs/init.el file.
 109 (setq load-path (add-to-list 'load-path "/path/to/muse"))
 110 (require 'muse-mode)
 111 (require 'muse-publish)
 112 (require 'muse-html)  ;; and so on
 113
 114 Documentation
 115 -------------
 116
 117 The Muse manual may be generated by running `make doc'.
 118
 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
 121 `texi' directory.
 122
 123 This manual is also available online in several forms.
 124
 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/
 128
 129 QuickStart
 130 ----------
 131
 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.
 136
 137 If you do not have a working LaTeX installation with the proper fonts,
 138 the PDF file will not be successfully generated.
 139
 140 To see the document that is interpreted in order to generate these
 141 files, take a look at `examples/QuickStart.muse'.
 142
 143 To view the generated Info document from within Emacs, try the
 144 following.
 145
 146 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 147
 148 Further Documentation
 149 =====================
 150
 151 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
 152 more information on bugs, unimplemented features, and user-contributed
 153 tweaks.
 154
 155 The current maintainer's webpage for Muse is at
 156 http://www.mwolson.org/projects/EmacsMuse.html.
 157
 158 Mailing Lists
 159 =============
 160
 161 Mailing lists for Muse exist.
 162
 163 muse-el-announce ::
 164   Low-traffic list for Muse-related announcements.
 165
 166   You can join this mailing list (muse-el-announce@gna.org)
 167   using the subscription form at
 168   http://mail.gna.org/listinfo/muse-el-announce/.
 169
 170   This mailing list is also available via Gmane (http://gmane.org/).
 171   The group is called
 172   gmane.emacs.muse.announce.
 173
 174 muse-el-discuss ::
 175   Discussion, bugfixes, suggestions, tips, and the like for Muse.
 176   This mailing list also includes the content of muse-el-announce.
 177
 178   You can join this mailing list (muse-el-discuss@gna.org)
 179   using the subscription form at
 180   http://mail.gna.org/listinfo/muse-el-discuss/.
 181
 182   This mailing list is also available via Gmane with the identifier
 183   gmane.emacs.muse.general.
 184
 185 muse-el-logs ::
 186   Log messages for commits made to Muse.
 187
 188   You can join this mailing list (muse-el-logs@gna.org) using
 189   the subscription form at
 190   http://mail.gna.org/listinfo/muse-el-logs/.
 191
 192   This mailing list is also available via Gmane with the identifier
 193   gmane.emacs.muse.scm.
 194
 195 muse-el-commits ::
 196   Generated bug reports for Emacs Muse.  If you use our bug-tracker at
 197   https://gna.org/bugs/?group=muse-el, the bug reports will be sent to
 198   this list automatically.
 199
 200   You can join this mailing list (muse-el-commits@gna.org) using
 201   the subscription form at
 202   http://mail.gna.org/listinfo/muse-el-commits/.
 203
 204   This mailing list is also available via Gmane with the identifier
 205   gmane.emacs.muse.cvs.
 206
 207 License
 208 =======
 209
 210 Emacs Muse is free software; you can redistribute it and/or modify it
 211 under the terms of the GNU General Public License as published by the
 212 Free Software Foundation; either version 2, or (at your option) any
 213 later version.
 214
 215 Emacs Muse is distributed in the hope that it will be useful, but
 216 WITHOUT ANY WARRANTY; without even the implied warranty of
 217 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 218 General Public License for more details.
 219
 220 You should have received a copy of the GNU General Public License
 221 along with Emacs Muse; see the file COPYING.  If not, write to the
 222 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 223 Boston, MA 02110-1301, USA.
 224
 225 The Muse manual is available under the terms of the GNU Free
 226 Documentation License, Version 1.2 or any later version published by
 227 the Free Software Foundation; with no Invariant Sections, and with the
 228 Front-Cover texts and Back-Cover Texts as specified in the manual.  A
 229 copy of the license is included in the section entitled "GNU Free
 230 Documentation License" in the Muse manual.  All Emacs Lisp code
 231 contained in the manual may be used, distributed, and modified without
 232 restriction.