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 When you unpack the Muse tarball, you will find the source files for
  22 Muse in the top level of the newly-created directory.  The directory
  23 structure is as follows.
  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, as well as
  29             a publishable quickstart guide.
  30
  31 experimental :: Source code that is not yet considered stable.
  32
  33 scripts :: Scripts that are used when publishing the QuickStart
  34            document; they might prove useful if you want to automate
  35            the building of Muse documents.
  36
  37 Getting started
  38 ===============
  39
  40 Compiling
  41 ---------
  42
  43 This is an optional step, since Emacs Lisp source code does not
  44 necessarily have to be byte-compiled.  It will yield a speed increase,
  45 however.
  46
  47 A working copy of Emacs or XEmacs is needed in order to compile the
  48 Emacs Muse.  By default, the program that is installed with the name
  49 `emacs' will be used.
  50
  51 If you want to use the `xemacs' binary to perform the compilation, we
  52 would need to do the following.
  53
  54  - Change the second line of `Makefile' and `examples/Makefile' to:
  55
  56 EMACS    = xemacs
  57
  58  - Change the use of "--no-site-file" in `Makefile' to
  59    "-no-site-file".
  60
  61 It is hoped that these steps will be unnecessary in future Muse
  62 releases.
  63
  64 Installation
  65 ------------
  66
  67 Two things need to happen in order for Muse to be usable with your
  68 version of Emacs or XEmacs.
  69
  70  1. The location of the Muse directory needs to be added to the load
  71     path so that your variant of Emacs can find it.
  72
  73  2. You need to load whichever Muse files you wish to make use of.
  74
  75 A quick example that accomplishes both of these follows.
  76
  77 ;; Add this to your .emacs or .xemacs/init.el file.
  78 (setq load-path (add-to-list 'load-path "/path/to/muse"))
  79 (require 'muse-mode)
  80
  81 Documentation
  82 -------------
  83
  84 The Muse manual may be generated by running `make doc'.
  85
  86 It will produce two files: an Info file called `muse.info' and an HTML
  87 document called `muse.html'.
  88
  89 QuickStart
  90 ----------
  91
  92 Type "make examples" to generate a quickstart guide for Muse.  An HTML
  93 document called QuickStart.html, an Info document called
  94 QuickStart.info, and a PDF file called QuickStart.pdf will be created
  95 in the `examples' directory.
  96
  97 If you do not have a working LaTeX installation with the proper fonts,
  98 the PDF file will not be successfully generated.
  99
 100 To see the document that is interpreted in order to generate these
 101 files, take a look at `examples/QuickStart'.
 102
 103 To view the generated Info document from within Emacs, try the
 104 following.
 105
 106 C-u M-x info RET /path/to/muse/examples/QuickStart.info
 107
 108 Further Documentation
 109 =====================
 110
 111 Please consult http://www.emacswiki.org/cgi-bin/wiki/MuseMode to find
 112 more information on bugs, unimplemented features, and user-contributed
 113 tweaks.
 114
 115 A TexInfo document is distributed with Muse in the `muse.texi' file.
 116 It is currently incomplete, but may still be of use.
 117
 118 A mailing list for Muse and some related software exists; consult
 119 http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList for details
 120 on joining it or viewing its contents.