Fix bug #6399; designate this 3.02.91 (RC2).

[muse-el.git] / NEWS

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

* Changes in Muse 3.03 (not yet released)

** Blosxom publishing (lisp/muse-blosxom.el)

*** New option: muse-blosxom-use-tags.
This specifies whether or not we are using tags.  Tags allow a page to
belong to multiple categories, but they do not rely on the directory
structure for categorization.

** Core functionality (lisp/muse.el)

*** Fix an XEmacs beta byte-compiler issue.

*** Make nested list manipulation accessible to both Muse Mode
and Muse publishing.

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

*** Make sure spaces in URLs get escaped properly.

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

*** Improve escaping of specials.

*** Use \label{} and \ref{} for anchors and anchor references.

*** Emphasize table elements.

*** Improve table generation.

*** Use \url{} to publish bare URLs.

*** Handle case where a Muse page begins with a quote character.

*** Display footnotes when we have both a URL and description.
This makes the URLs show up on printed documents in a sensible
fashion.

*** Escape the "@" character in the entire document.

** Muse Manual (muse.texi)

*** Implicit Links

**** Mention how to customize the WikiName recognition.

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

*** `C-c TAB' now inserts an object, prompting the user for which type.
`C-c TAB l' inserts a relative link.
`C-c TAB t' inserts a Muse tag.
`C-c TAB u' inserts a URL.

These keybindings may be modified by editing `muse-insert-map'.  Note
that the prompt you get when you hit `C-c TAB' will not change.

*** New list-oriented keybindings:
`M-RET' inserts a list item.
`C->' increases list item indentation.
`C-<' decreases list item indentation.

*** New option: muse-colors-inline-images.
This determines whether or not to inline an image.  The default is to
enable this behavior.

**** `C-c C-i' toggles whether images are inlined.

**** New option: muse-colors-inline-image-method.
This determines how to find an image that we want to inline.  The
default is to look in the current directory.  If set to
'muse-colors-use-publishing-directory, it will look in the directory
where the current page will be published.

*** Slightly improvement speed of flyspell integration

*** Implement searching through Muse files.

**** `C-c C-s' performs a search through Muse files.

**** New option: muse-grep-command.
Customize this to specify the command used for searching.  In
particular, "glimpse" is handy.  Check the documentation for this
command for details.

*** Changed keybindings:
`C-c C-b' is now `muse-find-backlinks'
`C-c C-v' is now `muse-browse-result'

*** Don't require muse-publish.el, since publishing and viewing Muse
files are supposed to be completely separable.

** New modules

*** lisp/muse-backlink.el -- Provide backlink support for Muse.

*** lisp/muse-groff.el --  This introduces the publishing styles
"groff" and "groff-pdf".

*** lisp/muse-latex2png.el -- Publish embedded LaTeX content to a PNG file.
This introduces the <latex> tag.

*** lisp/muse-xml-common.el -- Common functionality used by XML-based
publishing styles, such as HTML, XML, and DocBook.

*** experimental/muse-mathml.el -- This introduces the "mathml"
publishing style and the <math> tag.

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

*** Introduce the `with-muse-project' macro, which makes it easier
to switch to a given Muse project and execute some code.

*** Fix an error with `custom-quote'.

*** Ignore buffers that have no associated filename.
This fixes an annoyance where Muse prompts to save BBDB and ERC
buffers before publishing.

** Publishing (lisp/muse-publish.el)

*** Implement escaping of specials throughout the entire document.
This makes it much easier to publish documents to multiple kinds of
formats, since you no longer have to worry about putting <verbatim>
around specials.

*** Make escaping of specials context-sensitive.
Muse now realizes that URLs, normal document text, <example> regions,
and the like have different special characters to escape.

*** Distinguish links and footnotes better.

*** Simplify markup string for anchors.

*** Allow text like "%N%" in markup strings.
This makes it much easier to re-use the same text or put strings in
a different order.

*** Support nested lists.
Muse now determines the nested level of a list by its initial
whitespace.  Ordered lists, unordered lists, and definition lists can
all be nested.  It is even possible to force a line break in a list
item by inserting a blank line on the same level between the lines.
Blockquotes may also be nested inside of a list.

*** Create parent directories when publishing for the first time.

*** Allow empty elements in tables.

*** Handle case where we are trying to publish a file that has not
been saved.

*** Handle nested emphasis types better.
It should now publish exactly the way it looks in Muse Mode.

*** Fix XEmacs issue where text at beginning of buffer is read-only.

*** Allow publishing styles to specify a function to use for
escaping specials in a particular context.  This is especially handy
for HTML URLs, since they have a larger subset of special characters
than normal characters.

See `muse-xml-decide-specials' in muse-xml-common.el for details.
This functionality already exists for escaping specials in strings.

*** New tags, see the Tag Summary section in the manual for details

**** <comment> -- Designate entire regions as comments.

**** <quote> -- Publish the region as a blockquote.

** Texinfo publishing (lisp/muse-texinfo.el)

*** Escape commas in URLs.

*** Make it so that links to other info or PDF documents use the proper
suffix.

** URL protocols (lisp/muse-protocols.el)

*** Add support for DOI's.
DOI's (digitial object identifiers) are a standard identifier used in
the publishing industry.

*** Add support for "dict:" URLs.
This is used to look up terms on the Wikipedia website.

**** New option: muse-wikipedia-country.
This specified the country code to use for Wikipedia.

** Wiki (lisp/muse-wiki.el)

*** If the document does not have a valid title string, use the
empty string.

*** Fix some bugs.

** XML publishing (lisp/muse-xml.el)

*** Update examples/muse.rnc to handle nested list items.

*** Fix table generation when some attributes are not given.

* Changes in Muse 3.02.6

** Building Muse

*** Autoloads for Muse are now generated in the muse-autoloads.el
file at build time.

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

*** Don't escape "%" and "+" in URLs.

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

*** <lisp> tags are now evaluated at display time.
The actual contents of the buffer will not change, just the displayed
text.  To toggle this behavior, set `muse-colors-evaluate-lisp-tags'.

** Publishing (lisp/muse-publish.el)

*** When errors happen during publishing, a more explanatory message
is displayed.

*** It is now possible to specify non-breaking-space with "~~"
(two tildes).  This helps prevent proper names from being split up in
the output.

*** Escape specials in all forms of emphasis.

*** Escape "[" and "]" in links that are entered using muse-make-link.

*** Errors from invalid lisp code in a <lisp> tag will be published
as a comment.  If you have `muse-publish-comments-p' set to nil, the
effect is to remove the error message.

*** Fix several publishing issues involving comments and numbered lists.

** Wiki (lisp/muse-wiki.el)

*** Interwiki links in extended links that have special characters are
now handled properly.

** XML publishing (lisp/muse-xml.el)

*** The XML publishing style is now considered stable.
Its schema is available in `examples/muse.rnc'.

* Changes in Muse 3.02.5

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

*** Use a better algorithm for determining how many times we need to
call pdflatex for publishing.  Anything with a Table of Contents needs
2 passes.

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

*** The 3 levels of emphasis now have corresponding muse-emphasis-N faces.
This permits the user to customize them, which may be useful if a font
does not have italic and/or bold versions.

*** Visiting pages with anchors works better.

*** Fix fill bug with semicolons in the middle of paragraphs.

*** Fix a bug with editing the link at point.

*** Fix a display bug with text like =<verbatim><example></verbatim>=.

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

*** Fix an edge case that yielded a stringp: nil error.

*** Prevent auto-save files from being recognized as Muse files.

** Wiki (lisp/muse-wiki.el)

*** By default, WikiWords can have consecutive capital letters.

*** Fix an error that occurs when muse-colors is not loaded.

*** It is now possible to specify a suffix for WikiWord links.
For example: WikiName''''s.  The WikiName part will be displayed and
colored as a link, but the "s" will be left alone.

* Changes in Muse 3.02.02

** Configuration

*** A bug with customizing `muse-project-alist' has been fixed.

*** We use a file extension for Muse files by default.
To obtain the old behavior, set `muse-file-extension' to nil and
`muse-mode-auto-p' to t.

To go along with the new behavior, be sure to rename all of your Muse
files to have a ".muse" extension.

*** New option: `muse-wiki-ignore-bare-project-names'.
This causes Muse to ignore bare project names if specified.  The
default is to turn bare project names into links.

*** New option: `muse-publish-comments-p'.
This causes Muse to publish comments as markup.  The default is to
remove comments before publishing rather than trying to mark them up.

*** New option: `muse-wiki-allow-nonexistent-wikiword'.
Enabling this will cause WikiWords with no corresponding file to be
colored as bad links.  The default is not to color them and turn them
into links.

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

*** An error with intangible links has been fixed.

*** Visiting a page with an anchor works better than before.

*** Flyspell behaves better with Emacs21 than before.

*** Links to nonexistent files will be colored red by default.
This happened previously, but the algorithm was buggy and didn't cover
implicit links.

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

*** A convenience macro called `with-muse-project' has been added.
This allows a code block to be executed after changing the current
Muse project.  It is analogous to emacs-wiki's
`with-emacs-wiki-project' function.

** Publishing (lisp/muse-publish.el)

*** An issue involving anchors at the end of a line has been
addressed.

*** Non-word characters are now allowed before an anchor.

*** Comments may now be published, if desired.
This behavior may be controlled with the `muse-publish-comments-p'
option.  The default is to remove comments before publishing rather
than trying to mark them up.

*** Publishing directives may now include a dash character.

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

*** A bug with footnotes has been addressed.
An attempt has been made to make generated footnote markup look more
"natural" to experienced LaTeX users.

*** Table headers are underlined and table footers are overlined.

*** PDF publishing will cause pdflatex to be called as needed.
The previous behavior was to always call pdflatex twice.  Currently,
if pdflatex succeeds, it will not be called again.  Otherwise, call it
up to three times.

*** Escaping of special characters should be drastically improved.
An attempt has been made to get escaping done right in most contexts.
The only quirk is that you must surround dollar signs with equal signs
to ensure escaping.  This makes publishing PDF documents much more
useful.

** Texinfo publishing (lisp/muse-texinfo.el.el)

*** An attempt was made to hone some of the markup.

* Changes in Muse 3.02.01

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

*** Links should no longer prevent moving the point, and help text for
links should no longer cause errors to occur.

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

*** `muse-project-alist' -- This variable should now save customizations
to the correct form in the .emacs file.  Before, it was saving an
intermediate form of the variable.

If you have used the customize interface in the previous release of
Muse to set `muse-project-alist', please do the following to import
your settings.

 - Open your .emacs file.
 - Move the point to where `muse-project-alist' is set.
 - Type `M-: (setq muse-project-alist-using-customize t) RET'.
 - Type `C-M-x'.
 - Type `M-x customize-save-variable RET muse-project-alist RET'.

*** `muse-project-alist' -- A bug involving the deleting of items
using Emacs21 and XEmacs21 has been fixed.

** Publishing (lisp/muse-publish.el)

*** If 2 or more blank lines separate list or table items, each item
will be published in a separate list or table.

*** The #date directive is now populated by default with the last
modified time of each file, rather than the current time of day.  To
use this value, add '<lisp>(muse-publishing-directive "date")<lisp>'
to your header or footer.

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

*** `muse-xhtml-style-sheet' -- New option that indicates the style
settings to use for XHTML documents.  This may be either a filename or
a string of stylesheet settings.

* Changes in Muse 3.02

** New modules

*** lisp/muse-wiki.el --- Provide automatic linking for WikiWords and
InterWiki links.  These words are clickable and publish as links.
Project names from `muse-project-alist' are available for InterWiki
linking by default.  The list of InterWiki names and handlers may be
customized through `muse-wiki-interwiki-alist'.

WikiWords that do not correspond with real files will not be displayed
as links nor published as links.  It is expected that this behavior
will be made optional in future versions of Muse.

**** This module includes a few helper functions that may be added to
`muse-publish-desc-transforms' in order to modify link descriptions at
publish time.

**** The concept of "implicit links" and "explicit links" has been
introduced.  Explicit links are surrounded by brackets, i.e.
[[http://blah.org][this is a explicit link]].  Implicit links are URLs
and email addresses that are not surrounded by brackets: they will not
be colorized or published if surrounded by double-quotes.

***** `muse-wiki-publish-pretty-title' causes words to be Title-cased,
ignoring words like `the' and `at' which should not be changed.

***** `muse-wiki-publish-pretty-interwiki' changes the delimiter of
interwiki links according to the text of the
`muse-wiki-interwiki-replacement' option.

*** lisp/muse-protocols.el --- URL protocols that Muse recognizes.
This automatically-included module provides an easily customizable
list of URL protocols, how to browse them, and how to resolve them for
publishing.  Customize `muse-url-protocols' to add and remove
protocols.

** Compatibility fixes

*** Muse has been tested with XEmacs 21.4, both Mule and non-Mule versions.
There are no known problems remaining.  To make things work by
default, the iso-8859-1 charset is used as a default option in some
places.

** Configuration

*** `muse-file-extension' -- New option that allows the file extension
for Muse files to be specified.  For example, setting this to "muse"
assumes that you have renamed your Muse files with a ".muse"
extension.  Using this (and setting `muse-mode-auto-p' to nil) will
prevent miscellaneous non-Muse files from being accidentally opened in
Muse Mode.

*** `muse-ignored-extensions' -- New option that determines which file
extensions to omit from the ending of a Muse page name.

*** `muse-ignored-extensions-regexp' -- This is no longer customizable.
It will be automatically generated from `muse-file-extension' and
`muse-ignored-extensions'.

*** `muse-project-alist' -- The customize interface for this option has
been greatly improved, and much effort has been spent in order to make
this user-friendly.

*** The `:force-publish' tag may be specified in `muse-project-alist'.
This causes a particular list of files to be re-created every time the
publishing process is invoked, even if they haven't been changed
according to their timestamps.  One use for this is to keep an index
of available pages by adding the following to a file in this list.

<lisp>(muse-index-as-string t t t)</lisp>

*** `muse-project-ignore-regexp' -- By default, version control directories
are now included in this regexp so that they don't appear when you hit
C-c C-f to browse files in a project.

*** The `muse-project-alist-styles' and `muse-project-alist-dirs' functions
may be used in `muse-project-alist' to recursively add styles and
directory listings for a given directory.  The following is an
example.  We use a backtick instead of a single quote to begin the
list.

(setq muse-project-alist
      `(("Blog"
         (,@(muse-project-alist-dirs "~/proj/wiki/blog")  ;; base dir
          :default "guestbook")

         ,@(muse-project-alist-styles "~/proj/wiki/blog"  ;; base dir
                                      ;; output dir
                                      "~/personal-site/site/blog"
                                      ;; style
                                      "my-blosxom"))))

Note that if you use the customize interface for `muse-project-alist',
you will still have to manually add information for any new
sub-directories.

** Debian packaging

*** Debian packages for Muse have entered Debian unstable, thanks
to Romain Francoise, my sponsor.

It is possible to roll your own Muse packages if you want to do so.
Packages may be built by using `make debrelease', once the proper
options in Makefile.defs are set.  Revisions may be built using `make
debrevision'.

The manual and relevant documentation files have been included with
the Debian package for Muse.

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

*** Allow use of Muse with outline-minor-mode.

*** Filling text does the right thing with list items and footnotes.
List items and footnotes will no longer be concatenated when hitting
M-q in the midst of consecutive items.

*** Links will never be split in the middle when using Fill.

*** Some flyspell crash issues were addressed.
Using intangible text can cause strange problems with flyspell mode.
Hence, by default, the intangible property will be ignored.  A new
option called `muse-mode-intangible-links' indicates whether this
should be the case.

*** Links will no longer be highlighted by flyspell.
If you're using XEmacs or Emacs 22, flyspell will ignore links,
including link text.  This keeps flyspell from making the links
unclickable.  If you're using Emacs 21, flyspell will continue to
interfere with links.  If you know how to fix this, please send a
patch!

*** A few edge cases for emphasis and underlining have been addressed.

*** <example>, <verbatim>, and =surrounded text= are now colored using
the new face `muse-verbatim-face'.

*** All marked up text properties, like emphasis and underlining,
will be removed for the text between <example>, <verbatim>, <code>,
<literal>, and <lisp> tags.

*** Links to temporary files may be visited.
A "temporary file" in this case is a buffer that is not associated
with any file.  For some dynamic content import scripts with Planner,
this is helpful.

*** Typing "#title" should never crash Emacs anymore.

** Muse manual (muse.texi)

*** Fix problem with producing a PDF version of the manual.

*** Document WikiNames.

*** Bring up-to-date with latest features.

*** Massively update Common Elements section.

*** New Directives section.
This describes the use of #title and #author, as well as other
directives that may be used.

*** New Comments section.
Describes the use of "; comment text".

** Publishing (lisp/muse-publish.el)

*** The order of rules should be much improved.
This means that emphasis characters like `*' and `_' will never be
interpreted as such if they are within links.

*** The user will be notified when `muse-publish-this-file' fails to
publish the current file.  This happens when the timestamp of the
current file indicates that it is up-to-date.

*** Special characters are escaped in link descriptions and links on a
more consistent basis.  What defines a "special character" varies
according to the publishing style.

*** Errors that occur during publish time will cause a warning to be
displayed prominently, rather than being ignored.  It should no longer
be possible to mess up a Muse source file by tweaking the Muse
publishing process.

*** Errors in <lisp> tags cause a warning to be displayed and
return "<!--INVALID LISP CODE-->".  Muse will try to continue
publishing the page.

*** An emdash ("--") can now be used after a list, as long as there is
a blank line between the end of the list and the emdash.

*** The <code> tag has been introduced.
It does the same thing that =equal signs= do: escape specials and
publish as teletype text.  Use it for short command snippets and the
like.  <example> is a better choice for large blocks of code, since it
preserves whitespace.

*** An edge case involving links at the beginning of a paragraph
has been addressed.

*** An edge case involving consecutive directives of the same size
has been addressed.

*** Every publishing style is now capable of specifying strings to use
for sections beyond the third level.

*** Every publishing style may specify an end-of-section string.
This is used, for example, by the experimental XML style and the
DocBook style.

*** Every publishing style may specify a method of handling "internal
link" markup.  An internal link is a link that refers to an anchor on
the current page.

*** Every publishing style may specify a link suffix to use.
This allows the file extensions in links to other Muse files to be
different from their actual extension.  Blosxom makes use of this
(since its published files are .txt and the dynamically-generated
output is .html), and it could come in handy for PHP stuff.

If a link suffix is not specified via :link-suffix, the value of
:suffix will be used.

** Blosxom publishing (lisp/muse-blosxom.el)

*** muse-blosxom-new-entry: A #category directive is added by default.
Nothing is done with this yet, but it could be handy for tag-based
(multiple category) blogging, once we figure out a good way to do that
in both Muse and Pyblosxom.  Ideas are welcome, and patches even more
so.

** DocBook publishing (lisp/muse-docbook.el)

*** The markup has been comprehensively improved.
Published documents will now pass validation tests and look better in
general.

*** It is now possible to specify the encoding of DocBook documents.
The default encoding is utf-8.

*** Footnotes will be embedded into paragraphs, since this is
The DocBook Way.

*** Tables will be sorted by section.
Headers first, then footers, then the rest of the table.

*** Anchors are now handled correctly and publish to the best available
form.  Links to anchors are published with the <link> tag.

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

*** Fix minor issue with anchors.

*** Paragraph publishing will no longer insert <div> tags before images.
This was causing too much hassle for some programs that were trying to
extend Muse, like the Muse port of Planner.

*** The `&', `<', and '>' characters will be escaped using their specific
HTML escape codes, rather than with "&#NNN;".  This makes the
published output display correctly in more web browsers.

*** Use HTML 4.0 Transitional by default for `muse-html-header'.

*** Include empty alt element in markup string for images that lack a
description.

*** Tables will be sorted by section.
Headers first, then footers, then the rest of the table.

*** `muse-xhtml-extension' -- The default extension for XHTML publishing.
This is a new option.

** Journal publishing (lisp/muse-journal.el)

*** Use "div class=..." rather than "div id=..." for sections.

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

*** A newline will be appended to the default footer for the latex and
latexpdf publishing styles.  This keeps the PDF-building process from
failing due to lack of a newline at end of file.

*** Anchors and links to them now work properly.

*** When generating PDF files, call pdflatex twice.
This should ensure that the table of contents gets generated, if one
is due to be published.

*** PDF files with spaces may be published.
A bug preventing this has been fixed.

*** Teletype text is now published using \\texttt{...}.

*** An attempt has been made to escape special characters more
consistently.

** Texinfo publishing (lisp/muse-texinfo.el)

*** Fix a fatal error that occurs when publishing tables.

*** Generate the contents in the header by default rather than the footer.
This is the way that most Texinfo manuals do it.

*** The info-pdf publishing style currently produces the best PDF output
on the maintainer's machine, so it is now used to publish the PDF
version of the Muse Manual.

*** The characters `{' and `}' will be treated as special characters that
need to be escaped at publish-time.

*** Improve dots and enddots markup strings.

*** Surround underlined text with "_" since Texinfo doesn't seem to have
any better options for producing underlined text.

*** Anchors and links to them now work properly.