1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for the Emacs Muse version 3.01.91 (3.02 RC2).
17 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU General Public License.
27 @subtitle an authoring and publishing environment
28 @subtitle for GNU Emacs and XEmacs
30 @c The following two commands
31 @c start the copyright page.
33 @vskip 0pt plus 1filll
37 @c So the toc is printed at the start
41 @node Top, Preface, (dir), (dir)
42 @comment node-name, next, previous, up
49 * Preface:: About the documentation.
50 * Introduction:: What is Muse?
51 * Obtaining Muse:: How to get Muse releases and development
53 * Installation:: Compiling and installing Muse.
54 * Getting Started:: Settings for Muse.
55 * Projects:: Creating and managing Muse projects.
56 * Keystroke Summary:: Keys used in Muse mode.
57 * Markup Rules:: Rules for using markup.
58 * Publishing Styles:: Publishing various types of documents.
59 * Getting Help and Reporting Bugs::
60 * History:: History of this document.
61 * Contributors:: Contributors to this documentation.
62 * GNU General Public License:: The license for this manual and Muse.
63 * Concept Index:: Search for terms.
66 --- The Detailed Node Listing ---
68 How to Get Muse Releases and Development Changes
70 * Releases:: Released versions of Muse.
71 * Development:: Latest unreleased development changes.
73 Rules for Using Markup
75 * Paragraphs:: Paragraphs: centering and quoting.
76 * Headings:: Levels of headings.
77 * Directives:: Directives at the beginning of a
79 * Emphasizing Text:: Bold, italicized, and underlined text.
80 * Footnotes:: Making notes to be shown at the end.
81 * Verse:: Indicating poetic stanzas.
82 * Lists:: Lists of items.
83 * Tables:: Generation of data tables.
84 * Explicit Links:: Hyperlinks and email addresses with
86 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
88 * Images:: Publishing and displaying images.
89 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
90 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
93 Publishing Various Types of Documents
95 * Blosxom:: Integrating Muse and pyblosxom.cgi.
96 * Book:: Publishing entries into a compilation.
97 * DocBook:: Publishing in DocBook XML form.
98 * HTML:: Publishing in HTML or XHTML form.
99 * Journal:: Keeping a journal or blog.
100 * LaTeX:: Publishing LaTeX documents.
101 * Poem:: Publish a poem to LaTex or PDF.
102 * Texinfo:: Publish entries to Texinfo format or PDF.
103 * Common Elements:: Common functionality shared by styles.
104 * Deriving Styles:: Deriving a new style from an existing
107 Integrating Muse and pyblosxom.cgi
109 * Blosxom Requirements:: Other tools needed to the Blosxom style.
110 * Blosxom Entries:: Format of a Blosxom entry and automation.
111 * Blosxom Options:: Blosxom styles and options provided.
116 @node Preface, Introduction, Top, Top
117 @comment node-name, next, previous, up
118 @chapter About the documentation
120 This document describes Muse, which was written by John Wiegley
121 and is now maintained by Michael Olson. Several versions of it are
125 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
126 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
127 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
130 @node Introduction, Obtaining Muse, Preface, Top
131 @comment node-name, next, previous, up
132 @chapter What is Muse?
134 Emacs Muse is an authoring and publishing environment for Emacs. It
135 simplifies the process of writing documents and publishing them to
136 various output formats.
138 Muse consists of two main parts: an enhanced text-mode for authoring
139 documents and navigating within Muse projects, and a set of publishing
140 styles for generating different kinds of output.
142 This idea is not in any way new. Numerous systems exist -- even one
143 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
144 more modular environment, with a rather simple core, in which "styles"
145 are derived from to create new styles. Much of Muse's overall
146 functionality is optional. For example, you can use the publisher
147 without the major-mode, or the mode without doing any publishing; or if
148 you don't load the Texinfo or LaTeX modules, those styles won't be
151 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
152 code has been restructured and rewritten, especially its publishing
153 functions. The focus in this revision is on the authoring and publishing
154 aspects, and the "wikiness" has been removed as a default behavior (to
155 be offered again as an optional module). CamelCase words are no longer
158 @node Obtaining Muse, Installation, Introduction, Top
159 @comment node-name, next, previous, up
160 @chapter How to Get Muse Releases and Development Changes
163 * Releases:: Released versions of Muse.
164 * Development:: Latest unreleased development changes.
167 @node Releases, Development, Obtaining Muse, Obtaining Muse
168 @comment node-name, next, previous, up
169 @section Released versions of Muse
171 Choose to install a release if you want to minimize risk.
173 Errors are corrected in development first. User-visible changes will be
174 announced on the @email{emacs-wiki-discuss@@nongnu.org} mailing list.
175 This mailing list also provides support for @command{Planner} and
176 @command{emacs-wiki}, which is the predecessor of Muse.
177 @pxref{Getting Help and Reporting Bugs}.
179 @cindex releases, Debian package
180 @cindex Debian package for Muse
181 Debian users can get Muse via apt-get. The @file{muse-el} package is
182 available both at Michael Olson's Debian repository and the official
183 Debian repository. To make use of the former, add the following line to
184 your @file{/etc/apt/sources.list} file and run @code{apt-get install
188 deb http://www.mwolson.org/debian/ ./
191 @cindex releases, from source
192 Alternatively, you can download the latest release from
193 @uref{http://www.mwolson.org/static/dist/muse/} .
195 @node Development, , Releases, Obtaining Muse
196 @comment node-name, next, previous, up
197 @section Latest unreleased development changes
200 Choose the development version if you want to live on the bleeding edge
201 of Muse development or try out new features before release.
203 @cindex arch revision control system, using
204 The Arch revision control system allows you to retrieve previous
205 versions and select specific features and bug fixes. If you would like
206 to contribute to Muse development, it is highly recommended that you use
207 Arch, but this is not a requirement.
209 If you are new to Arch, you might find this tutorial helpful:
210 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
212 Downloading the Muse module with Arch and staying up-to-date involves
219 @item Debian: @kbd{apt-get install tla}.
220 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
223 @item Register the archive.
225 tla register-archive -f http://www.mwolson.org/archives/2005
228 @item Download the Muse package.
230 # Download Muse into the @file{muse} directory.
231 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
234 @item List upstream changes that are missing from your local copy.
235 Do this whenever you want to see whether new changes have been committed
239 # Change to the source directory you are interested in.
242 # Display the summary of changes
243 tla missing --summary
246 @cindex updating Muse with Arch
247 @item Update to the latest version by replaying missing changes.
255 There are other ways to interact with the Muse archive.
258 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
259 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
262 The latest development snapshot will be kept up-to-date since it is
263 updated at the same time as the Arch repository.
265 @node Installation, Getting Started, Obtaining Muse, Top
266 @comment node-name, next, previous, up
267 @chapter Compiling and Installing Muse
269 Muse may be compiled and installed on your machine.
273 This is an optional step, since Emacs Lisp source code does not
274 necessarily have to be byte-compiled. It will yield a speed increase,
277 A working copy of Emacs or XEmacs is needed in order to compile the
278 Emacs Muse. By default, the program that is installed with the name
279 @command{emacs} will be used.
281 If you want to use the @command{xemacs} binary to perform the
282 compilation, you would need to edit @file{Makefile.defs} in the
283 top-level directory as follows. You can put either a full path to an
284 Emacs or XEmacs binary or just the command name, as long as it is in the
289 SITEFLAG = -no-site-file
292 Running @code{make} should compile the Muse source files in the
293 @file{lisp} directory.
297 Muse may be installed into your file hierarchy by doing the following.
299 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
300 where you want the source and compiled Muse files to be installed and
301 @env{INFODIR} indicates where to put the Muse manual. Of course, you
302 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
303 Compilation section if you are using XEmacs.
305 If you are installing Muse on a Debian system, you might want to change
306 the value of @env{INSTALLINFO} as specified in @file{Makefile.defs}.
308 If you wish to install Muse to different locations than the defaults
309 specify, edit @file{Makefile.defs} accordingly.
311 Run @code{make} as a normal user.
313 Run @code{make install} as the root user if you have chosen installation
314 locations that require this.
317 @node Getting Started, Projects, Installation, Top
318 @comment node-name, next, previous, up
319 @chapter Getting Started
322 To use Muse, add the directory containing its files to your
323 @code{load-path} variable, in your @file{.emacs} file. Then, load in
324 the authoring mode, and the styles you wish to publish to. An example
328 (add-to-list 'load-path "<path to Muse>")
330 (require 'muse-mode) ; load authoring mode
332 (require 'muse-html) ; load publishing styles I use
333 (require 'muse-latex)
334 (require 'muse-texinfo)
335 (require 'muse-docbook)
338 Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
339 an input document to any available style. If you enable
340 @file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
341 command will be bound to @kbd{C-c C-t}.
343 If the currently opened file is part of a defined project in
344 @code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
346 You should also type @kbd{M-x customize-group}, and give the name
347 @samp{muse}. Each of the options has its own documentation.
350 @node Projects, Keystroke Summary, Getting Started, Top
351 @comment node-name, next, previous, up
352 @chapter Creating and Managing Muse Projects
355 Often you will want to publish all the files within a directory to a
356 particular set of output styles automatically. To support, Muse
357 allows for the creations of "projects". Here is a sample project, to
358 be defined in your @file{.emacs} file.
361 (require 'muse-project)
363 (setq muse-project-alist
364 '(("website" ; my various writings
365 ("~/Pages" :default "index")
366 (:base "html" :path "~/public_html")
367 (:base "pdf" :path "~/public_html/pdf"))))
370 The above defines a project named "website", whose files are located
371 in the directory @file{~/Pages}. The default page to visit is
372 @file{index}. When this project is published, each page will be
373 output as HTML to the directory @file{~/public_html}, and as PDF to
374 the directory @file{~/public_html/pdf}. Within any project page, you
375 may create a link to other pages using the syntax @samp{[[pagename]]}.
378 @node Keystroke Summary, Markup Rules, Projects, Top
379 @comment node-name, next, previous, up
380 @chapter Keys Used in Muse Mode
383 This is a summary of keystrokes available in every Muse buffer.
387 @item C-c C-a (`muse-index')
388 Display an index of all known Muse pages.
390 @item C-c C-b (`muse-browse-result')
391 Show the published result of this page.
393 @item C-c C-e (`muse-edit-link-at-point')
396 @item C-c C-f (`muse-project-find-file'), also C-c C-v
397 Open another Muse page. Prompt for the name.
399 @item C-c C-l (`font-lock-mode')
400 Highlight/refresh the current buffer.
402 @item C-c C-p (`muse-project-publish')
403 Publish any Muse pages that have changed.
405 @item C-c C-v (`muse-project-find-file'), also C-c C-f
406 Open another Muse page. Prompt for the name.
408 @item C-c = (`muse-what-changed')
409 Diff this page against the last backup version.
411 @item C-c TAB (`muse-insert-tag')
412 Insert a tag interactively.
415 Move to the next Wiki reference.
418 Move to the previous Wiki reference.
423 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
424 @comment node-name, next, previous, up
425 @chapter Rules for Using Markup
428 A Muse document uses special, contextual markup rules to determine how
429 to format the output result. For example, if a paragraph is indented,
430 Muse assumes it should be quoted.
432 There are not too many markup rules, and all of them strive to be as
433 simple as possible so that you can focus on document creation, rather
437 * Paragraphs:: Paragraphs: centering and quoting.
438 * Headings:: Levels of headings.
439 * Directives:: Directives at the beginning of a
441 * Emphasizing Text:: Bold, italicized, and underlined text.
442 * Footnotes:: Making notes to be shown at the end.
443 * Verse:: Indicating poetic stanzas.
444 * Lists:: Lists of items.
445 * Tables:: Generation of data tables.
446 * Explicit Links:: Hyperlinks and email addresses with
448 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
450 * Images:: Publishing and displaying images.
451 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
452 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
456 @node Paragraphs, Headings, Markup Rules, Markup Rules
457 @comment node-name, next, previous, up
458 @section Paragraphs: centering and quoting
461 Paragraphs in Muse must be separated by a blank line.
463 @cindex paragraphs, centered
464 @strong{Centered paragraphs and quotations}
466 A line that begins with six or more columns of whitespace (either tabs
467 or spaces) indicates a centered paragraph.
469 @cindex paragraphs, quoted
471 But if a line begins with whitespace, though less than six columns, it
472 indicates a quoted paragraph.
475 @cindex monospace, rendering blocks
476 @cindex HTML, rendering blocks in monospace
477 @strong{Literal paragraphs}
479 The @verb{|<example>|} tag is used for examples, where whitespace should
480 be preserved, the text rendered in monospace, and any characters special
481 to the output style escaped.
484 @cindex HTML, inserting a raw block
485 There is also the @verb{|<literal>|} tag, which causes a marked block to
486 be entirely left alone. This can be used for inserting a hand-coded
487 HTML blocks into HTML output, for example.
489 @node Headings, Directives, Paragraphs, Markup Rules
490 @comment node-name, next, previous, up
491 @section Levels of headings
494 A heading becomes a chapter or section in printed output -- depending on
495 the style. To indicate a heading, start a new paragraph with one or
496 more asterices, followed by a space and the heading title. Then begin
497 another paragraph to enter the text for that section.
499 All levels of headings will be published. Most publishing styles only
500 distinguish the between the first 4 levels, however.
512 @node Directives, Emphasizing Text, Headings, Markup Rules
513 @comment node-name, next, previous, up
514 @section Directives at the beginning of a document
517 Directives are lines beginning with the @samp{#} character that come
518 before any paragraphs or sections in the document. Directives are of
519 the form ``#directive content of directive''. You can use any
520 combination of uppercase and lowercase letters for directives, even if
521 the directive is not in the list below.
523 The @code{muse-publishing-directive} function may be used in header and
524 footer text to access directives. For example, to access the
525 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
527 The following is a list of directives that Muse uses.
532 The author of this document.
534 If this is not specified, Muse will attempt to figure it out from the
535 @code{user-full-name} variable.
539 The date that the document was originally published.
541 This is used by publishing styles that are able to embed the date
546 A short description of this document.
548 This is used by the @code{journal} publishing style to embed information
549 inside of an RSS/RDF feed.
553 The title of this document.
555 If this is not specified, the name of the file is used.
559 @node Emphasizing Text, Footnotes, Directives, Markup Rules
560 @comment node-name, next, previous, up
561 @section Bold, italicized, and underlined text
562 @cindex emphasizing text
563 @cindex underlining text
564 @cindex italicizing text
565 @cindex verbatim text
566 @cindex monospace, rendering words
568 To emphasize text, surround it with certain specially recognized
574 ***very strong emphasis***
576 =verbatim and monospace=
580 While editing a Muse document in Muse mode, these forms of emphasis will
581 be highlighted in a WYSIWYG manner. Each of these forms may span
584 Verbatim text will be colored as gray by default. To change this,
585 customize @code{muse-verbatim-face}.
587 @node Footnotes, Verse, Emphasizing Text, Markup Rules
588 @comment node-name, next, previous, up
589 @section Making notes to be shown at the end
592 A footnote reference is simply a number in square brackets. To define
593 the footnote, place this definition at the bottom of your file.
594 @samp{footnote-mode} can be used to greatly facilitate the creation of
595 these kinds of footnotes.
597 Footnotes are defined by the same number in brackets occurring at the
598 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
599 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
600 the point of insertion.
602 @node Verse, Lists, Footnotes, Markup Rules
603 @comment node-name, next, previous, up
604 @section Indicating poetic stanzas
608 Poetry requires that whitespace be preserved, but without resorting to
609 monospace. To indicate this, use the following markup, reminiscent of
613 > A line of Emacs verse;
614 > forgive its being so terse.
617 You can also use the @verb{|<verse>|} tag, if you prefer.
621 A line of Emacs verse;
622 forgive its being so terse.
626 @cindex verses, multiple stanzas
627 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
632 A line of Emacs verse;
633 forgive its being so terse.
635 In terms of terse verse,
640 @node Lists, Tables, Verse, Markup Rules
641 @comment node-name, next, previous, up
642 @section Lists of items
645 Lists are given using special characters at the beginning of a line.
646 Whitespace must occur before bullets or numbered items, to distinguish
647 from the possibility of those characters occurring in a real sentence.
649 @cindex lists, bullets
650 These are rendered as a bullet list.
657 @cindex lists, enumerated
658 An enumerated list follows.
665 @cindex lists, definitions
666 Here is a definition list.
670 This is a first definition
671 And it has two lines;
675 This is a second definition
678 @node Tables, Explicit Links, Lists, Markup Rules
679 @comment node-name, next, previous, up
680 @section Generation of data tables
683 @cindex tables, simple
684 Only very simple tables are supported. The syntax is as follows.
687 Double bars || Separate header fields
689 Single bars | Separate body fields
690 Here are more | body fields
692 Triple bars ||| Separate footer fields
695 Some publishing styles require header fields to come first, then footer
696 fields, and then the body fields. You can use any order for these
697 sections that you like, and Muse will re-order them for you at
700 @node Explicit Links, Implicit Links, Tables, Markup Rules
701 @comment node-name, next, previous, up
702 @section Hyperlinks and email addresses with descriptions
703 @cindex links, explicit
705 A hyperlink can reference a URL, or another page within a Muse
706 project. In addition, descriptive text can be specified, which should
707 be displayed rather than the link text in output styles that supports
708 link descriptions. The syntax is as follows.
711 [[link target][link description]]
712 [[link target without description]]
715 Thus, the current maintainer's homepage for Muse can be found
716 @samp{[[http://www.mwolson.org/projects/MuseMode.html][here]]},
717 or at @samp{[[http://www.mwolson.org/projects/MuseMode.html]]}.
719 @node Implicit Links, Images, Explicit Links, Markup Rules
720 @comment node-name, next, previous, up
721 @section Bare URLs, WikiNames, and InterWiki links
722 @cindex links, implicit
725 @cindex Email addresses
727 A URL or email address encountered in the input text is published as a
728 hyperlink. These kind of links are called @dfn{implicit links} because
729 they are not separated from the rest of the Muse document in any way.
732 If the @command{muse-wiki} module is loaded, another form of implicit
733 link will be made available. WikiNames, which are typed in camelcase,
734 will be highlighted and published as links, provided that the file they
737 @cindex InterWiki links
738 @cindex inter-project links
739 The @command{muse-wiki} module also allows for InterWiki links. These
740 are similar to WikiWords, but they specify both the project and page of
741 a file. The names of your project entries in @code{muse-project-alist}
742 will be used as InterWiki names by default. Several examples follow.
745 Blog::DocumentingMuse
750 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
751 the project name, and @samp{DocumentingMuse} is the page name. In the
752 second example, @samp{#} is the interwiki delimiter. If the name of a
753 project occurs by itself in text, like the third case, it will be
754 colorized and published as a link to the default page of the given
757 Customization of interwiki links may be accomplished by editing the
758 @code{muse-wiki-interwiki-alist} option.
760 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
761 @comment node-name, next, previous, up
762 @section Publishing and displaying images
764 @cindex links, with images
767 Links to images may be used in either the target or the description, or
768 both. Thus, the following code will publish as a clickable image that
769 points to @url{http://www.mwolson.org/}.
772 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
775 @cindex images, displaying
776 @cindex images, inlined
777 @cindex images, local
778 If a link to a locally-available image is encountered in the link
779 description, Muse mode will attempt to display it if your version of
780 Emacs permits this. The following example will display correctly and
781 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
782 exists in the @file{../pics/} directory.
785 [[TestPage][../pics/TestLogo.png]]
788 @cindex images, without a description
789 An image link is not required to have a description. The link
790 @samp{[[../myimage.png]]} will display and publish as expected.
792 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
793 @comment node-name, next, previous, up
794 @section Inserting a horizontal line or anchor
796 @cindex horizontal rules
798 @strong{Horizontal Rules}
800 Four or more dashes indicate a horizontal rule. Be sure to put blank
801 lines around it, or it will be considered part of the proceeding or
805 @cindex links, with target on same page
808 If you begin a line with "#anchor" -- where "anchor" can be any word
809 that doesn't contain whitespace -- it defines an anchor at that point
810 into the document. This point can be referenced using "page#anchor" as
811 the target in a Muse link.
813 @node Embedded Lisp, , Horizontal Rules and Anchors, Markup Rules
814 @comment node-name, next, previous, up
815 @section Evaluating Emacs Lisp code in documents for extensibility
816 @cindex lisp, embedded
818 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
819 which is the only Muse tag supported in a style's header and footer
820 text. With the @verb{|<lisp>|} tag, you may generated whatever output
821 text you wish. The inserted output will get marked up, if the
822 @verb{|<lisp>|} tag appears within the main text of the document.
825 <lisp>(concat "This form gets " "inserted")</lisp>
828 @cindex lisp, and insert command
829 Note that you should not use the @code{insert} command within a set of
830 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
831 tags will be automatically inserted into the document.
833 @node Publishing Styles, Getting Help and Reporting Bugs, Markup Rules, Top
834 @comment node-name, next, previous, up
835 @chapter Publishing Various Types of Documents
836 @cindex publishing styles
838 One of the principle features of Muse is the ability to publish a simple
839 input text to a variety of different output styles. Muse also makes it
840 easy to create new styles, or derive from an existing style.
843 * Blosxom:: Integrating Muse and pyblosxom.cgi.
844 * Book:: Publishing entries into a compilation.
845 * DocBook:: Publishing in DocBook XML form.
846 * HTML:: Publishing in HTML or XHTML form.
847 * Journal:: Keeping a journal or blog.
848 * LaTeX:: Publishing LaTeX documents.
849 * Poem:: Publish a poem to LaTex or PDF.
850 * Texinfo:: Publish entries to Texinfo format or PDF.
851 * Common Elements:: Common functionality shared by styles.
852 * Deriving Styles:: Deriving a new style from an existing
856 @node Blosxom, Book, Publishing Styles, Publishing Styles
857 @comment node-name, next, previous, up
858 @section Integrating Muse and pyblosxom.cgi
859 @cindex blog, one-file-per-entry style
861 The Blosxom publishing style publishes a tree of categorised files to a
862 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
863 In other words, each blog entry corresponds with one file.
866 * Blosxom Requirements:: Other tools needed to the Blosxom style.
867 * Blosxom Entries:: Format of a Blosxom entry and automation.
868 * Blosxom Options:: Blosxom styles and options provided.
871 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
872 @comment node-name, next, previous, up
873 @subsection Other tools needed to the Blosxom style
875 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
876 installed on a machine that you have upload access to.
878 The following additional components are required in order to make the
879 date of blog entries display as something sensible.
883 A script to gather date directives from the entire blog tree into a
884 single file. The file must associate a blog entry with a date.
887 A plugin for (py)blosxom that reads this file.
890 These 2 things are provided for @command{pyblosxom.cgi} in the
891 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
892 former service, while @file{hardcodedates.py} provides the latter
893 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
894 script will be found/written.
896 Here is a sample listing from my @file{timestamps} file, which maps
897 each file to a date. This can really be in any format, as long as your
898 date-gathering script and your plugin can both understand it.
901 2005-04-01-14-16 personal/paper_cranes
902 2005-03-21 personal/spring_break_over
903 2004-10-24 personal/finished_free_culture
906 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
907 @comment node-name, next, previous, up
908 @subsection Format of a Blosxom entry and automation
910 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
911 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
912 plus whatever normal content is desired.
914 The date directive is not used directly by @command{pyblosxom.cgi} or
915 this program. You need to have the two additional items from the former
916 section to make use of this feature.
918 There is a function called @code{muse-blosxom-new-entry} that will
919 automate the process of making a new blog entry. To make use of it, do
924 Customize @code{muse-blosxom-base-directory} to the location that your
925 blog entries are stored.
928 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
929 use the following code to assign this function to @kbd{C-c p l'}.
932 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
936 You should create your directory structure ahead of time under your base
937 directory. These directories, which correspond with category names, may
941 When you enter this key sequence, you will be prompted for the category
942 of your entry and its title. Upon entering this information, a new file
943 will be created that corresponds with the title, but in lowercase
944 letters and having special characters converted to underscores. The
945 title and date directives will be inserted automatically.
948 @node Blosxom Options, , Blosxom Entries, Blosxom
949 @comment node-name, next, previous, up
950 @subsection Blosxom styles and options provided
952 The following styles and options are available in the Blosxom publishing
955 @emph{Styles provided}
959 @cindex publishing styles, blosxom-html
961 Publish Blosxom entries in HTML form.
963 @cindex publishing styles, blosxom-xhtml
965 Publish Blosxom entries in XHTML form.
969 @emph{Options provided}
973 @item muse-blosxom-extension
974 Default file extension for publishing Blosxom files.
976 @item muse-blosxom-header
977 Header used for publishing Blosxom files.
979 This may be text or a filename.
981 @item muse-blosxom-footer
982 Footer used for publishing Blosxom files.
984 This may be text or a filename.
986 @item muse-blosxom-base-directory
987 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
989 This is the top-level directory where your blog entries may be found
994 @node Book, DocBook, Blosxom, Publishing Styles
995 @comment node-name, next, previous, up
996 @section Publishing entries into a compilation
998 This publishing style is used to output ``books'' in LaTeX or PDF
1001 Each page will become a separate chapter in the book, unless the style
1002 keyword @option{:nochapters} is used, in which case they are all run
1003 together as if one giant chapter.
1005 You will need to call the @code{muse-book-publish-project} function in
1006 order to publish this style. An example of this may be found in John
1007 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1009 @emph{Styles provided}
1013 @cindex publishing styles, book-latex
1015 Publish a book in LaTeX form. The header and footer are different than
1016 the normal LaTeX publishing mode.
1018 @cindex publishing styles, book-pdf
1020 Publish a book in PDF form. The header and footer are different than
1021 the normal PDF publishing mode.
1025 @emph{Options provided}
1029 @item muse-book-before-publish-hook
1030 A hook run in the book buffer before it is marked up.
1032 @item muse-book-after-publish-hook
1033 A hook run in the book buffer after it is marked up.
1035 @item muse-book-latex-header
1036 Header used for publishing books to LaTeX.
1038 This may be text or a filename.
1040 @item muse-book-latex-footer
1041 Footer used for publishing books to LaTeX.
1043 This may be text or a filename.
1047 @node DocBook, HTML, Book, Publishing Styles
1048 @comment node-name, next, previous, up
1049 @section Publishing in DocBook XML form
1051 This publishing style is used to generate DocBook XML files.
1053 @emph{Styles provided}
1057 @cindex publishing styles, docbook
1062 @emph{Options provided}
1066 @item muse-docbook-extension
1067 Default file extension for publishing DocBook XML files.
1069 @item muse-docbook-header
1070 Header used for publishing DocBook XML files.
1072 This may be text or a filename.
1074 @item muse-docbook-footer
1075 Footer used for publishing DocBook XML files.
1077 This may be text or a filename.
1079 @item muse-docbook-publishing-regexps
1080 List of markup rules for publishing a Muse page to DocBook XML.
1082 @item muse-docbook-markup-function
1083 An alist of style types to custom functions for that kind of text.
1085 @item muse-docbook-publishing-strings
1086 Strings used for marking up text.
1088 These cover the most basic kinds of markup, the handling of which
1089 differs little between the various styles.
1091 @item muse-docbook-markup-specials
1092 A table of characters which must be represented specially.
1096 @node HTML, Journal, DocBook, Publishing Styles
1097 @comment node-name, next, previous, up
1098 @section Publishing in HTML or XHTML form
1100 This publishing style is capable of producing HTML or XHTML documents.
1102 @emph{Styles provided}
1106 @cindex publishing styles, html
1108 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1111 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1115 @emph{Options provided}
1117 If an HTML option does not have a corresponding XHTML option, it will
1118 be used for both of these publishing styles.
1122 @item muse-html-extension
1123 Default file extension for publishing HTML files.
1125 @item muse-html-style-sheet
1126 Store your stylesheet definitions here.
1128 This is used in @code{muse-html-header}. You can put raw CSS in here or
1129 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1130 @verb{|<lisp>|} markup tags.
1132 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1135 @item muse-html-header
1136 Header used for publishing HTML files.
1138 This may be text or a filename.
1140 @item muse-html-footer
1141 Footer used for publishing HTML files.
1143 This may be text or a filename.
1145 @item muse-xhtml-header
1146 Header used for publishing XHTML files.
1148 This may be text or a filename.
1150 @item muse-xhtml-footer
1151 Footer used for publishing XHTML files.
1153 This may be text or a filename.
1155 @item muse-html-anchor-on-word
1156 When true, anchors surround the closest word.
1158 This allows you to select them in a browser (i.e. for pasting), but has
1159 the side-effect of marking up headers in multiple colors if your header
1160 style is different from your link style.
1162 @item muse-html-table-attributes
1163 The attribute to be used with HTML @verb{|<table>|} tags.
1165 Note that since Muse supports direct insertion of HTML tags, you can
1166 easily create any kind of table you want, as long as each line begins at
1167 column 0 (to prevent it from being blockquoted).
1169 @item muse-html-markup-regexps
1170 List of markup rules for publishing a Muse page to HTML.
1172 @item muse-html-markup-functions
1173 An alist of style types to custom functions for that kind of text.
1175 @item muse-html-markup-strings
1176 Strings used for marking up text as HTML.
1178 These cover the most basic kinds of markup, the handling of which
1179 differs little between the various styles.
1181 @item muse-xhtml-markup-strings
1182 Strings used for marking up text as XHTML.
1184 These cover the most basic kinds of markup, the handling of which
1185 differs little between the various styles.
1187 @item muse-html-markup-tags
1188 A list of tag specifications, for specially marking up HTML.
1189 @xref{muse-publish-markup-tags}, for more information.
1191 @item muse-html-markup-specials
1192 A table of characters which must be represented specially. By default,
1193 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1195 @item muse-html-meta-http-equiv
1196 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1198 @item muse-html-meta-content-type
1199 The content type used for the HTML @verb{|<meta>|} tag.
1201 If you are striving for XHTML 1.1 compliance, you may want to change
1202 this to ``application/xhtml+xml''.
1204 @item muse-html-meta-content-encoding
1205 The charset to append to the HTML @verb{|<meta>|} tag.
1207 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1208 and determine the HTML charset from emacs's coding. If set to a string,
1209 this string will be used to force a particular charset.
1211 @item muse-html-charset-default
1212 The default HTML meta charset to use if no translation is found in
1213 @code{muse-html-encoding-map}.
1215 @item muse-html-encoding-default
1216 The default Emacs buffer encoding to use in published files.
1217 This will be used if no special characters are found.
1219 @item muse-html-encoding-map
1220 An alist mapping emacs coding systems to appropriate HTML charsets.
1221 Use the base name of the coding system (i.e. without the -unix).
1225 @node Journal, LaTeX, HTML, Publishing Styles
1226 @comment node-name, next, previous, up
1227 @section Keeping a journal or blog
1229 @cindex blog, journal style
1231 The module facilitates the keeping and publication of a journal. When
1232 publishing to HTML, it assumes the form of a web log, or blog.
1234 The input format for each entry is as follows.
1237 * 20040317: Title of entry
1242 "You know who you are. It comes down to a simple gut check: You
1243 either love what you do or you don't. Period." -- P. Bronson
1247 The "qotd", or Quote of the Day, is entirely optional. When generated
1248 to HTML, this entry is rendered as the following.
1252 <div class="entry-qotd">
1253 <h3>Quote of the Day:</h3>
1254 <p>"You know who you are. It comes down to a simple gut
1255 check: You either love what you do or you don't. Period."
1258 <div class="entry-body">
1259 <div class="entry-head">
1260 <div class="entry-date">
1261 <span class="date">March 17, 2004</span>
1263 <div class="entry-title">
1264 <h2>Title of entry</h2>
1267 <div class="entry-text">
1268 <p>Text for the entry.</p>
1274 The plurality of "div" tags makes it possible to display the entries in
1275 any form you wish, using a CSS style.
1277 Also, an .RDF file can be generated from your journal by publishing it
1278 with the "rdf" style. It uses the first two sentences of the first
1279 paragraph of each entry as its "description", and auto-generates tags
1280 for linking to the various entries.
1282 @emph{Styles provided}
1286 @cindex publishing styles, journal-html
1288 Publish journal entries as an HTML document.
1290 @cindex publishing styles, journal-xhtml
1292 Publish journal entries as an XHTML document.
1294 @cindex publishing styles, journal-latex
1296 Publish journal entries as a LaTeX document.
1298 @cindex publishing styles, journal-pdf
1300 Publish journal entries as a PDF document.
1302 @cindex publishing styles, journal-book-latex
1303 @item journal-book-latex
1304 Publish journal entries as a LaTeX book.
1306 @cindex publishing styles, journal-book-pdf
1307 @item journal-book-pdf
1308 Publish journal entries as a PDF book.
1310 @cindex publishing styles, journal-rdf
1311 @cindex publishing styles, RSS 1.0
1313 Publish journal entries as an RDF file (RSS 1.0).
1315 @cindex publishing styles, journal-rss
1316 @cindex publishing styles, RSS 2.0
1318 Publish journal entries as an RSS file (RSS 2.0).
1322 @emph{Options provided}
1326 @item muse-journal-heading-regexp
1327 A regexp that matches a journal heading.
1329 Paren group 1 is the ISO date, group 2 is the optional category, and
1330 group 3 is the optional heading for the entry.
1332 @item muse-journal-date-format
1333 Date format to use for journal entries.
1335 @item muse-journal-html-heading-regexp
1336 A regexp that matches a journal heading from an HTML document.
1338 Paren group 1 is the ISO date, group 2 is the optional category, and
1339 group 3 is the optional heading for the entry.
1341 @item muse-journal-html-entry-template
1342 Template used to publish individual journal entries as HTML.
1344 @item muse-journal-latex-section
1345 Template used to publish a LaTeX section.
1347 @item muse-journal-latex-subsection
1348 Template used to publish a LaTeX subsection.
1350 @item muse-journal-latex-markup-tags
1351 A list of tag specifications, for specially marking up LaTeX.
1353 @xref{muse-publish-markup-tags}, for more information.
1355 @item muse-journal-rdf-extension
1356 Default file extension for publishing RDF (RSS 1.0) files.
1358 @item muse-journal-rdf-base-url
1359 The base URL of the website referenced by the RDF file.
1361 @item muse-journal-rdf-header
1362 Header used for publishing RDF (RSS 1.0) files.
1364 This may be text or a filename.
1366 @item muse-journal-rdf-footer
1367 Footer used for publishing RDF (RSS 1.0) files.
1369 This may be text or a filename.
1371 @item muse-journal-rdf-date-format
1372 Date format to use for RDF entries.
1374 @item muse-journal-rdf-entry-template
1375 Template used to publish individual journal entries as RDF.
1377 @item muse-journal-rdf-summarize-entries
1378 If non-nil, include only summaries in the RDF file, not the full data.
1380 @item muse-journal-rss-extension
1381 Default file extension for publishing RSS 2.0 files.
1383 @item muse-journal-rss-base-url
1384 The base URL of the website referenced by the RSS file.
1386 @item muse-journal-rss-header
1387 Header used for publishing RSS 2.0 files.
1389 This may be text or a filename.
1391 @item muse-journal-rss-footer
1392 Footer used for publishing RSS 2.0 files.
1394 This may be text or a filename.
1396 @item muse-journal-rss-date-format
1397 Date format to use for RSS 2.0 entries.
1399 @item muse-journal-rss-entry-template
1400 Template used to publish individual journal entries as RSS 2.0.
1402 @item muse-journal-rss-enclosure-types-alist
1403 File types that are accepted as RSS enclosures.
1405 This is an alist that maps file extension to content type.
1407 Useful for podcasting.
1409 @item muse-journal-rss-summarize-entries
1410 If non-nil, include only summaries in the RSS file, not the full data.
1412 Many RSS subscribers find this annoying.
1414 @item muse-journal-rss-markup-regexps
1415 List of markup rules for publishing a Muse journal page to RSS.
1417 For more information on the structure of this list,
1418 @xref{muse-publish-markup-regexps}.
1420 @item muse-journal-rss-markup-functions
1421 An alist of style types to custom functions for that kind of text.
1423 For more on the structure of this list,
1424 @xref{muse-publish-markup-functions}.
1428 @node LaTeX, Poem, Journal, Publishing Styles
1429 @comment node-name, next, previous, up
1430 @section Publishing LaTeX documents
1432 This publishing style is capable of producing LaTeX or PDF documents.
1434 If you wish to publish PDF documents, you will need to have a good TeX
1435 installation. For Debian, this can be accomplished by installing the
1436 ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1438 @emph{Styles provided}
1442 @cindex publishing styles, latex
1444 Publish a LaTeX document.
1446 @cindex publishing styles, pdf
1448 Publish a PDF document, using an external LaTeX document conversion
1451 @cindex publishing styles, latexcjk
1453 Publish a LaTeX document with CJK (Chinese) encodings.
1455 @cindex publishing styles, pdfcjk
1457 Publish a PDF document with CJK (Chinese) encodings, using an external
1458 LaTeX document conversion tool.
1462 @emph{Options provided}
1466 @item muse-latex-extension
1467 Default file extension for publishing LaTeX files.
1469 @item muse-latex-pdf-extension
1470 Default file extension for publishing LaTeX files to PDF.
1472 @item muse-latex-header
1473 Header used for publishing LaTeX files.
1475 This may be text or a filename.
1477 @item muse-latex-footer
1478 Footer used for publishing LaTeX files.
1480 This may be text or a filename.
1482 @item muse-latexcjk-header
1483 Header used for publishing LaTeX files (CJK).
1485 This may be text or a filename.
1487 @item muse-latexcjk-footer
1488 Footer used for publishing LaTeX files (CJK).
1490 This may be text or a filename.
1492 @item muse-latex-markup-regexps
1493 List of markup regexps for identifying regions in a Muse page.
1495 For more on the structure of this list,
1496 @xref{muse-publish-markup-regexps}.
1498 @item muse-latex-markup-functions
1499 An alist of style types to custom functions for that kind of text.
1501 For more on the structure of this list,
1502 @xref{muse-publish-markup-functions}.
1504 @item muse-latex-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-latexcjk-encoding-map
1511 An alist mapping emacs coding systems to appropriate CJK codings.
1512 Use the base name of the coding system (ie, without the -unix).
1514 @item muse-latexcjk-encoding-default
1515 The default Emacs buffer encoding to use in published files.
1517 This will be used if no special characters are found.
1519 @item muse-latex-markup-specials
1520 A table of characters which must be represented specially.
1524 @node Poem, Texinfo, LaTeX, Publishing Styles
1525 @comment node-name, next, previous, up
1526 @section Publish a poem to LaTex or PDF
1528 The @code{muse-poem} module makes it easy to attractively publish and
1529 reference poems in the following format, using the "memoir" module for
1530 LaTeX publishing. It will also markup poems for every other output
1531 style, though none are nearly as pretty.
1540 Annotations, history, notes, etc.
1543 Once a poem is written in this format, just publish it to PDF using the
1544 @code{poem-pdf} style. To make an inlined reference to a poem that
1545 you've written -- for example, from a blog page -- there is a "poem" tag
1546 defined by this module.
1549 <poem title="name.of.poem.page">
1552 Let's assume the template above was called @file{name.of.poem.page};
1553 then the above tag would result in this inclusion.
1561 John Wiegley uses this module for publishing all of the poems on his
1562 website, which are at
1563 @uref{http://www.newartisans.com/johnw/poems.html}.
1565 @emph{Styles provided}
1569 @cindex publishing styles, poem-latex
1571 Publish a poem in LaTeX form.
1573 @cindex publishing styles, poem-pdf
1575 Publish a poem to a PDF document.
1577 @cindex publishing styles, chapbook-latex
1578 @item chapbook-latex
1579 Publish a book of poems in LaTeX form.
1581 @cindex publishing styles, chapbook-pdf
1583 Publish a book of poems to a PDF document.
1587 @emph{Options provided}
1591 @item muse-poem-latex-header
1592 Header used for publishing LaTeX poems.
1594 This may be text or a filename.
1596 @item muse-poem-latex-footer
1597 Footer used for publishing LaTeX files.
1599 This may be text or a filename.
1601 @item muse-poem-markup-strings
1602 Strings used for marking up poems.
1604 These cover the most basic kinds of markup, the handling of which
1605 differs little between the various styles.
1607 @item muse-chapbook-latex-header
1608 Header used for publishing a book of poems in LaTeX form.
1610 This may be text or a filename.
1612 @item muse-chapbook-latex-footer
1613 Footer used for publishing a book of poems in LaTeX form.
1615 This may be text or a filename.
1617 @item muse-poem-chapbook-strings
1618 Strings used for marking up books of poems.
1620 These cover the most basic kinds of markup, the handling of which
1621 differs little between the various styles.
1625 @node Texinfo, Common Elements, Poem, Publishing Styles
1626 @comment node-name, next, previous, up
1627 @section Publish entries to Texinfo format or PDF
1629 Rules for publishing a Muse file as a Texinfo article.
1631 @emph{Styles provided}
1635 @cindex publishing styles, texi
1637 Publish a file in Texinfo form.
1639 @cindex publishing styles, texi
1641 Generate an Info file from a Muse file.
1643 @cindex publishing styles, info-pdf
1645 Publish a file in PDF form.
1649 @emph{Options provided}
1653 @item muse-texinfo-process-natively
1654 If non-nil, use the Emacs `texinfmt' module to make Info files.
1656 @item muse-texinfo-extension
1657 Default file extension for publishing Texinfo files.
1659 @item muse-texinfo-info-extension
1660 Default file extension for publishing Info files.
1662 @item muse-texinfo-pdf-extension
1663 Default file extension for publishing PDF files.
1665 @item muse-texinfo-header
1666 Text to prepend to a Muse page being published as Texinfo.
1668 This may be text or a filename.
1669 It may contain @verb{|<lisp>|} markup tags.
1671 @item muse-texinfo-footer
1672 Text to append to a Muse page being published as Texinfo.
1674 This may be text or a filename.
1675 It may contain @verb{|<lisp>|} markup tags.
1677 @item muse-texinfo-markup-regexps
1678 List of markup rules for publishing a Muse page to Texinfo.
1680 For more on the structure of this list,
1681 @xref{muse-publish-markup-regexps}.
1683 @item muse-texinfo-markup-functions
1684 An alist of style types to custom functions for that kind of text.
1686 For more on the structure of this list, see
1687 @xref{muse-publish-markup-functions}.
1689 @item muse-texinfo-markup-strings
1690 Strings used for marking up text.
1692 These cover the most basic kinds of markup, the handling of which
1693 differs little between the various styles.
1695 @item muse-texinfo-markup-specials
1696 A table of characters which must be represented specially.
1700 @node Common Elements, Deriving Styles, Texinfo, Publishing Styles
1701 @comment node-name, next, previous, up
1702 @section Common functionality shared by styles
1703 @cindex publishing styles, common
1707 @cindex publishing, markup functions
1708 @anchor{muse-publish-markup-functions}
1709 @item muse-publish-markup-functions
1710 An alist of style types to custom functions for that kind of text.
1712 This is used by publishing styles to attempt to minimize the amount of
1713 custom regexps that each has to define. @file{muse-publish} provides
1714 rules for the most common types of markup.
1716 Each member of the list is of the following form.
1724 Describes the type of text to associate with this rule.
1725 @code{muse-publish-markup-regexps} maps regexps to these symbols.
1728 Function to use to mark up this kind of rule if no suitable function is
1729 found through the @option{:functions} tag of the current style.
1732 @cindex publishing, markup regexps
1733 @anchor{muse-publish-markup-regexps}
1734 @item muse-publish-markup-regexps
1735 List of markup rules for publishing a page with Muse.
1737 The rules given in this variable are invoked first, followed by whatever
1738 rules are specified by the current style.
1740 Each member of the list is either a function, or a list of the following
1744 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1749 A regular expression, or symbol whose value is a regular expression,
1750 which is searched for using `re-search-forward'.
1752 @item TEXT-BEGIN-GROUP
1753 The matching group within that regexp which denotes the beginning of the
1754 actual text to be marked up.
1756 @item REPLACEMENT-TEXT
1757 A string that will be passed to `replace-match'.
1759 If it is not a string, but a function, it will be called to determine
1760 what the replacement text should be (it must return a string). If it is
1761 a symbol, the value of that symbol should be a string.
1764 The replacements are done in order, one rule at a time. Writing
1765 the regular expressions can be a tricky business. Note that case
1766 is never ignored. `case-fold-search' is always bound to nil
1767 while processing the markup rules.
1769 @cindex publishing, markup tags
1770 @anchor{muse-publish-markup-tags}
1771 @item muse-publish-markup-tags
1772 A list of tag specifications, for specially marking up text.
1774 XML-style tags are the best way to add custom markup to Muse. This is
1775 easily accomplished by customizing this list of markup tags.
1777 For each entry, the name of the tag is given, whether it expects a
1778 closing tag and/or an optional set of attributes, and a function that
1779 performs whatever action is desired within the delimited region.
1781 The tags themselves are deleted during publishing, before the function
1782 is called. The function is called with three arguments, the beginning
1783 and end of the region surrounded by the tags. If properties are
1784 allowed, they are passed as a third argument in the form of an alist.
1785 The `end' argument to the function is always a marker.
1787 Point is always at the beginning of the region within the tags, when the
1788 function is called. Wherever point is when the function finishes is
1789 where tag markup will resume.
1791 These tag rules are processed once at the beginning of markup, and once
1792 at the end, to catch any tags which may have been inserted in-between.
1796 @node Deriving Styles, , Common Elements, Publishing Styles
1797 @comment node-name, next, previous, up
1798 @section Deriving a new style from an existing one
1799 @cindex publishing styles, deriving
1801 To create a new style from an existing one, use @code{muse-derive-style}
1802 as follows. This is a good way to fix something you don't like about a
1803 particular publishing style, or to personalize it.
1806 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
1809 The derived name is a string defining the new style, such as "my-html".
1810 The base name must identify an existing style, such as "html" -- if you
1811 have loaded @file{muse-html}. The style parameters are the same as
1812 those used to create a style, except that they override whatever
1813 definitions exist in the base style. However, some definitions only
1814 partially override. The following parameters support partial
1820 If a markup function is not found in the derived style's function list,
1821 the base style's function list will be queried.
1824 If a markup string is not found in the derived style's string list, the
1825 base style's string list will be queried.
1828 If this option is specified, it will be consulted rather than the
1829 corresponding value in the derived style. This applies to the following
1839 @node Getting Help and Reporting Bugs, History, Publishing Styles, Top
1840 @comment node-name, next, previous, up
1841 @chapter Getting Help and Reporting Bugs
1842 @cindex help, getting
1843 @cindex bugs, reporting
1845 After you have read this guide, if you still have questions about
1846 Muse, or if you have bugs to report, there are several places you can
1852 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
1853 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
1857 @uref{http://www.mwolson.org/projects/MuseMode.html} is the web page
1858 that Michael Olson (the current maintainer) made for Muse.
1861 You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
1862 using the subscription form at
1863 @uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
1864 This mailing list provides support for Muse, @command{Planner} and
1865 @command{emacs-wiki}, which is the predecessor of Muse.
1867 There are additional methods for accessing the mailing list, adding
1868 content to it, and searching it. Consult
1869 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
1873 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
1874 contributors are frequently around and willing to answer your
1875 questions. The @samp{#muse} channel is also available for
1876 Muse-specific help, and its current maintainer hangs out there.
1879 The maintainer of MuseMode, Michael Olson, may be contacted at
1880 @email{mwolson@@gnu.org}.
1884 @node History, Contributors, Getting Help and Reporting Bugs, Top
1885 @comment node-name, next, previous, up
1886 @chapter History of This Document
1887 @cindex history, of Muse
1891 John Wiegley started Muse upon realizing that EmacsWiki had some serious
1892 limitations. Around February 2004, he started making "emacs-wiki version
1893 3.00 APLHA", which eventually became known as Muse.
1895 Most of those who frequent the emacs-wiki mailing list continued to use
1896 emacs-wiki, mainly because Planner hasn't been ported over to it.
1898 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
1899 John Wiegley's request.
1902 Michael Olson overhauled this document and added many new sections in
1903 preparation for the first release of Muse (3.01).
1907 @node Contributors, GNU General Public License, History, Top
1908 @comment node-name, next, previous, up
1909 @chapter Contributors to This Documentation
1910 @cindex contributors
1912 The first draft of this document was taken from the emacs-wiki texinfo
1913 manual. Michael Olson adapted it for Muse and added most of its
1916 John Sullivan did a majority of the work on the emacs-wiki texinfo
1919 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
1920 emacs-wiki texinfo manual.
1922 @node GNU General Public License, Concept Index, Contributors, Top
1923 @comment node-name, next, previous, up
1924 @appendix GNU GENERAL PUBLIC LICENSE
1925 @center Version 2, June 1991
1927 @cindex GNU General Public License
1929 @c This file is intended to be included in another file.
1932 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
1933 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
1935 Everyone is permitted to copy and distribute verbatim copies
1936 of this license document, but changing it is not allowed.
1939 @appendixsec Preamble
1941 The licenses for most software are designed to take away your
1942 freedom to share and change it. By contrast, the GNU General Public
1943 License is intended to guarantee your freedom to share and change free
1944 software---to make sure the software is free for all its users. This
1945 General Public License applies to most of the Free Software
1946 Foundation's software and to any other program whose authors commit to
1947 using it. (Some other Free Software Foundation software is covered by
1948 the GNU Library General Public License instead.) You can apply it to
1951 When we speak of free software, we are referring to freedom, not
1952 price. Our General Public Licenses are designed to make sure that you
1953 have the freedom to distribute copies of free software (and charge for
1954 this service if you wish), that you receive source code or can get it
1955 if you want it, that you can change the software or use pieces of it
1956 in new free programs; and that you know you can do these things.
1958 To protect your rights, we need to make restrictions that forbid
1959 anyone to deny you these rights or to ask you to surrender the rights.
1960 These restrictions translate to certain responsibilities for you if you
1961 distribute copies of the software, or if you modify it.
1963 For example, if you distribute copies of such a program, whether
1964 gratis or for a fee, you must give the recipients all the rights that
1965 you have. You must make sure that they, too, receive or can get the
1966 source code. And you must show them these terms so they know their
1969 We protect your rights with two steps: (1) copyright the software, and
1970 (2) offer you this license which gives you legal permission to copy,
1971 distribute and/or modify the software.
1973 Also, for each author's protection and ours, we want to make certain
1974 that everyone understands that there is no warranty for this free
1975 software. If the software is modified by someone else and passed on, we
1976 want its recipients to know that what they have is not the original, so
1977 that any problems introduced by others will not reflect on the original
1978 authors' reputations.
1980 Finally, any free program is threatened constantly by software
1981 patents. We wish to avoid the danger that redistributors of a free
1982 program will individually obtain patent licenses, in effect making the
1983 program proprietary. To prevent this, we have made it clear that any
1984 patent must be licensed for everyone's free use or not licensed at all.
1986 The precise terms and conditions for copying, distribution and
1987 modification follow.
1990 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1993 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1998 This License applies to any program or other work which contains
1999 a notice placed by the copyright holder saying it may be distributed
2000 under the terms of this General Public License. The ``Program'', below,
2001 refers to any such program or work, and a ``work based on the Program''
2002 means either the Program or any derivative work under copyright law:
2003 that is to say, a work containing the Program or a portion of it,
2004 either verbatim or with modifications and/or translated into another
2005 language. (Hereinafter, translation is included without limitation in
2006 the term ``modification''.) Each licensee is addressed as ``you''.
2008 Activities other than copying, distribution and modification are not
2009 covered by this License; they are outside its scope. The act of
2010 running the Program is not restricted, and the output from the Program
2011 is covered only if its contents constitute a work based on the
2012 Program (independent of having been made by running the Program).
2013 Whether that is true depends on what the Program does.
2016 You may copy and distribute verbatim copies of the Program's
2017 source code as you receive it, in any medium, provided that you
2018 conspicuously and appropriately publish on each copy an appropriate
2019 copyright notice and disclaimer of warranty; keep intact all the
2020 notices that refer to this License and to the absence of any warranty;
2021 and give any other recipients of the Program a copy of this License
2022 along with the Program.
2024 You may charge a fee for the physical act of transferring a copy, and
2025 you may at your option offer warranty protection in exchange for a fee.
2028 You may modify your copy or copies of the Program or any portion
2029 of it, thus forming a work based on the Program, and copy and
2030 distribute such modifications or work under the terms of Section 1
2031 above, provided that you also meet all of these conditions:
2035 You must cause the modified files to carry prominent notices
2036 stating that you changed the files and the date of any change.
2039 You must cause any work that you distribute or publish, that in
2040 whole or in part contains or is derived from the Program or any
2041 part thereof, to be licensed as a whole at no charge to all third
2042 parties under the terms of this License.
2045 If the modified program normally reads commands interactively
2046 when run, you must cause it, when started running for such
2047 interactive use in the most ordinary way, to print or display an
2048 announcement including an appropriate copyright notice and a
2049 notice that there is no warranty (or else, saying that you provide
2050 a warranty) and that users may redistribute the program under
2051 these conditions, and telling the user how to view a copy of this
2052 License. (Exception: if the Program itself is interactive but
2053 does not normally print such an announcement, your work based on
2054 the Program is not required to print an announcement.)
2057 These requirements apply to the modified work as a whole. If
2058 identifiable sections of that work are not derived from the Program,
2059 and can be reasonably considered independent and separate works in
2060 themselves, then this License, and its terms, do not apply to those
2061 sections when you distribute them as separate works. But when you
2062 distribute the same sections as part of a whole which is a work based
2063 on the Program, the distribution of the whole must be on the terms of
2064 this License, whose permissions for other licensees extend to the
2065 entire whole, and thus to each and every part regardless of who wrote it.
2067 Thus, it is not the intent of this section to claim rights or contest
2068 your rights to work written entirely by you; rather, the intent is to
2069 exercise the right to control the distribution of derivative or
2070 collective works based on the Program.
2072 In addition, mere aggregation of another work not based on the Program
2073 with the Program (or with a work based on the Program) on a volume of
2074 a storage or distribution medium does not bring the other work under
2075 the scope of this License.
2078 You may copy and distribute the Program (or a work based on it,
2079 under Section 2) in object code or executable form under the terms of
2080 Sections 1 and 2 above provided that you also do one of the following:
2084 Accompany it with the complete corresponding machine-readable
2085 source code, which must be distributed under the terms of Sections
2086 1 and 2 above on a medium customarily used for software interchange; or,
2089 Accompany it with a written offer, valid for at least three
2090 years, to give any third party, for a charge no more than your
2091 cost of physically performing source distribution, a complete
2092 machine-readable copy of the corresponding source code, to be
2093 distributed under the terms of Sections 1 and 2 above on a medium
2094 customarily used for software interchange; or,
2097 Accompany it with the information you received as to the offer
2098 to distribute corresponding source code. (This alternative is
2099 allowed only for noncommercial distribution and only if you
2100 received the program in object code or executable form with such
2101 an offer, in accord with Subsection b above.)
2104 The source code for a work means the preferred form of the work for
2105 making modifications to it. For an executable work, complete source
2106 code means all the source code for all modules it contains, plus any
2107 associated interface definition files, plus the scripts used to
2108 control compilation and installation of the executable. However, as a
2109 special exception, the source code distributed need not include
2110 anything that is normally distributed (in either source or binary
2111 form) with the major components (compiler, kernel, and so on) of the
2112 operating system on which the executable runs, unless that component
2113 itself accompanies the executable.
2115 If distribution of executable or object code is made by offering
2116 access to copy from a designated place, then offering equivalent
2117 access to copy the source code from the same place counts as
2118 distribution of the source code, even though third parties are not
2119 compelled to copy the source along with the object code.
2122 You may not copy, modify, sublicense, or distribute the Program
2123 except as expressly provided under this License. Any attempt
2124 otherwise to copy, modify, sublicense or distribute the Program is
2125 void, and will automatically terminate your rights under this License.
2126 However, parties who have received copies, or rights, from you under
2127 this License will not have their licenses terminated so long as such
2128 parties remain in full compliance.
2131 You are not required to accept this License, since you have not
2132 signed it. However, nothing else grants you permission to modify or
2133 distribute the Program or its derivative works. These actions are
2134 prohibited by law if you do not accept this License. Therefore, by
2135 modifying or distributing the Program (or any work based on the
2136 Program), you indicate your acceptance of this License to do so, and
2137 all its terms and conditions for copying, distributing or modifying
2138 the Program or works based on it.
2141 Each time you redistribute the Program (or any work based on the
2142 Program), the recipient automatically receives a license from the
2143 original licensor to copy, distribute or modify the Program subject to
2144 these terms and conditions. You may not impose any further
2145 restrictions on the recipients' exercise of the rights granted herein.
2146 You are not responsible for enforcing compliance by third parties to
2150 If, as a consequence of a court judgment or allegation of patent
2151 infringement or for any other reason (not limited to patent issues),
2152 conditions are imposed on you (whether by court order, agreement or
2153 otherwise) that contradict the conditions of this License, they do not
2154 excuse you from the conditions of this License. If you cannot
2155 distribute so as to satisfy simultaneously your obligations under this
2156 License and any other pertinent obligations, then as a consequence you
2157 may not distribute the Program at all. For example, if a patent
2158 license would not permit royalty-free redistribution of the Program by
2159 all those who receive copies directly or indirectly through you, then
2160 the only way you could satisfy both it and this License would be to
2161 refrain entirely from distribution of the Program.
2163 If any portion of this section is held invalid or unenforceable under
2164 any particular circumstance, the balance of the section is intended to
2165 apply and the section as a whole is intended to apply in other
2168 It is not the purpose of this section to induce you to infringe any
2169 patents or other property right claims or to contest validity of any
2170 such claims; this section has the sole purpose of protecting the
2171 integrity of the free software distribution system, which is
2172 implemented by public license practices. Many people have made
2173 generous contributions to the wide range of software distributed
2174 through that system in reliance on consistent application of that
2175 system; it is up to the author/donor to decide if he or she is willing
2176 to distribute software through any other system and a licensee cannot
2179 This section is intended to make thoroughly clear what is believed to
2180 be a consequence of the rest of this License.
2183 If the distribution and/or use of the Program is restricted in
2184 certain countries either by patents or by copyrighted interfaces, the
2185 original copyright holder who places the Program under this License
2186 may add an explicit geographical distribution limitation excluding
2187 those countries, so that distribution is permitted only in or among
2188 countries not thus excluded. In such case, this License incorporates
2189 the limitation as if written in the body of this License.
2192 The Free Software Foundation may publish revised and/or new versions
2193 of the General Public License from time to time. Such new versions will
2194 be similar in spirit to the present version, but may differ in detail to
2195 address new problems or concerns.
2197 Each version is given a distinguishing version number. If the Program
2198 specifies a version number of this License which applies to it and ``any
2199 later version'', you have the option of following the terms and conditions
2200 either of that version or of any later version published by the Free
2201 Software Foundation. If the Program does not specify a version number of
2202 this License, you may choose any version ever published by the Free Software
2206 If you wish to incorporate parts of the Program into other free
2207 programs whose distribution conditions are different, write to the author
2208 to ask for permission. For software which is copyrighted by the Free
2209 Software Foundation, write to the Free Software Foundation; we sometimes
2210 make exceptions for this. Our decision will be guided by the two goals
2211 of preserving the free status of all derivatives of our free software and
2212 of promoting the sharing and reuse of software generally.
2215 @heading NO WARRANTY
2222 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2223 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2224 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2225 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2226 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2227 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2228 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2229 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2230 REPAIR OR CORRECTION.
2233 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2234 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2235 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2236 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2237 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2238 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2239 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2240 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2241 POSSIBILITY OF SUCH DAMAGES.
2245 @heading END OF TERMS AND CONDITIONS
2248 @center END OF TERMS AND CONDITIONS
2252 @appendixsec Appendix: How to Apply These Terms to Your New Programs
2254 If you develop a new program, and you want it to be of the greatest
2255 possible use to the public, the best way to achieve this is to make it
2256 free software which everyone can redistribute and change under these terms.
2258 To do so, attach the following notices to the program. It is safest
2259 to attach them to the start of each source file to most effectively
2260 convey the exclusion of warranty; and each file should have at least
2261 the ``copyright'' line and a pointer to where the full notice is found.
2264 @var{one line to give the program's name and a brief idea of what it does.}
2265 Copyright (C) @var{yyyy} @var{name of author}
2267 This program is free software; you can redistribute it and/or modify
2268 it under the terms of the GNU General Public License as published by
2269 the Free Software Foundation; either version 2 of the License, or
2270 (at your option) any later version.
2272 This program is distributed in the hope that it will be useful,
2273 but WITHOUT ANY WARRANTY; without even the implied warranty of
2274 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2275 GNU General Public License for more details.
2277 You should have received a copy of the GNU General Public License along
2278 with this program; if not, write to the Free Software Foundation, Inc.,
2279 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2282 Also add information on how to contact you by electronic and paper mail.
2284 If the program is interactive, make it output a short notice like this
2285 when it starts in an interactive mode:
2288 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2289 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2290 This is free software, and you are welcome to redistribute it
2291 under certain conditions; type `show c' for details.
2294 The hypothetical commands @samp{show w} and @samp{show c} should show
2295 the appropriate parts of the General Public License. Of course, the
2296 commands you use may be called something other than @samp{show w} and
2297 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2300 You should also get your employer (if you work as a programmer) or your
2301 school, if any, to sign a ``copyright disclaimer'' for the program, if
2302 necessary. Here is a sample; alter the names:
2305 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2306 `Gnomovision' (which makes passes at compilers) written by James Hacker.
2308 @var{signature of Ty Coon}, 1 April 1989
2309 Ty Coon, President of Vice
2312 This General Public License does not permit incorporating your program into
2313 proprietary programs. If your program is a subroutine library, you may
2314 consider it more useful to permit linking proprietary applications with the
2315 library. If this is what you want to do, use the GNU Library General
2316 Public License instead of this License.
2319 @node Concept Index, , GNU General Public License, Top
2320 @comment node-name, next, previous, up
2328 @c ispell-local-pdict: "ispell-dict"