GNU-devel ELPA - muse

                                                          -*- Text -*-
This is the README file for Emacs Muse.

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.

Emacs Muse NEWS --- History of user-visible changes    -*- outline -*-

* Changes in Muse 3.20

** Fix bug with duplicates in completing-read of wiki page names.

** Mark some tags as dangerous for text by untrusted contributors.

** Implement <div> tag.

** When viewing a page, publish it first.

** Include non-working alpha of Ikiwiki publishing.

** Make it easier to browse published PDF files.

** Fix bug with C-c C-v on a file not part of any project.

** Add workaround for Emacs 23 and htmlize issue.

** muse-latex2png: Fix handling of filenames with spaces in them.

** muse-colors: Separate highlighting rules according to major mode.

** muse-latex: Make lecture notes and slides work with images,
title page, and table of contents.

** Publishing

*** Fix end-of-line conversion bug when using Windows.

*** Fix bug where dates in journal entries could be published incorrectly.

*** Preserve the value of muse-current-project.

*** Conditionally interpret local variables.

*** Values set by file-local variables trump project variables.

*** muse-latex: Fix publishing of tags inside of <slide> tags.

*** Render <example> correctly in slides.

*** Fix bug in publishing of table.el style tables.

*** Fix bug where the first paragraph would not be published properly
if it started with a link.

** Build system

*** Makefile.defs.default (INFODIR): Place files in .../share/info.

** Manual

*** Miscellaneous updates.

* Changes in Muse 3.12

** New interactive function `muse-update-values': Call this after
changing muse-project-alist, in order to update various autogenerated
values.

** Tag attributes may now span multiple lines.

** Don't keep track of undo data when publishing.
This should yield a speed-up.

** Build system

*** Add support for the DESTDIR variable, which allows the destination
directory to be easily set.

** Muse Mode highlighting (lisp/muse-colors.el)

*** Display message when muse-colors-toggle-inline-images is called.

** ConTeXt publishing (lisp/muse-context.el)

*** Fix publishing bug in Windows.

** HTML publishing (lisp/muse-html.el)

*** Fix bug where nested class tags were not working.

*** Fix error that occurred when a class tag had no name element.
In this case, we do not publish the tag at all.

** LaTeX publishing (lisp/muse-latex.el)

*** Escape specials in image filenames properly
Previously, it was not possible to escape "/", "#", or "|" in image
filenames.  In order to make this work, be certain that you have the
following LaTeX code in your header.

\def\museincludegraphics{%
  \begingroup
  \catcode`\|=0
  \catcode`\\=12
  \catcode`\#=12
  \includegraphics[width=0.75\textwidth]
}

*** Escape specials in the title string in headers
In order to achieve this effect in custom headers, replace

  \title{<lisp>(muse-publishing-directive "title")</lisp>}

with

  \title{<lisp>(muse-publish-escape-specials-in-string
    (muse-publishing-directive "title") 'document)</lisp>}

in your headers.

*** Default to using UTF-8 rather than latin1 in headers.

*** Fix publishing bug in Windows.

*** Escape backslash as \textbackslash{} in monospace regions.

** Publish embedded LaTeX content to a PNG file (lisp/muse-latex2png.el)

*** Detect whether the tag ends at the end of a line.
If not, do not use "$$" to publish it.

** Muse Mode (lisp/muse-mode.el)

*** New option: `muse-insert-url-initial-input' specifies the initial text
to use when reading a URL.

*** Fix bug with browsing anchors that come after a link to them.

*** Fix bug involving filling and paragraphs next to headings.

*** Fill definition lists with two initial spaces in lines after the
definition list term.

** Project support (lisp/muse-project.el)

*** Fix issue that occurred when saving several files at once, where only
one of them would make it into the project file-alist.

*** If the PAGE argument to `muse-project-page-file' is nil, then return
the first directory of the project.

*** Fix bug where directory names without slashes in projects were not
...
...