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