Introduction

Emacs Muse is an authoring and publishing environment for Emacs. It simplifies the process of writing documents and publishing them to various output formats. Muse consists of two main parts:

1. An enhanced text-mode for authoring documents and navigating within Muse projects
2. A set of publishing styles for generating different kinds of output.

What makes Muse distinct from other text-publishing systems is a modular environment, with a rather simple core, in which so called styles are derived from some default, yet fully usable styles, in order to create new styles. Much of Muse overall functionality is optional. For example, one can use the publisher without the major-mode, or the major-mode without doing any publishing, or if desired one does not have to load the Texinfo or LaTeX modules, so those styles will not be available and thus save system resources.

From the authors point of view, Muse is like a Wiki with all its benefits i.e. linking pages with hyperlinks and referencing and navigation amongst them becomes a piece of cake. With Muse, one can create/manage his personal notebook which might become his on-the-net website when publishing to XHTML, have his weblog or write his doctoral thesis when publishing to LaTeX etc. Another highly impacting benefit from the authors point of view is, that once familiar with Muse, one might never need to switch to different application software again and spend time on the initial learning process — with Muse, one can do everything i.e. keeping a notebook, putting a wiki on-the-net, writing articles for journals, write letters, laboratory protocols or even write his master thesis etc. Next to that, there are other Emacs packages that are stacked on top of Muse (Planner for example).

One of the principal aims in the development of Muse is to make it very easy to produce good-looking, standards-compliant documents. The Muse codebase is a departure from emacs-wiki.el (thus the powerful wiki aspect with Muse). The code has been restructured and rewritten, especially its publishing functions.

Install

Please take a look at the Emacs main page — it has a section telling about how to set up and configure Muse.

Notes

Emacs Muse is an authoring and publishing environment for Emacs. It simplifies the process of writing documents and publishing them to various output formats. This section is intended as a notebook for me to take notes and maybe also provide useful information to others. For more information about muse you might take a jump...

Images with Muse

Coolest thing for the coolest kid on the block describes it best. Imagine a world without images!? Cannot be. Would not work.

A picture is worth 10k words — but only those to describe
the picture. Hardly any sets of 10k words can be adequately described
with pictures.
    — Unknown

See! Pictures alone are no guarantee for successfully transferring information from writers to readers — it also takes words — in fact the correct mixture has the capability to make it a great experience for writers and readers or turn it into the opposite.

Muse provides a great deal in flexibility how to incorporate and handle images for the writer. It is fast, simple and has a variety of possibilities plus it integrates like charm with all CLI (Command Line Interface) tool on is already used to in order to alter images the fast and easy way.

Thumbnails

I create and manage my website with muse-mode in GNU Emacs. Take a look at the muse manual. To place thumbnail images onto pages which then in turn link to the full-sized version of the same image one can do [[URL-to-full-sized-version][URL-to-thumbnail]]. The thumbnail will then occur on the website and point to the full-sized version.

You can take an image via your CLI (Command Line Interface) i.e. import -window root /tmp/gnus_face.png which creates a screenshot of size 1600x1200 pixel on my computer.

sa@pc1:/tmp$ identify gnus_face.png
gnus_face.png PNG 1600x1200 1600x1200+0+0 DirectClass 132kb
sa@pc1:/tmp$

Then resize it to thumbnail size

sa@pc1:/tmp$ convert -resize 200x gnus_face.png gnus_face_small.png
sa@pc1:/tmp$ identify gnus_face*
gnus_face.png PNG 1600x1200 1600x1200+0+0 DirectClass 132kb
gnus_face_small.png[1] PNG 200x150 200x150+0+0 DirectClass 80kb
sa@pc1:/tmp$

and include it into your muse page as shown above. You can of course do much more funkier stuff on the CLI if you want to. As of now (August 2007) I have created myself another lovely one-liner which I invoke with tsh at the CLI. Check out the .bashrc customization I did.

Miscellaneous

C-c C-a runs muse-index

,----[ C-h f muse-index RET ]
| muse-index is an interactive Lisp function in `muse-mode.el'.
| It is bound to <f6> i, C-c C-a.
| (muse-index)
|
| Display an index of all known Muse pages.
|
| [back]
`----

muse-protocols.el

Issue M-x find-library RET muse-protocols.el RET and take a look at the comments and code. It allows to use things like dict:eagle which creates a link to http://en.wikipedia.org/wiki/Eagle without you having to make your way to the web browser and back. Also, get familiar with the possibility to use YubNub.

Into this

YubNub I say; YubNub I mean!
      — A random Ewok

(Trivia: YubNub means freedom in the language of Star Wars Ewoks)

muse-colors-evaluate-lisp-tags

If you do not want to get code inside `<lisp>' tags evaluated during display time in your muse buffer just alter

,----[ C-h v muse-colors-evaluate-lisp-tags RET ]
| muse-colors-evaluate-lisp-tags is a variable defined in `muse-colors.el'.
| Its value is t
|
|
| Documentation:
| Specify whether to evaluate the contents of <lisp> tags at
| display time.  If nil, don't evaluate them.  If non-nil, evaluate
| them.
|
| The actual contents of the buffer are not changed, only the
| displayed text.
|
| You can customize this variable.
|
| [back]
`----

`C-c TAB' 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.

Search through Muse files

,----[ C-h k C-c C-s ]
| C-c C-s runs the command muse-search
|   which is an interactive Lisp function in `muse-mode.el'.
| It is bound to C-c C-s.
| (muse-search)
|
| Search for the given TEXT using the default grep command.
|
| [back]
`----

List-oriented keybindings

`M-RET' inserts a list item.
`C->' increases list item indentation.
`C-<' decreases list item indentation.

Backlinks

Shows backlinks to a particular page.

,----[ C-h k C-c C-b ]
| C-c C-b runs the command muse-find-backlinks
|   which is an interactive Lisp function in `muse-mode.el'.
| It is bound to C-c C-b.
| (muse-find-backlinks)
|
| Grep for the current pagename in all the project directories.
|
| [back]
`----

Browse Result

Displays page in iceweasel.

,----[ C-h k C-c C-v ]
| C-c C-v runs the command muse-browse-result
|   which is an interactive Lisp function in `muse-mode.el'.
| It is bound to C-c C-v.
| (muse-browse-result style &optional other-window)
|
| Visit the current page's published result.
|
| [back]
`----

Editing existing links with `C-c C-e'

,----[ C-h k C-c C-e ]
| C-c C-e runs the command muse-edit-link-at-point
|   which is an interactive Lisp function in `muse-mode.el'.
| It is bound to C-c C-e.
| (muse-edit-link-at-point)
|
| Edit the current link.
| Do not rename the page originally referred to.
|
| [back]
`----

Publish current page with a particular style

,----[ C-h k C-c C-t ]
| C-c C-t runs the command muse-project-publish-this-file
|   which is an interactive Lisp function in `muse-project.el'.
| It is bound to C-c C-t.
| (muse-project-publish-this-file &optional force)
|
| Publish the currently-visited file according to `muse-project-alist',
| prompting if more than one style applies.
|
| If force is given, publish the file even if it is up-to-date.
|
| [back]
`----

Inline Images (or not)

,----[ C-h v muse-colors-inline-images RET ]
| muse-colors-inline-images is a variable defined in `muse-colors.el'.
| Its value is t
|
|
| Documentation:
| Specify whether to inline images inside the Emacs buffer.  If
| nil, don't inline them.  If non-nil, an image link will be
| replaced by the image.
|
| The actual contents of the buffer are not changed, only whether
| an image is displayed.
|
| You can customize this variable.
|
| [back]
`----

Or do it selectively per image. It is now possible to force images to not be inlined. To accomplish this, place the text URL: immediately in front of the link text.

Example: URL:http://example.org/image.png

Privacy with some files

,----[ C-h v muse-project-publish-private-files RET ]
| muse-project-publish-private-files is a variable defined in `muse-project.el'.
| Its value is t
|
|
| Documentation:
| If this is non-nil, files will be published even if their permissions
| are set so that no one else on the filesystem can read them.
|
| Set this to nil if you would like to indicate that some files
| should not be published by manually doing "chmod o-rwx" on
| them.
|
| This setting has no effect under Windows (that is, all files are
| published regardless of permissions) because Windows lacks the
| needed filesystem attributes.
|
| You can customize this variable.
|
| [back]
`----

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.

Interactive function: muse-publish-region

,----
| muse-publish-region is an interactive Lisp function in `muse-publish.el'.
| (muse-publish-region beg end &optional title style)
|
| Apply the given style's markup rules to the given region.
| The result is placed in a new buffer that includes title in its name.
|
| [back]
`----

This command publishes the current region, prompting for the title of the page (if any) and the style to use.

This is handy for firing off quick blog entries and pasting the result into a web browser — for this use case, it is recommended to use the blosxom-html or blosxom-xhtml styles, as they omit the large header and footer.

Publish image links with descriptions as captioned images

This has been implemented for all Muse publishing styles.

The major change is that image links with descriptions will be centered and the description will be displayed just below the image as a "caption". Thus, it is meant to only be used as its own paragraph, not surrounded by other text. Images without descriptions may still have surrounding text.

Add support for "dict:" URLs

This is used to look up terms on the Wikipedia website.

muse-wikipedia-country

This specified the country code to use for Wikipedia.

,----[ C-h v muse-wikipedia-country RET ]
| muse-wikipedia-country is a variable defined in `muse-protocols.el'.
| Its value is "en"
|
|
| Documentation:
| Indicate the 2-digit country code that we use for Wikipedia
| queries.
|
| You can customize this variable.
|
| [back]
`----

Three-part links

Example: Project::File#anchor now works.