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 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 Compilation
  44 -----------
  45
  46 This is an optional step, since Emacs Lisp source code does not
  47 necessarily have to be byte-compiled.  It will yield a speed increase,
  48 though.
  49
  50 A working copy of Emacs or XEmacs is needed in order to compile the
  51 Emacs Muse.  By default, the program that is installed with the name
  52 `emacs' will be used.
  53
  54 If you want to use the `xemacs' binary to perform the compilation, you
  55 would need to edit `Makefile.defs' in the top-level directory as
  56 follows.  You can put either a full path to an Emacs or XEmacs binary
  57 or just the command name, as long as it is in the PATH.
  58
  59 EMACS    = xemacs
  60 SITEFLAG = -no-site-file
  61
  62 Running `make' should compile the Muse source files in the `lisp'
  63 directory.
  64
  65 Installation
  66 ------------
  67
  68 Muse may be installed into your file hierarchy by doing the following.
  69
  70 Edit the `Makefile.defs' file so that ELISPDIR points to where you
  71 want the source and compiled Muse files to be installed and INFODIR
  72 indicates where to put the Muse manual.  Of course, you will want to
  73 edit EMACS and SITEFLAG as shown in the Compilation section if you are
  74 using XEmacs.
  75
  76 If you are installing Muse on a Debian or Ubuntu system, you might
  77 want to change the value of INSTALLINFO as specified in
  78 `Makefile.defs'.
  79
  80 If you wish to install Muse to different locations than the defaults
  81 specify, edit `Makefile.defs' accordingly.
  82
  83 Run `make' as a normal user.
  84
  85 Run `make install' as the root user if you have chosen installation
  86 locations that require this.
  87
  88 Insinuation
  89 -----------
  90
  91 Two things need to happen in order for Muse to be usable with your
  92 version of Emacs or XEmacs.
  93
  94  1. The location of the Muse directory needs to be added to the load
  95     path so that your variant of Emacs can find it.
  96
  97  2. You need to load whichever Muse files you wish to make use of.
  98
  99 A quick example that accomplishes both of these follows.
 100
 101 ;; Add this to your .emacs or .xemacs/init.el file.
 102 (setq load-path (add-to-list 'load-path "/path/to/muse"))
 103 (require 'muse-mode)
 104 (require 'muse-publish)
 105 (require 'muse-html)  ;; and so on
 106
 107 Documentation
 108 -------------
 109
 110 The Muse manual may be generated by running `make doc'.
 111
 112 It will produce two files: an Info file called `muse.info' and an HTML
 113 document called `muse.html'.  Both of these will be created in the
 114 `texi' directory.
 115
 116 This manual is also available online in several forms.
 117
 118  - PDF: http://www.mwolson.org/static/doc/muse.pdf
 119  - HTML (single file): http://www.mwolson.org/static/doc/muse.html
 120  - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
 121
 122 QuickStart
 123 ----------
 124
 125 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 126 document called QuickStart.html, an Info document called
 127 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 128 in the `examples' directory.
 129
 130 If you do not have a working LaTeX installation with the proper fonts,
 131 the PDF file will not be successfully generated.
 132
 133 To see the document that is interpreted in order to generate these
 134 files, take a look at `examples/QuickStart.muse'.
 135
 136 To view the generated Info document from within Emacs, try the
 137 following.
 138
 139 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 140
 141 Further Documentation
 142 =====================
 143
 144 Please consult http://www.emacswiki.org/cgi-bin/wiki/MuseMode to find
 145 more information on bugs, unimplemented features, and user-contributed
 146 tweaks.
 147
 148 The current maintainer's webpage for Muse is at
 149 http://www.mwolson.org/projects/EmacsMuse.html.
 150
 151 A mailing list for Muse and some related software exists; consult
 152 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
 153 on joining it or viewing its contents.
 154
 155 License
 156 =======
 157
 158 Emacs Muse is free software; you can redistribute it and/or modify it
 159 under the terms of the GNU General Public License as published by the
 160 Free Software Foundation; either version 2, or (at your option) any
 161 later version.
 162
 163 Emacs Muse is distributed in the hope that it will be useful, but
 164 WITHOUT ANY WARRANTY; without even the implied warranty of
 165 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 166 General Public License for more details.
 167
 168 You should have received a copy of the GNU General Public License
 169 along with Emacs Muse; see the file COPYING.  If not, write to the
 170 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 171 Boston, MA 02110-1301, USA.
 172
 173 The Muse manual is available under the terms of the GNU Free
 174 Documentation License, Version 1.2 or any later version published by
 175 the Free Software Foundation; with no Invariant Sections, and with the
 176 Front-Cover texts and Back-Cover Texts as specified in the manual.  A
 177 copy of the license is included in the section entitled "GNU Free
 178 Documentation License" in the Muse manual.  All Emacs Lisp code
 179 contained in the manual may be used, distributed, and modified without
 180 restriction.