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 system, you might want to
  95 change the value of INSTALLINFO as specified in `Makefile.defs'.
  96
  97 If you wish to install Muse to different locations than the defaults
  98 specify, edit `Makefile.defs' accordingly.
  99
 100 Run `make' as a normal user.
 101
 102 Run `make install' as the root user if you have chosen installation
 103 locations that require this.
 104
 105 Insinuation
 106 -----------
 107
 108 Two things need to happen in order for Muse to be usable with your
 109 version of Emacs or XEmacs.
 110
 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.
 113
 114  2. You need to load whichever Muse files you wish to make use of.
 115
 116 A quick example that accomplishes both of these follows.
 117
 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
 122 Documentation
 123 -------------
 124
 125 The Muse manual may be generated by running `make doc'.
 126
 127 It will produce two files: an Info file called `muse.info' and an HTML
 128 document called `muse.html'.
 129
 130 This manual is also available online in several forms.
 131
 132  - PDF: http://www.mwolson.org/static/doc/muse.pdf
 133  - HTML (single file): http://www.mwolson.org/static/doc/muse.html
 134  - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
 135
 136 QuickStart
 137 ----------
 138
 139 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 140 document called QuickStart.html, an Info document called
 141 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 142 in the `examples' directory.
 143
 144 If you do not have a working LaTeX installation with the proper fonts,
 145 the PDF file will not be successfully generated.
 146
 147 To see the document that is interpreted in order to generate these
 148 files, take a look at `examples/QuickStart.muse'.
 149
 150 To view the generated Info document from within Emacs, try the
 151 following.
 152
 153 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 154
 155 Further Documentation
 156 =====================
 157
 158 Please consult http://www.emacswiki.org/cgi-bin/wiki/MuseMode to find
 159 more information on bugs, unimplemented features, and user-contributed
 160 tweaks.
 161
 162 The current maintainer's website is at
 163 http://www.mwolson.org/projects/EmacsMuse.html.
 164
 165 A mailing list for Muse and some related software exists; consult
 166 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
 167 on joining it or viewing its contents.