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 "src", treat the included text as if it was surrounded by the
1068 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1071 If "verse", treat the region as if it was surrounded by the
1072 @verb{|<verse>|} tag, to preserve newlines.
1074 Otherwise, it should be the name of a function to call, with the buffer
1075 narrowed to the region.
1078 Treat the entire region as a comment. If the option
1079 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1080 publish it using the comment syntax of the current publishing style.
1083 Publish a Table of Contents. This will either be inserted in-place or
1084 at the beginning of the document, depending on your publishing style.
1085 It does not have a delimiting tag.
1087 By default, only 2 levels of headings will be included in the generated
1088 Table of Contents. To change this globally, customize the
1089 @var{muse-publish-contents-depth} option. To change this only for the
1090 current tag, use the ``depth'' argument.
1093 Publish the region in monospace, preserving the newlines in the region.
1094 This is useful for snippets of code.
1097 Insert the given file at the current location during publishing. The
1098 basic use of this tag is as follows, replacing ``included_file'' with
1099 the name of the file that you want to include.
1102 <include file="included_file">
1105 The ``markup'' argument controls how this section is marked up.
1107 If it is omitted, publish the included text with the normal Muse
1110 If "nil", do not mark up the included text at all.
1112 If "example", treat the included text as if it was surrounded by the
1113 @verb{|<example>|} tag.
1115 If "src", treat the included text as if it was surrounded by the
1116 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1119 If "verse", treat the included text as if it was surrounded by the
1120 @verb{|<verse>|} tag, to preserve newlines.
1122 Otherwise, it should be the name of a function to call after inserting
1123 the file with the buffer narrowed to the section inserted.
1126 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1127 The result is then inserted into the document, so you do not need to
1128 explicitly call @code{insert}. All text properties are removed from the
1131 This tag takes the ``markup'' argument. See the description of
1132 @verb{|<command>|} for details.
1135 Make sure that the text enclosed by this tag is published without
1136 escaping it in any way. This is useful for inserting markup directly
1137 into the published document, when Muse does not provide the desired
1141 Mark up the text between the initial and ending tags. The markup
1142 command to use may be specified by the ``function'' argument. The
1143 standard Muse markup routines are used by default if no ``function''
1144 argument is provided.
1146 This is useful for marking up regions in headers and footers. One
1147 example that comes to mind is generating a published index of all of the
1148 files in the current project by doing the following.
1151 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1155 Run the @command{perl} language interpreter on the region, replacing the
1156 region with the result of the command.
1158 This tag takes the ``markup'' argument. See the description of
1159 @verb{|<command>|} for details.
1162 Run the @command{python} language interpreter on the region, replacing
1163 the region with the result of the command.
1165 This tag takes the ``markup'' argument. See the description of
1166 @verb{|<command>|} for details.
1169 Publish the region as a blockquote. This will either be inserted
1170 in-place or at the beginning of the document, depending on your
1171 publishing style. It does not have a delimiting tag.
1174 Run the @command{ruby} language interpreter on the region, replacing the
1175 region with the result of the command.
1177 This tag takes the ``markup'' argument. See the description of
1178 @verb{|<command>|} for details.
1181 Publish the region using htmlize.
1182 The language to use may be specified by the ``lang'' attribute.
1184 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1185 the value of the ``lang'' attribute.
1187 This tag requires htmlize 1.34 or later in order to work. If this is
1188 not satisfied, or the current publishing style is not HTML-based, Muse
1189 will publish the region like an @verb{|<example>|} tag.
1192 This is used when you want to prevent Muse from trying to interpret some
1193 markup. Surround the markup in @verb{|<verbatim>|} and
1194 @verb{|</verbatim>|}, and it will not be interpreted.
1196 This tag was used often in previous versions of Muse because they did
1197 not support whole-document escaping of specials. Now, it will only be
1198 needed for other tags, and perhaps footnotes as well.
1201 Preserve the newlines in the region. In formats like HTML, newlines are
1202 removed by default, hence the need for this tag. In other publishing
1203 styles, this tag may cause the text to be indented slightly in a way
1204 that looks nice for poetry and prose.
1208 @node Publishing Styles, Extending Muse, Markup Rules, Top
1209 @comment node-name, next, previous, up
1210 @chapter Publishing Various Types of Documents
1211 @cindex publishing styles
1213 One of the principle features of Muse is the ability to publish a simple
1214 input text to a variety of different output styles. Muse also makes it
1215 easy to create new styles, or derive from an existing style.
1218 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1219 * Book:: Publishing entries into a compilation.
1220 * DocBook:: Publishing in DocBook XML form.
1221 * HTML:: Publishing in HTML or XHTML form.
1222 * Journal:: Keeping a journal or blog.
1223 * LaTeX:: Publishing LaTeX documents.
1224 * Poem:: Publish a poem to LaTex or PDF.
1225 * Texinfo:: Publish entries to Texinfo format or PDF.
1228 @node Blosxom, Book, Publishing Styles, Publishing Styles
1229 @comment node-name, next, previous, up
1230 @section Integrating Muse and pyblosxom.cgi
1231 @cindex blog, one-file-per-entry style
1233 The Blosxom publishing style publishes a tree of categorised files to a
1234 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1235 In other words, each blog entry corresponds with one file.
1238 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1239 * Blosxom Entries:: Format of a Blosxom entry and automation.
1240 * Blosxom Options:: Blosxom styles and options provided.
1243 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1244 @comment node-name, next, previous, up
1245 @subsection Other tools needed for the Blosxom style
1247 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1248 installed on a machine that you have upload access to.
1250 The following additional components are required in order to make the
1251 date of blog entries display as something sensible.
1255 A script to gather date directives from the entire blog tree into a
1256 single file. The file must associate a blog entry with a date.
1259 A plugin for (py)blosxom that reads this file.
1262 These 2 things are provided for @command{pyblosxom.cgi} in the
1263 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1264 former service, while @file{hardcodedates.py} provides the latter
1265 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1266 script will be found/written.
1268 Here is a sample listing from my @file{timestamps} file, which maps
1269 each file to a date. This can really be in any format, as long as your
1270 date-gathering script and your plugin can both understand it.
1273 2005-04-01-14-16 personal/paper_cranes
1274 2005-03-21 personal/spring_break_over
1275 2004-10-24 personal/finished_free_culture
1278 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1279 @file{getstamps.py}. Note that you will need to set the current
1280 directory to where your Muse files are, execute @file{getstamps.py}, and
1281 then move the generated timestamps file to your publishing directory.
1283 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1284 @comment node-name, next, previous, up
1285 @subsection Format of a Blosxom entry and automation
1287 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1288 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1289 plus whatever normal content is desired.
1291 The date directive is not used directly by @command{pyblosxom.cgi} or
1292 this program. You need to have the two additional items from the former
1293 section to make use of this feature.
1295 There is a function called @code{muse-blosxom-new-entry} that will
1296 automate the process of making a new blog entry. To make use of it, do
1301 Customize @code{muse-blosxom-base-directory} to the location that your
1302 blog entries are stored.
1305 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1306 use the following code to assign this function to @kbd{C-c p l'}.
1309 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1313 You should create your directory structure ahead of time under your base
1314 directory. These directories, which correspond with category names, may
1318 When you enter this key sequence, you will be prompted for the category
1319 of your entry and its title. Upon entering this information, a new file
1320 will be created that corresponds with the title, but in lowercase
1321 letters and having special characters converted to underscores. The
1322 title and date directives will be inserted automatically.
1325 @node Blosxom Options, , Blosxom Entries, Blosxom
1326 @comment node-name, next, previous, up
1327 @subsection Blosxom styles and options provided
1329 The following styles and options are available in the Blosxom publishing
1332 @subheading Styles provided
1336 @cindex publishing styles, blosxom-html
1338 Publish Blosxom entries in HTML form.
1340 @cindex publishing styles, blosxom-xhtml
1342 Publish Blosxom entries in XHTML form.
1346 @subheading Options provided
1350 @item muse-blosxom-extension
1351 Default file extension for publishing Blosxom files.
1353 @item muse-blosxom-header
1354 Header used for publishing Blosxom files.
1356 This may be text or a filename.
1358 @item muse-blosxom-footer
1359 Footer used for publishing Blosxom files.
1361 This may be text or a filename.
1363 @item muse-blosxom-base-directory
1364 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1366 This is the top-level directory where your blog entries may be found
1371 @node Book, DocBook, Blosxom, Publishing Styles
1372 @comment node-name, next, previous, up
1373 @section Publishing entries into a compilation
1375 This publishing style is used to output ``books'' in LaTeX or PDF
1378 Each page will become a separate chapter in the book, unless the style
1379 keyword @option{:nochapters} is used, in which case they are all run
1380 together as if one giant chapter.
1382 One way of publishing a book is to make a project for it, add the
1383 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1384 with a very specific @code{:include} value to specify some page whose
1385 contents will be checked for the values of @code{#title} and
1386 @code{#date}, and whose name will be used in the output file. Then to
1387 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1388 @kbd{C-c C-p} to trigger the publishing process. An example
1389 @code{muse-project-alist} for this method follows.
1392 (setq muse-project-alist
1393 '(("MyNotes" (:nochapters t ; do automatically add chapters
1394 :book-chapter "Computer Science"
1396 :book-chapter "Mathematics"
1398 :book-chapter "Emacs"
1400 :book-end t ; the rest will not be placed in the book
1401 "~/Notes" ; so we can find the notes-anthology page
1403 :force-publish ("index")
1406 :include "/notes-anthology[^/]*$"
1407 :path "~/public_html/notes")
1408 ;; other publishing styles for each directory go here,
1413 In this example, there would be a file called
1414 @file{~/Notes/notes-anthology.muse}, which would contain just the
1415 following. The resulting book would be published to
1416 @file{~/public_html/notes/notes-anthology.pdf}.
1419 #title My Technology Ramblings
1422 Another way is to call the @code{muse-book-publish-project} function
1423 manually, with a custom project entry. An example of this may be found
1424 in John Wiegley's configuration file at
1425 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
1428 @subheading Styles provided
1432 @cindex publishing styles, book-latex
1434 Publish a book in LaTeX form. The header and footer are different than
1435 the normal LaTeX publishing mode.
1437 @cindex publishing styles, book-pdf
1439 Publish a book in PDF form. The header and footer are different than
1440 the normal PDF publishing mode.
1444 @subheading Options provided
1448 @item muse-book-before-publish-hook
1449 A hook run in the book buffer before it is marked up.
1451 @item muse-book-after-publish-hook
1452 A hook run in the book buffer after it is marked up.
1454 @item muse-book-latex-header
1455 Header used for publishing books to LaTeX.
1457 This may be text or a filename.
1459 @item muse-book-latex-footer
1460 Footer used for publishing books to LaTeX.
1462 This may be text or a filename.
1466 @node DocBook, HTML, Book, Publishing Styles
1467 @comment node-name, next, previous, up
1468 @section Publishing in DocBook XML form
1470 This publishing style is used to generate DocBook XML files.
1472 @subheading Styles provided
1476 @cindex publishing styles, docbook
1481 @subheading Options provided
1485 @item muse-docbook-extension
1486 Default file extension for publishing DocBook XML files.
1488 @item muse-docbook-header
1489 Header used for publishing DocBook XML files.
1491 This may be text or a filename.
1493 @item muse-docbook-footer
1494 Footer used for publishing DocBook XML files.
1496 This may be text or a filename.
1498 @item muse-docbook-markup-regexps
1499 List of markup rules for publishing a Muse page to DocBook XML.
1501 @item muse-docbook-markup-functions
1502 An alist of style types to custom functions for that kind of text.
1504 @item muse-docbook-markup-strings
1505 Strings used for marking up text.
1507 These cover the most basic kinds of markup, the handling of which
1508 differs little between the various styles.
1510 @item muse-docbook-markup-specials
1511 A table of characters which must be represented specially.
1513 @item muse-docbook-encoding-default
1514 The default Emacs buffer encoding to use in published files.
1515 This will be used if no special characters are found.
1517 @item muse-docbook-charset-default
1518 The default DocBook XML charset to use if no translation is
1519 found in @code{muse-docbook-encoding-map}.
1521 @item muse-docbook-encoding-map
1522 An alist mapping emacs coding systems to appropriate DocBook charsets.
1523 Use the base name of the coding system (i.e. without the -unix).
1527 @node HTML, Journal, DocBook, Publishing Styles
1528 @comment node-name, next, previous, up
1529 @section Publishing in HTML or XHTML form
1531 This publishing style is capable of producing HTML or XHTML documents.
1533 @subheading Styles provided
1537 @cindex publishing styles, html
1539 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1542 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1546 @subheading Options provided
1548 If an HTML option does not have a corresponding XHTML option, it will
1549 be used for both of these publishing styles.
1553 @item muse-html-extension
1554 Default file extension for publishing HTML files.
1556 @item muse-xhtml-extension
1557 Default file extension for publishing XHTML files.
1559 @item muse-html-style-sheet
1560 Store your stylesheet definitions here.
1562 This is used in @code{muse-html-header}. You can put raw CSS in here or
1563 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1564 @verb{|<lisp>|} markup tags.
1566 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1569 @item muse-html-header
1570 Header used for publishing HTML files.
1572 This may be text or a filename.
1574 @item muse-html-footer
1575 Footer used for publishing HTML files.
1577 This may be text or a filename.
1579 @item muse-xhtml-header
1580 Header used for publishing XHTML files.
1582 This may be text or a filename.
1584 @item muse-xhtml-footer
1585 Footer used for publishing XHTML files.
1587 This may be text or a filename.
1589 @item muse-html-anchor-on-word
1590 When true, anchors surround the closest word.
1592 This allows you to select them in a browser (i.e. for pasting), but has
1593 the side-effect of marking up headers in multiple colors if your header
1594 style is different from your link style.
1596 @item muse-html-table-attributes
1597 The attribute to be used with HTML @verb{|<table>|} tags.
1599 If you want to make more-complicated tables in HTML, surround the HTML
1600 with the @verb{|literal|} tag, so that it does not get escaped.
1602 @item muse-html-markup-regexps
1603 List of markup rules for publishing a Muse page to HTML.
1605 @item muse-html-markup-functions
1606 An alist of style types to custom functions for that kind of text.
1608 @item muse-html-markup-strings
1609 Strings used for marking up text as HTML.
1611 These cover the most basic kinds of markup, the handling of which
1612 differs little between the various styles.
1614 @item muse-xhtml-markup-strings
1615 Strings used for marking up text as XHTML.
1617 These cover the most basic kinds of markup, the handling of which
1618 differs little between the various styles.
1620 @item muse-html-markup-tags
1621 A list of tag specifications, for specially marking up HTML.
1622 @xref{muse-publish-markup-tags}, for more information.
1624 @item muse-html-markup-specials
1625 A table of characters which must be represented specially. By default,
1626 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1628 @item muse-html-meta-http-equiv
1629 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1631 @item muse-html-meta-content-type
1632 The content type used for the HTML @verb{|<meta>|} tag.
1634 If you are striving for XHTML 1.1 compliance, you may want to change
1635 this to ``application/xhtml+xml''.
1637 @item muse-html-meta-content-encoding
1638 The charset to append to the HTML @verb{|<meta>|} tag.
1640 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1641 and determine the HTML charset from emacs's coding. If set to a string,
1642 this string will be used to force a particular charset.
1644 @item muse-html-charset-default
1645 The default HTML meta charset to use if no translation is found in
1646 @code{muse-html-encoding-map}.
1648 @item muse-html-encoding-default
1649 The default Emacs buffer encoding to use in published files.
1650 This will be used if no special characters are found.
1652 @item muse-html-encoding-map
1653 An alist mapping emacs coding systems to appropriate HTML charsets.
1654 Use the base name of the coding system (i.e. without the -unix).
1658 @node Journal, LaTeX, HTML, Publishing Styles
1659 @comment node-name, next, previous, up
1660 @section Keeping a journal or blog
1662 @cindex blog, journal style
1664 The module facilitates the keeping and publication of a journal. When
1665 publishing to HTML, it assumes the form of a web log, or blog.
1667 The input format for each entry is as follows.
1670 * 20040317: Title of entry
1675 "You know who you are. It comes down to a simple gut check: You
1676 either love what you do or you don't. Period." -- P. Bronson
1680 The "qotd", or Quote of the Day, is entirely optional. When generated
1681 to HTML, this entry is rendered as the following.
1685 <div class="entry-qotd">
1686 <h3>Quote of the Day:</h3>
1687 <p>"You know who you are. It comes down to a simple gut
1688 check: You either love what you do or you don't. Period."
1691 <div class="entry-body">
1692 <div class="entry-head">
1693 <div class="entry-date">
1694 <span class="date">March 17, 2004</span>
1696 <div class="entry-title">
1697 <h2>Title of entry</h2>
1700 <div class="entry-text">
1701 <p>Text for the entry.</p>
1707 The plurality of "div" tags makes it possible to display the entries in
1708 any form you wish, using a CSS style.
1710 Also, an .RDF file can be generated from your journal by publishing it
1711 with the "rdf" style. It uses the first two sentences of the first
1712 paragraph of each entry as its "description", and auto-generates tags
1713 for linking to the various entries.
1715 @subheading Styles provided
1719 @cindex publishing styles, journal-html
1721 Publish journal entries as an HTML document.
1723 @cindex publishing styles, journal-xhtml
1725 Publish journal entries as an XHTML document.
1727 @cindex publishing styles, journal-latex
1729 Publish journal entries as a LaTeX document.
1731 @cindex publishing styles, journal-pdf
1733 Publish journal entries as a PDF document.
1735 @cindex publishing styles, journal-book-latex
1736 @item journal-book-latex
1737 Publish journal entries as a LaTeX book.
1739 @cindex publishing styles, journal-book-pdf
1740 @item journal-book-pdf
1741 Publish journal entries as a PDF book.
1743 @cindex publishing styles, journal-rdf
1744 @cindex publishing styles, RSS 1.0
1746 Publish journal entries as an RDF file (RSS 1.0).
1748 @cindex publishing styles, journal-rss
1749 @cindex publishing styles, RSS 2.0
1751 Publish journal entries as an RSS file (RSS 2.0).
1755 @subheading Options provided
1759 @item muse-journal-heading-regexp
1760 A regexp that matches a journal heading.
1762 Paren group 1 is the ISO date, group 2 is the optional category, and
1763 group 3 is the optional heading for the entry.
1765 @item muse-journal-date-format
1766 Date format to use for journal entries.
1768 @item muse-journal-html-heading-regexp
1769 A regexp that matches a journal heading from an HTML document.
1771 Paren group 1 is the ISO date, group 2 is the optional category, and
1772 group 3 is the optional heading for the entry.
1774 @item muse-journal-html-entry-template
1775 Template used to publish individual journal entries as HTML.
1777 @item muse-journal-latex-section
1778 Template used to publish a LaTeX section.
1780 @item muse-journal-latex-subsection
1781 Template used to publish a LaTeX subsection.
1783 @item muse-journal-latex-markup-tags
1784 A list of tag specifications, for specially marking up LaTeX.
1786 @xref{muse-publish-markup-tags}, for more information.
1788 @item muse-journal-rdf-extension
1789 Default file extension for publishing RDF (RSS 1.0) files.
1791 @item muse-journal-rdf-base-url
1792 The base URL of the website referenced by the RDF file.
1794 @item muse-journal-rdf-header
1795 Header used for publishing RDF (RSS 1.0) files.
1797 This may be text or a filename.
1799 @item muse-journal-rdf-footer
1800 Footer used for publishing RDF (RSS 1.0) files.
1802 This may be text or a filename.
1804 @item muse-journal-rdf-date-format
1805 Date format to use for RDF entries.
1807 @item muse-journal-rdf-entry-template
1808 Template used to publish individual journal entries as RDF.
1810 @item muse-journal-rdf-summarize-entries
1811 If non-nil, include only summaries in the RDF file, not the full data.
1813 @item muse-journal-rss-extension
1814 Default file extension for publishing RSS 2.0 files.
1816 @item muse-journal-rss-base-url
1817 The base URL of the website referenced by the RSS file.
1819 @item muse-journal-rss-header
1820 Header used for publishing RSS 2.0 files.
1822 This may be text or a filename.
1824 @item muse-journal-rss-footer
1825 Footer used for publishing RSS 2.0 files.
1827 This may be text or a filename.
1829 @item muse-journal-rss-date-format
1830 Date format to use for RSS 2.0 entries.
1832 @item muse-journal-rss-entry-template
1833 Template used to publish individual journal entries as RSS 2.0.
1835 @item muse-journal-rss-enclosure-types-alist
1836 File types that are accepted as RSS enclosures.
1838 This is an alist that maps file extension to content type.
1840 Useful for podcasting.
1842 @item muse-journal-rss-summarize-entries
1843 If non-nil, include only summaries in the RSS file, not the full data.
1845 Many RSS subscribers find this annoying.
1847 @item muse-journal-rss-markup-regexps
1848 List of markup rules for publishing a Muse journal page to RSS.
1850 For more information on the structure of this list,
1851 @xref{muse-publish-markup-regexps}.
1853 @item muse-journal-rss-markup-functions
1854 An alist of style types to custom functions for that kind of text.
1856 For more on the structure of this list,
1857 @xref{muse-publish-markup-functions}.
1861 @node LaTeX, Poem, Journal, Publishing Styles
1862 @comment node-name, next, previous, up
1863 @section Publishing LaTeX documents
1865 This publishing style is capable of producing LaTeX or PDF documents.
1867 If you wish to publish PDF documents, you will need to have a good TeX
1868 installation. For Debian and Ubuntu, this can be accomplished by
1869 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
1872 @subheading Styles provided
1876 @cindex publishing styles, latex
1878 Publish a LaTeX document.
1880 @cindex publishing styles, pdf
1882 Publish a PDF document, using an external LaTeX document conversion
1885 @cindex publishing styles, latexcjk
1887 Publish a LaTeX document with CJK (Chinese) encodings.
1889 @cindex publishing styles, pdfcjk
1891 Publish a PDF document with CJK (Chinese) encodings, using an external
1892 LaTeX document conversion tool.
1896 @subheading Options provided
1900 @item muse-latex-extension
1901 Default file extension for publishing LaTeX files.
1903 @item muse-latex-pdf-extension
1904 Default file extension for publishing LaTeX files to PDF.
1906 @item muse-latex-header
1907 Header used for publishing LaTeX files.
1909 This may be text or a filename.
1911 @item muse-latex-footer
1912 Footer used for publishing LaTeX files.
1914 This may be text or a filename.
1916 @item muse-latexcjk-header
1917 Header used for publishing LaTeX files (CJK).
1919 This may be text or a filename.
1921 @item muse-latexcjk-footer
1922 Footer used for publishing LaTeX files (CJK).
1924 This may be text or a filename.
1926 @item muse-latex-markup-regexps
1927 List of markup regexps for identifying regions in a Muse page.
1929 For more on the structure of this list,
1930 @xref{muse-publish-markup-regexps}.
1932 @item muse-latex-markup-functions
1933 An alist of style types to custom functions for that kind of text.
1935 For more on the structure of this list,
1936 @xref{muse-publish-markup-functions}.
1938 @item muse-latex-markup-strings
1939 Strings used for marking up text.
1941 These cover the most basic kinds of markup, the handling of which
1942 differs little between the various styles.
1944 @item muse-latexcjk-encoding-map
1945 An alist mapping emacs coding systems to appropriate CJK codings.
1946 Use the base name of the coding system (ie, without the -unix).
1948 @item muse-latexcjk-encoding-default
1949 The default Emacs buffer encoding to use in published files.
1951 This will be used if no special characters are found.
1953 @item muse-latex-markup-specials-example
1954 A table of characters which must be represented specially.
1955 These are applied to @verb{|example>|} regions.
1957 With the default interpretation of @verb{|<example>|} regions, no
1958 specials need to be escaped.
1960 @item muse-latex-markup-specials-document
1961 A table of characters which must be represented specially.
1962 These are applied to the entire document, sans already-escaped
1965 @item muse-latex-markup-specials-literal
1966 A table of characters which must be represented specially.
1967 This applies to =monospaced text= and @verb{|<code>|} regions.
1969 @item muse-latex-markup-specials-url
1970 A table of characters which must be represented specially.
1971 These are applied to URLs.
1973 @item muse-latex-permit-contents-tag
1974 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
1977 Most of the time, it is best to have a table of contents on the
1978 first page, with a new page immediately following. To make this
1979 work with documents published in both HTML and LaTeX, we need to
1980 ignore the @verb{|<contents>|} tag.
1982 If you don't agree with this, then set this option to non-nil,
1983 and it will do what you expect.
1987 @node Poem, Texinfo, LaTeX, Publishing Styles
1988 @comment node-name, next, previous, up
1989 @section Publish a poem to LaTex or PDF
1991 The @code{muse-poem} module makes it easy to attractively publish and
1992 reference poems in the following format, using the "memoir" module for
1993 LaTeX publishing. It will also markup poems for every other output
1994 style, though none are nearly as pretty.
2003 Annotations, history, notes, etc.
2006 Once a poem is written in this format, just publish it to PDF using the
2007 @code{poem-pdf} style. To make an inlined reference to a poem that
2008 you've written -- for example, from a blog page -- there is a "poem" tag
2009 defined by this module.
2012 <poem title="name.of.poem.page">
2015 Let's assume the template above was called @file{name.of.poem.page};
2016 then the above tag would result in this inclusion.
2024 John Wiegley uses this module for publishing all of the poems on his
2025 website, which are at
2026 @uref{http://www.newartisans.com/johnw/poems.html}.
2028 @subheading Styles provided
2032 @cindex publishing styles, poem-latex
2034 Publish a poem in LaTeX form.
2036 @cindex publishing styles, poem-pdf
2038 Publish a poem to a PDF document.
2040 @cindex publishing styles, chapbook-latex
2041 @item chapbook-latex
2042 Publish a book of poems in LaTeX form.
2044 @cindex publishing styles, chapbook-pdf
2046 Publish a book of poems to a PDF document.
2050 @subheading Options provided
2054 @item muse-poem-latex-header
2055 Header used for publishing LaTeX poems.
2057 This may be text or a filename.
2059 @item muse-poem-latex-footer
2060 Footer used for publishing LaTeX files.
2062 This may be text or a filename.
2064 @item muse-poem-markup-strings
2065 Strings used for marking up poems.
2067 These cover the most basic kinds of markup, the handling of which
2068 differs little between the various styles.
2070 @item muse-chapbook-latex-header
2071 Header used for publishing a book of poems in LaTeX form.
2073 This may be text or a filename.
2075 @item muse-chapbook-latex-footer
2076 Footer used for publishing a book of poems in LaTeX form.
2078 This may be text or a filename.
2080 @item muse-poem-chapbook-strings
2081 Strings used for marking up books of poems.
2083 These cover the most basic kinds of markup, the handling of which
2084 differs little between the various styles.
2088 @node Texinfo, , Poem, Publishing Styles
2089 @comment node-name, next, previous, up
2090 @section Publish entries to Texinfo format or PDF
2092 Rules for publishing a Muse file as a Texinfo article.
2094 @subheading Styles provided
2098 @cindex publishing styles, texi
2100 Publish a file in Texinfo form.
2102 @cindex publishing styles, texi
2104 Generate an Info file from a Muse file.
2106 @cindex publishing styles, info-pdf
2108 Publish a file in PDF form.
2112 @subheading Options provided
2116 @item muse-texinfo-process-natively
2117 If non-nil, use the Emacs `texinfmt' module to make Info files.
2119 @item muse-texinfo-extension
2120 Default file extension for publishing Texinfo files.
2122 @item muse-texinfo-info-extension
2123 Default file extension for publishing Info files.
2125 @item muse-texinfo-pdf-extension
2126 Default file extension for publishing PDF files.
2128 @item muse-texinfo-header
2129 Text to prepend to a Muse page being published as Texinfo.
2131 This may be text or a filename.
2132 It may contain @verb{|<lisp>|} markup tags.
2134 @item muse-texinfo-footer
2135 Text to append to a Muse page being published as Texinfo.
2137 This may be text or a filename.
2138 It may contain @verb{|<lisp>|} markup tags.
2140 @item muse-texinfo-markup-regexps
2141 List of markup rules for publishing a Muse page to Texinfo.
2143 For more on the structure of this list,
2144 @xref{muse-publish-markup-regexps}.
2146 @item muse-texinfo-markup-functions
2147 An alist of style types to custom functions for that kind of text.
2149 For more on the structure of this list, see
2150 @xref{muse-publish-markup-functions}.
2152 @item muse-texinfo-markup-strings
2153 Strings used for marking up text.
2155 These cover the most basic kinds of markup, the handling of which
2156 differs little between the various styles.
2158 @item muse-texinfo-markup-specials
2159 A table of characters which must be represented specially.
2164 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
2165 @comment node-name, next, previous, up
2166 @chapter Making your own publishing styles
2169 * Common Elements:: Common functionality shared by styles.
2170 * Deriving Styles:: Deriving a new style from an existing
2174 @node Common Elements, Deriving Styles, , Extending Muse
2175 @comment node-name, next, previous, up
2176 @section Common functionality shared by styles
2177 @cindex publishing styles, common
2180 * Markup Functions:: Specifying functions to marking up text.
2181 * Markup Regexps:: Markup rules for publishing.
2182 * Markup Strings:: Strings specific to a publishing style.
2183 * Markup Tags:: Tag specifications for special markup.
2184 * Style Elements:: Parameters used for defining styles.
2187 @node Markup Functions, Markup Regexps, , Common Elements
2188 @comment node-name, next, previous, up
2189 @subsection Specifying functions to mark up text
2190 @cindex publishing, markup functions
2192 @anchor{muse-publish-markup-functions}
2193 @code{muse-publish-markup-functions}
2195 An alist of style types to custom functions for that kind of text.
2197 This is used by publishing styles to attempt to minimize the amount of
2198 custom regexps that each has to define. @file{muse-publish} provides
2199 rules for the most common types of markup.
2201 Each member of the list is of the following form.
2209 Describes the type of text to associate with this rule.
2210 @code{muse-publish-markup-regexps} maps regexps to these symbols.
2213 Function to use to mark up this kind of rule if no suitable function is
2214 found through the @option{:functions} tag of the current style.
2217 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
2218 @comment node-name, next, previous, up
2219 @subsection Markup rules for publishing
2220 @cindex publishing, markup regexps
2221 @cindex publishing, rules
2223 @anchor{muse-publish-markup-regexps}
2224 @code{muse-publish-markup-regexps}
2226 List of markup rules for publishing a page with Muse.
2228 The rules given in this variable are invoked first, followed by whatever
2229 rules are specified by the current style.
2231 Each member of the list is either a function, or a list of the following
2235 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
2240 A regular expression, or symbol whose value is a regular expression,
2241 which is searched for using `re-search-forward'.
2243 @item TEXT-BEGIN-GROUP
2244 The matching group within that regexp which denotes the beginning of the
2245 actual text to be marked up.
2247 @item REPLACEMENT-TEXT
2248 A string that will be passed to `replace-match'.
2250 If it is not a string, but a function, it will be called to determine
2251 what the replacement text should be (it must return a string). If it is
2252 a symbol, the value of that symbol should be a string.
2255 The replacements are done in order, one rule at a time. Writing
2256 the regular expressions can be a tricky business. Note that case
2257 is never ignored. `case-fold-search' is always bound to nil
2258 while processing the markup rules.
2260 @subheading Publishing order
2262 This is the order that the publishing rules are consulted, by default.
2263 This may be changed by customizing @code{muse-publish-markup-regexps}.
2267 @item trailing and leading whitespace
2268 Remove trailing and leading whitespace from a file.
2273 This is only recognized at the beginning of a file.
2284 @item explicit links
2285 Prevent emphasis characters in explicit links from being marked up.
2287 Don't actually publish them here, just add a special no-emphasis text
2291 Whitespace-delimited word, possibly with emphasis characters
2293 This function is responsible for marking up emphasis and escaping some
2304 Outline-mode style headings.
2309 These are ellipses with a dot at end.
2319 Horizontal rule or section separator.
2324 beginning of footnotes section
2329 Footnote definition or reference. If at beginning of line, it is a
2344 Numbered list, item list, or term definition list.
2347 spaces before beginning of text
2355 @samp{table | cells}
2358 @samp{[[explicit][links]]}
2361 @samp{http://example.com/}
2364 @samp{bare-email@@example.com}
2368 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
2369 @comment node-name, next, previous, up
2370 @subsection Strings specific to a publishing style
2371 @cindex publishing, markup strings
2373 @dfn{Markup strings} are strings used for marking up text for a
2376 These cover the most basic kinds of markup, the handling of which
2377 differs little between the various styles.
2379 @subheading Available markup strings
2383 @item image-with-desc
2384 An image and a description.
2386 Argument 1: image without extension. Argument 2: image extension.
2387 Argument 3: description.
2392 Argument 1: image without extension. Argument 2: image extension.
2397 Argument 1: link. Argument 2: image without extension.
2398 Argument 3: image extension.
2401 A reference to an anchor on the current page.
2403 Argument 1: anchor name. Argument 2: description if one exists, or the
2404 original link otherwise.
2407 A URL without a description.
2412 A link with a description.
2414 Argument 1: link. Argument 2: description if one exists, or the
2415 original link otherwise.
2417 @item link-and-anchor
2418 A link to a page with an anchor, and a description.
2420 Argument 1: link. Argument 2: anchor name.
2421 Argument 3: description if one exists, or the original link otherwise.
2424 A link to an email address.
2426 Argument 1: email address. Argument 2: email address.
2431 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
2434 Beginning of a comment.
2440 A horizontal line or space.
2442 @item no-break-space
2443 A space that separates two words which are not to be separated.
2446 Beginning of footnote.
2452 Mark a reference for the current footnote.
2454 Argument 1: number of this footnote.
2456 @item footnotemark-end
2457 End of a reference for the current footnote.
2460 Indicate the text of the current footnote.
2462 Argument 1: number of this footnote.
2464 @item footnotetext-end
2465 End of a footnote text line.
2468 Text used to replace ``Footnotes:'' line.
2477 Beginning of a part indicator line. This is used by book publishing.
2480 End of a part indicator line. This is used by book publishing.
2483 Beginning of a chapter indicator line. This is used by book publishing.
2486 End of a chapter indicator line. This is used by book publishing.
2489 Beginning of level 1 section indicator line.
2491 Argument 1: level of section; always 1.
2494 End of level 1 section indicator line.
2496 Argument 1: level of section; always 1.
2499 Beginning of level 2 section indicator line.
2501 Argument 1: level of section; always 2.
2503 @item subsection-end
2504 End of level 2 section indicator line.
2506 Argument 1: level of section; always 2.
2509 Beginning of level 3 section indicator line.
2511 Argument 1: level of section; always 3.
2513 @item subsubsection-end
2514 End of level 3 section indicator line.
2516 Argument 1: level of section; always 3.
2519 Beginning of section indicator line, where level is greater than 3.
2521 Argument 1: level of section.
2523 @item section-other-end
2524 End of section indicator line, where level is greater than 3.
2526 Argument 1: level of section.
2528 @item begin-underline
2529 Beginning of underlined text.
2532 End of underlined text.
2535 Beginning of verbatim text. This includes @verb{|<code>|} tags and
2539 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2543 Beginning of the first level of emphasized text.
2546 End of the first level of emphasized text.
2548 @item begin-more-emph
2549 Beginning of the second level of emphasized text.
2552 End of the second level of emphasized text.
2554 @item begin-most-emph
2555 Beginning of the third (and final) level of emphasized text.
2558 End of the third (and final) level of emphasized text.
2561 Beginning of verse text.
2564 String used to each space that is further indented than the beginning of
2567 @item begin-verse-line
2568 Beginning of a line of verse.
2570 @item empty-verse-line
2571 End of a line of verse.
2573 @item begin-last-stanza-line
2574 Beginning of the last line of a verse stanza.
2576 @item end-last-stanza-line
2577 End of the last line of a verse stanza.
2583 Beginning of an example region. To make use of this, an
2584 @samp{<example>} tag is needed.
2587 End of an example region. To make use of this, an @samp{</example>} tag
2591 Begin a centered line.
2594 End a centered line.
2597 Begin a quoted region.
2600 End a quoted region.
2603 Begin an unordered list.
2606 End an unordered list.
2608 @item begin-uli-item
2609 Begin an unordered list item.
2612 End an unordered list item.
2615 Begin an ordered list.
2618 End an ordered list.
2620 @item begin-oli-item
2621 Begin an ordered list item.
2624 End an ordered list item.
2627 Begin a definition list.
2630 End a definition list.
2633 Begin a definition list item.
2636 End a definition list item.
2639 Begin a definition list term.
2642 End a definition list term.
2645 Begin a definition list entry.
2648 End a definition list entry.
2656 @item begin-table-group
2657 Begin a table grouping.
2659 @item end-table-group
2660 End a table grouping.
2662 @item begin-table-row
2668 @item begin-table-entry
2669 Begin a table entry.
2671 @item end-table-entry
2676 @node Markup Tags, Style Elements, Markup Strings, Common Elements
2677 @comment node-name, next, previous, up
2678 @subsection Tag specifications for special markup
2679 @cindex publishing, markup tags
2681 @anchor{muse-publish-markup-tags}
2682 @code{muse-publish-markup-tags}
2684 A list of tag specifications, for specially marking up text.
2686 XML-style tags are the best way to add custom markup to Muse. This is
2687 easily accomplished by customizing this list of markup tags.
2689 For each entry, the name of the tag is given, whether it expects a
2690 closing tag and/or an optional set of attributes, whether it is
2691 nestable, and a function that performs whatever action is desired within
2692 the delimited region.
2694 The tags themselves are deleted during publishing, before the function
2695 is called. The function is called with three arguments, the beginning
2696 and end of the region surrounded by the tags. If properties are
2697 allowed, they are passed as a third argument in the form of an alist.
2698 The `end' argument to the function is always a marker.
2700 Point is always at the beginning of the region within the tags, when the
2701 function is called. Wherever point is when the function finishes is
2702 where tag markup will resume.
2704 These tag rules are processed once at the beginning of markup, and once
2705 at the end, to catch any tags which may have been inserted in-between.
2707 @node Style Elements, , Markup Tags, Common Elements
2708 @comment node-name, next, previous, up
2709 @subsection Parameters used for defining styles
2710 @cindex publishing, style elements
2712 Style elements are tags that define a style. Use
2713 @code{muse-define-style} to create a new style.
2716 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2719 @subheading Usable elements
2724 File extension to use for publishing files with this style.
2727 File extension to use for publishing links to Muse files with this
2731 File extension to use for publishing second-stage files with this style.
2733 For example, PDF publishing generates a LaTeX file first, then a PDF
2734 from that LaTeX file.
2737 List of markup rules for publishing a page with Muse.
2738 @xref{muse-publish-markup-regexps}.
2741 An alist of style types to custom functions for that kind of text.
2742 @xref{muse-publish-markup-functions}.
2745 Strings used for marking up text with this style.
2747 These cover the most basic kinds of markup, the handling of which
2748 differs little between the various styles.
2751 A list of tag specifications, used for handling extra tags.
2752 @xref{muse-publish-markup-tags}.
2755 A table of characters which must be represented specially.
2758 A function that is to be executed on the newly-created publishing buffer
2759 (or the current region) before any publishing occurs.
2761 This is used to set extra parameters that direct the publishing process.
2764 A function that is to be executed on the publishing buffer (or the
2765 current region) immediately after applying all of the markup regexps.
2767 This is used to fix the order of table elements (header, footer, body)
2771 A function that is to be executed on the publishing buffer after
2772 :before-end, and immediately after inserting the header and footer.
2774 This is used for generating the table of contents as well as setting the
2778 A function that is to be executed after saving the published file, but
2779 while still in its buffer.
2781 This is used for generating second-stage documents like PDF files from
2782 just-published LaTeX files.
2785 Header used for publishing files of this style.
2787 This may be a variable, text, or a filename. It is inserted at the
2788 beginning of a file, after evaluating the publishing markup.
2791 Footer used for publishing files of this style.
2793 This may be a variable, text, or a filename. It is inserted at the end
2794 of a file, after evaluating the publishing markup.
2797 Style sheet used for publishing files of this style.
2799 This may be a variable or text. It is used in the header of HTML and
2800 XHTML based publishing styles.
2803 The function used to browse the published result of files of this style.
2807 @node Deriving Styles, , Common Elements, Extending Muse
2808 @comment node-name, next, previous, up
2809 @section Deriving a new style from an existing one
2810 @cindex publishing styles, deriving
2812 To create a new style from an existing one, use @code{muse-derive-style}
2813 as follows. This is a good way to fix something you don't like about a
2814 particular publishing style, or to personalize it.
2817 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2820 The derived name is a string defining the new style, such as "my-html".
2821 The base name must identify an existing style, such as "html" -- if you
2822 have loaded @file{muse-html}. The style parameters are the same as
2823 those used to create a style, except that they override whatever
2824 definitions exist in the base style. However, some definitions only
2825 partially override. The following parameters support partial
2828 @xref{Style Elements}, for a complete list of all parameters.
2833 If a markup function is not found in the derived style's function list,
2834 the base style's function list will be queried.
2837 All regexps in the current style and the base style(s) will be used.
2840 If a markup string is not found in the derived style's string list, the
2841 base style's string list will be queried.
2846 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
2847 @comment node-name, next, previous, up
2848 @chapter Getting Help and Reporting Bugs
2849 @cindex help, getting
2850 @cindex bugs, reporting
2852 After you have read this guide, if you still have questions about
2853 Muse, or if you have bugs to report, there are several places you can
2859 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
2860 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2864 @uref{http://www.mwolson.org/projects/EmacsMuse.html} is the web page
2865 that Michael Olson (the current maintainer) made for Muse.
2868 Muse has four mailing lists.
2872 @item muse-el-announce
2873 Low-traffic list for Muse-related announcements.
2875 You can join this mailing list (@email{muse-el-announce@@gna.org})
2876 using the subscription form at
2877 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
2878 mailing list is also available via Gmane (@url{http://gmane.org/}). The
2879 group is called @samp{gmane.emacs.muse.announce}.
2881 @item muse-el-discuss
2882 Discussion, bugfixes, suggestions, tips, and the like for Muse.
2883 This mailing list also includes the content of muse-el-announce.
2885 You can join this mailing list (@email{muse-el-discuss@@gna.org})
2886 using the subscription form at
2887 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
2888 list is also available via Gmane with the identifier
2889 @samp{gmane.emacs.muse.general}.
2891 @item muse-el-commits
2892 Log messages for changes committed to Muse.
2894 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
2895 the subscription form at
2896 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
2897 is also available via Gmane with the identifier
2898 @samp{gmane.emacs.muse.cvs}.
2900 @item muse-el-internationalization
2901 Discussion of translation of the Muse website and documentation into
2904 You can join this mailing list
2905 (@email{muse-el-internationalization@@gna.org}) using the subscription
2906 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
2907 mailing list is also available via Gmane with the identifier
2908 @samp{gmane.emacs.muse.internationalization}.
2913 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2914 contributors are frequently around and willing to answer your
2915 questions. The @samp{#muse} channel is also available for
2916 Muse-specific help, and its current maintainer hangs out there.
2919 The maintainer of Emacs Muse, Michael Olson, may be contacted at
2920 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
2921 it is often better to use the muse-el-discuss mailing list.
2925 @node History, Contributors, Getting Help and Reporting Bugs, Top
2926 @comment node-name, next, previous, up
2927 @chapter History of This Document
2928 @cindex history, of Muse
2932 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2933 limitations. Around February 2004, he started making "emacs-wiki version
2934 3.00 APLHA", which eventually became known as Muse.
2936 Most of those who frequent the emacs-wiki mailing list continued to use
2937 emacs-wiki, mainly because Planner hasn't been ported over to it.
2939 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2940 John Wiegley's request.
2943 Michael Olson overhauled this document and added many new sections in
2944 preparation for the first release of Muse (3.01).
2948 @node Contributors, GNU Free Documentation License, History, Top
2949 @comment node-name, next, previous, up
2950 @chapter Contributors to This Documentation
2951 @cindex contributors
2953 The first draft of this document was taken from the emacs-wiki texinfo
2954 manual. Michael Olson adapted it for Muse and added most of its
2957 John Sullivan did a majority of the work on the emacs-wiki texinfo
2960 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2961 emacs-wiki texinfo manual.
2964 @include doclicense.texi
2967 @node Concept Index, , GNU Free Documentation License, Top
2968 @comment node-name, next, previous, up