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 etc :: Miscellaneous files like the emacs-wiki migration guide, the
  24   list of ideas for the future, and a RelaxNG schema for Muse XML.
  25
  26 contrib :: Files that are not a part of Muse proper, but are useful
  27   enough to be bundled with Muse.
  28
  29 examples :: Example configuration files for use with Muse, a
  30   publishable quickstart guide, and miscellaneous helper stuff.
  31
  32 experimental :: Source code that is not yet considered stable.
  33
  34 lisp :: Muse source code.
  35
  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.
  39
  40 texi :: The manual (muse.texi) and any supplemental sections.
  41
  42 Getting started
  43 ===============
  44
  45 Prerequisites
  46 -------------
  47
  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 recommend using Emacs.
  51
  52 Compilation
  53 -----------
  54
  55 This is an optional step, since Emacs Lisp source code does not
  56 necessarily have to be byte-compiled.  It will yield a speed increase,
  57 though.
  58
  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.
  62
  63 If you want to use the `xemacs' binary to perform the compilation, you
  64 would need to edit `Makefile.defs' in the top-level directory as
  65 follows.  You can put either a full path to an Emacs or XEmacs binary
  66 or just the command name, as long as it is in the PATH.
  67
  68 EMACS    = xemacs
  69 SITEFLAG = -no-site-file
  70
  71 Running `make' should compile the Muse source files in the `lisp'
  72 directory.
  73
  74 Installation
  75 ------------
  76
  77 Muse may be installed into your file hierarchy by doing the following.
  78
  79 Edit the `Makefile.defs' file so that ELISPDIR points to where you
  80 want the source and compiled Muse files to be installed and INFODIR
  81 indicates where to put the Muse manual.  Of course, you will want to
  82 edit EMACS and SITEFLAG as shown in the Compilation section if you are
  83 using XEmacs.
  84
  85 If you are installing Muse on a Debian or Ubuntu system, you might
  86 want to change the value of INSTALLINFO as specified in
  87 `Makefile.defs'.
  88
  89 If you wish to install Muse to different locations than the defaults
  90 specify, edit `Makefile.defs' accordingly.
  91
  92 Run `make' as a normal user.
  93
  94 Run `make install' as the root user if you have chosen installation
  95 locations that require this.
  96
  97 Insinuation
  98 -----------
  99
 100 Two things need to happen in order for Muse to be usable with your
 101 version of Emacs or XEmacs.
 102
 103  1. The location of the Muse directory needs to be added to the load
 104     path so that your variant of Emacs can find it.
 105
 106  2. You need to load whichever Muse files you wish to make use of.
 107
 108 A quick example that accomplishes both of these follows.
 109
 110 ;; Add this to your .emacs or .xemacs/init.el file.
 111 (setq load-path (add-to-list 'load-path "/path/to/muse"))
 112 (require 'muse-mode)
 113 (require 'muse-publish)
 114 (require 'muse-html)  ;; and so on
 115
 116 Documentation
 117 -------------
 118
 119 The Muse manual may be generated by running `make doc'.
 120
 121 It will produce two files: an Info file called `muse.info' and an HTML
 122 document called `muse.html'.  Both of these will be created in the
 123 `texi' directory.
 124
 125 This manual is also available online in several forms.
 126
 127  - PDF: http://www.mwolson.org/static/doc/muse.pdf
 128  - HTML (single file): http://www.mwolson.org/static/doc/muse.html
 129  - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
 130
 131 QuickStart
 132 ----------
 133
 134 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 135 document called QuickStart.html, an Info document called
 136 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 137 in the `examples' directory.
 138
 139 If you do not have a working LaTeX installation with the proper fonts,
 140 the PDF file will not be successfully generated.
 141
 142 To see the document that is interpreted in order to generate these
 143 files, take a look at `examples/QuickStart.muse'.
 144
 145 To view the generated Info document from within Emacs, try the
 146 following.
 147
 148 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 149
 150 Further Documentation
 151 =====================
 152
 153 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
 154 more information on bugs, unimplemented features, and user-contributed
 155 tweaks.
 156
 157 The current maintainer's webpage for Muse is at
 158 http://www.mwolson.org/projects/EmacsMuse.html.
 159
 160 Mailing Lists
 161 =============
 162
 163 Mailing lists for Muse exist.
 164
 165 muse-el-announce ::
 166   Low-traffic list for Muse-related announcements.
 167
 168   You can join this mailing list (muse-el-announce@gna.org)
 169   using the subscription form at
 170   http://mail.gna.org/listinfo/muse-el-announce/.
 171
 172   This mailing list is also available via Gmane (http://gmane.org/).
 173   The group is called
 174   gmane.emacs.muse.announce.
 175
 176 muse-el-discuss ::
 177   Discussion, bugfixes, suggestions, tips, and the like for Muse.
 178   This mailing list also includes the content of muse-el-announce.
 179
 180   You can join this mailing list (muse-el-discuss@gna.org)
 181   using the subscription form at
 182   http://mail.gna.org/listinfo/muse-el-discuss/.
 183
 184   This mailing list is also available via Gmane with the identifier
 185   gmane.emacs.muse.general.
 186
 187 muse-el-logs ::
 188   Log messages for commits made to Muse.
 189
 190   You can join this mailing list (muse-el-logs@gna.org) using
 191   the subscription form at
 192   http://mail.gna.org/listinfo/muse-el-logs/.
 193
 194   This mailing list is also available via Gmane with the identifier
 195   gmane.emacs.muse.scm.
 196
 197 muse-el-commits ::
 198   Generated bug reports for Emacs Muse.  If you use our bug-tracker at
 199   https://gna.org/bugs/?group=muse-el, the bug reports will be sent to
 200   this list automatically.
 201
 202   You can join this mailing list (muse-el-commits@gna.org) using
 203   the subscription form at
 204   http://mail.gna.org/listinfo/muse-el-commits/.
 205
 206   This mailing list is also available via Gmane with the identifier
 207   gmane.emacs.muse.cvs.
 208
 209 License
 210 =======
 211
 212 Emacs Muse is free software; you can redistribute it and/or modify it
 213 under the terms of the GNU General Public License as published by the
 214 Free Software Foundation; either version 2, or (at your option) any
 215 later version.
 216
 217 Emacs Muse is distributed in the hope that it will be useful, but
 218 WITHOUT ANY WARRANTY; without even the implied warranty of
 219 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 220 General Public License for more details.
 221
 222 You should have received a copy of the GNU General Public License
 223 along with Emacs Muse; see the file COPYING.  If not, write to the
 224 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 225 Boston, MA 02110-1301, USA.
 226
 227 The Muse manual is available under the terms of the GNU Free
 228 Documentation License, Version 1.2 or any later version published by
 229 the Free Software Foundation; with no Invariant Sections, and with the
 230 Front-Cover texts and Back-Cover Texts as specified in the manual.  A
 231 copy of the license is included in the section entitled "GNU Free
 232 Documentation License" in the Muse manual.  All Emacs Lisp code
 233 contained in the manual may be used, distributed, and modified without
 234 restriction.
 235
 236 The PNG images included in the examples/ directory may be used,
 237 distributed, and modified without restriction.