README

   1
   2 This is the README file for the Emacs Muse.
   3
   4 The terms "the Emacs Muse", "Emacs Muse", and "Muse" are used
   5 interchangeably throughout 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 License
  19 =======
  20
  21 Emacs Muse is free software; you can redistribute it and/or modify it
  22 under the terms of the GNU General Public License as published by the
  23 Free Software Foundation; either version 2, or (at your option) any
  24 later version.
  25
  26 Emacs Muse is distributed in the hope that it will be useful, but
  27 WITHOUT ANY WARRANTY; without even the implied warranty of
  28 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  29 General Public License for more details.
  30
  31 You should have received a copy of the GNU General Public License
  32 along with Emacs Muse; see the file COPYING.  If not, write to the
  33 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  34 Boston, MA 02110-1301, USA.
  35
  36 Directory contents
  37 ==================
  38
  39 The directory structure is as follows.
  40
  41 The manual (muse.texi) is in the top-level directory.
  42
  43 contrib :: Files that are not a part of Muse proper, but are useful
  44            enough to be bundled with Muse.
  45
  46 examples :: Example configuration files for use with Muse, a
  47             publishable quickstart guide, and miscellaneous helper
  48             stuff.
  49
  50 experimental :: Source code that is not yet considered stable.
  51
  52 lisp :: Muse source code.
  53
  54 scripts :: Scripts that are used when compiling Muse and publishing
  55            the QuickStart document; they might prove useful if you
  56            want to automate the building of Muse documents.
  57
  58 Getting started
  59 ===============
  60
  61 Compilation
  62 -----------
  63
  64 This is an optional step, since Emacs Lisp source code does not
  65 necessarily have to be byte-compiled.  It will yield a speed increase,
  66 though.
  67
  68 A working copy of Emacs or XEmacs is needed in order to compile the
  69 Emacs Muse.  By default, the program that is installed with the name
  70 `emacs' will be used.
  71
  72 If you want to use the `xemacs' binary to perform the compilation, you
  73 would need to edit `Makefile.defs' in the top-level directory as
  74 follows.  You can put either a full path to an Emacs or XEmacs binary
  75 or just the command name, as long as it is in the PATH.
  76
  77 EMACS    = xemacs
  78 SITEFLAG = -no-site-file
  79
  80 Running `make' should compile the Muse source files in the `lisp'
  81 directory.
  82
  83 Installation
  84 ------------
  85
  86 Muse may be installed into your file hierarchy by doing the following.
  87
  88 Edit the `Makefile.defs' file so that ELISPDIR points to where you
  89 want the source and compiled Muse files to be installed and INFODIR
  90 indicates where to put the Muse manual.  Of course, you will want to
  91 edit EMACS and SITEFLAG as shown in the Compilation section if you are
  92 using XEmacs.
  93
  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
  96 `Makefile.defs'.
  97
  98 If you wish to install Muse to different locations than the defaults
  99 specify, edit `Makefile.defs' accordingly.
 100
 101 Run `make' as a normal user.
 102
 103 Run `make install' as the root user if you have chosen installation
 104 locations that require this.
 105
 106 Insinuation
 107 -----------
 108
 109 Two things need to happen in order for Muse to be usable with your
 110 version of Emacs or XEmacs.
 111
 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.
 114
 115  2. You need to load whichever Muse files you wish to make use of.
 116
 117 A quick example that accomplishes both of these follows.
 118
 119 ;; Add this to your .emacs or .xemacs/init.el file.
 120 (setq load-path (add-to-list 'load-path "/path/to/muse"))
 121 (require 'muse-mode)
 122
 123 Documentation
 124 -------------
 125
 126 The Muse manual may be generated by running `make doc'.
 127
 128 It will produce two files: an Info file called `muse.info' and an HTML
 129 document called `muse.html'.
 130
 131 This manual is also available online in several forms.
 132
 133  - PDF: http://www.mwolson.org/static/doc/muse.pdf
 134  - HTML (single file): http://www.mwolson.org/static/doc/muse.html
 135  - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
 136
 137 QuickStart
 138 ----------
 139
 140 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 141 document called QuickStart.html, an Info document called
 142 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 143 in the `examples' directory.
 144
 145 If you do not have a working LaTeX installation with the proper fonts,
 146 the PDF file will not be successfully generated.
 147
 148 To see the document that is interpreted in order to generate these
 149 files, take a look at `examples/QuickStart.muse'.
 150
 151 To view the generated Info document from within Emacs, try the
 152 following.
 153
 154 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 155
 156 Further Documentation
 157 =====================
 158
 159 Please consult http://www.emacswiki.org/cgi-bin/wiki/MuseMode to find
 160 more information on bugs, unimplemented features, and user-contributed
 161 tweaks.
 162
 163 The current maintainer's website is at
 164 http://www.mwolson.org/projects/EmacsMuse.html.
 165
 166 A mailing list for Muse and some related software exists; consult
 167 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
 168 on joining it or viewing its contents.