1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.02.93 (3.03 RC3).
17 Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.2 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover texts being ``A GNU
24 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
25 license is included in the section entitled ``GNU Free Documentation
26 License'' in this manual.
28 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
29 this GNU Manual, like GNU software. Copies published by the Free
30 Software Foundation raise funds for GNU development.''
32 This document is part of a collection distributed under the GNU Free
33 Documentation License. If you want to distribute this document
34 separately from the collection, you can do so by adding a copy of the
35 license to the document, as described in section 6 of the license.
37 All Emacs Lisp code contained in the manual may be used, distributed,
38 and modified without restriction.
44 @subtitle an authoring and publishing environment
45 @subtitle for GNU Emacs and XEmacs
47 @c The following two commands
48 @c start the copyright page.
50 @vskip 0pt plus 1filll
54 @c So the toc is printed at the start
58 @node Top, Preface, (dir), (dir)
59 @comment node-name, next, previous, up
66 * Preface:: About the documentation.
67 * Introduction:: What is Muse?
68 * Obtaining Muse:: How to get Muse releases and development
70 * Installation:: Compiling and installing Muse.
71 * Getting Started:: Settings for Muse.
72 * Projects:: Creating and managing Muse projects.
73 * Keystroke Summary:: Keys used in Muse mode.
74 * Markup Rules:: Rules for using markup.
75 * Publishing Styles:: Publishing various types of documents.
76 * Extending Muse:: Making your own publishing styles.
77 * Getting Help and Reporting Bugs::
78 * History:: History of this document.
79 * Contributors:: Contributors to this documentation.
80 * GNU Free Documentation License:: The license for this documentation.
81 * Concept Index:: Search for terms.
84 --- The Detailed Node Listing ---
86 How to Get Muse Releases and Development Changes
88 * Releases:: Released versions of Muse.
89 * Development:: Latest unreleased development changes.
91 Rules for Using Markup
93 * Paragraphs:: Paragraphs: centering and quoting.
94 * Headings:: Levels of headings.
95 * Directives:: Directives at the beginning of a
97 * Emphasizing Text:: Bold, italicized, and underlined text.
98 * Footnotes:: Making notes to be shown at the end.
99 * Verse:: Indicating poetic stanzas.
100 * Lists:: Lists of items.
101 * Tables:: Generation of data tables.
102 * Explicit Links:: Hyperlinks and email addresses with
104 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
106 * Images:: Publishing and displaying images.
107 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
108 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
110 * Comments:: Lines to omit from published output.
111 * Tag Summary:: Tags that Muse recognizes.
113 Publishing Various Types of Documents
115 * Blosxom:: Integrating Muse and pyblosxom.cgi.
116 * Book:: Publishing entries into a compilation.
117 * DocBook:: Publishing in DocBook XML form.
118 * HTML:: Publishing in HTML or XHTML form.
119 * Journal:: Keeping a journal or blog.
120 * LaTeX:: Publishing LaTeX documents.
121 * Poem:: Publish a poem to LaTex or PDF.
122 * Texinfo:: Publish entries to Texinfo format or PDF.
124 Integrating Muse and pyblosxom.cgi
126 * Blosxom Requirements:: Other tools needed for the Blosxom style.
127 * Blosxom Entries:: Format of a Blosxom entry and automation.
128 * Blosxom Options:: Blosxom styles and options provided.
130 Making your own publishing styles
132 * Common Elements:: Common functionality shared by styles.
133 * Deriving Styles:: Deriving a new style from an existing
136 Common functionality shared by styles
138 * Markup Functions:: Specifying functions to marking up text.
139 * Markup Regexps:: Markup rules for publishing.
140 * Markup Strings:: Strings specific to a publishing style.
141 * Markup Tags:: Tag specifications for special markup.
142 * Style Elements:: Parameters used for defining styles.
147 @node Preface, Introduction, Top, Top
148 @comment node-name, next, previous, up
149 @chapter About the documentation
151 This document describes Muse, which was written by John Wiegley
152 and is now maintained by Michael Olson. Several versions of it are
156 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
157 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
158 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
161 @node Introduction, Obtaining Muse, Preface, Top
162 @comment node-name, next, previous, up
163 @chapter What is Muse?
165 Emacs Muse is an authoring and publishing environment for Emacs. It
166 simplifies the process of writing documents and publishing them to
167 various output formats.
169 Muse consists of two main parts: an enhanced text-mode for authoring
170 documents and navigating within Muse projects, and a set of publishing
171 styles for generating different kinds of output.
173 This idea is not in any way new. Numerous systems exist -- even one
174 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
175 more modular environment, with a rather simple core, in which "styles"
176 are derived from to create new styles. Much of Muse's overall
177 functionality is optional. For example, you can use the publisher
178 without the major-mode, or the mode without doing any publishing; or if
179 you don't load the Texinfo or LaTeX modules, those styles won't be
182 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
183 code has been restructured and rewritten, especially its publishing
184 functions. The focus in this revision is on the authoring and publishing
185 aspects, and the "wikiness" has been removed as a default behavior
186 (available in the optional @file{muse-wiki} module). CamelCase words are
187 no longer special by default.
189 @node Obtaining Muse, Installation, Introduction, Top
190 @comment node-name, next, previous, up
191 @chapter How to Get Muse Releases and Development Changes
194 * Releases:: Released versions of Muse.
195 * Development:: Latest unreleased development changes.
198 @node Releases, Development, Obtaining Muse, Obtaining Muse
199 @comment node-name, next, previous, up
200 @section Released versions of Muse
202 Choose to install a release if you want to minimize risk.
204 Errors are corrected in development first. User-visible changes will be
205 announced on the @email{muse-el-discuss@@gna.org} mailing list.
206 @xref{Getting Help and Reporting Bugs}.
208 @cindex releases, Debian package
209 @cindex Debian package for Muse
210 Debian and Ubuntu users can get Muse via apt-get. The @file{muse-el}
211 package is available both at Michael Olson's APT repository and the
212 official Debian and Ubuntu repositories. To make use of the former, add
213 the following line to your @file{/etc/apt/sources.list} file and run
214 @code{apt-get install muse}.
217 deb http://www.mwolson.org/debian/ ./
220 @cindex releases, from source
221 Alternatively, you can download the latest release from
222 @uref{http://www.mwolson.org/static/dist/muse/} .
224 @node Development, , Releases, Obtaining Muse
225 @comment node-name, next, previous, up
226 @section Latest unreleased development changes
229 Choose the development version if you want to live on the bleeding edge
230 of Muse development or try out new features before release.
232 @cindex arch revision control system, using
233 The Arch revision control system allows you to retrieve previous
234 versions and select specific features and bug fixes. If you would like
235 to contribute to Muse development, it is highly recommended that you use
236 Arch, but this is not a requirement.
238 If you are new to Arch, you might find this tutorial helpful:
239 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
241 Downloading the Muse module with Arch and staying up-to-date involves
248 @item Debian and Ubuntu: @kbd{apt-get install tla}.
249 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
252 @item Register the archive.
254 tla register-archive -f http://www.mwolson.org/archives/2005
257 @item Download the Muse package.
259 # Download Muse into the @file{muse} directory.
260 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
263 @item List upstream changes that are missing from your local copy.
264 Do this whenever you want to see whether new changes have been committed
268 # Change to the source directory you are interested in.
271 # Display the summary of changes
272 tla missing --summary
275 @cindex updating Muse with Arch
276 @item Update to the latest version by replaying missing changes.
284 There are other ways to interact with the Muse archive.
287 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
288 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
291 The latest development snapshot will be kept up-to-date since it is
292 updated at the same time as the Arch repository.
294 @node Installation, Getting Started, Obtaining Muse, Top
295 @comment node-name, next, previous, up
296 @chapter Compiling and Installing Muse
298 Muse may be compiled and installed on your machine.
300 @subheading Compilation
302 This is an optional step, since Emacs Lisp source code does not
303 necessarily have to be byte-compiled. It will yield a speed increase,
306 A working copy of Emacs or XEmacs is needed in order to compile the
307 Emacs Muse. By default, the program that is installed with the name
308 @command{emacs} will be used.
310 If you want to use the @command{xemacs} binary to perform the
311 compilation, you would need to edit @file{Makefile.defs} in the
312 top-level directory as follows. You can put either a full path to an
313 Emacs or XEmacs binary or just the command name, as long as it is in the
318 SITEFLAG = -no-site-file
321 Running @code{make} should compile the Muse source files in the
322 @file{lisp} directory.
324 @subheading Installation
326 Muse may be installed into your file hierarchy by doing the following.
328 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
329 where you want the source and compiled Muse files to be installed and
330 @env{INFODIR} indicates where to put the Muse manual. Of course, you
331 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
332 Compilation section if you are using XEmacs.
334 If you are installing Muse on a Debian or Ubuntu system, you might want
335 to change the value of @env{INSTALLINFO} as specified in
336 @file{Makefile.defs}.
338 If you wish to install Muse to different locations than the defaults
339 specify, edit @file{Makefile.defs} accordingly.
341 Run @code{make} as a normal user.
343 Run @code{make install} as the root user if you have chosen installation
344 locations that require this.
347 @node Getting Started, Projects, Installation, Top
348 @comment node-name, next, previous, up
349 @chapter Getting Started
352 To use Muse, add the directory containing its files to your
353 @code{load-path} variable, in your @file{.emacs} file. Then, load in
354 the authoring mode, and the styles you wish to publish to. An example
358 (add-to-list 'load-path "<path to Muse>")
360 (require 'muse-mode) ; load authoring mode
362 (require 'muse-html) ; load publishing styles I use
363 (require 'muse-latex)
364 (require 'muse-texinfo)
365 (require 'muse-docbook)
368 Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
369 an input document to any available style. If you enable
370 @file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
371 command will be bound to @kbd{C-c C-t}.
373 If the currently opened file is part of a defined project in
374 @code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
376 You should also type @kbd{M-x customize-group}, and give the name
377 @samp{muse}. Each of the options has its own documentation.
380 @node Projects, Keystroke Summary, Getting Started, Top
381 @comment node-name, next, previous, up
382 @chapter Creating and Managing Muse Projects
385 Often you will want to publish all the files within a directory to a
386 particular set of output styles automatically. To support, Muse
387 allows for the creations of "projects". Here is a sample project, to
388 be defined in your @file{.emacs} file.
391 (require 'muse-project)
393 (setq muse-project-alist
394 '(("website" ; my various writings
395 ("~/Pages" :default "index")
396 (:base "html" :path "~/public_html")
397 (:base "pdf" :path "~/public_html/pdf"))))
400 The above defines a project named "website", whose files are located
401 in the directory @file{~/Pages}. The default page to visit is
402 @file{index}. When this project is published, each page will be
403 output as HTML to the directory @file{~/public_html}, and as PDF to
404 the directory @file{~/public_html/pdf}. Within any project page, you
405 may create a link to other pages using the syntax @samp{[[pagename]]}.
407 By default, Muse expects all project files to have the file extension
408 @file{.muse}. Files without this extension will not be associated with
409 Muse mode and will not be considered part of any project, even if they
410 are within a project directory.
412 If you don't want to use @file{.muse}, you can customize the extension
413 by setting the value of @code{muse-file-extension}.
415 If you don't want to use any extension at all, and want Muse to
416 autodetect project files based on their location, then add the following
417 to your Muse settings file.
420 (setq muse-file-extension nil
424 If you would like to include only some files from a directory in a Muse
425 project, you may use a regexp in place of @file{~/Pages} in the example.
427 @c PRE3_03: Give more examples
428 @c PRE3_03: Describe :set and other options fully
430 @node Keystroke Summary, Markup Rules, Projects, Top
431 @comment node-name, next, previous, up
432 @chapter Keys Used in Muse Mode
435 This is a summary of keystrokes available in every Muse buffer.
439 @item C-c C-a (`muse-index')
440 Display an index of all known Muse pages.
442 @item C-c C-b (`muse-find-backlinks')
443 Find all pages that link to this page.
445 @item C-c C-e (`muse-edit-link-at-point')
448 @item C-c C-f (`muse-project-find-file')
449 Open another Muse page. Prompt for the name.
451 @item C-c C-i (`muse-insert-tag')
452 Insert a tag interactively.
454 @item C-c C-l (`font-lock-mode')
455 Toggle font lock / highlighting for the current buffer.
457 @item C-c C-p (`muse-project-publish')
458 Publish any Muse pages that have changed.
460 @item C-c C-s (`muse-search')
461 Find text in all files of the current project.
463 @item C-c C-t (`muse-project-publish-this-file')
464 Publish the currently-visited file. Prompt for the style if the current
465 file can be published using more than one style.
467 @item C-c C-T (`muse-publish-this-file')
468 Publish the currently-visited file. Prompt for both the style and
471 @item C-c C-v (`muse-browse-result')
472 Show the published result of this page.
474 @item C-c = (`muse-what-changed')
475 Diff this page against the last backup version.
477 @item C-c TAB l (`muse-insert-relative-link-to-file')
478 Insert a link to a file interactively.
480 @item C-c TAB t (`muse-insert-tag')
481 Insert a tag interactively.
483 @item C-c TAB u (`muse-insert-url')
484 Insert a URL interactively.
487 Move to the next Wiki reference.
490 Move to the previous Wiki reference.
493 Complete the name of a page from the current project at point.
496 Insert a new list item at point, indenting properly.
499 Decrease the indentation of the list item at point.
502 Increase the indentation of the list item at point.
507 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
508 @comment node-name, next, previous, up
509 @chapter Rules for Using Markup
512 A Muse document uses special, contextual markup rules to determine how
513 to format the output result. For example, if a paragraph is indented,
514 Muse assumes it should be quoted.
516 There are not too many markup rules, and all of them strive to be as
517 simple as possible so that you can focus on document creation, rather
521 * Paragraphs:: Paragraphs: centering and quoting.
522 * Headings:: Levels of headings.
523 * Directives:: Directives at the beginning of a
525 * Emphasizing Text:: Bold, italicized, and underlined text.
526 * Footnotes:: Making notes to be shown at the end.
527 * Verse:: Indicating poetic stanzas.
528 * Lists:: Lists of items.
529 * Tables:: Generation of data tables.
530 * Explicit Links:: Hyperlinks and email addresses with
532 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
534 * Images:: Publishing and displaying images.
535 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
536 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
538 * Comments:: Lines to omit from published output.
539 * Tag Summary:: Tags that Muse recognizes.
542 @node Paragraphs, Headings, Markup Rules, Markup Rules
543 @comment node-name, next, previous, up
544 @section Paragraphs: centering and quoting
547 Paragraphs in Muse must be separated by a blank line.
549 @cindex paragraphs, centered
550 @subheading Centered paragraphs and quotations
552 A line that begins with six or more columns of whitespace (either tabs
553 or spaces) indicates a centered paragraph. Alternatively, you can use
554 the @verb{|<center>|} tag to surround regions that are to be published as
557 @cindex paragraphs, quoted
559 But if a line begins with whitespace, though less than six columns, it
560 indicates a quoted paragraph. Alternatively, you can use the
561 @verb{|<quote>|} tag to surround regions that are to be published as
565 @cindex monospace, rendering blocks
566 @cindex HTML, rendering blocks in monospace
567 @subheading Literal paragraphs
569 The @verb{|<example>|} tag is used for examples, where whitespace should
570 be preserved, the text rendered in monospace, and any characters special
571 to the output style escaped.
574 @cindex HTML, inserting a raw block
575 There is also the @verb{|<literal>|} tag, which causes a marked block to
576 be entirely left alone. This can be used for inserting a hand-coded
577 HTML blocks into HTML output, for example.
579 @node Headings, Directives, Paragraphs, Markup Rules
580 @comment node-name, next, previous, up
581 @section Levels of headings
584 A heading becomes a chapter or section in printed output -- depending on
585 the style. To indicate a heading, start a new paragraph with one or
586 more asterices, followed by a space and the heading title. Then begin
587 another paragraph to enter the text for that section.
589 All levels of headings will be published. Most publishing styles only
590 distinguish the between the first 4 levels, however.
602 @node Directives, Emphasizing Text, Headings, Markup Rules
603 @comment node-name, next, previous, up
604 @section Directives at the beginning of a document
607 Directives are lines beginning with the @samp{#} character that come
608 before any paragraphs or sections in the document. Directives are of
609 the form ``#directive content of directive''. You can use any
610 combination of uppercase and lowercase letters for directives, even if
611 the directive is not in the list below.
613 The @code{muse-publishing-directive} function may be used in header and
614 footer text to access directives. For example, to access the
615 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
617 The following is a list of directives that Muse uses.
622 The author of this document.
624 If this is not specified, Muse will attempt to figure it out from the
625 @code{user-full-name} variable.
629 The date that the document was last modified.
631 This is used by publishing styles that are able to embed the date
636 A short description of this document.
638 This is used by the @code{journal} publishing style to embed information
639 inside of an RSS/RDF feed.
643 The title of this document.
645 If this is not specified, the name of the file is used.
649 @node Emphasizing Text, Footnotes, Directives, Markup Rules
650 @comment node-name, next, previous, up
651 @section Bold, italicized, and underlined text
652 @cindex emphasizing text
653 @cindex underlining text
654 @cindex italicizing text
655 @cindex verbatim text
656 @cindex monospace, rendering words
658 To emphasize text, surround it with certain specially recognized
664 ***very strong emphasis***
666 =verbatim and monospace=
670 While editing a Muse document in Muse mode, these forms of emphasis will
671 be highlighted in a WYSIWYG manner. Each of these forms may span
674 Verbatim text will be colored as gray by default. To change this,
675 customize @code{muse-verbatim-face}.
677 You can also use the @verb{|<code>|} tag to indicate verbatim and
678 monospace text. This is handy for regions that have an ``='' in them.
680 @node Footnotes, Verse, Emphasizing Text, Markup Rules
681 @comment node-name, next, previous, up
682 @section Making notes to be shown at the end
685 A footnote reference is simply a number in square brackets. To define
686 the footnote, place this definition at the bottom of your file.
687 @samp{footnote-mode} can be used to greatly facilitate the creation of
688 these kinds of footnotes.
690 Footnotes are defined by the same number in brackets occurring at the
691 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
692 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
693 the point of insertion.
695 @node Verse, Lists, Footnotes, Markup Rules
696 @comment node-name, next, previous, up
697 @section Indicating poetic stanzas
701 Poetry requires that whitespace be preserved, but without resorting to
702 monospace. To indicate this, use the following markup, reminiscent of
706 > A line of Emacs verse;
707 > forgive its being so terse.
710 You can also use the @verb{|<verse>|} tag, if you prefer.
714 A line of Emacs verse;
715 forgive its being so terse.
719 @cindex verses, multiple stanzas
720 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
725 A line of Emacs verse;
726 forgive its being so terse.
728 In terms of terse verse,
733 @node Lists, Tables, Verse, Markup Rules
734 @comment node-name, next, previous, up
735 @section Lists of items
738 Lists are given using special characters at the beginning of a line.
739 Whitespace must occur before bullets or numbered items, to distinguish
740 from the possibility of those characters occurring in a real sentence.
742 @cindex lists, bullets
743 These are rendered as a bullet list.
750 @cindex lists, enumerated
751 An enumerated list follows.
758 @cindex lists, definitions
759 Here is a definition list.
763 This is a first definition
764 And it has two lines;
768 This is a second definition
771 @node Tables, Explicit Links, Lists, Markup Rules
772 @comment node-name, next, previous, up
773 @section Generation of data tables
776 @cindex tables, simple
777 Only very simple tables are supported. The syntax is as follows.
780 Double bars || Separate header fields
782 Single bars | Separate body fields
783 Here are more | body fields
785 Triple bars ||| Separate footer fields
788 Some publishing styles require header fields to come first, then footer
789 fields, and then the body fields. You can use any order for these
790 sections that you like, and Muse will re-order them for you at
793 If you wish to disable table generation for one Muse file, add the
794 directive @samp{#disable-tables t} to the top of the file.
796 @node Explicit Links, Implicit Links, Tables, Markup Rules
797 @comment node-name, next, previous, up
798 @section Hyperlinks and email addresses with descriptions
799 @cindex links, explicit
801 A hyperlink can reference a URL, or another page within a Muse
802 project. In addition, descriptive text can be specified, which should
803 be displayed rather than the link text in output styles that supports
804 link descriptions. The syntax is as follows.
807 [[link target][link description]]
808 [[link target without description]]
811 Thus, the current maintainer's homepage for Muse can be found
812 @samp{[[http://www.mwolson.org/projects/EmacsMuse.html][here]]},
813 or at @samp{[[http://www.mwolson.org/projects/EmacsMuse.html]]}.
815 @node Implicit Links, Images, Explicit Links, Markup Rules
816 @comment node-name, next, previous, up
817 @section Bare URLs, WikiNames, and InterWiki links
818 @cindex links, implicit
822 @cindex Email addresses
824 A URL or email address encountered in the input text is published as a
825 hyperlink. These kind of links are called @dfn{implicit links} because
826 they are not separated from the rest of the Muse document in any way.
828 Some characters in URLs will prevent Muse from recognizing them as
829 implicit links. If you want to link to a URL containing spaces or any of
830 the characters ``][,"'`()<>^'', you will have to make the link
831 explicit. The punctuation characters ``.,;:'' are also not recognized as
832 part of a URL when they appear at its end. For information on how to
833 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
834 addresses with descriptions}.
837 If the @command{muse-wiki} module is loaded, another form of implicit
838 link will be made available. WikiNames, which are typed in CamelCase,
839 are highlighted and published as links, provided that the file they
842 Customization of WikiName recognition may be accomplished by editing the
843 @code{muse-wiki-wikiword-regexp} option and subsequently running
844 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
845 If you use the Customize interface, the latter will be done
848 @cindex InterWiki links
849 @cindex inter-project links
850 The @command{muse-wiki} module also allows for InterWiki links. These
851 are similar to WikiWords, but they specify both the project and page of
852 a file. The names of your project entries in @code{muse-project-alist}
853 will be used as InterWiki names by default. Several examples follow.
856 Blog::DocumentingMuse
861 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
862 the project name, and @samp{DocumentingMuse} is the page name. In the
863 second example, @samp{#} is the interwiki delimiter. If the name of a
864 project occurs by itself in text, like the third case, it will be
865 colorized and published as a link to the default page of the given
868 Customization of interwiki links may be accomplished by editing the
869 @code{muse-wiki-interwiki-alist} option.
871 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
872 @comment node-name, next, previous, up
873 @section Publishing and displaying images
875 @cindex links, with images
876 @subheading Image links
878 Links to images may be used in either the target or the description, or
879 both. Thus, the following code will publish as a clickable image that
880 points to @url{http://www.mwolson.org/}.
883 [[http://www.mwolson.org/][/static/logos/site-logo.png]]
886 @cindex images, displaying
887 @cindex images, local
888 @subheading Displaying images in Muse mode
889 If a link to a locally-available image is encountered in the link
890 description, Muse mode will attempt to display it if your version of
893 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
894 by setting the @code{muse-colors-inline-images} option to @code{nil}.
896 The method for finding images may be altered by customizing the
897 @code{muse-colors-inline-image-method} option. One useful value for
898 this option is @code{muse-colors-use-publishing-directory}, which tells
899 Muse mode to look in the directory where the current file will be
900 published. The default is to look in the current directory. Relative
901 paths like @samp{../pics/} should work for either setting.
903 Eventually, it is hoped that Muse will be able to copy images from the a
904 ``source'' directory to a publishing directory by customizing
905 @code{muse-project-alist}, but this has not been implemented yet.
907 @cindex images, without descriptions
908 @cindex images, inlined
909 @subheading Publishing simple images
910 The following example will display correctly and publish correctly if a
911 @acronym{PNG} file called @file{TestLogo.png} exists in the
912 @file{../pics/} directory. If text is on the same line as the picture,
913 it will remain so in the output.
919 @cindex images, captions
920 @subheading Publishing images with captions
921 If you want to add a caption to an image, use the following syntax.
922 This will center the image (if the output format supports it) and add a
923 centered caption below the picture. Formats that do not support
924 centering the image will instead leave it against the left margin.
927 [[../pics/mycat.png][My cat Dexter]]
930 Images with captions may only occur in their own paragraphs, with no
931 text on the same line. Otherwise, the published output will not be
932 syntactically correct.
934 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
935 @comment node-name, next, previous, up
936 @section Inserting a horizontal line or anchor
938 @cindex horizontal rules
940 @subheading Horizontal Rules
942 Four or more dashes indicate a horizontal rule. Be sure to put blank
943 lines around it, or it will be considered part of the proceeding or
947 @cindex links, with target on same page
950 If you begin a line with "#anchor" -- where "anchor" can be any word
951 that doesn't contain whitespace -- it defines an anchor at that point
952 into the document. This point can be referenced using "page#anchor" as
953 the target in a Muse link.
955 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
956 @comment node-name, next, previous, up
957 @section Evaluating Emacs Lisp code in documents for extensibility
958 @cindex lisp, embedded
960 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
961 which is the only Muse tag supported in a style's header and footer
962 text. With the @verb{|<lisp>|} tag, you may generated whatever output
963 text you wish. The inserted output will get marked up, if the
964 @verb{|<lisp>|} tag appears within the main text of the document.
967 <lisp>(concat "This form gets " "inserted")</lisp>
970 @cindex lisp, and insert command
971 Note that you should not use the @code{insert} command within a set of
972 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
973 tags will be automatically inserted into the document.
975 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
976 @comment node-name, next, previous, up
977 @section Lines to omit from published output
979 @cindex publishing, omitting lines
981 Use the following syntax to indicate a comment. Comments will not be
985 ; Comment text goes here.
988 That is, only a semi-colon at the beginning of a line, followed by a
989 literal space, will cause that line to be treated as a comment.
991 @node Tag Summary, , Comments, Markup Rules
992 @comment node-name, next, previous, up
993 @section Tags that Muse recognizes
995 @cindex inserting files at publish time
996 @cindex publishing, including markup in headers and footers
997 @cindex publishing, inserting files
999 Muse has several built-in tags that may prove useful during publishing.
1000 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1001 Muse uses, as well as make your own tags.
1005 If a tag takes arguments, it will look like this, where ``tagname'' is
1006 the name of the tag.
1009 <tagname arg1="string1" arg2="string2">
1012 If you want the tag to look like it came straight from an XHTML
1013 document, you can alternatively do the following.
1016 <tagname arg1="string1" arg2="string2" />
1019 If a tag surrounds some text, it will look like this.
1022 <tagname>Some text</tagname>
1025 If a tag surrounds a large region, it will look like this.
1034 @subheading Tag listing
1036 This is the complete list of tags that Muse accepts, including those
1037 that were mentioned in previous sections.
1042 If publishing to HTML, surround the given text with a @verb{|<span>|}
1043 tag. It takes one argument called ``name'' that specifies the class
1044 attribute of the @verb{|<span>|} tag.
1046 If publishing to a different format, do nothing extra to the text.
1049 Treat the text surrounded by the tag as if they were enclosed in equal
1050 signs, that is, make it monospace.
1053 Run a command on the region, replacing the region with the result of the
1054 command. The command is specified with the ``interp'' argument. If no
1055 value for ``interp'' is given, pass the entire region to the shell.
1057 The ``markup'' argument controls how this section is marked up.
1059 If it is omitted, publish the region with the normal Muse rules.
1061 If "nil", do not mark up the region at all, but prevent Muse from
1062 further interpreting it.
1064 If "example", treat the region as if it was surrounded by the
1065 @verb{|<example>|} tag.
1067 If "verse", treat the region as if it was surrounded by the
1068 @verb{|<verse>|} tag, to preserve newlines.
1070 Otherwise, it should be the name of a function to call, with the buffer
1071 narrowed to the region.
1074 Treat the entire region as a comment. If the option
1075 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1076 publish it using the comment syntax of the current publishing style.
1079 Publish a Table of Contents. This will either be inserted in-place or
1080 at the beginning of the document, depending on your publishing style.
1081 It does not have a delimiting tag.
1083 By default, only 2 levels of headings will be included in the generated
1084 Table of Contents. To change this globally, customize the
1085 @var{muse-publish-contents-depth} option. To change this only for the
1086 current tag, use the ``depth'' argument.
1089 Publish the region in monospace, preserving the newlines in the region.
1090 This is useful for snippets of code.
1093 Insert the given file at the current location during publishing. The
1094 basic use of this tag is as follows, replacing ``included_file'' with
1095 the name of the file that you want to include.
1098 <include file="included_file">
1101 The ``markup'' argument controls how this section is marked up.
1103 If it is omitted, publish the included text with the normal Muse
1106 If "nil", do not mark up the included text at all.
1108 If "example", treat the included text as if it was surrounded by the
1109 @verb{|<example>|} tag.
1111 If "verse", treat the included text as if it was surrounded by the
1112 @verb{|<verse>|} tag, to preserve newlines.
1114 Otherwise, it should be the name of a function to call after inserting
1115 the file with the buffer narrowed to the section inserted.
1118 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1119 The result is then inserted into the document, so you do not need to
1120 explicitly call @code{insert}. All text properties are removed from the
1123 This tag takes the ``markup'' argument. See the description of
1124 @verb{|<command>|} for details.
1127 Make sure that the text enclosed by this tag is published without
1128 escaping it in any way. This is useful for inserting markup directly
1129 into the published document, when Muse does not provide the desired
1133 Mark up the text between the initial and ending tags. The markup
1134 command to use may be specified by the ``function'' argument. The
1135 standard Muse markup routines are used by default if no ``function''
1136 argument is provided.
1138 This is useful for marking up regions in headers and footers. One
1139 example that comes to mind is generating a published index of all of the
1140 files in the current project by doing the following.
1143 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1147 Run the @command{perl} language interpreter on the region, replacing the
1148 region with the result of the command.
1150 This tag takes the ``markup'' argument. See the description of
1151 @verb{|<command>|} for details.
1154 Run the @command{python} language interpreter on the region, replacing
1155 the region with the result of the command.
1157 This tag takes the ``markup'' argument. See the description of
1158 @verb{|<command>|} for details.
1161 Publish the region as a blockquote. This will either be inserted
1162 in-place or at the beginning of the document, depending on your
1163 publishing style. It does not have a delimiting tag.
1166 Run the @command{ruby} language interpreter on the region, replacing the
1167 region with the result of the command.
1169 This tag takes the ``markup'' argument. See the description of
1170 @verb{|<command>|} for details.
1173 This is used when you want to prevent Muse from trying to interpret some
1174 markup. Surround the markup in @verb{|<verbatim>|} and
1175 @verb{|</verbatim>|}, and it will not be interpreted.
1177 This tag was used often in previous versions of Muse because they did
1178 not support whole-document escaping of specials. Now, it will only be
1179 needed for other tags, and perhaps footnotes as well.
1182 Preserve the newlines in the region. In formats like HTML, newlines are
1183 removed by default, hence the need for this tag. In other publishing
1184 styles, this tag may cause the text to be indented slightly in a way
1185 that looks nice for poetry and prose.
1189 @node Publishing Styles, Extending Muse, Markup Rules, Top
1190 @comment node-name, next, previous, up
1191 @chapter Publishing Various Types of Documents
1192 @cindex publishing styles
1194 One of the principle features of Muse is the ability to publish a simple
1195 input text to a variety of different output styles. Muse also makes it
1196 easy to create new styles, or derive from an existing style.
1199 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1200 * Book:: Publishing entries into a compilation.
1201 * DocBook:: Publishing in DocBook XML form.
1202 * HTML:: Publishing in HTML or XHTML form.
1203 * Journal:: Keeping a journal or blog.
1204 * LaTeX:: Publishing LaTeX documents.
1205 * Poem:: Publish a poem to LaTex or PDF.
1206 * Texinfo:: Publish entries to Texinfo format or PDF.
1209 @node Blosxom, Book, Publishing Styles, Publishing Styles
1210 @comment node-name, next, previous, up
1211 @section Integrating Muse and pyblosxom.cgi
1212 @cindex blog, one-file-per-entry style
1214 The Blosxom publishing style publishes a tree of categorised files to a
1215 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1216 In other words, each blog entry corresponds with one file.
1219 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1220 * Blosxom Entries:: Format of a Blosxom entry and automation.
1221 * Blosxom Options:: Blosxom styles and options provided.
1224 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1225 @comment node-name, next, previous, up
1226 @subsection Other tools needed for the Blosxom style
1228 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1229 installed on a machine that you have upload access to.
1231 The following additional components are required in order to make the
1232 date of blog entries display as something sensible.
1236 A script to gather date directives from the entire blog tree into a
1237 single file. The file must associate a blog entry with a date.
1240 A plugin for (py)blosxom that reads this file.
1243 These 2 things are provided for @command{pyblosxom.cgi} in the
1244 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1245 former service, while @file{hardcodedates.py} provides the latter
1246 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1247 script will be found/written.
1249 Here is a sample listing from my @file{timestamps} file, which maps
1250 each file to a date. This can really be in any format, as long as your
1251 date-gathering script and your plugin can both understand it.
1254 2005-04-01-14-16 personal/paper_cranes
1255 2005-03-21 personal/spring_break_over
1256 2004-10-24 personal/finished_free_culture
1259 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1260 @file{getstamps.py}. Note that you will need to set the current
1261 directory to where your Muse files are, execute @file{getstamps.py}, and
1262 then move the generated timestamps file to your publishing directory.
1264 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1265 @comment node-name, next, previous, up
1266 @subsection Format of a Blosxom entry and automation
1268 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1269 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1270 plus whatever normal content is desired.
1272 The date directive is not used directly by @command{pyblosxom.cgi} or
1273 this program. You need to have the two additional items from the former
1274 section to make use of this feature.
1276 There is a function called @code{muse-blosxom-new-entry} that will
1277 automate the process of making a new blog entry. To make use of it, do
1282 Customize @code{muse-blosxom-base-directory} to the location that your
1283 blog entries are stored.
1286 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1287 use the following code to assign this function to @kbd{C-c p l'}.
1290 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1294 You should create your directory structure ahead of time under your base
1295 directory. These directories, which correspond with category names, may
1299 When you enter this key sequence, you will be prompted for the category
1300 of your entry and its title. Upon entering this information, a new file
1301 will be created that corresponds with the title, but in lowercase
1302 letters and having special characters converted to underscores. The
1303 title and date directives will be inserted automatically.
1306 @node Blosxom Options, , Blosxom Entries, Blosxom
1307 @comment node-name, next, previous, up
1308 @subsection Blosxom styles and options provided
1310 The following styles and options are available in the Blosxom publishing
1313 @subheading Styles provided
1317 @cindex publishing styles, blosxom-html
1319 Publish Blosxom entries in HTML form.
1321 @cindex publishing styles, blosxom-xhtml
1323 Publish Blosxom entries in XHTML form.
1327 @subheading Options provided
1331 @item muse-blosxom-extension
1332 Default file extension for publishing Blosxom files.
1334 @item muse-blosxom-header
1335 Header used for publishing Blosxom files.
1337 This may be text or a filename.
1339 @item muse-blosxom-footer
1340 Footer used for publishing Blosxom files.
1342 This may be text or a filename.
1344 @item muse-blosxom-base-directory
1345 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1347 This is the top-level directory where your blog entries may be found
1352 @node Book, DocBook, Blosxom, Publishing Styles
1353 @comment node-name, next, previous, up
1354 @section Publishing entries into a compilation
1356 This publishing style is used to output ``books'' in LaTeX or PDF
1359 Each page will become a separate chapter in the book, unless the style
1360 keyword @option{:nochapters} is used, in which case they are all run
1361 together as if one giant chapter.
1363 One way of publishing a book is to make a project for it, add the
1364 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1365 with a very specific @code{:include} value to specify some page whose
1366 contents will be checked for the values of @code{#title} and
1367 @code{#date}, and whose name will be used in the output file. Then to
1368 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1369 @kbd{C-c C-p} to trigger the publishing process. An example
1370 @code{muse-project-alist} for this method follows.
1373 (setq muse-project-alist
1374 '(("MyNotes" (:nochapters t ; do automatically add chapters
1375 :book-chapter "Computer Science"
1377 :book-chapter "Mathematics"
1379 :book-chapter "Emacs"
1381 :book-end t ; the rest will not be placed in the book
1382 "~/Notes" ; so we can find the notes-anthology page
1384 :force-publish ("index")
1387 :include "/notes-anthology[^/]*$"
1388 :path "~/public_html/notes")
1389 ;; other publishing styles for each directory go here,
1394 In this example, there would be a file called
1395 @file{~/Notes/notes-anthology.muse}, which would contain just the
1396 following. The resulting book would be published to
1397 @file{~/public_html/notes/notes-anthology.pdf}.
1400 #title My Technology Ramblings
1403 Another way is to call the @code{muse-book-publish-project} function
1404 manually, with a custom project entry. An example of this may be found
1405 in John Wiegley's configuration file at
1406 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
1409 @subheading Styles provided
1413 @cindex publishing styles, book-latex
1415 Publish a book in LaTeX form. The header and footer are different than
1416 the normal LaTeX publishing mode.
1418 @cindex publishing styles, book-pdf
1420 Publish a book in PDF form. The header and footer are different than
1421 the normal PDF publishing mode.
1425 @subheading Options provided
1429 @item muse-book-before-publish-hook
1430 A hook run in the book buffer before it is marked up.
1432 @item muse-book-after-publish-hook
1433 A hook run in the book buffer after it is marked up.
1435 @item muse-book-latex-header
1436 Header used for publishing books to LaTeX.
1438 This may be text or a filename.
1440 @item muse-book-latex-footer
1441 Footer used for publishing books to LaTeX.
1443 This may be text or a filename.
1447 @node DocBook, HTML, Book, Publishing Styles
1448 @comment node-name, next, previous, up
1449 @section Publishing in DocBook XML form
1451 This publishing style is used to generate DocBook XML files.
1453 @subheading Styles provided
1457 @cindex publishing styles, docbook
1462 @subheading Options provided
1466 @item muse-docbook-extension
1467 Default file extension for publishing DocBook XML files.
1469 @item muse-docbook-header
1470 Header used for publishing DocBook XML files.
1472 This may be text or a filename.
1474 @item muse-docbook-footer
1475 Footer used for publishing DocBook XML files.
1477 This may be text or a filename.
1479 @item muse-docbook-markup-regexps
1480 List of markup rules for publishing a Muse page to DocBook XML.
1482 @item muse-docbook-markup-functions
1483 An alist of style types to custom functions for that kind of text.
1485 @item muse-docbook-markup-strings
1486 Strings used for marking up text.
1488 These cover the most basic kinds of markup, the handling of which
1489 differs little between the various styles.
1491 @item muse-docbook-markup-specials
1492 A table of characters which must be represented specially.
1494 @item muse-docbook-encoding-default
1495 The default Emacs buffer encoding to use in published files.
1496 This will be used if no special characters are found.
1498 @item muse-docbook-charset-default
1499 The default DocBook XML charset to use if no translation is
1500 found in @code{muse-docbook-encoding-map}.
1502 @item muse-docbook-encoding-map
1503 An alist mapping emacs coding systems to appropriate DocBook charsets.
1504 Use the base name of the coding system (i.e. without the -unix).
1508 @node HTML, Journal, DocBook, Publishing Styles
1509 @comment node-name, next, previous, up
1510 @section Publishing in HTML or XHTML form
1512 This publishing style is capable of producing HTML or XHTML documents.
1514 @subheading Styles provided
1518 @cindex publishing styles, html
1520 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1523 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1527 @subheading Options provided
1529 If an HTML option does not have a corresponding XHTML option, it will
1530 be used for both of these publishing styles.
1534 @item muse-html-extension
1535 Default file extension for publishing HTML files.
1537 @item muse-xhtml-extension
1538 Default file extension for publishing XHTML files.
1540 @item muse-html-style-sheet
1541 Store your stylesheet definitions here.
1543 This is used in @code{muse-html-header}. You can put raw CSS in here or
1544 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1545 @verb{|<lisp>|} markup tags.
1547 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1550 @item muse-html-header
1551 Header used for publishing HTML files.
1553 This may be text or a filename.
1555 @item muse-html-footer
1556 Footer used for publishing HTML files.
1558 This may be text or a filename.
1560 @item muse-xhtml-header
1561 Header used for publishing XHTML files.
1563 This may be text or a filename.
1565 @item muse-xhtml-footer
1566 Footer used for publishing XHTML files.
1568 This may be text or a filename.
1570 @item muse-html-anchor-on-word
1571 When true, anchors surround the closest word.
1573 This allows you to select them in a browser (i.e. for pasting), but has
1574 the side-effect of marking up headers in multiple colors if your header
1575 style is different from your link style.
1577 @item muse-html-table-attributes
1578 The attribute to be used with HTML @verb{|<table>|} tags.
1580 If you want to make more-complicated tables in HTML, surround the HTML
1581 with the @verb{|literal|} tag, so that it does not get escaped.
1583 @item muse-html-markup-regexps
1584 List of markup rules for publishing a Muse page to HTML.
1586 @item muse-html-markup-functions
1587 An alist of style types to custom functions for that kind of text.
1589 @item muse-html-markup-strings
1590 Strings used for marking up text as HTML.
1592 These cover the most basic kinds of markup, the handling of which
1593 differs little between the various styles.
1595 @item muse-xhtml-markup-strings
1596 Strings used for marking up text as XHTML.
1598 These cover the most basic kinds of markup, the handling of which
1599 differs little between the various styles.
1601 @item muse-html-markup-tags
1602 A list of tag specifications, for specially marking up HTML.
1603 @xref{muse-publish-markup-tags}, for more information.
1605 @item muse-html-markup-specials
1606 A table of characters which must be represented specially. By default,
1607 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1609 @item muse-html-meta-http-equiv
1610 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1612 @item muse-html-meta-content-type
1613 The content type used for the HTML @verb{|<meta>|} tag.
1615 If you are striving for XHTML 1.1 compliance, you may want to change
1616 this to ``application/xhtml+xml''.
1618 @item muse-html-meta-content-encoding
1619 The charset to append to the HTML @verb{|<meta>|} tag.
1621 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1622 and determine the HTML charset from emacs's coding. If set to a string,
1623 this string will be used to force a particular charset.
1625 @item muse-html-charset-default
1626 The default HTML meta charset to use if no translation is found in
1627 @code{muse-html-encoding-map}.
1629 @item muse-html-encoding-default
1630 The default Emacs buffer encoding to use in published files.
1631 This will be used if no special characters are found.
1633 @item muse-html-encoding-map
1634 An alist mapping emacs coding systems to appropriate HTML charsets.
1635 Use the base name of the coding system (i.e. without the -unix).
1639 @node Journal, LaTeX, HTML, Publishing Styles
1640 @comment node-name, next, previous, up
1641 @section Keeping a journal or blog
1643 @cindex blog, journal style
1645 The module facilitates the keeping and publication of a journal. When
1646 publishing to HTML, it assumes the form of a web log, or blog.
1648 The input format for each entry is as follows.
1651 * 20040317: Title of entry
1656 "You know who you are. It comes down to a simple gut check: You
1657 either love what you do or you don't. Period." -- P. Bronson
1661 The "qotd", or Quote of the Day, is entirely optional. When generated
1662 to HTML, this entry is rendered as the following.
1666 <div class="entry-qotd">
1667 <h3>Quote of the Day:</h3>
1668 <p>"You know who you are. It comes down to a simple gut
1669 check: You either love what you do or you don't. Period."
1672 <div class="entry-body">
1673 <div class="entry-head">
1674 <div class="entry-date">
1675 <span class="date">March 17, 2004</span>
1677 <div class="entry-title">
1678 <h2>Title of entry</h2>
1681 <div class="entry-text">
1682 <p>Text for the entry.</p>
1688 The plurality of "div" tags makes it possible to display the entries in
1689 any form you wish, using a CSS style.
1691 Also, an .RDF file can be generated from your journal by publishing it
1692 with the "rdf" style. It uses the first two sentences of the first
1693 paragraph of each entry as its "description", and auto-generates tags
1694 for linking to the various entries.
1696 @subheading Styles provided
1700 @cindex publishing styles, journal-html
1702 Publish journal entries as an HTML document.
1704 @cindex publishing styles, journal-xhtml
1706 Publish journal entries as an XHTML document.
1708 @cindex publishing styles, journal-latex
1710 Publish journal entries as a LaTeX document.
1712 @cindex publishing styles, journal-pdf
1714 Publish journal entries as a PDF document.
1716 @cindex publishing styles, journal-book-latex
1717 @item journal-book-latex
1718 Publish journal entries as a LaTeX book.
1720 @cindex publishing styles, journal-book-pdf
1721 @item journal-book-pdf
1722 Publish journal entries as a PDF book.
1724 @cindex publishing styles, journal-rdf
1725 @cindex publishing styles, RSS 1.0
1727 Publish journal entries as an RDF file (RSS 1.0).
1729 @cindex publishing styles, journal-rss
1730 @cindex publishing styles, RSS 2.0
1732 Publish journal entries as an RSS file (RSS 2.0).
1736 @subheading Options provided
1740 @item muse-journal-heading-regexp
1741 A regexp that matches a journal heading.
1743 Paren group 1 is the ISO date, group 2 is the optional category, and
1744 group 3 is the optional heading for the entry.
1746 @item muse-journal-date-format
1747 Date format to use for journal entries.
1749 @item muse-journal-html-heading-regexp
1750 A regexp that matches a journal heading from an HTML document.
1752 Paren group 1 is the ISO date, group 2 is the optional category, and
1753 group 3 is the optional heading for the entry.
1755 @item muse-journal-html-entry-template
1756 Template used to publish individual journal entries as HTML.
1758 @item muse-journal-latex-section
1759 Template used to publish a LaTeX section.
1761 @item muse-journal-latex-subsection
1762 Template used to publish a LaTeX subsection.
1764 @item muse-journal-latex-markup-tags
1765 A list of tag specifications, for specially marking up LaTeX.
1767 @xref{muse-publish-markup-tags}, for more information.
1769 @item muse-journal-rdf-extension
1770 Default file extension for publishing RDF (RSS 1.0) files.
1772 @item muse-journal-rdf-base-url
1773 The base URL of the website referenced by the RDF file.
1775 @item muse-journal-rdf-header
1776 Header used for publishing RDF (RSS 1.0) files.
1778 This may be text or a filename.
1780 @item muse-journal-rdf-footer
1781 Footer used for publishing RDF (RSS 1.0) files.
1783 This may be text or a filename.
1785 @item muse-journal-rdf-date-format
1786 Date format to use for RDF entries.
1788 @item muse-journal-rdf-entry-template
1789 Template used to publish individual journal entries as RDF.
1791 @item muse-journal-rdf-summarize-entries
1792 If non-nil, include only summaries in the RDF file, not the full data.
1794 @item muse-journal-rss-extension
1795 Default file extension for publishing RSS 2.0 files.
1797 @item muse-journal-rss-base-url
1798 The base URL of the website referenced by the RSS file.
1800 @item muse-journal-rss-header
1801 Header used for publishing RSS 2.0 files.
1803 This may be text or a filename.
1805 @item muse-journal-rss-footer
1806 Footer used for publishing RSS 2.0 files.
1808 This may be text or a filename.
1810 @item muse-journal-rss-date-format
1811 Date format to use for RSS 2.0 entries.
1813 @item muse-journal-rss-entry-template
1814 Template used to publish individual journal entries as RSS 2.0.
1816 @item muse-journal-rss-enclosure-types-alist
1817 File types that are accepted as RSS enclosures.
1819 This is an alist that maps file extension to content type.
1821 Useful for podcasting.
1823 @item muse-journal-rss-summarize-entries
1824 If non-nil, include only summaries in the RSS file, not the full data.
1826 Many RSS subscribers find this annoying.
1828 @item muse-journal-rss-markup-regexps
1829 List of markup rules for publishing a Muse journal page to RSS.
1831 For more information on the structure of this list,
1832 @xref{muse-publish-markup-regexps}.
1834 @item muse-journal-rss-markup-functions
1835 An alist of style types to custom functions for that kind of text.
1837 For more on the structure of this list,
1838 @xref{muse-publish-markup-functions}.
1842 @node LaTeX, Poem, Journal, Publishing Styles
1843 @comment node-name, next, previous, up
1844 @section Publishing LaTeX documents
1846 This publishing style is capable of producing LaTeX or PDF documents.
1848 If you wish to publish PDF documents, you will need to have a good TeX
1849 installation. For Debian and Ubuntu, this can be accomplished by
1850 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
1853 @subheading Styles provided
1857 @cindex publishing styles, latex
1859 Publish a LaTeX document.
1861 @cindex publishing styles, pdf
1863 Publish a PDF document, using an external LaTeX document conversion
1866 @cindex publishing styles, latexcjk
1868 Publish a LaTeX document with CJK (Chinese) encodings.
1870 @cindex publishing styles, pdfcjk
1872 Publish a PDF document with CJK (Chinese) encodings, using an external
1873 LaTeX document conversion tool.
1877 @subheading Options provided
1881 @item muse-latex-extension
1882 Default file extension for publishing LaTeX files.
1884 @item muse-latex-pdf-extension
1885 Default file extension for publishing LaTeX files to PDF.
1887 @item muse-latex-header
1888 Header used for publishing LaTeX files.
1890 This may be text or a filename.
1892 @item muse-latex-footer
1893 Footer used for publishing LaTeX files.
1895 This may be text or a filename.
1897 @item muse-latexcjk-header
1898 Header used for publishing LaTeX files (CJK).
1900 This may be text or a filename.
1902 @item muse-latexcjk-footer
1903 Footer used for publishing LaTeX files (CJK).
1905 This may be text or a filename.
1907 @item muse-latex-markup-regexps
1908 List of markup regexps for identifying regions in a Muse page.
1910 For more on the structure of this list,
1911 @xref{muse-publish-markup-regexps}.
1913 @item muse-latex-markup-functions
1914 An alist of style types to custom functions for that kind of text.
1916 For more on the structure of this list,
1917 @xref{muse-publish-markup-functions}.
1919 @item muse-latex-markup-strings
1920 Strings used for marking up text.
1922 These cover the most basic kinds of markup, the handling of which
1923 differs little between the various styles.
1925 @item muse-latexcjk-encoding-map
1926 An alist mapping emacs coding systems to appropriate CJK codings.
1927 Use the base name of the coding system (ie, without the -unix).
1929 @item muse-latexcjk-encoding-default
1930 The default Emacs buffer encoding to use in published files.
1932 This will be used if no special characters are found.
1934 @item muse-latex-markup-specials-example
1935 A table of characters which must be represented specially.
1936 These are applied to @verb{|example>|} regions.
1938 With the default interpretation of @verb{|<example>|} regions, no
1939 specials need to be escaped.
1941 @item muse-latex-markup-specials-document
1942 A table of characters which must be represented specially.
1943 These are applied to the entire document, sans already-escaped
1946 @item muse-latex-markup-specials-literal
1947 A table of characters which must be represented specially.
1948 This applies to =monospaced text= and @verb{|<code>|} regions.
1950 @item muse-latex-markup-specials-url
1951 A table of characters which must be represented specially.
1952 These are applied to URLs.
1954 @item muse-latex-permit-contents-tag
1955 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
1958 Most of the time, it is best to have a table of contents on the
1959 first page, with a new page immediately following. To make this
1960 work with documents published in both HTML and LaTeX, we need to
1961 ignore the @verb{|<contents>|} tag.
1963 If you don't agree with this, then set this option to non-nil,
1964 and it will do what you expect.
1968 @node Poem, Texinfo, LaTeX, Publishing Styles
1969 @comment node-name, next, previous, up
1970 @section Publish a poem to LaTex or PDF
1972 The @code{muse-poem} module makes it easy to attractively publish and
1973 reference poems in the following format, using the "memoir" module for
1974 LaTeX publishing. It will also markup poems for every other output
1975 style, though none are nearly as pretty.
1984 Annotations, history, notes, etc.
1987 Once a poem is written in this format, just publish it to PDF using the
1988 @code{poem-pdf} style. To make an inlined reference to a poem that
1989 you've written -- for example, from a blog page -- there is a "poem" tag
1990 defined by this module.
1993 <poem title="name.of.poem.page">
1996 Let's assume the template above was called @file{name.of.poem.page};
1997 then the above tag would result in this inclusion.
2005 John Wiegley uses this module for publishing all of the poems on his
2006 website, which are at
2007 @uref{http://www.newartisans.com/johnw/poems.html}.
2009 @subheading Styles provided
2013 @cindex publishing styles, poem-latex
2015 Publish a poem in LaTeX form.
2017 @cindex publishing styles, poem-pdf
2019 Publish a poem to a PDF document.
2021 @cindex publishing styles, chapbook-latex
2022 @item chapbook-latex
2023 Publish a book of poems in LaTeX form.
2025 @cindex publishing styles, chapbook-pdf
2027 Publish a book of poems to a PDF document.
2031 @subheading Options provided
2035 @item muse-poem-latex-header
2036 Header used for publishing LaTeX poems.
2038 This may be text or a filename.
2040 @item muse-poem-latex-footer
2041 Footer used for publishing LaTeX files.
2043 This may be text or a filename.
2045 @item muse-poem-markup-strings
2046 Strings used for marking up poems.
2048 These cover the most basic kinds of markup, the handling of which
2049 differs little between the various styles.
2051 @item muse-chapbook-latex-header
2052 Header used for publishing a book of poems in LaTeX form.
2054 This may be text or a filename.
2056 @item muse-chapbook-latex-footer
2057 Footer used for publishing a book of poems in LaTeX form.
2059 This may be text or a filename.
2061 @item muse-poem-chapbook-strings
2062 Strings used for marking up books of poems.
2064 These cover the most basic kinds of markup, the handling of which
2065 differs little between the various styles.
2069 @node Texinfo, , Poem, Publishing Styles
2070 @comment node-name, next, previous, up
2071 @section Publish entries to Texinfo format or PDF
2073 Rules for publishing a Muse file as a Texinfo article.
2075 @subheading Styles provided
2079 @cindex publishing styles, texi
2081 Publish a file in Texinfo form.
2083 @cindex publishing styles, texi
2085 Generate an Info file from a Muse file.
2087 @cindex publishing styles, info-pdf
2089 Publish a file in PDF form.
2093 @subheading Options provided
2097 @item muse-texinfo-process-natively
2098 If non-nil, use the Emacs `texinfmt' module to make Info files.
2100 @item muse-texinfo-extension
2101 Default file extension for publishing Texinfo files.
2103 @item muse-texinfo-info-extension
2104 Default file extension for publishing Info files.
2106 @item muse-texinfo-pdf-extension
2107 Default file extension for publishing PDF files.
2109 @item muse-texinfo-header
2110 Text to prepend to a Muse page being published as Texinfo.
2112 This may be text or a filename.
2113 It may contain @verb{|<lisp>|} markup tags.
2115 @item muse-texinfo-footer
2116 Text to append to a Muse page being published as Texinfo.
2118 This may be text or a filename.
2119 It may contain @verb{|<lisp>|} markup tags.
2121 @item muse-texinfo-markup-regexps
2122 List of markup rules for publishing a Muse page to Texinfo.
2124 For more on the structure of this list,
2125 @xref{muse-publish-markup-regexps}.
2127 @item muse-texinfo-markup-functions
2128 An alist of style types to custom functions for that kind of text.
2130 For more on the structure of this list, see
2131 @xref{muse-publish-markup-functions}.
2133 @item muse-texinfo-markup-strings
2134 Strings used for marking up text.
2136 These cover the most basic kinds of markup, the handling of which
2137 differs little between the various styles.
2139 @item muse-texinfo-markup-specials
2140 A table of characters which must be represented specially.
2145 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
2146 @comment node-name, next, previous, up
2147 @chapter Making your own publishing styles
2150 * Common Elements:: Common functionality shared by styles.
2151 * Deriving Styles:: Deriving a new style from an existing
2155 @node Common Elements, Deriving Styles, , Extending Muse
2156 @comment node-name, next, previous, up
2157 @section Common functionality shared by styles
2158 @cindex publishing styles, common
2161 * Markup Functions:: Specifying functions to marking up text.
2162 * Markup Regexps:: Markup rules for publishing.
2163 * Markup Strings:: Strings specific to a publishing style.
2164 * Markup Tags:: Tag specifications for special markup.
2165 * Style Elements:: Parameters used for defining styles.
2168 @node Markup Functions, Markup Regexps, , Common Elements
2169 @comment node-name, next, previous, up
2170 @subsection Specifying functions to mark up text
2171 @cindex publishing, markup functions
2173 @anchor{muse-publish-markup-functions}
2174 @code{muse-publish-markup-functions}
2176 An alist of style types to custom functions for that kind of text.
2178 This is used by publishing styles to attempt to minimize the amount of
2179 custom regexps that each has to define. @file{muse-publish} provides
2180 rules for the most common types of markup.
2182 Each member of the list is of the following form.
2190 Describes the type of text to associate with this rule.
2191 @code{muse-publish-markup-regexps} maps regexps to these symbols.
2194 Function to use to mark up this kind of rule if no suitable function is
2195 found through the @option{:functions} tag of the current style.
2198 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
2199 @comment node-name, next, previous, up
2200 @subsection Markup rules for publishing
2201 @cindex publishing, markup regexps
2202 @cindex publishing, rules
2204 @anchor{muse-publish-markup-regexps}
2205 @code{muse-publish-markup-regexps}
2207 List of markup rules for publishing a page with Muse.
2209 The rules given in this variable are invoked first, followed by whatever
2210 rules are specified by the current style.
2212 Each member of the list is either a function, or a list of the following
2216 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
2221 A regular expression, or symbol whose value is a regular expression,
2222 which is searched for using `re-search-forward'.
2224 @item TEXT-BEGIN-GROUP
2225 The matching group within that regexp which denotes the beginning of the
2226 actual text to be marked up.
2228 @item REPLACEMENT-TEXT
2229 A string that will be passed to `replace-match'.
2231 If it is not a string, but a function, it will be called to determine
2232 what the replacement text should be (it must return a string). If it is
2233 a symbol, the value of that symbol should be a string.
2236 The replacements are done in order, one rule at a time. Writing
2237 the regular expressions can be a tricky business. Note that case
2238 is never ignored. `case-fold-search' is always bound to nil
2239 while processing the markup rules.
2241 @subheading Publishing order
2243 This is the order that the publishing rules are consulted, by default.
2244 This may be changed by customizing @code{muse-publish-markup-regexps}.
2248 @item trailing and leading whitespace
2249 Remove trailing and leading whitespace from a file.
2254 This is only recognized at the beginning of a file.
2265 @item explicit links
2266 Prevent emphasis characters in explicit links from being marked up.
2268 Don't actually publish them here, just add a special no-emphasis text
2272 Whitespace-delimited word, possibly with emphasis characters
2274 This function is responsible for marking up emphasis and escaping some
2285 Outline-mode style headings.
2290 These are ellipses with a dot at end.
2300 Horizontal rule or section separator.
2305 beginning of footnotes section
2310 Footnote definition or reference. If at beginning of line, it is a
2325 Numbered list, item list, or term definition list.
2328 spaces before beginning of text
2336 @samp{table | cells}
2339 @samp{[[explicit][links]]}
2342 @samp{http://example.com/}
2345 @samp{bare-email@@example.com}
2349 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
2350 @comment node-name, next, previous, up
2351 @subsection Strings specific to a publishing style
2352 @cindex publishing, markup strings
2354 @dfn{Markup strings} are strings used for marking up text for a
2357 These cover the most basic kinds of markup, the handling of which
2358 differs little between the various styles.
2360 @subheading Available markup strings
2364 @item image-with-desc
2365 An image and a description.
2367 Argument 1: image without extension. Argument 2: image extension.
2368 Argument 3: description.
2373 Argument 1: image without extension. Argument 2: image extension.
2378 Argument 1: link. Argument 2: image without extension.
2379 Argument 3: image extension.
2382 A reference to an anchor on the current page.
2384 Argument 1: anchor name. Argument 2: description if one exists, or the
2385 original link otherwise.
2388 A URL without a description.
2393 A link with a description.
2395 Argument 1: link. Argument 2: description if one exists, or the
2396 original link otherwise.
2398 @item link-and-anchor
2399 A link to a page with an anchor, and a description.
2401 Argument 1: link. Argument 2: anchor name.
2402 Argument 3: description if one exists, or the original link otherwise.
2405 A link to an email address.
2407 Argument 1: email address. Argument 2: email address.
2412 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
2415 Beginning of a comment.
2421 A horizontal line or space.
2423 @item no-break-space
2424 A space that separates two words which are not to be separated.
2427 Beginning of footnote.
2433 Mark a reference for the current footnote.
2435 Argument 1: number of this footnote.
2437 @item footnotemark-end
2438 End of a reference for the current footnote.
2441 Indicate the text of the current footnote.
2443 Argument 1: number of this footnote.
2445 @item footnotetext-end
2446 End of a footnote text line.
2449 Text used to replace ``Footnotes:'' line.
2458 Beginning of a part indicator line. This is used by book publishing.
2461 End of a part indicator line. This is used by book publishing.
2464 Beginning of a chapter indicator line. This is used by book publishing.
2467 End of a chapter indicator line. This is used by book publishing.
2470 Beginning of level 1 section indicator line.
2472 Argument 1: level of section; always 1.
2475 End of level 1 section indicator line.
2477 Argument 1: level of section; always 1.
2480 Beginning of level 2 section indicator line.
2482 Argument 1: level of section; always 2.
2484 @item subsection-end
2485 End of level 2 section indicator line.
2487 Argument 1: level of section; always 2.
2490 Beginning of level 3 section indicator line.
2492 Argument 1: level of section; always 3.
2494 @item subsubsection-end
2495 End of level 3 section indicator line.
2497 Argument 1: level of section; always 3.
2500 Beginning of section indicator line, where level is greater than 3.
2502 Argument 1: level of section.
2504 @item section-other-end
2505 End of section indicator line, where level is greater than 3.
2507 Argument 1: level of section.
2509 @item begin-underline
2510 Beginning of underlined text.
2513 End of underlined text.
2516 Beginning of verbatim text. This includes @verb{|<code>|} tags and
2520 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2524 Beginning of the first level of emphasized text.
2527 End of the first level of emphasized text.
2529 @item begin-more-emph
2530 Beginning of the second level of emphasized text.
2533 End of the second level of emphasized text.
2535 @item begin-most-emph
2536 Beginning of the third (and final) level of emphasized text.
2539 End of the third (and final) level of emphasized text.
2542 Beginning of verse text.
2545 String used to each space that is further indented than the beginning of
2548 @item begin-verse-line
2549 Beginning of a line of verse.
2551 @item empty-verse-line
2552 End of a line of verse.
2554 @item begin-last-stanza-line
2555 Beginning of the last line of a verse stanza.
2557 @item end-last-stanza-line
2558 End of the last line of a verse stanza.
2564 Beginning of an example region. To make use of this, an
2565 @samp{<example>} tag is needed.
2568 End of an example region. To make use of this, an @samp{</example>} tag
2572 Begin a centered line.
2575 End a centered line.
2578 Begin a quoted region.
2581 End a quoted region.
2584 Begin an unordered list.
2587 End an unordered list.
2589 @item begin-uli-item
2590 Begin an unordered list item.
2593 End an unordered list item.
2596 Begin an ordered list.
2599 End an ordered list.
2601 @item begin-oli-item
2602 Begin an ordered list item.
2605 End an ordered list item.
2608 Begin a definition list.
2611 End a definition list.
2614 Begin a definition list item.
2617 End a definition list item.
2620 Begin a definition list term.
2623 End a definition list term.
2626 Begin a definition list entry.
2629 End a definition list entry.
2637 @item begin-table-group
2638 Begin a table grouping.
2640 @item end-table-group
2641 End a table grouping.
2643 @item begin-table-row
2649 @item begin-table-entry
2650 Begin a table entry.
2652 @item end-table-entry
2657 @node Markup Tags, Style Elements, Markup Strings, Common Elements
2658 @comment node-name, next, previous, up
2659 @subsection Tag specifications for special markup
2660 @cindex publishing, markup tags
2662 @anchor{muse-publish-markup-tags}
2663 @code{muse-publish-markup-tags}
2665 A list of tag specifications, for specially marking up text.
2667 XML-style tags are the best way to add custom markup to Muse. This is
2668 easily accomplished by customizing this list of markup tags.
2670 For each entry, the name of the tag is given, whether it expects a
2671 closing tag and/or an optional set of attributes, whether it is
2672 nestable, and a function that performs whatever action is desired within
2673 the delimited region.
2675 The tags themselves are deleted during publishing, before the function
2676 is called. The function is called with three arguments, the beginning
2677 and end of the region surrounded by the tags. If properties are
2678 allowed, they are passed as a third argument in the form of an alist.
2679 The `end' argument to the function is always a marker.
2681 Point is always at the beginning of the region within the tags, when the
2682 function is called. Wherever point is when the function finishes is
2683 where tag markup will resume.
2685 These tag rules are processed once at the beginning of markup, and once
2686 at the end, to catch any tags which may have been inserted in-between.
2688 @node Style Elements, , Markup Tags, Common Elements
2689 @comment node-name, next, previous, up
2690 @subsection Parameters used for defining styles
2691 @cindex publishing, style elements
2693 Style elements are tags that define a style. Use
2694 @code{muse-define-style} to create a new style.
2697 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2700 @subheading Usable elements
2705 File extension to use for publishing files with this style.
2708 File extension to use for publishing links to Muse files with this
2712 File extension to use for publishing second-stage files with this style.
2714 For example, PDF publishing generates a LaTeX file first, then a PDF
2715 from that LaTeX file.
2718 List of markup rules for publishing a page with Muse.
2719 @xref{muse-publish-markup-regexps}.
2722 An alist of style types to custom functions for that kind of text.
2723 @xref{muse-publish-markup-functions}.
2726 Strings used for marking up text with this style.
2728 These cover the most basic kinds of markup, the handling of which
2729 differs little between the various styles.
2732 A list of tag specifications, used for handling extra tags.
2733 @xref{muse-publish-markup-tags}.
2736 A table of characters which must be represented specially.
2739 A function that is to be executed on the newly-created publishing buffer
2740 (or the current region) before any publishing occurs.
2742 This is used to set extra parameters that direct the publishing process.
2745 A function that is to be executed on the publishing buffer (or the
2746 current region) immediately after applying all of the markup regexps.
2748 This is used to fix the order of table elements (header, footer, body)
2752 A function that is to be executed on the publishing buffer after
2753 :before-end, and immediately after inserting the header and footer.
2755 This is used for generating the table of contents as well as setting the
2759 A function that is to be executed after saving the published file, but
2760 while still in its buffer.
2762 This is used for generating second-stage documents like PDF files from
2763 just-published LaTeX files.
2766 Header used for publishing files of this style.
2768 This may be a variable, text, or a filename. It is inserted at the
2769 beginning of a file, after evaluating the publishing markup.
2772 Footer used for publishing files of this style.
2774 This may be a variable, text, or a filename. It is inserted at the end
2775 of a file, after evaluating the publishing markup.
2778 Style sheet used for publishing files of this style.
2780 This may be a variable or text. It is used in the header of HTML and
2781 XHTML based publishing styles.
2784 The function used to browse the published result of files of this style.
2788 @node Deriving Styles, , Common Elements, Extending Muse
2789 @comment node-name, next, previous, up
2790 @section Deriving a new style from an existing one
2791 @cindex publishing styles, deriving
2793 To create a new style from an existing one, use @code{muse-derive-style}
2794 as follows. This is a good way to fix something you don't like about a
2795 particular publishing style, or to personalize it.
2798 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2801 The derived name is a string defining the new style, such as "my-html".
2802 The base name must identify an existing style, such as "html" -- if you
2803 have loaded @file{muse-html}. The style parameters are the same as
2804 those used to create a style, except that they override whatever
2805 definitions exist in the base style. However, some definitions only
2806 partially override. The following parameters support partial
2809 @xref{Style Elements}, for a complete list of all parameters.
2814 If a markup function is not found in the derived style's function list,
2815 the base style's function list will be queried.
2818 All regexps in the current style and the base style(s) will be used.
2821 If a markup string is not found in the derived style's string list, the
2822 base style's string list will be queried.
2827 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
2828 @comment node-name, next, previous, up
2829 @chapter Getting Help and Reporting Bugs
2830 @cindex help, getting
2831 @cindex bugs, reporting
2833 After you have read this guide, if you still have questions about
2834 Muse, or if you have bugs to report, there are several places you can
2840 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
2841 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2845 @uref{http://www.mwolson.org/projects/EmacsMuse.html} is the web page
2846 that Michael Olson (the current maintainer) made for Muse.
2849 Muse has four mailing lists.
2853 @item muse-el-announce
2854 Low-traffic list for Muse-related announcements.
2856 You can join this mailing list (@email{muse-el-announce@@gna.org})
2857 using the subscription form at
2858 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
2859 mailing list is also available via Gmane (@url{http://gmane.org/}). The
2860 group is called @samp{gmane.emacs.muse.announce}.
2862 @item muse-el-discuss
2863 Discussion, bugfixes, suggestions, tips, and the like for Muse.
2864 This mailing list also includes the content of muse-el-announce.
2866 You can join this mailing list (@email{muse-el-discuss@@gna.org})
2867 using the subscription form at
2868 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
2869 list is also available via Gmane with the identifier
2870 @samp{gmane.emacs.muse.general}.
2872 @item muse-el-commits
2873 Log messages for changes committed to Muse.
2875 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
2876 the subscription form at
2877 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
2878 is also available via Gmane with the identifier
2879 @samp{gmane.emacs.muse.cvs}.
2881 @item muse-el-internationalization
2882 Discussion of translation of the Muse website and documentation into
2885 You can join this mailing list
2886 (@email{muse-el-internationalization@@gna.org}) using the subscription
2887 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
2888 mailing list is also available via Gmane with the identifier
2889 @samp{gmane.emacs.muse.internationalization}.
2894 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2895 contributors are frequently around and willing to answer your
2896 questions. The @samp{#muse} channel is also available for
2897 Muse-specific help, and its current maintainer hangs out there.
2900 The maintainer of Emacs Muse, Michael Olson, may be contacted at
2901 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
2902 it is often better to use the muse-el-discuss mailing list.
2906 @node History, Contributors, Getting Help and Reporting Bugs, Top
2907 @comment node-name, next, previous, up
2908 @chapter History of This Document
2909 @cindex history, of Muse
2913 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2914 limitations. Around February 2004, he started making "emacs-wiki version
2915 3.00 APLHA", which eventually became known as Muse.
2917 Most of those who frequent the emacs-wiki mailing list continued to use
2918 emacs-wiki, mainly because Planner hasn't been ported over to it.
2920 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2921 John Wiegley's request.
2924 Michael Olson overhauled this document and added many new sections in
2925 preparation for the first release of Muse (3.01).
2929 @node Contributors, GNU Free Documentation License, History, Top
2930 @comment node-name, next, previous, up
2931 @chapter Contributors to This Documentation
2932 @cindex contributors
2934 The first draft of this document was taken from the emacs-wiki texinfo
2935 manual. Michael Olson adapted it for Muse and added most of its
2938 John Sullivan did a majority of the work on the emacs-wiki texinfo
2941 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2942 emacs-wiki texinfo manual.
2945 @include doclicense.texi
2948 @node Concept Index, , GNU Free Documentation License, Top
2949 @comment node-name, next, previous, up