diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 258 |
1 files changed, 252 insertions, 6 deletions
@@ -1,7 +1,253 @@ -Muse is a tool for easily authoring and publishing documents. It -allows for rapid prototyping of hyperlinked text, which may then be -exported to multiple output formats, such as HTML, LaTeX, and Texinfo. + -*- Text -*- +This is the README file for Emacs Muse. -The markup rules used by Muse are intended to be very friendly to -people familiar with Emacs. See the included manual for more -information. +The terms "Emacs Muse", "Emacs-Muse", and "Muse" are used +interchangeably throughout this document to refer to this software. + +Synopsis +======== + +Emacs Muse is an authoring and publishing environment for Emacs. It +simplifies the process of writings documents and publishing them to +various output formats. + +Emacs Muse consists of two main parts: an enhanced text-mode for +authoring documents and navigating within Muse projects, and a set of +publishing styles for generating different kinds of output. + +Directory contents +================== + +The directory structure is as follows. + +etc :: Miscellaneous files like the emacs-wiki migration guide, the + list of ideas for the future, and a RelaxNG schema for Muse XML. + +contrib :: Files that are not a part of Muse proper, but are useful + enough to be bundled with Muse. + +examples :: Example configuration files for use with Muse, a + publishable quickstart guide, and miscellaneous helper stuff. + +experimental :: Source code that is not yet considered stable. + +lisp :: Muse source code. + +scripts :: Scripts that are used when compiling Muse and publishing + the QuickStart document; they might prove useful if you want to + automate the building of Muse documents. + +texi :: The manual (muse.texi) and any supplemental sections. + +Getting started +=============== + +Prerequisites +------------- + +You need either Emacs (21.1 or greater), XEmacs (21.4 or greater), or +SXEmacs (warning: Muse has not been tested with SXEmacs). The current +maintainer recommends using Emacs. + +Compilation +----------- + +This is an optional step, since Emacs Lisp source code does not +necessarily have to be byte-compiled. It may yield a slight speed +increase, however. + +A working copy of Emacs or XEmacs is needed in order to compile the +Emacs Muse. By default, the program that is installed with the name +`emacs' will be used. + +If you want to use the `xemacs' binary to perform the compilation, you +must copy `Makefile.defs.default' to `Makefile.defs' in the top-level +directory, and then edit `Makefile.defs' as follows. You can put +either a full path to an Emacs or XEmacs binary or just the command +name, as long as it is in the PATH. + +EMACS = xemacs +SITEFLAG = -no-site-file +# Edit the section as necessary +install_info = install-info --section "XEmacs 21.4" $(1).info \ + $(INFODIR)/dir || : + +Running `make' in the top-level directory should compile the Muse +source files in the `lisp' directory, and generate an autoloads +file in `lisp/muse-autoloads.el'. + +Installation +------------ + +Muse may be installed into your file hierarchy by doing the following. + +Copy `Makefile.defs.default' to `Makefile.defs' in the top-level +directory, if you haven't done so already. Then edit the +`Makefile.defs' file so that ELISPDIR points to where you want the +source and compiled Muse files to be installed and INFODIR indicates +where to put the Muse manual. You may use a combination of DESTDIR +and PREFIX to further determine where the installed files should be +placed. As mentioned earlier, you will want to edit EMACS and +SITEFLAG as shown in the Compilation section if you are using XEmacs. + +If you are installing Muse on a Debian or Ubuntu system, you might +want to change the value of INSTALLINFO as specified in +`Makefile.defs'. + +If you wish to install Muse to different locations than the defaults +specify, edit `Makefile.defs' accordingly. + +Run `make' as a normal user, if you haven't done so already. + +Run `make install' as the root user if you have chosen installation +locations that require this. + +Insinuation +----------- + +Two things need to happen in order for Muse to be usable with your +version of Emacs or XEmacs. + + 1. The location of the Muse directory needs to be added to the load + path so that your variant of Emacs can find it. + + 2. You need to load whichever Muse files you wish to make use of. + +A quick example that accomplishes both of these follows. + +;; Add this to your .emacs or .xemacs/init.el file. +(setq load-path (add-to-list 'load-path "/path/to/muse")) +(require 'muse-mode) +(require 'muse-publish) +(require 'muse-html) ;; and so on + +Documentation +------------- + +The Muse manual may be generated by running `make doc'. + +It will produce two files: an Info file called `muse.info' and an HTML +document called `muse.html'. Both of these will be created in the +`texi' directory. + +This manual is also available online in several forms. + + - PDF: http://mwolson.org/static/doc/muse.pdf + - HTML (single file): http://mwolson.org/static/doc/muse.html + - HTML (multiple files): http://mwolson.org/static/doc/muse/ + +QuickStart +---------- + +Type "make examples" to generate a quickstart guide for Muse. An HTML +document called QuickStart.html, an Info document called +QuickStart.info, and a PDF file called QuickStart.pdf will be created +in the `examples' directory. + +If you do not have a working LaTeX installation with the proper fonts, +the PDF file will not be successfully generated. + +To see the document that is interpreted in order to generate these +files, take a look at `examples/QuickStart.muse'. + +To view the generated Info document from within Emacs, try the +following. + +C-u M-x info RET /path/to/muse/examples/QuickStart.info RET + +Further Documentation +===================== + +Please consult http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse to find +more information on bugs, unimplemented features, and user-contributed +tweaks. + +The current maintainer's webpage for Muse is at +http://mwolson.org/projects/EmacsMuse.html. + +If you wish to participate in the development of Muse, or track the +latest development changes, please read the `Development' section of +the Muse manual (in the `Obtaining Muse' chapter) for instructions. + +Mailing Lists +============= + +Mailing lists for Muse exist. + +muse-el-announce :: + Low-traffic list for Muse-related announcements. + + You can join this mailing list (muse-el-announce@gna.org) + using the subscription form at + http://mail.gna.org/listinfo/muse-el-announce/. + + This mailing list is also available via Gmane (http://gmane.org/). + The group is called + gmane.emacs.muse.announce. + +muse-el-discuss :: + Discussion, bugfixes, suggestions, tips, and the like for Muse. + This mailing list also includes the content of muse-el-announce. + + You can join this mailing list (muse-el-discuss@gna.org) + using the subscription form at + http://mail.gna.org/listinfo/muse-el-discuss/. + + This mailing list is also available via Gmane with the identifier + gmane.emacs.muse.general. + +muse-el-logs :: + Log messages for commits made to Muse. + + You can join this mailing list (muse-el-logs@gna.org) using + the subscription form at + http://mail.gna.org/listinfo/muse-el-logs/. + + This mailing list is also available via Gmane with the identifier + gmane.emacs.muse.scm. + +muse-el-commits :: + Generated bug reports for Emacs Muse. If you use our bug-tracker at + https://gna.org/bugs/?group=muse-el, the bug reports will be sent to + this list automatically. + + You can join this mailing list (muse-el-commits@gna.org) using + the subscription form at + http://mail.gna.org/listinfo/muse-el-commits/. + + This mailing list is also available via Gmane with the identifier + gmane.emacs.muse.cvs. + +License +======= + +Emacs Muse is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 3, or (at your option) any +later version. + +Emacs Muse is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with Emacs Muse; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, USA. + +The Muse manual is available under the terms of the GNU Free +Documentation License, Version 1.2 or any later version published by +the Free Software Foundation; with no Invariant Sections, and with the +Front-Cover texts and Back-Cover Texts as specified in the manual. A +copy of the license is included in the section entitled "GNU Free +Documentation License" in the Muse manual. All Emacs Lisp code +contained in the manual may be used, distributed, and modified without +restriction. + +The PNG images included in the examples/ directory may be used, +distributed, and modified without restriction. + +The contents of the contrib/blosxom and contrib/pyblosxom directories +are available under the terms of other licenses. Please consult the +header of each file for the appropriate license text. |