README

   1                                                           -*- Text -*-
   2 This is the README file for Emacs Muse.
   3
   4 The terms "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 etc :: Miscellaneous files like the emacs-wiki migration guide, the
  24   list of ideas for the future, and a RelaxNG schema for Muse XML.
  25
  26 contrib :: Files that are not a part of Muse proper, but are useful
  27   enough to be bundled with Muse.
  28
  29 examples :: Example configuration files for use with Muse, a
  30   publishable quickstart guide, and miscellaneous helper 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 want to
  38   automate the building of Muse documents.
  39
  40 texi :: The manual (muse.texi) and any supplemental sections.
  41
  42 Getting started
  43 ===============
  44
  45 Prerequisites
  46 -------------
  47
  48 You need either Emacs (21.1 or greater), XEmacs (21.4 or greater), or
  49 SXEmacs (warning: Muse has not been tested with SXEmacs).  The current
  50 maintainer recommends using Emacs.
  51
  52 Compilation
  53 -----------
  54
  55 This is an optional step, since Emacs Lisp source code does not
  56 necessarily have to be byte-compiled.  It may yield a slight speed
  57 increase, however.
  58
  59 A working copy of Emacs or XEmacs is needed in order to compile the
  60 Emacs Muse.  By default, the program that is installed with the name
  61 `emacs' will be used.
  62
  63 If you want to use the `xemacs' binary to perform the compilation, you
  64 must copy `Makefile.defs.default' to `Makefile.defs' in the top-level
  65 directory, and then edit `Makefile.defs' as follows.  You can put
  66 either a full path to an Emacs or XEmacs binary or just the command
  67 name, as long as it is in the PATH.  Depending on your setup, changes
  68 to the PREFIX, ELISPDIR, and/or INFODIR variables may also need to be
  69 made.
  70
  71 EMACS    = xemacs
  72 SITEFLAG = -no-site-file
  73 # Edit the section as necessary
  74 install_info = install-info --section "XEmacs 21.4" $(1).info \
  75         $(INFODIR)/dir || :
  76
  77 Running `make' in the top-level directory should compile the Muse
  78 source files in the `lisp' directory, and generate an autoloads
  79 file in `lisp/muse-autoloads.el'.
  80
  81 Installation
  82 ------------
  83
  84 Muse may be installed into your file hierarchy by doing the following.
  85
  86 Copy `Makefile.defs.default' to `Makefile.defs' in the top-level
  87 directory, if you haven't done so already.  Then edit the
  88 `Makefile.defs' file so that ELISPDIR points to where you want the
  89 source and compiled Muse files to be installed and INFODIR indicates
  90 where to put the Muse manual.  As mentioned earlier, 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, if you haven't done so already.
 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 (require 'muse-publish)
 123 (require 'muse-html)  ;; and so on
 124
 125 Documentation
 126 -------------
 127
 128 The Muse manual may be generated by running `make doc'.
 129
 130 It will produce two files: an Info file called `muse.info' and an HTML
 131 document called `muse.html'.  Both of these will be created in the
 132 `texi' directory.
 133
 134 This manual is also available online in several forms.
 135
 136  - PDF: http://mwolson.org/static/doc/muse.pdf
 137  - HTML (single file): http://mwolson.org/static/doc/muse.html
 138  - HTML (multiple files): http://mwolson.org/static/doc/muse/
 139
 140 QuickStart
 141 ----------
 142
 143 Type "make examples" to generate a quickstart guide for Muse.  An HTML
 144 document called QuickStart.html, an Info document called
 145 QuickStart.info, and a PDF file called QuickStart.pdf will be created
 146 in the `examples' directory.
 147
 148 If you do not have a working LaTeX installation with the proper fonts,
 149 the PDF file will not be successfully generated.
 150
 151 To see the document that is interpreted in order to generate these
 152 files, take a look at `examples/QuickStart.muse'.
 153
 154 To view the generated Info document from within Emacs, try the
 155 following.
 156
 157 C-u M-x info RET /path/to/muse/examples/QuickStart.info RET
 158
 159 Further Documentation
 160 =====================
 161
 162 Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find
 163 more information on bugs, unimplemented features, and user-contributed
 164 tweaks.
 165
 166 The current maintainer's webpage for Muse is at
 167 http://mwolson.org/projects/EmacsMuse.html.
 168
 169 If you wish to participate in the development of Muse, or track the
 170 latest development changes, please read the `Development' section of
 171 the Muse manual (in the `Obtaining Muse' chapter) for instructions.
 172
 173 Mailing Lists
 174 =============
 175
 176 Mailing lists for Muse exist.
 177
 178 muse-el-announce ::
 179   Low-traffic list for Muse-related announcements.
 180
 181   You can join this mailing list (muse-el-announce@gna.org)
 182   using the subscription form at
 183   http://mail.gna.org/listinfo/muse-el-announce/.
 184
 185   This mailing list is also available via Gmane (http://gmane.org/).
 186   The group is called
 187   gmane.emacs.muse.announce.
 188
 189 muse-el-discuss ::
 190   Discussion, bugfixes, suggestions, tips, and the like for Muse.
 191   This mailing list also includes the content of muse-el-announce.
 192
 193   You can join this mailing list (muse-el-discuss@gna.org)
 194   using the subscription form at
 195   http://mail.gna.org/listinfo/muse-el-discuss/.
 196
 197   This mailing list is also available via Gmane with the identifier
 198   gmane.emacs.muse.general.
 199
 200 muse-el-logs ::
 201   Log messages for commits made to Muse.
 202
 203   You can join this mailing list (muse-el-logs@gna.org) using
 204   the subscription form at
 205   http://mail.gna.org/listinfo/muse-el-logs/.
 206
 207   This mailing list is also available via Gmane with the identifier
 208   gmane.emacs.muse.scm.
 209
 210 muse-el-commits ::
 211   Generated bug reports for Emacs Muse.  If you use our bug-tracker at
 212   https://gna.org/bugs/?group=muse-el, the bug reports will be sent to
 213   this list automatically.
 214
 215   You can join this mailing list (muse-el-commits@gna.org) using
 216   the subscription form at
 217   http://mail.gna.org/listinfo/muse-el-commits/.
 218
 219   This mailing list is also available via Gmane with the identifier
 220   gmane.emacs.muse.cvs.
 221
 222 License
 223 =======
 224
 225 Emacs Muse is free software; you can redistribute it and/or modify it
 226 under the terms of the GNU General Public License as published by the
 227 Free Software Foundation; either version 3, or (at your option) any
 228 later version.
 229
 230 Emacs Muse is distributed in the hope that it will be useful, but
 231 WITHOUT ANY WARRANTY; without even the implied warranty of
 232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 233 General Public License for more details.
 234
 235 You should have received a copy of the GNU General Public License
 236 along with Emacs Muse; see the file COPYING.  If not, write to the
 237 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 238 Boston, MA 02110-1301, USA.
 239
 240 The Muse manual is available under the terms of the GNU Free
 241 Documentation License, Version 1.2 or any later version published by
 242 the Free Software Foundation; with no Invariant Sections, and with the
 243 Front-Cover texts and Back-Cover Texts as specified in the manual.  A
 244 copy of the license is included in the section entitled "GNU Free
 245 Documentation License" in the Muse manual.  All Emacs Lisp code
 246 contained in the manual may be used, distributed, and modified without
 247 restriction.
 248
 249 The PNG images included in the examples/ directory may be used,
 250 distributed, and modified without restriction.
 251
 252 The contents of the contrib/blosxom and contrib/pyblosxom directories
 253 are available under the terms of other licenses.  Please consult the
 254 header of each file for the appropriate license text.