README

   1
   2 This is the README file for the Emacs Muse.
   3
   4 The terms "the Emacs Muse", "Emacs Muse", and "Muse" will be 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 Muse consists of two main parts: an enhanced text-mode for authoring
  15 documents and navigating within Muse projects, and a set of publishing
  16 styles for generating different kinds of output.
  17
  18 Directory contents
  19 ==================
  20
  21 The directory structure is as follows.
  22
  23 The manual (muse.texi) is in the top-level directory.
  24
  25 contrib :: Files that are not a part of Muse proper, but are useful
  26            enough to be bundled with Muse.
  27
  28 examples :: Example configuration files for use with Muse, a
  29             publishable quickstart guide, and miscellaneous helper
  30             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
  38            want to automate the building of Muse documents.
  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 system, you might want to
  77 change the value of INSTALLINFO as specified in `Makefile.defs'.
  78
  79 If you wish to install Muse to different locations than the defaults
  80 specify, edit `Makefile.defs' accordingly.
  81
  82 Run `make' as a normal user.
  83
  84 Run `make install' as the root user if you have chosen installation
  85 locations that require this.
  86
  87 Insinuation
  88 -----------
  89
  90 Two things need to happen in order for Muse to be usable with your
  91 version of Emacs or XEmacs.
  92
  93  1. The location of the Muse directory needs to be added to the load
  94     path so that your variant of Emacs can find it.
  95
  96  2. You need to load whichever Muse files you wish to make use of.
  97
  98 A quick example that accomplishes both of these follows.
  99
 100 ;; Add this to your .emacs or .xemacs/init.el file.
 101 (setq load-path (add-to-list 'load-path "/path/to/muse"))
 102 (require 'muse-mode)
 103
 104 Documentation
 105 -------------
 106
 107 The Muse manual may be generated by running `make doc'.
 108
 109 It will produce two files: an Info file called `muse.info' and an HTML
 110 document called `muse.html'.
 111
 112 This manual is also available online in several forms.
 113
 114  - PDF: http://www.mwolson.org/static/doc/muse.pdf
 115  - HTML (single file): http://www.mwolson.org/static/doc/muse.html
 116  - HTML (multiple files): http://www.mwolson.org/static/doc/muse/
 117
 118 QuickStart
 119 ----------
 120
 121 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 122 document called QuickStart.html, an Info document called
 123 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 124 in the `examples' directory.
 125
 126 If you do not have a working LaTeX installation with the proper fonts,
 127 the PDF file will not be successfully generated.
 128
 129 To see the document that is interpreted in order to generate these
 130 files, take a look at `examples/QuickStart.muse'.
 131
 132 To view the generated Info document from within Emacs, try the
 133 following.
 134
 135 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 136
 137 Further Documentation
 138 =====================
 139
 140 Please consult http://www.emacswiki.org/cgi-bin/wiki/MuseMode to find
 141 more information on bugs, unimplemented features, and user-contributed
 142 tweaks.
 143
 144 The current maintainer's website is at
 145 http://www.mwolson.org/projects/MuseMode.html.
 146
 147 A mailing list for Muse and some related software exists; consult
 148 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
 149 on joining it or viewing its contents.