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.
113 Common functionality shared by styles
115 * Markup Functions:: Specifying functions to marking up text.
116 * Markup Regexps:: Markup rules for publishing.
117 * Markup Strings:: Strings specific to a publishing style.
118 * Markup Tags:: Tag specifications for special markup.
123 @node Preface, Introduction, Top, Top
124 @comment node-name, next, previous, up
125 @chapter About the documentation
127 This document describes Muse, which was written by John Wiegley
128 and is now maintained by Michael Olson. Several versions of it are
132 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
133 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
134 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
137 @node Introduction, Obtaining Muse, Preface, Top
138 @comment node-name, next, previous, up
139 @chapter What is Muse?
141 Emacs Muse is an authoring and publishing environment for Emacs. It
142 simplifies the process of writing documents and publishing them to
143 various output formats.
145 Muse consists of two main parts: an enhanced text-mode for authoring
146 documents and navigating within Muse projects, and a set of publishing
147 styles for generating different kinds of output.
149 This idea is not in any way new. Numerous systems exist -- even one
150 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
151 more modular environment, with a rather simple core, in which "styles"
152 are derived from to create new styles. Much of Muse's overall
153 functionality is optional. For example, you can use the publisher
154 without the major-mode, or the mode without doing any publishing; or if
155 you don't load the Texinfo or LaTeX modules, those styles won't be
158 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
159 code has been restructured and rewritten, especially its publishing
160 functions. The focus in this revision is on the authoring and publishing
161 aspects, and the "wikiness" has been removed as a default behavior (to
162 be offered again as an optional module). CamelCase words are no longer
165 @node Obtaining Muse, Installation, Introduction, Top
166 @comment node-name, next, previous, up
167 @chapter How to Get Muse Releases and Development Changes
170 * Releases:: Released versions of Muse.
171 * Development:: Latest unreleased development changes.
174 @node Releases, Development, Obtaining Muse, Obtaining Muse
175 @comment node-name, next, previous, up
176 @section Released versions of Muse
178 Choose to install a release if you want to minimize risk.
180 Errors are corrected in development first. User-visible changes will be
181 announced on the @email{emacs-wiki-discuss@@nongnu.org} mailing list.
182 This mailing list also provides support for @command{Planner} and
183 @command{emacs-wiki}, which is the predecessor of Muse.
184 @pxref{Getting Help and Reporting Bugs}.
186 @cindex releases, Debian package
187 @cindex Debian package for Muse
188 Debian users can get Muse via apt-get. The @file{muse-el} package is
189 available both at Michael Olson's Debian repository and the official
190 Debian repository. To make use of the former, add the following line to
191 your @file{/etc/apt/sources.list} file and run @code{apt-get install
195 deb http://www.mwolson.org/debian/ ./
198 @cindex releases, from source
199 Alternatively, you can download the latest release from
200 @uref{http://www.mwolson.org/static/dist/muse/} .
202 @node Development, , Releases, Obtaining Muse
203 @comment node-name, next, previous, up
204 @section Latest unreleased development changes
207 Choose the development version if you want to live on the bleeding edge
208 of Muse development or try out new features before release.
210 @cindex arch revision control system, using
211 The Arch revision control system allows you to retrieve previous
212 versions and select specific features and bug fixes. If you would like
213 to contribute to Muse development, it is highly recommended that you use
214 Arch, but this is not a requirement.
216 If you are new to Arch, you might find this tutorial helpful:
217 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
219 Downloading the Muse module with Arch and staying up-to-date involves
226 @item Debian: @kbd{apt-get install tla}.
227 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
230 @item Register the archive.
232 tla register-archive -f http://www.mwolson.org/archives/2005
235 @item Download the Muse package.
237 # Download Muse into the @file{muse} directory.
238 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
241 @item List upstream changes that are missing from your local copy.
242 Do this whenever you want to see whether new changes have been committed
246 # Change to the source directory you are interested in.
249 # Display the summary of changes
250 tla missing --summary
253 @cindex updating Muse with Arch
254 @item Update to the latest version by replaying missing changes.
262 There are other ways to interact with the Muse archive.
265 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
266 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
269 The latest development snapshot will be kept up-to-date since it is
270 updated at the same time as the Arch repository.
272 @node Installation, Getting Started, Obtaining Muse, Top
273 @comment node-name, next, previous, up
274 @chapter Compiling and Installing Muse
276 Muse may be compiled and installed on your machine.
278 @subsubheading Compilation
280 This is an optional step, since Emacs Lisp source code does not
281 necessarily have to be byte-compiled. It will yield a speed increase,
284 A working copy of Emacs or XEmacs is needed in order to compile the
285 Emacs Muse. By default, the program that is installed with the name
286 @command{emacs} will be used.
288 If you want to use the @command{xemacs} binary to perform the
289 compilation, you would need to edit @file{Makefile.defs} in the
290 top-level directory as follows. You can put either a full path to an
291 Emacs or XEmacs binary or just the command name, as long as it is in the
296 SITEFLAG = -no-site-file
299 Running @code{make} should compile the Muse source files in the
300 @file{lisp} directory.
302 @subsubheading Installation
304 Muse may be installed into your file hierarchy by doing the following.
306 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
307 where you want the source and compiled Muse files to be installed and
308 @env{INFODIR} indicates where to put the Muse manual. Of course, you
309 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
310 Compilation section if you are using XEmacs.
312 If you are installing Muse on a Debian system, you might want to change
313 the value of @env{INSTALLINFO} as specified in @file{Makefile.defs}.
315 If you wish to install Muse to different locations than the defaults
316 specify, edit @file{Makefile.defs} accordingly.
318 Run @code{make} as a normal user.
320 Run @code{make install} as the root user if you have chosen installation
321 locations that require this.
324 @node Getting Started, Projects, Installation, Top
325 @comment node-name, next, previous, up
326 @chapter Getting Started
329 To use Muse, add the directory containing its files to your
330 @code{load-path} variable, in your @file{.emacs} file. Then, load in
331 the authoring mode, and the styles you wish to publish to. An example
335 (add-to-list 'load-path "<path to Muse>")
337 (require 'muse-mode) ; load authoring mode
339 (require 'muse-html) ; load publishing styles I use
340 (require 'muse-latex)
341 (require 'muse-texinfo)
342 (require 'muse-docbook)
345 Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
346 an input document to any available style. If you enable
347 @file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
348 command will be bound to @kbd{C-c C-t}.
350 If the currently opened file is part of a defined project in
351 @code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
353 You should also type @kbd{M-x customize-group}, and give the name
354 @samp{muse}. Each of the options has its own documentation.
357 @node Projects, Keystroke Summary, Getting Started, Top
358 @comment node-name, next, previous, up
359 @chapter Creating and Managing Muse Projects
362 Often you will want to publish all the files within a directory to a
363 particular set of output styles automatically. To support, Muse
364 allows for the creations of "projects". Here is a sample project, to
365 be defined in your @file{.emacs} file.
368 (require 'muse-project)
370 (setq muse-project-alist
371 '(("website" ; my various writings
372 ("~/Pages" :default "index")
373 (:base "html" :path "~/public_html")
374 (:base "pdf" :path "~/public_html/pdf"))))
377 The above defines a project named "website", whose files are located
378 in the directory @file{~/Pages}. The default page to visit is
379 @file{index}. When this project is published, each page will be
380 output as HTML to the directory @file{~/public_html}, and as PDF to
381 the directory @file{~/public_html/pdf}. Within any project page, you
382 may create a link to other pages using the syntax @samp{[[pagename]]}.
385 @node Keystroke Summary, Markup Rules, Projects, Top
386 @comment node-name, next, previous, up
387 @chapter Keys Used in Muse Mode
390 This is a summary of keystrokes available in every Muse buffer.
394 @item C-c C-a (`muse-index')
395 Display an index of all known Muse pages.
397 @item C-c C-b (`muse-browse-result')
398 Show the published result of this page.
400 @item C-c C-e (`muse-edit-link-at-point')
403 @item C-c C-f (`muse-project-find-file'), also C-c C-v
404 Open another Muse page. Prompt for the name.
406 @item C-c C-l (`font-lock-mode')
407 Highlight/refresh the current buffer.
409 @item C-c C-p (`muse-project-publish')
410 Publish any Muse pages that have changed.
412 @item C-c C-v (`muse-project-find-file'), also C-c C-f
413 Open another Muse page. Prompt for the name.
415 @item C-c = (`muse-what-changed')
416 Diff this page against the last backup version.
418 @item C-c TAB (`muse-insert-tag')
419 Insert a tag interactively.
422 Move to the next Wiki reference.
425 Move to the previous Wiki reference.
430 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
431 @comment node-name, next, previous, up
432 @chapter Rules for Using Markup
435 A Muse document uses special, contextual markup rules to determine how
436 to format the output result. For example, if a paragraph is indented,
437 Muse assumes it should be quoted.
439 There are not too many markup rules, and all of them strive to be as
440 simple as possible so that you can focus on document creation, rather
444 * Paragraphs:: Paragraphs: centering and quoting.
445 * Headings:: Levels of headings.
446 * Directives:: Directives at the beginning of a
448 * Emphasizing Text:: Bold, italicized, and underlined text.
449 * Footnotes:: Making notes to be shown at the end.
450 * Verse:: Indicating poetic stanzas.
451 * Lists:: Lists of items.
452 * Tables:: Generation of data tables.
453 * Explicit Links:: Hyperlinks and email addresses with
455 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
457 * Images:: Publishing and displaying images.
458 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
459 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
463 @node Paragraphs, Headings, Markup Rules, Markup Rules
464 @comment node-name, next, previous, up
465 @section Paragraphs: centering and quoting
468 Paragraphs in Muse must be separated by a blank line.
470 @cindex paragraphs, centered
471 @strong{Centered paragraphs and quotations}
473 A line that begins with six or more columns of whitespace (either tabs
474 or spaces) indicates a centered paragraph.
476 @cindex paragraphs, quoted
478 But if a line begins with whitespace, though less than six columns, it
479 indicates a quoted paragraph.
482 @cindex monospace, rendering blocks
483 @cindex HTML, rendering blocks in monospace
484 @strong{Literal paragraphs}
486 The @verb{|<example>|} tag is used for examples, where whitespace should
487 be preserved, the text rendered in monospace, and any characters special
488 to the output style escaped.
491 @cindex HTML, inserting a raw block
492 There is also the @verb{|<literal>|} tag, which causes a marked block to
493 be entirely left alone. This can be used for inserting a hand-coded
494 HTML blocks into HTML output, for example.
496 @node Headings, Directives, Paragraphs, Markup Rules
497 @comment node-name, next, previous, up
498 @section Levels of headings
501 A heading becomes a chapter or section in printed output -- depending on
502 the style. To indicate a heading, start a new paragraph with one or
503 more asterices, followed by a space and the heading title. Then begin
504 another paragraph to enter the text for that section.
506 All levels of headings will be published. Most publishing styles only
507 distinguish the between the first 4 levels, however.
519 @node Directives, Emphasizing Text, Headings, Markup Rules
520 @comment node-name, next, previous, up
521 @section Directives at the beginning of a document
524 Directives are lines beginning with the @samp{#} character that come
525 before any paragraphs or sections in the document. Directives are of
526 the form ``#directive content of directive''. You can use any
527 combination of uppercase and lowercase letters for directives, even if
528 the directive is not in the list below.
530 The @code{muse-publishing-directive} function may be used in header and
531 footer text to access directives. For example, to access the
532 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
534 The following is a list of directives that Muse uses.
539 The author of this document.
541 If this is not specified, Muse will attempt to figure it out from the
542 @code{user-full-name} variable.
546 The date that the document was originally published.
548 This is used by publishing styles that are able to embed the date
553 A short description of this document.
555 This is used by the @code{journal} publishing style to embed information
556 inside of an RSS/RDF feed.
560 The title of this document.
562 If this is not specified, the name of the file is used.
566 @node Emphasizing Text, Footnotes, Directives, Markup Rules
567 @comment node-name, next, previous, up
568 @section Bold, italicized, and underlined text
569 @cindex emphasizing text
570 @cindex underlining text
571 @cindex italicizing text
572 @cindex verbatim text
573 @cindex monospace, rendering words
575 To emphasize text, surround it with certain specially recognized
581 ***very strong emphasis***
583 =verbatim and monospace=
587 While editing a Muse document in Muse mode, these forms of emphasis will
588 be highlighted in a WYSIWYG manner. Each of these forms may span
591 Verbatim text will be colored as gray by default. To change this,
592 customize @code{muse-verbatim-face}.
594 @node Footnotes, Verse, Emphasizing Text, Markup Rules
595 @comment node-name, next, previous, up
596 @section Making notes to be shown at the end
599 A footnote reference is simply a number in square brackets. To define
600 the footnote, place this definition at the bottom of your file.
601 @samp{footnote-mode} can be used to greatly facilitate the creation of
602 these kinds of footnotes.
604 Footnotes are defined by the same number in brackets occurring at the
605 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
606 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
607 the point of insertion.
609 @node Verse, Lists, Footnotes, Markup Rules
610 @comment node-name, next, previous, up
611 @section Indicating poetic stanzas
615 Poetry requires that whitespace be preserved, but without resorting to
616 monospace. To indicate this, use the following markup, reminiscent of
620 > A line of Emacs verse;
621 > forgive its being so terse.
624 You can also use the @verb{|<verse>|} tag, if you prefer.
628 A line of Emacs verse;
629 forgive its being so terse.
633 @cindex verses, multiple stanzas
634 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
639 A line of Emacs verse;
640 forgive its being so terse.
642 In terms of terse verse,
647 @node Lists, Tables, Verse, Markup Rules
648 @comment node-name, next, previous, up
649 @section Lists of items
652 Lists are given using special characters at the beginning of a line.
653 Whitespace must occur before bullets or numbered items, to distinguish
654 from the possibility of those characters occurring in a real sentence.
656 @cindex lists, bullets
657 These are rendered as a bullet list.
664 @cindex lists, enumerated
665 An enumerated list follows.
672 @cindex lists, definitions
673 Here is a definition list.
677 This is a first definition
678 And it has two lines;
682 This is a second definition
685 @node Tables, Explicit Links, Lists, Markup Rules
686 @comment node-name, next, previous, up
687 @section Generation of data tables
690 @cindex tables, simple
691 Only very simple tables are supported. The syntax is as follows.
694 Double bars || Separate header fields
696 Single bars | Separate body fields
697 Here are more | body fields
699 Triple bars ||| Separate footer fields
702 Some publishing styles require header fields to come first, then footer
703 fields, and then the body fields. You can use any order for these
704 sections that you like, and Muse will re-order them for you at
707 @node Explicit Links, Implicit Links, Tables, Markup Rules
708 @comment node-name, next, previous, up
709 @section Hyperlinks and email addresses with descriptions
710 @cindex links, explicit
712 A hyperlink can reference a URL, or another page within a Muse
713 project. In addition, descriptive text can be specified, which should
714 be displayed rather than the link text in output styles that supports
715 link descriptions. The syntax is as follows.
718 [[link target][link description]]
719 [[link target without description]]
722 Thus, the current maintainer's homepage for Muse can be found
723 @samp{[[http://www.mwolson.org/projects/MuseMode.html][here]]},
724 or at @samp{[[http://www.mwolson.org/projects/MuseMode.html]]}.
726 @node Implicit Links, Images, Explicit Links, Markup Rules
727 @comment node-name, next, previous, up
728 @section Bare URLs, WikiNames, and InterWiki links
729 @cindex links, implicit
732 @cindex Email addresses
734 A URL or email address encountered in the input text is published as a
735 hyperlink. These kind of links are called @dfn{implicit links} because
736 they are not separated from the rest of the Muse document in any way.
739 If the @command{muse-wiki} module is loaded, another form of implicit
740 link will be made available. WikiNames, which are typed in camelcase,
741 will be highlighted and published as links, provided that the file they
744 @cindex InterWiki links
745 @cindex inter-project links
746 The @command{muse-wiki} module also allows for InterWiki links. These
747 are similar to WikiWords, but they specify both the project and page of
748 a file. The names of your project entries in @code{muse-project-alist}
749 will be used as InterWiki names by default. Several examples follow.
752 Blog::DocumentingMuse
757 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
758 the project name, and @samp{DocumentingMuse} is the page name. In the
759 second example, @samp{#} is the interwiki delimiter. If the name of a
760 project occurs by itself in text, like the third case, it will be
761 colorized and published as a link to the default page of the given
764 Customization of interwiki links may be accomplished by editing the
765 @code{muse-wiki-interwiki-alist} option.
767 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
768 @comment node-name, next, previous, up
769 @section Publishing and displaying images
771 @cindex links, with images
774 Links to images may be used in either the target or the description, or
775 both. Thus, the following code will publish as a clickable image that
776 points to @url{http://www.mwolson.org/}.
779 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
782 @cindex images, displaying
783 @cindex images, inlined
784 @cindex images, local
785 If a link to a locally-available image is encountered in the link
786 description, Muse mode will attempt to display it if your version of
787 Emacs permits this. The following example will display correctly and
788 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
789 exists in the @file{../pics/} directory.
792 [[TestPage][../pics/TestLogo.png]]
795 @cindex images, without a description
796 An image link is not required to have a description. The link
797 @samp{[[../myimage.png]]} will display and publish as expected.
799 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
800 @comment node-name, next, previous, up
801 @section Inserting a horizontal line or anchor
803 @cindex horizontal rules
805 @strong{Horizontal Rules}
807 Four or more dashes indicate a horizontal rule. Be sure to put blank
808 lines around it, or it will be considered part of the proceeding or
812 @cindex links, with target on same page
815 If you begin a line with "#anchor" -- where "anchor" can be any word
816 that doesn't contain whitespace -- it defines an anchor at that point
817 into the document. This point can be referenced using "page#anchor" as
818 the target in a Muse link.
820 @node Embedded Lisp, , Horizontal Rules and Anchors, Markup Rules
821 @comment node-name, next, previous, up
822 @section Evaluating Emacs Lisp code in documents for extensibility
823 @cindex lisp, embedded
825 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
826 which is the only Muse tag supported in a style's header and footer
827 text. With the @verb{|<lisp>|} tag, you may generated whatever output
828 text you wish. The inserted output will get marked up, if the
829 @verb{|<lisp>|} tag appears within the main text of the document.
832 <lisp>(concat "This form gets " "inserted")</lisp>
835 @cindex lisp, and insert command
836 Note that you should not use the @code{insert} command within a set of
837 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
838 tags will be automatically inserted into the document.
840 @node Publishing Styles, Getting Help and Reporting Bugs, Markup Rules, Top
841 @comment node-name, next, previous, up
842 @chapter Publishing Various Types of Documents
843 @cindex publishing styles
845 One of the principle features of Muse is the ability to publish a simple
846 input text to a variety of different output styles. Muse also makes it
847 easy to create new styles, or derive from an existing style.
850 * Blosxom:: Integrating Muse and pyblosxom.cgi.
851 * Book:: Publishing entries into a compilation.
852 * DocBook:: Publishing in DocBook XML form.
853 * HTML:: Publishing in HTML or XHTML form.
854 * Journal:: Keeping a journal or blog.
855 * LaTeX:: Publishing LaTeX documents.
856 * Poem:: Publish a poem to LaTex or PDF.
857 * Texinfo:: Publish entries to Texinfo format or PDF.
858 * Common Elements:: Common functionality shared by styles.
859 * Deriving Styles:: Deriving a new style from an existing
863 @node Blosxom, Book, Publishing Styles, Publishing Styles
864 @comment node-name, next, previous, up
865 @section Integrating Muse and pyblosxom.cgi
866 @cindex blog, one-file-per-entry style
868 The Blosxom publishing style publishes a tree of categorised files to a
869 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
870 In other words, each blog entry corresponds with one file.
873 * Blosxom Requirements:: Other tools needed to the Blosxom style.
874 * Blosxom Entries:: Format of a Blosxom entry and automation.
875 * Blosxom Options:: Blosxom styles and options provided.
878 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
879 @comment node-name, next, previous, up
880 @subsection Other tools needed to the Blosxom style
882 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
883 installed on a machine that you have upload access to.
885 The following additional components are required in order to make the
886 date of blog entries display as something sensible.
890 A script to gather date directives from the entire blog tree into a
891 single file. The file must associate a blog entry with a date.
894 A plugin for (py)blosxom that reads this file.
897 These 2 things are provided for @command{pyblosxom.cgi} in the
898 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
899 former service, while @file{hardcodedates.py} provides the latter
900 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
901 script will be found/written.
903 Here is a sample listing from my @file{timestamps} file, which maps
904 each file to a date. This can really be in any format, as long as your
905 date-gathering script and your plugin can both understand it.
908 2005-04-01-14-16 personal/paper_cranes
909 2005-03-21 personal/spring_break_over
910 2004-10-24 personal/finished_free_culture
913 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
914 @comment node-name, next, previous, up
915 @subsection Format of a Blosxom entry and automation
917 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
918 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
919 plus whatever normal content is desired.
921 The date directive is not used directly by @command{pyblosxom.cgi} or
922 this program. You need to have the two additional items from the former
923 section to make use of this feature.
925 There is a function called @code{muse-blosxom-new-entry} that will
926 automate the process of making a new blog entry. To make use of it, do
931 Customize @code{muse-blosxom-base-directory} to the location that your
932 blog entries are stored.
935 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
936 use the following code to assign this function to @kbd{C-c p l'}.
939 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
943 You should create your directory structure ahead of time under your base
944 directory. These directories, which correspond with category names, may
948 When you enter this key sequence, you will be prompted for the category
949 of your entry and its title. Upon entering this information, a new file
950 will be created that corresponds with the title, but in lowercase
951 letters and having special characters converted to underscores. The
952 title and date directives will be inserted automatically.
955 @node Blosxom Options, , Blosxom Entries, Blosxom
956 @comment node-name, next, previous, up
957 @subsection Blosxom styles and options provided
959 The following styles and options are available in the Blosxom publishing
962 @subsubheading Styles provided
966 @cindex publishing styles, blosxom-html
968 Publish Blosxom entries in HTML form.
970 @cindex publishing styles, blosxom-xhtml
972 Publish Blosxom entries in XHTML form.
976 @subsubheading Options provided
980 @item muse-blosxom-extension
981 Default file extension for publishing Blosxom files.
983 @item muse-blosxom-header
984 Header used for publishing Blosxom files.
986 This may be text or a filename.
988 @item muse-blosxom-footer
989 Footer used for publishing Blosxom files.
991 This may be text or a filename.
993 @item muse-blosxom-base-directory
994 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
996 This is the top-level directory where your blog entries may be found
1001 @node Book, DocBook, Blosxom, Publishing Styles
1002 @comment node-name, next, previous, up
1003 @section Publishing entries into a compilation
1005 This publishing style is used to output ``books'' in LaTeX or PDF
1008 Each page will become a separate chapter in the book, unless the style
1009 keyword @option{:nochapters} is used, in which case they are all run
1010 together as if one giant chapter.
1012 You will need to call the @code{muse-book-publish-project} function in
1013 order to publish this style. An example of this may be found in John
1014 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1016 @subsubheading Styles provided
1020 @cindex publishing styles, book-latex
1022 Publish a book in LaTeX form. The header and footer are different than
1023 the normal LaTeX publishing mode.
1025 @cindex publishing styles, book-pdf
1027 Publish a book in PDF form. The header and footer are different than
1028 the normal PDF publishing mode.
1032 @subsubheading Options provided
1036 @item muse-book-before-publish-hook
1037 A hook run in the book buffer before it is marked up.
1039 @item muse-book-after-publish-hook
1040 A hook run in the book buffer after it is marked up.
1042 @item muse-book-latex-header
1043 Header used for publishing books to LaTeX.
1045 This may be text or a filename.
1047 @item muse-book-latex-footer
1048 Footer used for publishing books to LaTeX.
1050 This may be text or a filename.
1054 @node DocBook, HTML, Book, Publishing Styles
1055 @comment node-name, next, previous, up
1056 @section Publishing in DocBook XML form
1058 This publishing style is used to generate DocBook XML files.
1060 @subsubheading Styles provided
1064 @cindex publishing styles, docbook
1069 @subsubheading Options provided
1073 @item muse-docbook-extension
1074 Default file extension for publishing DocBook XML files.
1076 @item muse-docbook-header
1077 Header used for publishing DocBook XML files.
1079 This may be text or a filename.
1081 @item muse-docbook-footer
1082 Footer used for publishing DocBook XML files.
1084 This may be text or a filename.
1086 @item muse-docbook-markup-regexps
1087 List of markup rules for publishing a Muse page to DocBook XML.
1089 @item muse-docbook-markup-functions
1090 An alist of style types to custom functions for that kind of text.
1092 @item muse-docbook-markup-strings
1093 Strings used for marking up text.
1095 These cover the most basic kinds of markup, the handling of which
1096 differs little between the various styles.
1098 @item muse-docbook-markup-specials
1099 A table of characters which must be represented specially.
1101 @item muse-docbook-encoding-default
1102 The default Emacs buffer encoding to use in published files.
1103 This will be used if no special characters are found.
1105 @item muse-docbook-charset-default
1106 The default DocBook XML charset to use if no translation is
1107 found in @code{muse-docbook-encoding-map}.
1109 @item muse-docbook-encoding-map
1110 An alist mapping emacs coding systems to appropriate DocBook charsets.
1111 Use the base name of the coding system (i.e. without the -unix).
1115 @node HTML, Journal, DocBook, Publishing Styles
1116 @comment node-name, next, previous, up
1117 @section Publishing in HTML or XHTML form
1119 This publishing style is capable of producing HTML or XHTML documents.
1121 @subsubheading Styles provided
1125 @cindex publishing styles, html
1127 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1130 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1134 @subsubheading Options provided
1136 If an HTML option does not have a corresponding XHTML option, it will
1137 be used for both of these publishing styles.
1141 @item muse-html-extension
1142 Default file extension for publishing HTML files.
1144 @item muse-xhtml-extension
1145 Default file extension for publishing XHTML files.
1147 @item muse-html-style-sheet
1148 Store your stylesheet definitions here.
1150 This is used in @code{muse-html-header}. You can put raw CSS in here or
1151 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1152 @verb{|<lisp>|} markup tags.
1154 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1157 @item muse-html-header
1158 Header used for publishing HTML files.
1160 This may be text or a filename.
1162 @item muse-html-footer
1163 Footer used for publishing HTML files.
1165 This may be text or a filename.
1167 @item muse-xhtml-header
1168 Header used for publishing XHTML files.
1170 This may be text or a filename.
1172 @item muse-xhtml-footer
1173 Footer used for publishing XHTML files.
1175 This may be text or a filename.
1177 @item muse-html-anchor-on-word
1178 When true, anchors surround the closest word.
1180 This allows you to select them in a browser (i.e. for pasting), but has
1181 the side-effect of marking up headers in multiple colors if your header
1182 style is different from your link style.
1184 @item muse-html-table-attributes
1185 The attribute to be used with HTML @verb{|<table>|} tags.
1187 Note that since Muse supports direct insertion of HTML tags, you can
1188 easily create any kind of table you want, as long as each line begins at
1189 column 0 (to prevent it from being blockquoted).
1191 @item muse-html-markup-regexps
1192 List of markup rules for publishing a Muse page to HTML.
1194 @item muse-html-markup-functions
1195 An alist of style types to custom functions for that kind of text.
1197 @item muse-html-markup-strings
1198 Strings used for marking up text as HTML.
1200 These cover the most basic kinds of markup, the handling of which
1201 differs little between the various styles.
1203 @item muse-xhtml-markup-strings
1204 Strings used for marking up text as XHTML.
1206 These cover the most basic kinds of markup, the handling of which
1207 differs little between the various styles.
1209 @item muse-html-markup-tags
1210 A list of tag specifications, for specially marking up HTML.
1211 @xref{muse-publish-markup-tags}, for more information.
1213 @item muse-html-markup-specials
1214 A table of characters which must be represented specially. By default,
1215 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1217 @item muse-html-meta-http-equiv
1218 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1220 @item muse-html-meta-content-type
1221 The content type used for the HTML @verb{|<meta>|} tag.
1223 If you are striving for XHTML 1.1 compliance, you may want to change
1224 this to ``application/xhtml+xml''.
1226 @item muse-html-meta-content-encoding
1227 The charset to append to the HTML @verb{|<meta>|} tag.
1229 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1230 and determine the HTML charset from emacs's coding. If set to a string,
1231 this string will be used to force a particular charset.
1233 @item muse-html-charset-default
1234 The default HTML meta charset to use if no translation is found in
1235 @code{muse-html-encoding-map}.
1237 @item muse-html-encoding-default
1238 The default Emacs buffer encoding to use in published files.
1239 This will be used if no special characters are found.
1241 @item muse-html-encoding-map
1242 An alist mapping emacs coding systems to appropriate HTML charsets.
1243 Use the base name of the coding system (i.e. without the -unix).
1247 @node Journal, LaTeX, HTML, Publishing Styles
1248 @comment node-name, next, previous, up
1249 @section Keeping a journal or blog
1251 @cindex blog, journal style
1253 The module facilitates the keeping and publication of a journal. When
1254 publishing to HTML, it assumes the form of a web log, or blog.
1256 The input format for each entry is as follows.
1259 * 20040317: Title of entry
1264 "You know who you are. It comes down to a simple gut check: You
1265 either love what you do or you don't. Period." -- P. Bronson
1269 The "qotd", or Quote of the Day, is entirely optional. When generated
1270 to HTML, this entry is rendered as the following.
1274 <div class="entry-qotd">
1275 <h3>Quote of the Day:</h3>
1276 <p>"You know who you are. It comes down to a simple gut
1277 check: You either love what you do or you don't. Period."
1280 <div class="entry-body">
1281 <div class="entry-head">
1282 <div class="entry-date">
1283 <span class="date">March 17, 2004</span>
1285 <div class="entry-title">
1286 <h2>Title of entry</h2>
1289 <div class="entry-text">
1290 <p>Text for the entry.</p>
1296 The plurality of "div" tags makes it possible to display the entries in
1297 any form you wish, using a CSS style.
1299 Also, an .RDF file can be generated from your journal by publishing it
1300 with the "rdf" style. It uses the first two sentences of the first
1301 paragraph of each entry as its "description", and auto-generates tags
1302 for linking to the various entries.
1304 @subsubheading Styles provided
1308 @cindex publishing styles, journal-html
1310 Publish journal entries as an HTML document.
1312 @cindex publishing styles, journal-xhtml
1314 Publish journal entries as an XHTML document.
1316 @cindex publishing styles, journal-latex
1318 Publish journal entries as a LaTeX document.
1320 @cindex publishing styles, journal-pdf
1322 Publish journal entries as a PDF document.
1324 @cindex publishing styles, journal-book-latex
1325 @item journal-book-latex
1326 Publish journal entries as a LaTeX book.
1328 @cindex publishing styles, journal-book-pdf
1329 @item journal-book-pdf
1330 Publish journal entries as a PDF book.
1332 @cindex publishing styles, journal-rdf
1333 @cindex publishing styles, RSS 1.0
1335 Publish journal entries as an RDF file (RSS 1.0).
1337 @cindex publishing styles, journal-rss
1338 @cindex publishing styles, RSS 2.0
1340 Publish journal entries as an RSS file (RSS 2.0).
1344 @subsubheading Options provided
1348 @item muse-journal-heading-regexp
1349 A regexp that matches a journal heading.
1351 Paren group 1 is the ISO date, group 2 is the optional category, and
1352 group 3 is the optional heading for the entry.
1354 @item muse-journal-date-format
1355 Date format to use for journal entries.
1357 @item muse-journal-html-heading-regexp
1358 A regexp that matches a journal heading from an HTML document.
1360 Paren group 1 is the ISO date, group 2 is the optional category, and
1361 group 3 is the optional heading for the entry.
1363 @item muse-journal-html-entry-template
1364 Template used to publish individual journal entries as HTML.
1366 @item muse-journal-latex-section
1367 Template used to publish a LaTeX section.
1369 @item muse-journal-latex-subsection
1370 Template used to publish a LaTeX subsection.
1372 @item muse-journal-latex-markup-tags
1373 A list of tag specifications, for specially marking up LaTeX.
1375 @xref{muse-publish-markup-tags}, for more information.
1377 @item muse-journal-rdf-extension
1378 Default file extension for publishing RDF (RSS 1.0) files.
1380 @item muse-journal-rdf-base-url
1381 The base URL of the website referenced by the RDF file.
1383 @item muse-journal-rdf-header
1384 Header used for publishing RDF (RSS 1.0) files.
1386 This may be text or a filename.
1388 @item muse-journal-rdf-footer
1389 Footer used for publishing RDF (RSS 1.0) files.
1391 This may be text or a filename.
1393 @item muse-journal-rdf-date-format
1394 Date format to use for RDF entries.
1396 @item muse-journal-rdf-entry-template
1397 Template used to publish individual journal entries as RDF.
1399 @item muse-journal-rdf-summarize-entries
1400 If non-nil, include only summaries in the RDF file, not the full data.
1402 @item muse-journal-rss-extension
1403 Default file extension for publishing RSS 2.0 files.
1405 @item muse-journal-rss-base-url
1406 The base URL of the website referenced by the RSS file.
1408 @item muse-journal-rss-header
1409 Header used for publishing RSS 2.0 files.
1411 This may be text or a filename.
1413 @item muse-journal-rss-footer
1414 Footer used for publishing RSS 2.0 files.
1416 This may be text or a filename.
1418 @item muse-journal-rss-date-format
1419 Date format to use for RSS 2.0 entries.
1421 @item muse-journal-rss-entry-template
1422 Template used to publish individual journal entries as RSS 2.0.
1424 @item muse-journal-rss-enclosure-types-alist
1425 File types that are accepted as RSS enclosures.
1427 This is an alist that maps file extension to content type.
1429 Useful for podcasting.
1431 @item muse-journal-rss-summarize-entries
1432 If non-nil, include only summaries in the RSS file, not the full data.
1434 Many RSS subscribers find this annoying.
1436 @item muse-journal-rss-markup-regexps
1437 List of markup rules for publishing a Muse journal page to RSS.
1439 For more information on the structure of this list,
1440 @xref{muse-publish-markup-regexps}.
1442 @item muse-journal-rss-markup-functions
1443 An alist of style types to custom functions for that kind of text.
1445 For more on the structure of this list,
1446 @xref{muse-publish-markup-functions}.
1450 @node LaTeX, Poem, Journal, Publishing Styles
1451 @comment node-name, next, previous, up
1452 @section Publishing LaTeX documents
1454 This publishing style is capable of producing LaTeX or PDF documents.
1456 If you wish to publish PDF documents, you will need to have a good TeX
1457 installation. For Debian, this can be accomplished by installing the
1458 ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1460 @subsubheading Styles provided
1464 @cindex publishing styles, latex
1466 Publish a LaTeX document.
1468 @cindex publishing styles, pdf
1470 Publish a PDF document, using an external LaTeX document conversion
1473 @cindex publishing styles, latexcjk
1475 Publish a LaTeX document with CJK (Chinese) encodings.
1477 @cindex publishing styles, pdfcjk
1479 Publish a PDF document with CJK (Chinese) encodings, using an external
1480 LaTeX document conversion tool.
1484 @subsubheading Options provided
1488 @item muse-latex-extension
1489 Default file extension for publishing LaTeX files.
1491 @item muse-latex-pdf-extension
1492 Default file extension for publishing LaTeX files to PDF.
1494 @item muse-latex-header
1495 Header used for publishing LaTeX files.
1497 This may be text or a filename.
1499 @item muse-latex-footer
1500 Footer used for publishing LaTeX files.
1502 This may be text or a filename.
1504 @item muse-latexcjk-header
1505 Header used for publishing LaTeX files (CJK).
1507 This may be text or a filename.
1509 @item muse-latexcjk-footer
1510 Footer used for publishing LaTeX files (CJK).
1512 This may be text or a filename.
1514 @item muse-latex-markup-regexps
1515 List of markup regexps for identifying regions in a Muse page.
1517 For more on the structure of this list,
1518 @xref{muse-publish-markup-regexps}.
1520 @item muse-latex-markup-functions
1521 An alist of style types to custom functions for that kind of text.
1523 For more on the structure of this list,
1524 @xref{muse-publish-markup-functions}.
1526 @item muse-latex-markup-strings
1527 Strings used for marking up text.
1529 These cover the most basic kinds of markup, the handling of which
1530 differs little between the various styles.
1532 @item muse-latexcjk-encoding-map
1533 An alist mapping emacs coding systems to appropriate CJK codings.
1534 Use the base name of the coding system (ie, without the -unix).
1536 @item muse-latexcjk-encoding-default
1537 The default Emacs buffer encoding to use in published files.
1539 This will be used if no special characters are found.
1541 @item muse-latex-markup-specials
1542 A table of characters which must be represented specially.
1546 @node Poem, Texinfo, LaTeX, Publishing Styles
1547 @comment node-name, next, previous, up
1548 @section Publish a poem to LaTex or PDF
1550 The @code{muse-poem} module makes it easy to attractively publish and
1551 reference poems in the following format, using the "memoir" module for
1552 LaTeX publishing. It will also markup poems for every other output
1553 style, though none are nearly as pretty.
1562 Annotations, history, notes, etc.
1565 Once a poem is written in this format, just publish it to PDF using the
1566 @code{poem-pdf} style. To make an inlined reference to a poem that
1567 you've written -- for example, from a blog page -- there is a "poem" tag
1568 defined by this module.
1571 <poem title="name.of.poem.page">
1574 Let's assume the template above was called @file{name.of.poem.page};
1575 then the above tag would result in this inclusion.
1583 John Wiegley uses this module for publishing all of the poems on his
1584 website, which are at
1585 @uref{http://www.newartisans.com/johnw/poems.html}.
1587 @subsubheading Styles provided
1591 @cindex publishing styles, poem-latex
1593 Publish a poem in LaTeX form.
1595 @cindex publishing styles, poem-pdf
1597 Publish a poem to a PDF document.
1599 @cindex publishing styles, chapbook-latex
1600 @item chapbook-latex
1601 Publish a book of poems in LaTeX form.
1603 @cindex publishing styles, chapbook-pdf
1605 Publish a book of poems to a PDF document.
1609 @subsubheading Options provided
1613 @item muse-poem-latex-header
1614 Header used for publishing LaTeX poems.
1616 This may be text or a filename.
1618 @item muse-poem-latex-footer
1619 Footer used for publishing LaTeX files.
1621 This may be text or a filename.
1623 @item muse-poem-markup-strings
1624 Strings used for marking up poems.
1626 These cover the most basic kinds of markup, the handling of which
1627 differs little between the various styles.
1629 @item muse-chapbook-latex-header
1630 Header used for publishing a book of poems in LaTeX form.
1632 This may be text or a filename.
1634 @item muse-chapbook-latex-footer
1635 Footer used for publishing a book of poems in LaTeX form.
1637 This may be text or a filename.
1639 @item muse-poem-chapbook-strings
1640 Strings used for marking up books of poems.
1642 These cover the most basic kinds of markup, the handling of which
1643 differs little between the various styles.
1647 @node Texinfo, Common Elements, Poem, Publishing Styles
1648 @comment node-name, next, previous, up
1649 @section Publish entries to Texinfo format or PDF
1651 Rules for publishing a Muse file as a Texinfo article.
1653 @subsubheading Styles provided
1657 @cindex publishing styles, texi
1659 Publish a file in Texinfo form.
1661 @cindex publishing styles, texi
1663 Generate an Info file from a Muse file.
1665 @cindex publishing styles, info-pdf
1667 Publish a file in PDF form.
1671 @subsubheading Options provided
1675 @item muse-texinfo-process-natively
1676 If non-nil, use the Emacs `texinfmt' module to make Info files.
1678 @item muse-texinfo-extension
1679 Default file extension for publishing Texinfo files.
1681 @item muse-texinfo-info-extension
1682 Default file extension for publishing Info files.
1684 @item muse-texinfo-pdf-extension
1685 Default file extension for publishing PDF files.
1687 @item muse-texinfo-header
1688 Text to prepend to a Muse page being published as Texinfo.
1690 This may be text or a filename.
1691 It may contain @verb{|<lisp>|} markup tags.
1693 @item muse-texinfo-footer
1694 Text to append to a Muse page being published as Texinfo.
1696 This may be text or a filename.
1697 It may contain @verb{|<lisp>|} markup tags.
1699 @item muse-texinfo-markup-regexps
1700 List of markup rules for publishing a Muse page to Texinfo.
1702 For more on the structure of this list,
1703 @xref{muse-publish-markup-regexps}.
1705 @item muse-texinfo-markup-functions
1706 An alist of style types to custom functions for that kind of text.
1708 For more on the structure of this list, see
1709 @xref{muse-publish-markup-functions}.
1711 @item muse-texinfo-markup-strings
1712 Strings used for marking up text.
1714 These cover the most basic kinds of markup, the handling of which
1715 differs little between the various styles.
1717 @item muse-texinfo-markup-specials
1718 A table of characters which must be represented specially.
1722 @node Common Elements, Deriving Styles, Texinfo, Publishing Styles
1723 @comment node-name, next, previous, up
1724 @section Common functionality shared by styles
1725 @cindex publishing styles, common
1728 * Markup Functions:: Specifying functions to marking up text.
1729 * Markup Regexps:: Markup rules for publishing.
1730 * Markup Strings:: Strings specific to a publishing style.
1731 * Markup Tags:: Tag specifications for special markup.
1734 @node Markup Functions, Markup Regexps, , Common Elements
1735 @comment node-name, next, previous, up
1736 @subsection Specifying functions to mark up text
1737 @cindex publishing, markup functions
1739 @anchor{muse-publish-markup-functions}
1740 @code{muse-publish-markup-functions}
1742 An alist of style types to custom functions for that kind of text.
1744 This is used by publishing styles to attempt to minimize the amount of
1745 custom regexps that each has to define. @file{muse-publish} provides
1746 rules for the most common types of markup.
1748 Each member of the list is of the following form.
1756 Describes the type of text to associate with this rule.
1757 @code{muse-publish-markup-regexps} maps regexps to these symbols.
1760 Function to use to mark up this kind of rule if no suitable function is
1761 found through the @option{:functions} tag of the current style.
1764 @c PRE302: Explain :functions
1766 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
1767 @comment node-name, next, previous, up
1768 @subsection Markup rules for publishing
1769 @cindex publishing, markup regexps
1770 @cindex publishing, rules
1772 @anchor{muse-publish-markup-regexps}
1773 @code{muse-publish-markup-regexps}
1775 List of markup rules for publishing a page with Muse.
1777 The rules given in this variable are invoked first, followed by whatever
1778 rules are specified by the current style.
1780 Each member of the list is either a function, or a list of the following
1784 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1789 A regular expression, or symbol whose value is a regular expression,
1790 which is searched for using `re-search-forward'.
1792 @item TEXT-BEGIN-GROUP
1793 The matching group within that regexp which denotes the beginning of the
1794 actual text to be marked up.
1796 @item REPLACEMENT-TEXT
1797 A string that will be passed to `replace-match'.
1799 If it is not a string, but a function, it will be called to determine
1800 what the replacement text should be (it must return a string). If it is
1801 a symbol, the value of that symbol should be a string.
1804 The replacements are done in order, one rule at a time. Writing
1805 the regular expressions can be a tricky business. Note that case
1806 is never ignored. `case-fold-search' is always bound to nil
1807 while processing the markup rules.
1809 @subsubheading Publishing order
1811 This is the order that the publishing rules are consulted, by default.
1812 This may be changed by customizing @code{muse-publish-markup-regexps}.
1816 @item trailing and leading whitespace
1817 Remove trailing and leading whitespace from a file.
1822 This is only recognized at the beginning of a file.
1833 @item explicit links
1834 Prevent emphasis characters in explicit links from being marked up.
1836 Don't actually publish them here, just add a special no-emphasis text
1840 Whitespace-delimited word, possibly with emphasis characters
1842 This function is responsible for marking up emphasis and escaping some
1853 Outline-mode style headings.
1858 These are ellipses with a dot at end.
1868 Horizontal rule or section separator.
1873 beginning of footnotes section
1878 Footnote definition or reference. If at beginning of line, it is a
1893 Numbered list, item list, or term definition list.
1896 spaces before beginning of text
1904 @samp{table | cells}
1907 @samp{[[explicit][links]]}
1910 @samp{http://example.com/}
1913 @samp{bare-email@@example.com}
1917 @c PRE302: Explain :regexps and inheritance
1919 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
1920 @comment node-name, next, previous, up
1921 @subsection Strings specific to a publishing style
1922 @cindex publishing, markup strings
1924 @c PRE302: description of :strings goes here
1926 @node Markup Tags, , Markup Strings, Common Elements
1927 @comment node-name, next, previous, up
1928 @subsection Tag specifications for special markup
1929 @cindex publishing, markup tags
1931 @anchor{muse-publish-markup-tags}
1932 @code{muse-publish-markup-tags}
1934 A list of tag specifications, for specially marking up text.
1936 XML-style tags are the best way to add custom markup to Muse. This is
1937 easily accomplished by customizing this list of markup tags.
1939 For each entry, the name of the tag is given, whether it expects a
1940 closing tag and/or an optional set of attributes, and a function that
1941 performs whatever action is desired within the delimited region.
1943 The tags themselves are deleted during publishing, before the function
1944 is called. The function is called with three arguments, the beginning
1945 and end of the region surrounded by the tags. If properties are
1946 allowed, they are passed as a third argument in the form of an alist.
1947 The `end' argument to the function is always a marker.
1949 Point is always at the beginning of the region within the tags, when the
1950 function is called. Wherever point is when the function finishes is
1951 where tag markup will resume.
1953 These tag rules are processed once at the beginning of markup, and once
1954 at the end, to catch any tags which may have been inserted in-between.
1956 @c PRE302: Explain :tags
1958 @node Deriving Styles, , Common Elements, Publishing Styles
1959 @comment node-name, next, previous, up
1960 @section Deriving a new style from an existing one
1961 @cindex publishing styles, deriving
1963 To create a new style from an existing one, use @code{muse-derive-style}
1964 as follows. This is a good way to fix something you don't like about a
1965 particular publishing style, or to personalize it.
1968 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
1971 The derived name is a string defining the new style, such as "my-html".
1972 The base name must identify an existing style, such as "html" -- if you
1973 have loaded @file{muse-html}. The style parameters are the same as
1974 those used to create a style, except that they override whatever
1975 definitions exist in the base style. However, some definitions only
1976 partially override. The following parameters support partial
1981 @c PRE302: Explain all of these
1984 If a markup function is not found in the derived style's function list,
1985 the base style's function list will be queried.
1988 If a markup string is not found in the derived style's string list, the
1989 base style's string list will be queried.
1992 If this option is specified, it will be consulted rather than the
1993 corresponding value in the derived style. This applies to the following
2003 @node Getting Help and Reporting Bugs, History, Publishing Styles, Top
2004 @comment node-name, next, previous, up
2005 @chapter Getting Help and Reporting Bugs
2006 @cindex help, getting
2007 @cindex bugs, reporting
2009 After you have read this guide, if you still have questions about
2010 Muse, or if you have bugs to report, there are several places you can
2016 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
2017 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2021 @uref{http://www.mwolson.org/projects/MuseMode.html} is the web page
2022 that Michael Olson (the current maintainer) made for Muse.
2025 You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
2026 using the subscription form at
2027 @uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
2028 This mailing list provides support for Muse, @command{Planner} and
2029 @command{emacs-wiki}, which is the predecessor of Muse.
2031 There are additional methods for accessing the mailing list, adding
2032 content to it, and searching it. Consult
2033 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
2037 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2038 contributors are frequently around and willing to answer your
2039 questions. The @samp{#muse} channel is also available for
2040 Muse-specific help, and its current maintainer hangs out there.
2043 The maintainer of MuseMode, Michael Olson, may be contacted at
2044 @email{mwolson@@gnu.org}.
2048 @node History, Contributors, Getting Help and Reporting Bugs, Top
2049 @comment node-name, next, previous, up
2050 @chapter History of This Document
2051 @cindex history, of Muse
2055 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2056 limitations. Around February 2004, he started making "emacs-wiki version
2057 3.00 APLHA", which eventually became known as Muse.
2059 Most of those who frequent the emacs-wiki mailing list continued to use
2060 emacs-wiki, mainly because Planner hasn't been ported over to it.
2062 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2063 John Wiegley's request.
2066 Michael Olson overhauled this document and added many new sections in
2067 preparation for the first release of Muse (3.01).
2071 @node Contributors, GNU General Public License, History, Top
2072 @comment node-name, next, previous, up
2073 @chapter Contributors to This Documentation
2074 @cindex contributors
2076 The first draft of this document was taken from the emacs-wiki texinfo
2077 manual. Michael Olson adapted it for Muse and added most of its
2080 John Sullivan did a majority of the work on the emacs-wiki texinfo
2083 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2084 emacs-wiki texinfo manual.
2086 @node GNU General Public License, Concept Index, Contributors, Top
2087 @comment node-name, next, previous, up
2088 @appendix GNU GENERAL PUBLIC LICENSE
2089 @center Version 2, June 1991
2091 @cindex GNU General Public License
2093 @c This file is intended to be included in another file.
2096 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2097 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2099 Everyone is permitted to copy and distribute verbatim copies
2100 of this license document, but changing it is not allowed.
2103 @appendixsec Preamble
2105 The licenses for most software are designed to take away your
2106 freedom to share and change it. By contrast, the GNU General Public
2107 License is intended to guarantee your freedom to share and change free
2108 software---to make sure the software is free for all its users. This
2109 General Public License applies to most of the Free Software
2110 Foundation's software and to any other program whose authors commit to
2111 using it. (Some other Free Software Foundation software is covered by
2112 the GNU Library General Public License instead.) You can apply it to
2115 When we speak of free software, we are referring to freedom, not
2116 price. Our General Public Licenses are designed to make sure that you
2117 have the freedom to distribute copies of free software (and charge for
2118 this service if you wish), that you receive source code or can get it
2119 if you want it, that you can change the software or use pieces of it
2120 in new free programs; and that you know you can do these things.
2122 To protect your rights, we need to make restrictions that forbid
2123 anyone to deny you these rights or to ask you to surrender the rights.
2124 These restrictions translate to certain responsibilities for you if you
2125 distribute copies of the software, or if you modify it.
2127 For example, if you distribute copies of such a program, whether
2128 gratis or for a fee, you must give the recipients all the rights that
2129 you have. You must make sure that they, too, receive or can get the
2130 source code. And you must show them these terms so they know their
2133 We protect your rights with two steps: (1) copyright the software, and
2134 (2) offer you this license which gives you legal permission to copy,
2135 distribute and/or modify the software.
2137 Also, for each author's protection and ours, we want to make certain
2138 that everyone understands that there is no warranty for this free
2139 software. If the software is modified by someone else and passed on, we
2140 want its recipients to know that what they have is not the original, so
2141 that any problems introduced by others will not reflect on the original
2142 authors' reputations.
2144 Finally, any free program is threatened constantly by software
2145 patents. We wish to avoid the danger that redistributors of a free
2146 program will individually obtain patent licenses, in effect making the
2147 program proprietary. To prevent this, we have made it clear that any
2148 patent must be licensed for everyone's free use or not licensed at all.
2150 The precise terms and conditions for copying, distribution and
2151 modification follow.
2154 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2157 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2162 This License applies to any program or other work which contains
2163 a notice placed by the copyright holder saying it may be distributed
2164 under the terms of this General Public License. The ``Program'', below,
2165 refers to any such program or work, and a ``work based on the Program''
2166 means either the Program or any derivative work under copyright law:
2167 that is to say, a work containing the Program or a portion of it,
2168 either verbatim or with modifications and/or translated into another
2169 language. (Hereinafter, translation is included without limitation in
2170 the term ``modification''.) Each licensee is addressed as ``you''.
2172 Activities other than copying, distribution and modification are not
2173 covered by this License; they are outside its scope. The act of
2174 running the Program is not restricted, and the output from the Program
2175 is covered only if its contents constitute a work based on the
2176 Program (independent of having been made by running the Program).
2177 Whether that is true depends on what the Program does.
2180 You may copy and distribute verbatim copies of the Program's
2181 source code as you receive it, in any medium, provided that you
2182 conspicuously and appropriately publish on each copy an appropriate
2183 copyright notice and disclaimer of warranty; keep intact all the
2184 notices that refer to this License and to the absence of any warranty;
2185 and give any other recipients of the Program a copy of this License
2186 along with the Program.
2188 You may charge a fee for the physical act of transferring a copy, and
2189 you may at your option offer warranty protection in exchange for a fee.
2192 You may modify your copy or copies of the Program or any portion
2193 of it, thus forming a work based on the Program, and copy and
2194 distribute such modifications or work under the terms of Section 1
2195 above, provided that you also meet all of these conditions:
2199 You must cause the modified files to carry prominent notices
2200 stating that you changed the files and the date of any change.
2203 You must cause any work that you distribute or publish, that in
2204 whole or in part contains or is derived from the Program or any
2205 part thereof, to be licensed as a whole at no charge to all third
2206 parties under the terms of this License.
2209 If the modified program normally reads commands interactively
2210 when run, you must cause it, when started running for such
2211 interactive use in the most ordinary way, to print or display an
2212 announcement including an appropriate copyright notice and a
2213 notice that there is no warranty (or else, saying that you provide
2214 a warranty) and that users may redistribute the program under
2215 these conditions, and telling the user how to view a copy of this
2216 License. (Exception: if the Program itself is interactive but
2217 does not normally print such an announcement, your work based on
2218 the Program is not required to print an announcement.)
2221 These requirements apply to the modified work as a whole. If
2222 identifiable sections of that work are not derived from the Program,
2223 and can be reasonably considered independent and separate works in
2224 themselves, then this License, and its terms, do not apply to those
2225 sections when you distribute them as separate works. But when you
2226 distribute the same sections as part of a whole which is a work based
2227 on the Program, the distribution of the whole must be on the terms of
2228 this License, whose permissions for other licensees extend to the
2229 entire whole, and thus to each and every part regardless of who wrote it.
2231 Thus, it is not the intent of this section to claim rights or contest
2232 your rights to work written entirely by you; rather, the intent is to
2233 exercise the right to control the distribution of derivative or
2234 collective works based on the Program.
2236 In addition, mere aggregation of another work not based on the Program
2237 with the Program (or with a work based on the Program) on a volume of
2238 a storage or distribution medium does not bring the other work under
2239 the scope of this License.
2242 You may copy and distribute the Program (or a work based on it,
2243 under Section 2) in object code or executable form under the terms of
2244 Sections 1 and 2 above provided that you also do one of the following:
2248 Accompany it with the complete corresponding machine-readable
2249 source code, which must be distributed under the terms of Sections
2250 1 and 2 above on a medium customarily used for software interchange; or,
2253 Accompany it with a written offer, valid for at least three
2254 years, to give any third party, for a charge no more than your
2255 cost of physically performing source distribution, a complete
2256 machine-readable copy of the corresponding source code, to be
2257 distributed under the terms of Sections 1 and 2 above on a medium
2258 customarily used for software interchange; or,
2261 Accompany it with the information you received as to the offer
2262 to distribute corresponding source code. (This alternative is
2263 allowed only for noncommercial distribution and only if you
2264 received the program in object code or executable form with such
2265 an offer, in accord with Subsection b above.)
2268 The source code for a work means the preferred form of the work for
2269 making modifications to it. For an executable work, complete source
2270 code means all the source code for all modules it contains, plus any
2271 associated interface definition files, plus the scripts used to
2272 control compilation and installation of the executable. However, as a
2273 special exception, the source code distributed need not include
2274 anything that is normally distributed (in either source or binary
2275 form) with the major components (compiler, kernel, and so on) of the
2276 operating system on which the executable runs, unless that component
2277 itself accompanies the executable.
2279 If distribution of executable or object code is made by offering
2280 access to copy from a designated place, then offering equivalent
2281 access to copy the source code from the same place counts as
2282 distribution of the source code, even though third parties are not
2283 compelled to copy the source along with the object code.
2286 You may not copy, modify, sublicense, or distribute the Program
2287 except as expressly provided under this License. Any attempt
2288 otherwise to copy, modify, sublicense or distribute the Program is
2289 void, and will automatically terminate your rights under this License.
2290 However, parties who have received copies, or rights, from you under
2291 this License will not have their licenses terminated so long as such
2292 parties remain in full compliance.
2295 You are not required to accept this License, since you have not
2296 signed it. However, nothing else grants you permission to modify or
2297 distribute the Program or its derivative works. These actions are
2298 prohibited by law if you do not accept this License. Therefore, by
2299 modifying or distributing the Program (or any work based on the
2300 Program), you indicate your acceptance of this License to do so, and
2301 all its terms and conditions for copying, distributing or modifying
2302 the Program or works based on it.
2305 Each time you redistribute the Program (or any work based on the
2306 Program), the recipient automatically receives a license from the
2307 original licensor to copy, distribute or modify the Program subject to
2308 these terms and conditions. You may not impose any further
2309 restrictions on the recipients' exercise of the rights granted herein.
2310 You are not responsible for enforcing compliance by third parties to
2314 If, as a consequence of a court judgment or allegation of patent
2315 infringement or for any other reason (not limited to patent issues),
2316 conditions are imposed on you (whether by court order, agreement or
2317 otherwise) that contradict the conditions of this License, they do not
2318 excuse you from the conditions of this License. If you cannot
2319 distribute so as to satisfy simultaneously your obligations under this
2320 License and any other pertinent obligations, then as a consequence you
2321 may not distribute the Program at all. For example, if a patent
2322 license would not permit royalty-free redistribution of the Program by
2323 all those who receive copies directly or indirectly through you, then
2324 the only way you could satisfy both it and this License would be to
2325 refrain entirely from distribution of the Program.
2327 If any portion of this section is held invalid or unenforceable under
2328 any particular circumstance, the balance of the section is intended to
2329 apply and the section as a whole is intended to apply in other
2332 It is not the purpose of this section to induce you to infringe any
2333 patents or other property right claims or to contest validity of any
2334 such claims; this section has the sole purpose of protecting the
2335 integrity of the free software distribution system, which is
2336 implemented by public license practices. Many people have made
2337 generous contributions to the wide range of software distributed
2338 through that system in reliance on consistent application of that
2339 system; it is up to the author/donor to decide if he or she is willing
2340 to distribute software through any other system and a licensee cannot
2343 This section is intended to make thoroughly clear what is believed to
2344 be a consequence of the rest of this License.
2347 If the distribution and/or use of the Program is restricted in
2348 certain countries either by patents or by copyrighted interfaces, the
2349 original copyright holder who places the Program under this License
2350 may add an explicit geographical distribution limitation excluding
2351 those countries, so that distribution is permitted only in or among
2352 countries not thus excluded. In such case, this License incorporates
2353 the limitation as if written in the body of this License.
2356 The Free Software Foundation may publish revised and/or new versions
2357 of the General Public License from time to time. Such new versions will
2358 be similar in spirit to the present version, but may differ in detail to
2359 address new problems or concerns.
2361 Each version is given a distinguishing version number. If the Program
2362 specifies a version number of this License which applies to it and ``any
2363 later version'', you have the option of following the terms and conditions
2364 either of that version or of any later version published by the Free
2365 Software Foundation. If the Program does not specify a version number of
2366 this License, you may choose any version ever published by the Free Software
2370 If you wish to incorporate parts of the Program into other free
2371 programs whose distribution conditions are different, write to the author
2372 to ask for permission. For software which is copyrighted by the Free
2373 Software Foundation, write to the Free Software Foundation; we sometimes
2374 make exceptions for this. Our decision will be guided by the two goals
2375 of preserving the free status of all derivatives of our free software and
2376 of promoting the sharing and reuse of software generally.
2379 @heading NO WARRANTY
2386 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2387 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2388 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2389 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2390 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2391 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2392 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2393 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2394 REPAIR OR CORRECTION.
2397 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2398 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2399 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2400 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2401 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2402 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2403 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2404 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2405 POSSIBILITY OF SUCH DAMAGES.
2409 @heading END OF TERMS AND CONDITIONS
2412 @center END OF TERMS AND CONDITIONS
2416 @appendixsec Appendix: How to Apply These Terms to Your New Programs
2418 If you develop a new program, and you want it to be of the greatest
2419 possible use to the public, the best way to achieve this is to make it
2420 free software which everyone can redistribute and change under these terms.
2422 To do so, attach the following notices to the program. It is safest
2423 to attach them to the start of each source file to most effectively
2424 convey the exclusion of warranty; and each file should have at least
2425 the ``copyright'' line and a pointer to where the full notice is found.
2428 @var{one line to give the program's name and a brief idea of what it does.}
2429 Copyright (C) @var{yyyy} @var{name of author}
2431 This program is free software; you can redistribute it and/or modify
2432 it under the terms of the GNU General Public License as published by
2433 the Free Software Foundation; either version 2 of the License, or
2434 (at your option) any later version.
2436 This program is distributed in the hope that it will be useful,
2437 but WITHOUT ANY WARRANTY; without even the implied warranty of
2438 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2439 GNU General Public License for more details.
2441 You should have received a copy of the GNU General Public License along
2442 with this program; if not, write to the Free Software Foundation, Inc.,
2443 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2446 Also add information on how to contact you by electronic and paper mail.
2448 If the program is interactive, make it output a short notice like this
2449 when it starts in an interactive mode:
2452 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2453 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2454 This is free software, and you are welcome to redistribute it
2455 under certain conditions; type `show c' for details.
2458 The hypothetical commands @samp{show w} and @samp{show c} should show
2459 the appropriate parts of the General Public License. Of course, the
2460 commands you use may be called something other than @samp{show w} and
2461 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2464 You should also get your employer (if you work as a programmer) or your
2465 school, if any, to sign a ``copyright disclaimer'' for the program, if
2466 necessary. Here is a sample; alter the names:
2469 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2470 `Gnomovision' (which makes passes at compilers) written by James Hacker.
2472 @var{signature of Ty Coon}, 1 April 1989
2473 Ty Coon, President of Vice
2476 This General Public License does not permit incorporating your program into
2477 proprietary programs. If your program is a subroutine library, you may
2478 consider it more useful to permit linking proprietary applications with the
2479 library. If this is what you want to do, use the GNU Library General
2480 Public License instead of this License.
2483 @node Concept Index, , GNU General Public License, Top
2484 @comment node-name, next, previous, up
2492 @c ispell-local-pdict: "ispell-dict"