1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for the Emacs Muse version 3.02.6.
17 Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU 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 * Extending Muse:: Making your own publishing styles.
60 * Getting Help and Reporting Bugs::
61 * History:: History of this document.
62 * Contributors:: Contributors to this documentation.
63 * GNU General Public License:: The license for this manual and Muse.
64 * Concept Index:: Search for terms.
67 --- The Detailed Node Listing ---
69 How to Get Muse Releases and Development Changes
71 * Releases:: Released versions of Muse.
72 * Development:: Latest unreleased development changes.
74 Rules for Using Markup
76 * Paragraphs:: Paragraphs: centering and quoting.
77 * Headings:: Levels of headings.
78 * Directives:: Directives at the beginning of a
80 * Emphasizing Text:: Bold, italicized, and underlined text.
81 * Footnotes:: Making notes to be shown at the end.
82 * Verse:: Indicating poetic stanzas.
83 * Lists:: Lists of items.
84 * Tables:: Generation of data tables.
85 * Explicit Links:: Hyperlinks and email addresses with
87 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
89 * Images:: Publishing and displaying images.
90 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
91 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
93 * Comments:: Lines to omit from published output.
95 Publishing Various Types of Documents
97 * Blosxom:: Integrating Muse and pyblosxom.cgi.
98 * Book:: Publishing entries into a compilation.
99 * DocBook:: Publishing in DocBook XML form.
100 * HTML:: Publishing in HTML or XHTML form.
101 * Journal:: Keeping a journal or blog.
102 * LaTeX:: Publishing LaTeX documents.
103 * Poem:: Publish a poem to LaTex or PDF.
104 * Texinfo:: Publish entries to Texinfo format or PDF.
106 Integrating Muse and pyblosxom.cgi
108 * Blosxom Requirements:: Other tools needed to the Blosxom style.
109 * Blosxom Entries:: Format of a Blosxom entry and automation.
110 * Blosxom Options:: Blosxom styles and options provided.
112 Making your own publishing styles
114 * Common Elements:: Common functionality shared by styles.
115 * Deriving Styles:: Deriving a new style from an existing
118 Common functionality shared by styles
120 * Markup Functions:: Specifying functions to marking up text.
121 * Markup Regexps:: Markup rules for publishing.
122 * Markup Strings:: Strings specific to a publishing style.
123 * Markup Tags:: Tag specifications for special markup.
124 * Style Elements:: Parameters used for defining styles.
129 @node Preface, Introduction, Top, Top
130 @comment node-name, next, previous, up
131 @chapter About the documentation
133 This document describes Muse, which was written by John Wiegley
134 and is now maintained by Michael Olson. Several versions of it are
138 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
139 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
140 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
143 @node Introduction, Obtaining Muse, Preface, Top
144 @comment node-name, next, previous, up
145 @chapter What is Muse?
147 Emacs Muse is an authoring and publishing environment for Emacs. It
148 simplifies the process of writing documents and publishing them to
149 various output formats.
151 Muse consists of two main parts: an enhanced text-mode for authoring
152 documents and navigating within Muse projects, and a set of publishing
153 styles for generating different kinds of output.
155 This idea is not in any way new. Numerous systems exist -- even one
156 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
157 more modular environment, with a rather simple core, in which "styles"
158 are derived from to create new styles. Much of Muse's overall
159 functionality is optional. For example, you can use the publisher
160 without the major-mode, or the mode without doing any publishing; or if
161 you don't load the Texinfo or LaTeX modules, those styles won't be
164 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
165 code has been restructured and rewritten, especially its publishing
166 functions. The focus in this revision is on the authoring and publishing
167 aspects, and the "wikiness" has been removed as a default behavior
168 (available in the optional @file{muse-wiki} module). CamelCase words are
169 no longer special by default.
171 @node Obtaining Muse, Installation, Introduction, Top
172 @comment node-name, next, previous, up
173 @chapter How to Get Muse Releases and Development Changes
176 * Releases:: Released versions of Muse.
177 * Development:: Latest unreleased development changes.
180 @node Releases, Development, Obtaining Muse, Obtaining Muse
181 @comment node-name, next, previous, up
182 @section Released versions of Muse
184 Choose to install a release if you want to minimize risk.
186 Errors are corrected in development first. User-visible changes will be
187 announced on the @email{emacs-wiki-discuss@@nongnu.org} mailing list.
188 This mailing list also provides support for @command{Planner} and
189 @command{emacs-wiki}, which is the predecessor of Muse.
190 @pxref{Getting Help and Reporting Bugs}.
192 @cindex releases, Debian package
193 @cindex Debian package for Muse
194 Debian users can get Muse via apt-get. The @file{muse-el} package is
195 available both at Michael Olson's Debian repository and the official
196 Debian repository. To make use of the former, add the following line to
197 your @file{/etc/apt/sources.list} file and run @code{apt-get install
201 deb http://www.mwolson.org/debian/ ./
204 @cindex releases, from source
205 Alternatively, you can download the latest release from
206 @uref{http://www.mwolson.org/static/dist/muse/} .
208 @node Development, , Releases, Obtaining Muse
209 @comment node-name, next, previous, up
210 @section Latest unreleased development changes
213 Choose the development version if you want to live on the bleeding edge
214 of Muse development or try out new features before release.
216 @cindex arch revision control system, using
217 The Arch revision control system allows you to retrieve previous
218 versions and select specific features and bug fixes. If you would like
219 to contribute to Muse development, it is highly recommended that you use
220 Arch, but this is not a requirement.
222 If you are new to Arch, you might find this tutorial helpful:
223 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
225 Downloading the Muse module with Arch and staying up-to-date involves
232 @item Debian: @kbd{apt-get install tla}.
233 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
236 @item Register the archive.
238 tla register-archive -f http://www.mwolson.org/archives/2005
241 @item Download the Muse package.
243 # Download Muse into the @file{muse} directory.
244 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
247 @item List upstream changes that are missing from your local copy.
248 Do this whenever you want to see whether new changes have been committed
252 # Change to the source directory you are interested in.
255 # Display the summary of changes
256 tla missing --summary
259 @cindex updating Muse with Arch
260 @item Update to the latest version by replaying missing changes.
268 There are other ways to interact with the Muse archive.
271 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
272 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
275 The latest development snapshot will be kept up-to-date since it is
276 updated at the same time as the Arch repository.
278 @node Installation, Getting Started, Obtaining Muse, Top
279 @comment node-name, next, previous, up
280 @chapter Compiling and Installing Muse
282 Muse may be compiled and installed on your machine.
284 @subsubheading Compilation
286 This is an optional step, since Emacs Lisp source code does not
287 necessarily have to be byte-compiled. It will yield a speed increase,
290 A working copy of Emacs or XEmacs is needed in order to compile the
291 Emacs Muse. By default, the program that is installed with the name
292 @command{emacs} will be used.
294 If you want to use the @command{xemacs} binary to perform the
295 compilation, you would need to edit @file{Makefile.defs} in the
296 top-level directory as follows. You can put either a full path to an
297 Emacs or XEmacs binary or just the command name, as long as it is in the
302 SITEFLAG = -no-site-file
305 Running @code{make} should compile the Muse source files in the
306 @file{lisp} directory.
308 @subsubheading Installation
310 Muse may be installed into your file hierarchy by doing the following.
312 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
313 where you want the source and compiled Muse files to be installed and
314 @env{INFODIR} indicates where to put the Muse manual. Of course, you
315 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
316 Compilation section if you are using XEmacs.
318 If you are installing Muse on a Debian system, you might want to change
319 the value of @env{INSTALLINFO} as specified in @file{Makefile.defs}.
321 If you wish to install Muse to different locations than the defaults
322 specify, edit @file{Makefile.defs} accordingly.
324 Run @code{make} as a normal user.
326 Run @code{make install} as the root user if you have chosen installation
327 locations that require this.
330 @node Getting Started, Projects, Installation, Top
331 @comment node-name, next, previous, up
332 @chapter Getting Started
335 To use Muse, add the directory containing its files to your
336 @code{load-path} variable, in your @file{.emacs} file. Then, load in
337 the authoring mode, and the styles you wish to publish to. An example
341 (add-to-list 'load-path "<path to Muse>")
343 (require 'muse-mode) ; load authoring mode
345 (require 'muse-html) ; load publishing styles I use
346 (require 'muse-latex)
347 (require 'muse-texinfo)
348 (require 'muse-docbook)
351 Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
352 an input document to any available style. If you enable
353 @file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
354 command will be bound to @kbd{C-c C-t}.
356 If the currently opened file is part of a defined project in
357 @code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
359 You should also type @kbd{M-x customize-group}, and give the name
360 @samp{muse}. Each of the options has its own documentation.
363 @node Projects, Keystroke Summary, Getting Started, Top
364 @comment node-name, next, previous, up
365 @chapter Creating and Managing Muse Projects
368 Often you will want to publish all the files within a directory to a
369 particular set of output styles automatically. To support, Muse
370 allows for the creations of "projects". Here is a sample project, to
371 be defined in your @file{.emacs} file.
374 (require 'muse-project)
376 (setq muse-project-alist
377 '(("website" ; my various writings
378 ("~/Pages" :default "index")
379 (:base "html" :path "~/public_html")
380 (:base "pdf" :path "~/public_html/pdf"))))
383 The above defines a project named "website", whose files are located
384 in the directory @file{~/Pages}. The default page to visit is
385 @file{index}. When this project is published, each page will be
386 output as HTML to the directory @file{~/public_html}, and as PDF to
387 the directory @file{~/public_html/pdf}. Within any project page, you
388 may create a link to other pages using the syntax @samp{[[pagename]]}.
390 By default, Muse expects all project files to have the file extension
391 @file{.muse}. Files without this extension will not be associated with
392 Muse mode and will not be considered part of any project, even if they
393 are within a project directory.
395 If you don't want to use @file{.muse}, you can customize the extension
396 by setting the value of @code{muse-file-extension}.
398 If you don't want to use any extension at all, and want Muse to
399 autodetect project files based on their location, then use:
402 (setq muse-file-extension nil
406 If you set these options directly in your @file{.emacs} outside of the
407 Customize interface, then you will also need to add:
410 (add-hook 'find-file-hooks 'muse-mode-maybe)
413 @c PRE3_03: Give more examples
414 @c PRE3_03: Describe :set and other options fully
416 @node Keystroke Summary, Markup Rules, Projects, Top
417 @comment node-name, next, previous, up
418 @chapter Keys Used in Muse Mode
421 This is a summary of keystrokes available in every Muse buffer.
425 @item C-c C-a (`muse-index')
426 Display an index of all known Muse pages.
428 @item C-c C-b (`muse-browse-result')
429 Show the published result of this page.
431 @item C-c C-e (`muse-edit-link-at-point')
434 @item C-c C-f (`muse-project-find-file'), also C-c C-v
435 Open another Muse page. Prompt for the name.
437 @item C-c C-l (`font-lock-mode')
438 Highlight/refresh the current buffer.
440 @item C-c C-p (`muse-project-publish')
441 Publish any Muse pages that have changed.
443 @item C-c C-v (`muse-project-find-file'), also C-c C-f
444 Open another Muse page. Prompt for the name.
446 @item C-c = (`muse-what-changed')
447 Diff this page against the last backup version.
449 @item C-c TAB (`muse-insert-tag')
450 Insert a tag interactively.
453 Move to the next Wiki reference.
456 Move to the previous Wiki reference.
461 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
462 @comment node-name, next, previous, up
463 @chapter Rules for Using Markup
466 A Muse document uses special, contextual markup rules to determine how
467 to format the output result. For example, if a paragraph is indented,
468 Muse assumes it should be quoted.
470 There are not too many markup rules, and all of them strive to be as
471 simple as possible so that you can focus on document creation, rather
475 * Paragraphs:: Paragraphs: centering and quoting.
476 * Headings:: Levels of headings.
477 * Directives:: Directives at the beginning of a
479 * Emphasizing Text:: Bold, italicized, and underlined text.
480 * Footnotes:: Making notes to be shown at the end.
481 * Verse:: Indicating poetic stanzas.
482 * Lists:: Lists of items.
483 * Tables:: Generation of data tables.
484 * Explicit Links:: Hyperlinks and email addresses with
486 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
488 * Images:: Publishing and displaying images.
489 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
490 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
492 * Comments:: Lines to omit from published output.
495 @node Paragraphs, Headings, Markup Rules, Markup Rules
496 @comment node-name, next, previous, up
497 @section Paragraphs: centering and quoting
500 Paragraphs in Muse must be separated by a blank line.
502 @cindex paragraphs, centered
503 @strong{Centered paragraphs and quotations}
505 A line that begins with six or more columns of whitespace (either tabs
506 or spaces) indicates a centered paragraph.
508 @cindex paragraphs, quoted
510 But if a line begins with whitespace, though less than six columns, it
511 indicates a quoted paragraph.
514 @cindex monospace, rendering blocks
515 @cindex HTML, rendering blocks in monospace
516 @strong{Literal paragraphs}
518 The @verb{|<example>|} tag is used for examples, where whitespace should
519 be preserved, the text rendered in monospace, and any characters special
520 to the output style escaped.
523 @cindex HTML, inserting a raw block
524 There is also the @verb{|<literal>|} tag, which causes a marked block to
525 be entirely left alone. This can be used for inserting a hand-coded
526 HTML blocks into HTML output, for example.
528 @node Headings, Directives, Paragraphs, Markup Rules
529 @comment node-name, next, previous, up
530 @section Levels of headings
533 A heading becomes a chapter or section in printed output -- depending on
534 the style. To indicate a heading, start a new paragraph with one or
535 more asterices, followed by a space and the heading title. Then begin
536 another paragraph to enter the text for that section.
538 All levels of headings will be published. Most publishing styles only
539 distinguish the between the first 4 levels, however.
551 @node Directives, Emphasizing Text, Headings, Markup Rules
552 @comment node-name, next, previous, up
553 @section Directives at the beginning of a document
556 Directives are lines beginning with the @samp{#} character that come
557 before any paragraphs or sections in the document. Directives are of
558 the form ``#directive content of directive''. You can use any
559 combination of uppercase and lowercase letters for directives, even if
560 the directive is not in the list below.
562 The @code{muse-publishing-directive} function may be used in header and
563 footer text to access directives. For example, to access the
564 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
566 The following is a list of directives that Muse uses.
571 The author of this document.
573 If this is not specified, Muse will attempt to figure it out from the
574 @code{user-full-name} variable.
578 The date that the document was last modified.
580 This is used by publishing styles that are able to embed the date
585 A short description of this document.
587 This is used by the @code{journal} publishing style to embed information
588 inside of an RSS/RDF feed.
592 The title of this document.
594 If this is not specified, the name of the file is used.
598 @node Emphasizing Text, Footnotes, Directives, Markup Rules
599 @comment node-name, next, previous, up
600 @section Bold, italicized, and underlined text
601 @cindex emphasizing text
602 @cindex underlining text
603 @cindex italicizing text
604 @cindex verbatim text
605 @cindex monospace, rendering words
607 To emphasize text, surround it with certain specially recognized
613 ***very strong emphasis***
615 =verbatim and monospace=
619 While editing a Muse document in Muse mode, these forms of emphasis will
620 be highlighted in a WYSIWYG manner. Each of these forms may span
623 Verbatim text will be colored as gray by default. To change this,
624 customize @code{muse-verbatim-face}.
626 You can also use the @verb{|<code>|} tag to indicate verbatim and
627 monospace text. This is handy for regions that have an ``='' in them.
629 @node Footnotes, Verse, Emphasizing Text, Markup Rules
630 @comment node-name, next, previous, up
631 @section Making notes to be shown at the end
634 A footnote reference is simply a number in square brackets. To define
635 the footnote, place this definition at the bottom of your file.
636 @samp{footnote-mode} can be used to greatly facilitate the creation of
637 these kinds of footnotes.
639 Footnotes are defined by the same number in brackets occurring at the
640 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
641 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
642 the point of insertion.
644 @node Verse, Lists, Footnotes, Markup Rules
645 @comment node-name, next, previous, up
646 @section Indicating poetic stanzas
650 Poetry requires that whitespace be preserved, but without resorting to
651 monospace. To indicate this, use the following markup, reminiscent of
655 > A line of Emacs verse;
656 > forgive its being so terse.
659 You can also use the @verb{|<verse>|} tag, if you prefer.
663 A line of Emacs verse;
664 forgive its being so terse.
668 @cindex verses, multiple stanzas
669 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
674 A line of Emacs verse;
675 forgive its being so terse.
677 In terms of terse verse,
682 @node Lists, Tables, Verse, Markup Rules
683 @comment node-name, next, previous, up
684 @section Lists of items
687 Lists are given using special characters at the beginning of a line.
688 Whitespace must occur before bullets or numbered items, to distinguish
689 from the possibility of those characters occurring in a real sentence.
691 @cindex lists, bullets
692 These are rendered as a bullet list.
699 @cindex lists, enumerated
700 An enumerated list follows.
707 @cindex lists, definitions
708 Here is a definition list.
712 This is a first definition
713 And it has two lines;
717 This is a second definition
720 @node Tables, Explicit Links, Lists, Markup Rules
721 @comment node-name, next, previous, up
722 @section Generation of data tables
725 @cindex tables, simple
726 Only very simple tables are supported. The syntax is as follows.
729 Double bars || Separate header fields
731 Single bars | Separate body fields
732 Here are more | body fields
734 Triple bars ||| Separate footer fields
737 Some publishing styles require header fields to come first, then footer
738 fields, and then the body fields. You can use any order for these
739 sections that you like, and Muse will re-order them for you at
742 @node Explicit Links, Implicit Links, Tables, Markup Rules
743 @comment node-name, next, previous, up
744 @section Hyperlinks and email addresses with descriptions
745 @cindex links, explicit
747 A hyperlink can reference a URL, or another page within a Muse
748 project. In addition, descriptive text can be specified, which should
749 be displayed rather than the link text in output styles that supports
750 link descriptions. The syntax is as follows.
753 [[link target][link description]]
754 [[link target without description]]
757 Thus, the current maintainer's homepage for Muse can be found
758 @samp{[[http://www.mwolson.org/projects/EmacsMuse.html][here]]},
759 or at @samp{[[http://www.mwolson.org/projects/EmacsMuse.html]]}.
761 @node Implicit Links, Images, Explicit Links, Markup Rules
762 @comment node-name, next, previous, up
763 @section Bare URLs, WikiNames, and InterWiki links
764 @cindex links, implicit
767 @cindex Email addresses
769 A URL or email address encountered in the input text is published as a
770 hyperlink. These kind of links are called @dfn{implicit links} because
771 they are not separated from the rest of the Muse document in any way.
774 If the @command{muse-wiki} module is loaded, another form of implicit
775 link will be made available. WikiNames, which are typed in camelcase,
776 will be highlighted and published as links, provided that the file they
779 Customization of WikiName recognition may be accomplished by editing the
780 @code{muse-wiki-wikiword-regexp} option and subsequently running
781 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
782 If you use the Customize interface, the latter will be done
785 @cindex InterWiki links
786 @cindex inter-project links
787 The @command{muse-wiki} module also allows for InterWiki links. These
788 are similar to WikiWords, but they specify both the project and page of
789 a file. The names of your project entries in @code{muse-project-alist}
790 will be used as InterWiki names by default. Several examples follow.
793 Blog::DocumentingMuse
798 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
799 the project name, and @samp{DocumentingMuse} is the page name. In the
800 second example, @samp{#} is the interwiki delimiter. If the name of a
801 project occurs by itself in text, like the third case, it will be
802 colorized and published as a link to the default page of the given
805 Customization of interwiki links may be accomplished by editing the
806 @code{muse-wiki-interwiki-alist} option.
808 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
809 @comment node-name, next, previous, up
810 @section Publishing and displaying images
812 @cindex links, with images
815 Links to images may be used in either the target or the description, or
816 both. Thus, the following code will publish as a clickable image that
817 points to @url{http://www.mwolson.org/}.
820 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
823 @cindex images, displaying
824 @cindex images, inlined
825 @cindex images, local
826 If a link to a locally-available image is encountered in the link
827 description, Muse mode will attempt to display it if your version of
828 Emacs permits this. The following example will display correctly and
829 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
830 exists in the @file{../pics/} directory.
833 [[TestPage][../pics/TestLogo.png]]
836 @cindex images, without a description
837 An image link is not required to have a description. The link
838 @samp{[[../myimage.png]]} will display and publish as expected.
840 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
841 @comment node-name, next, previous, up
842 @section Inserting a horizontal line or anchor
844 @cindex horizontal rules
846 @strong{Horizontal Rules}
848 Four or more dashes indicate a horizontal rule. Be sure to put blank
849 lines around it, or it will be considered part of the proceeding or
853 @cindex links, with target on same page
856 If you begin a line with "#anchor" -- where "anchor" can be any word
857 that doesn't contain whitespace -- it defines an anchor at that point
858 into the document. This point can be referenced using "page#anchor" as
859 the target in a Muse link.
861 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
862 @comment node-name, next, previous, up
863 @section Evaluating Emacs Lisp code in documents for extensibility
864 @cindex lisp, embedded
866 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
867 which is the only Muse tag supported in a style's header and footer
868 text. With the @verb{|<lisp>|} tag, you may generated whatever output
869 text you wish. The inserted output will get marked up, if the
870 @verb{|<lisp>|} tag appears within the main text of the document.
873 <lisp>(concat "This form gets " "inserted")</lisp>
876 @cindex lisp, and insert command
877 Note that you should not use the @code{insert} command within a set of
878 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
879 tags will be automatically inserted into the document.
881 @node Comments, , Embedded Lisp, Markup Rules
882 @comment node-name, next, previous, up
883 @section Lines to omit from published output
885 @cindex publishing, omitting lines
887 Use the following syntax to indicate a comment. Comments will not be
891 ; Comment text goes here.
894 That is, only a semi-colon at the beginning of a line, followed by a
895 literal space, will cause that line to be treated as a comment.
897 @node Publishing Styles, Extending Muse, Markup Rules, Top
898 @comment node-name, next, previous, up
899 @chapter Publishing Various Types of Documents
900 @cindex publishing styles
902 One of the principle features of Muse is the ability to publish a simple
903 input text to a variety of different output styles. Muse also makes it
904 easy to create new styles, or derive from an existing style.
907 * Blosxom:: Integrating Muse and pyblosxom.cgi.
908 * Book:: Publishing entries into a compilation.
909 * DocBook:: Publishing in DocBook XML form.
910 * HTML:: Publishing in HTML or XHTML form.
911 * Journal:: Keeping a journal or blog.
912 * LaTeX:: Publishing LaTeX documents.
913 * Poem:: Publish a poem to LaTex or PDF.
914 * Texinfo:: Publish entries to Texinfo format or PDF.
917 @node Blosxom, Book, Publishing Styles, Publishing Styles
918 @comment node-name, next, previous, up
919 @section Integrating Muse and pyblosxom.cgi
920 @cindex blog, one-file-per-entry style
922 The Blosxom publishing style publishes a tree of categorised files to a
923 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
924 In other words, each blog entry corresponds with one file.
927 * Blosxom Requirements:: Other tools needed to the Blosxom style.
928 * Blosxom Entries:: Format of a Blosxom entry and automation.
929 * Blosxom Options:: Blosxom styles and options provided.
932 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
933 @comment node-name, next, previous, up
934 @subsection Other tools needed to the Blosxom style
936 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
937 installed on a machine that you have upload access to.
939 The following additional components are required in order to make the
940 date of blog entries display as something sensible.
944 A script to gather date directives from the entire blog tree into a
945 single file. The file must associate a blog entry with a date.
948 A plugin for (py)blosxom that reads this file.
951 These 2 things are provided for @command{pyblosxom.cgi} in the
952 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
953 former service, while @file{hardcodedates.py} provides the latter
954 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
955 script will be found/written.
957 Here is a sample listing from my @file{timestamps} file, which maps
958 each file to a date. This can really be in any format, as long as your
959 date-gathering script and your plugin can both understand it.
962 2005-04-01-14-16 personal/paper_cranes
963 2005-03-21 personal/spring_break_over
964 2004-10-24 personal/finished_free_culture
967 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
968 @comment node-name, next, previous, up
969 @subsection Format of a Blosxom entry and automation
971 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
972 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
973 plus whatever normal content is desired.
975 The date directive is not used directly by @command{pyblosxom.cgi} or
976 this program. You need to have the two additional items from the former
977 section to make use of this feature.
979 There is a function called @code{muse-blosxom-new-entry} that will
980 automate the process of making a new blog entry. To make use of it, do
985 Customize @code{muse-blosxom-base-directory} to the location that your
986 blog entries are stored.
989 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
990 use the following code to assign this function to @kbd{C-c p l'}.
993 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
997 You should create your directory structure ahead of time under your base
998 directory. These directories, which correspond with category names, may
1002 When you enter this key sequence, you will be prompted for the category
1003 of your entry and its title. Upon entering this information, a new file
1004 will be created that corresponds with the title, but in lowercase
1005 letters and having special characters converted to underscores. The
1006 title and date directives will be inserted automatically.
1009 @node Blosxom Options, , Blosxom Entries, Blosxom
1010 @comment node-name, next, previous, up
1011 @subsection Blosxom styles and options provided
1013 The following styles and options are available in the Blosxom publishing
1016 @subsubheading Styles provided
1020 @cindex publishing styles, blosxom-html
1022 Publish Blosxom entries in HTML form.
1024 @cindex publishing styles, blosxom-xhtml
1026 Publish Blosxom entries in XHTML form.
1030 @subsubheading Options provided
1034 @item muse-blosxom-extension
1035 Default file extension for publishing Blosxom files.
1037 @item muse-blosxom-header
1038 Header used for publishing Blosxom files.
1040 This may be text or a filename.
1042 @item muse-blosxom-footer
1043 Footer used for publishing Blosxom files.
1045 This may be text or a filename.
1047 @item muse-blosxom-base-directory
1048 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1050 This is the top-level directory where your blog entries may be found
1055 @node Book, DocBook, Blosxom, Publishing Styles
1056 @comment node-name, next, previous, up
1057 @section Publishing entries into a compilation
1059 This publishing style is used to output ``books'' in LaTeX or PDF
1062 Each page will become a separate chapter in the book, unless the style
1063 keyword @option{:nochapters} is used, in which case they are all run
1064 together as if one giant chapter.
1066 You will need to call the @code{muse-book-publish-project} function in
1067 order to publish this style. An example of this may be found in John
1068 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1070 @subsubheading Styles provided
1074 @cindex publishing styles, book-latex
1076 Publish a book in LaTeX form. The header and footer are different than
1077 the normal LaTeX publishing mode.
1079 @cindex publishing styles, book-pdf
1081 Publish a book in PDF form. The header and footer are different than
1082 the normal PDF publishing mode.
1086 @subsubheading Options provided
1090 @item muse-book-before-publish-hook
1091 A hook run in the book buffer before it is marked up.
1093 @item muse-book-after-publish-hook
1094 A hook run in the book buffer after it is marked up.
1096 @item muse-book-latex-header
1097 Header used for publishing books to LaTeX.
1099 This may be text or a filename.
1101 @item muse-book-latex-footer
1102 Footer used for publishing books to LaTeX.
1104 This may be text or a filename.
1108 @node DocBook, HTML, Book, Publishing Styles
1109 @comment node-name, next, previous, up
1110 @section Publishing in DocBook XML form
1112 This publishing style is used to generate DocBook XML files.
1114 @subsubheading Styles provided
1118 @cindex publishing styles, docbook
1123 @subsubheading Options provided
1127 @item muse-docbook-extension
1128 Default file extension for publishing DocBook XML files.
1130 @item muse-docbook-header
1131 Header used for publishing DocBook XML files.
1133 This may be text or a filename.
1135 @item muse-docbook-footer
1136 Footer used for publishing DocBook XML files.
1138 This may be text or a filename.
1140 @item muse-docbook-markup-regexps
1141 List of markup rules for publishing a Muse page to DocBook XML.
1143 @item muse-docbook-markup-functions
1144 An alist of style types to custom functions for that kind of text.
1146 @item muse-docbook-markup-strings
1147 Strings used for marking up text.
1149 These cover the most basic kinds of markup, the handling of which
1150 differs little between the various styles.
1152 @item muse-docbook-markup-specials
1153 A table of characters which must be represented specially.
1155 @item muse-docbook-encoding-default
1156 The default Emacs buffer encoding to use in published files.
1157 This will be used if no special characters are found.
1159 @item muse-docbook-charset-default
1160 The default DocBook XML charset to use if no translation is
1161 found in @code{muse-docbook-encoding-map}.
1163 @item muse-docbook-encoding-map
1164 An alist mapping emacs coding systems to appropriate DocBook charsets.
1165 Use the base name of the coding system (i.e. without the -unix).
1169 @node HTML, Journal, DocBook, Publishing Styles
1170 @comment node-name, next, previous, up
1171 @section Publishing in HTML or XHTML form
1173 This publishing style is capable of producing HTML or XHTML documents.
1175 @subsubheading Styles provided
1179 @cindex publishing styles, html
1181 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1184 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1188 @subsubheading Options provided
1190 If an HTML option does not have a corresponding XHTML option, it will
1191 be used for both of these publishing styles.
1195 @item muse-html-extension
1196 Default file extension for publishing HTML files.
1198 @item muse-xhtml-extension
1199 Default file extension for publishing XHTML files.
1201 @item muse-html-style-sheet
1202 Store your stylesheet definitions here.
1204 This is used in @code{muse-html-header}. You can put raw CSS in here or
1205 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1206 @verb{|<lisp>|} markup tags.
1208 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1211 @item muse-html-header
1212 Header used for publishing HTML files.
1214 This may be text or a filename.
1216 @item muse-html-footer
1217 Footer used for publishing HTML files.
1219 This may be text or a filename.
1221 @item muse-xhtml-header
1222 Header used for publishing XHTML files.
1224 This may be text or a filename.
1226 @item muse-xhtml-footer
1227 Footer used for publishing XHTML files.
1229 This may be text or a filename.
1231 @item muse-html-anchor-on-word
1232 When true, anchors surround the closest word.
1234 This allows you to select them in a browser (i.e. for pasting), but has
1235 the side-effect of marking up headers in multiple colors if your header
1236 style is different from your link style.
1238 @item muse-html-table-attributes
1239 The attribute to be used with HTML @verb{|<table>|} tags.
1241 Note that since Muse supports direct insertion of HTML tags, you can
1242 easily create any kind of table you want, as long as each line begins at
1243 column 0 (to prevent it from being blockquoted).
1245 @item muse-html-markup-regexps
1246 List of markup rules for publishing a Muse page to HTML.
1248 @item muse-html-markup-functions
1249 An alist of style types to custom functions for that kind of text.
1251 @item muse-html-markup-strings
1252 Strings used for marking up text as HTML.
1254 These cover the most basic kinds of markup, the handling of which
1255 differs little between the various styles.
1257 @item muse-xhtml-markup-strings
1258 Strings used for marking up text as XHTML.
1260 These cover the most basic kinds of markup, the handling of which
1261 differs little between the various styles.
1263 @item muse-html-markup-tags
1264 A list of tag specifications, for specially marking up HTML.
1265 @xref{muse-publish-markup-tags}, for more information.
1267 @item muse-html-markup-specials
1268 A table of characters which must be represented specially. By default,
1269 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1271 @item muse-html-meta-http-equiv
1272 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1274 @item muse-html-meta-content-type
1275 The content type used for the HTML @verb{|<meta>|} tag.
1277 If you are striving for XHTML 1.1 compliance, you may want to change
1278 this to ``application/xhtml+xml''.
1280 @item muse-html-meta-content-encoding
1281 The charset to append to the HTML @verb{|<meta>|} tag.
1283 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1284 and determine the HTML charset from emacs's coding. If set to a string,
1285 this string will be used to force a particular charset.
1287 @item muse-html-charset-default
1288 The default HTML meta charset to use if no translation is found in
1289 @code{muse-html-encoding-map}.
1291 @item muse-html-encoding-default
1292 The default Emacs buffer encoding to use in published files.
1293 This will be used if no special characters are found.
1295 @item muse-html-encoding-map
1296 An alist mapping emacs coding systems to appropriate HTML charsets.
1297 Use the base name of the coding system (i.e. without the -unix).
1301 @node Journal, LaTeX, HTML, Publishing Styles
1302 @comment node-name, next, previous, up
1303 @section Keeping a journal or blog
1305 @cindex blog, journal style
1307 The module facilitates the keeping and publication of a journal. When
1308 publishing to HTML, it assumes the form of a web log, or blog.
1310 The input format for each entry is as follows.
1313 * 20040317: Title of entry
1318 "You know who you are. It comes down to a simple gut check: You
1319 either love what you do or you don't. Period." -- P. Bronson
1323 The "qotd", or Quote of the Day, is entirely optional. When generated
1324 to HTML, this entry is rendered as the following.
1328 <div class="entry-qotd">
1329 <h3>Quote of the Day:</h3>
1330 <p>"You know who you are. It comes down to a simple gut
1331 check: You either love what you do or you don't. Period."
1334 <div class="entry-body">
1335 <div class="entry-head">
1336 <div class="entry-date">
1337 <span class="date">March 17, 2004</span>
1339 <div class="entry-title">
1340 <h2>Title of entry</h2>
1343 <div class="entry-text">
1344 <p>Text for the entry.</p>
1350 The plurality of "div" tags makes it possible to display the entries in
1351 any form you wish, using a CSS style.
1353 Also, an .RDF file can be generated from your journal by publishing it
1354 with the "rdf" style. It uses the first two sentences of the first
1355 paragraph of each entry as its "description", and auto-generates tags
1356 for linking to the various entries.
1358 @subsubheading Styles provided
1362 @cindex publishing styles, journal-html
1364 Publish journal entries as an HTML document.
1366 @cindex publishing styles, journal-xhtml
1368 Publish journal entries as an XHTML document.
1370 @cindex publishing styles, journal-latex
1372 Publish journal entries as a LaTeX document.
1374 @cindex publishing styles, journal-pdf
1376 Publish journal entries as a PDF document.
1378 @cindex publishing styles, journal-book-latex
1379 @item journal-book-latex
1380 Publish journal entries as a LaTeX book.
1382 @cindex publishing styles, journal-book-pdf
1383 @item journal-book-pdf
1384 Publish journal entries as a PDF book.
1386 @cindex publishing styles, journal-rdf
1387 @cindex publishing styles, RSS 1.0
1389 Publish journal entries as an RDF file (RSS 1.0).
1391 @cindex publishing styles, journal-rss
1392 @cindex publishing styles, RSS 2.0
1394 Publish journal entries as an RSS file (RSS 2.0).
1398 @subsubheading Options provided
1402 @item muse-journal-heading-regexp
1403 A regexp that matches a journal heading.
1405 Paren group 1 is the ISO date, group 2 is the optional category, and
1406 group 3 is the optional heading for the entry.
1408 @item muse-journal-date-format
1409 Date format to use for journal entries.
1411 @item muse-journal-html-heading-regexp
1412 A regexp that matches a journal heading from an HTML document.
1414 Paren group 1 is the ISO date, group 2 is the optional category, and
1415 group 3 is the optional heading for the entry.
1417 @item muse-journal-html-entry-template
1418 Template used to publish individual journal entries as HTML.
1420 @item muse-journal-latex-section
1421 Template used to publish a LaTeX section.
1423 @item muse-journal-latex-subsection
1424 Template used to publish a LaTeX subsection.
1426 @item muse-journal-latex-markup-tags
1427 A list of tag specifications, for specially marking up LaTeX.
1429 @xref{muse-publish-markup-tags}, for more information.
1431 @item muse-journal-rdf-extension
1432 Default file extension for publishing RDF (RSS 1.0) files.
1434 @item muse-journal-rdf-base-url
1435 The base URL of the website referenced by the RDF file.
1437 @item muse-journal-rdf-header
1438 Header used for publishing RDF (RSS 1.0) files.
1440 This may be text or a filename.
1442 @item muse-journal-rdf-footer
1443 Footer used for publishing RDF (RSS 1.0) files.
1445 This may be text or a filename.
1447 @item muse-journal-rdf-date-format
1448 Date format to use for RDF entries.
1450 @item muse-journal-rdf-entry-template
1451 Template used to publish individual journal entries as RDF.
1453 @item muse-journal-rdf-summarize-entries
1454 If non-nil, include only summaries in the RDF file, not the full data.
1456 @item muse-journal-rss-extension
1457 Default file extension for publishing RSS 2.0 files.
1459 @item muse-journal-rss-base-url
1460 The base URL of the website referenced by the RSS file.
1462 @item muse-journal-rss-header
1463 Header used for publishing RSS 2.0 files.
1465 This may be text or a filename.
1467 @item muse-journal-rss-footer
1468 Footer used for publishing RSS 2.0 files.
1470 This may be text or a filename.
1472 @item muse-journal-rss-date-format
1473 Date format to use for RSS 2.0 entries.
1475 @item muse-journal-rss-entry-template
1476 Template used to publish individual journal entries as RSS 2.0.
1478 @item muse-journal-rss-enclosure-types-alist
1479 File types that are accepted as RSS enclosures.
1481 This is an alist that maps file extension to content type.
1483 Useful for podcasting.
1485 @item muse-journal-rss-summarize-entries
1486 If non-nil, include only summaries in the RSS file, not the full data.
1488 Many RSS subscribers find this annoying.
1490 @item muse-journal-rss-markup-regexps
1491 List of markup rules for publishing a Muse journal page to RSS.
1493 For more information on the structure of this list,
1494 @xref{muse-publish-markup-regexps}.
1496 @item muse-journal-rss-markup-functions
1497 An alist of style types to custom functions for that kind of text.
1499 For more on the structure of this list,
1500 @xref{muse-publish-markup-functions}.
1504 @node LaTeX, Poem, Journal, Publishing Styles
1505 @comment node-name, next, previous, up
1506 @section Publishing LaTeX documents
1508 This publishing style is capable of producing LaTeX or PDF documents.
1510 If you wish to publish PDF documents, you will need to have a good TeX
1511 installation. For Debian, this can be accomplished by installing the
1512 ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1514 @subsubheading Styles provided
1518 @cindex publishing styles, latex
1520 Publish a LaTeX document.
1522 @cindex publishing styles, pdf
1524 Publish a PDF document, using an external LaTeX document conversion
1527 @cindex publishing styles, latexcjk
1529 Publish a LaTeX document with CJK (Chinese) encodings.
1531 @cindex publishing styles, pdfcjk
1533 Publish a PDF document with CJK (Chinese) encodings, using an external
1534 LaTeX document conversion tool.
1538 @subsubheading Options provided
1542 @item muse-latex-extension
1543 Default file extension for publishing LaTeX files.
1545 @item muse-latex-pdf-extension
1546 Default file extension for publishing LaTeX files to PDF.
1548 @item muse-latex-header
1549 Header used for publishing LaTeX files.
1551 This may be text or a filename.
1553 @item muse-latex-footer
1554 Footer used for publishing LaTeX files.
1556 This may be text or a filename.
1558 @item muse-latexcjk-header
1559 Header used for publishing LaTeX files (CJK).
1561 This may be text or a filename.
1563 @item muse-latexcjk-footer
1564 Footer used for publishing LaTeX files (CJK).
1566 This may be text or a filename.
1568 @item muse-latex-markup-regexps
1569 List of markup regexps for identifying regions in a Muse page.
1571 For more on the structure of this list,
1572 @xref{muse-publish-markup-regexps}.
1574 @item muse-latex-markup-functions
1575 An alist of style types to custom functions for that kind of text.
1577 For more on the structure of this list,
1578 @xref{muse-publish-markup-functions}.
1580 @item muse-latex-markup-strings
1581 Strings used for marking up text.
1583 These cover the most basic kinds of markup, the handling of which
1584 differs little between the various styles.
1586 @item muse-latexcjk-encoding-map
1587 An alist mapping emacs coding systems to appropriate CJK codings.
1588 Use the base name of the coding system (ie, without the -unix).
1590 @item muse-latexcjk-encoding-default
1591 The default Emacs buffer encoding to use in published files.
1593 This will be used if no special characters are found.
1595 @item muse-latex-markup-specials
1596 A table of characters which must be represented specially.
1600 @node Poem, Texinfo, LaTeX, Publishing Styles
1601 @comment node-name, next, previous, up
1602 @section Publish a poem to LaTex or PDF
1604 The @code{muse-poem} module makes it easy to attractively publish and
1605 reference poems in the following format, using the "memoir" module for
1606 LaTeX publishing. It will also markup poems for every other output
1607 style, though none are nearly as pretty.
1616 Annotations, history, notes, etc.
1619 Once a poem is written in this format, just publish it to PDF using the
1620 @code{poem-pdf} style. To make an inlined reference to a poem that
1621 you've written -- for example, from a blog page -- there is a "poem" tag
1622 defined by this module.
1625 <poem title="name.of.poem.page">
1628 Let's assume the template above was called @file{name.of.poem.page};
1629 then the above tag would result in this inclusion.
1637 John Wiegley uses this module for publishing all of the poems on his
1638 website, which are at
1639 @uref{http://www.newartisans.com/johnw/poems.html}.
1641 @subsubheading Styles provided
1645 @cindex publishing styles, poem-latex
1647 Publish a poem in LaTeX form.
1649 @cindex publishing styles, poem-pdf
1651 Publish a poem to a PDF document.
1653 @cindex publishing styles, chapbook-latex
1654 @item chapbook-latex
1655 Publish a book of poems in LaTeX form.
1657 @cindex publishing styles, chapbook-pdf
1659 Publish a book of poems to a PDF document.
1663 @subsubheading Options provided
1667 @item muse-poem-latex-header
1668 Header used for publishing LaTeX poems.
1670 This may be text or a filename.
1672 @item muse-poem-latex-footer
1673 Footer used for publishing LaTeX files.
1675 This may be text or a filename.
1677 @item muse-poem-markup-strings
1678 Strings used for marking up poems.
1680 These cover the most basic kinds of markup, the handling of which
1681 differs little between the various styles.
1683 @item muse-chapbook-latex-header
1684 Header used for publishing a book of poems in LaTeX form.
1686 This may be text or a filename.
1688 @item muse-chapbook-latex-footer
1689 Footer used for publishing a book of poems in LaTeX form.
1691 This may be text or a filename.
1693 @item muse-poem-chapbook-strings
1694 Strings used for marking up books of poems.
1696 These cover the most basic kinds of markup, the handling of which
1697 differs little between the various styles.
1701 @node Texinfo, , Poem, Publishing Styles
1702 @comment node-name, next, previous, up
1703 @section Publish entries to Texinfo format or PDF
1705 Rules for publishing a Muse file as a Texinfo article.
1707 @subsubheading Styles provided
1711 @cindex publishing styles, texi
1713 Publish a file in Texinfo form.
1715 @cindex publishing styles, texi
1717 Generate an Info file from a Muse file.
1719 @cindex publishing styles, info-pdf
1721 Publish a file in PDF form.
1725 @subsubheading Options provided
1729 @item muse-texinfo-process-natively
1730 If non-nil, use the Emacs `texinfmt' module to make Info files.
1732 @item muse-texinfo-extension
1733 Default file extension for publishing Texinfo files.
1735 @item muse-texinfo-info-extension
1736 Default file extension for publishing Info files.
1738 @item muse-texinfo-pdf-extension
1739 Default file extension for publishing PDF files.
1741 @item muse-texinfo-header
1742 Text to prepend to a Muse page being published as Texinfo.
1744 This may be text or a filename.
1745 It may contain @verb{|<lisp>|} markup tags.
1747 @item muse-texinfo-footer
1748 Text to append to a Muse page being published as Texinfo.
1750 This may be text or a filename.
1751 It may contain @verb{|<lisp>|} markup tags.
1753 @item muse-texinfo-markup-regexps
1754 List of markup rules for publishing a Muse page to Texinfo.
1756 For more on the structure of this list,
1757 @xref{muse-publish-markup-regexps}.
1759 @item muse-texinfo-markup-functions
1760 An alist of style types to custom functions for that kind of text.
1762 For more on the structure of this list, see
1763 @xref{muse-publish-markup-functions}.
1765 @item muse-texinfo-markup-strings
1766 Strings used for marking up text.
1768 These cover the most basic kinds of markup, the handling of which
1769 differs little between the various styles.
1771 @item muse-texinfo-markup-specials
1772 A table of characters which must be represented specially.
1777 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
1778 @comment node-name, next, previous, up
1779 @chapter Making your own publishing styles
1782 * Common Elements:: Common functionality shared by styles.
1783 * Deriving Styles:: Deriving a new style from an existing
1787 @node Common Elements, Deriving Styles, , Extending Muse
1788 @comment node-name, next, previous, up
1789 @section Common functionality shared by styles
1790 @cindex publishing styles, common
1793 * Markup Functions:: Specifying functions to marking up text.
1794 * Markup Regexps:: Markup rules for publishing.
1795 * Markup Strings:: Strings specific to a publishing style.
1796 * Markup Tags:: Tag specifications for special markup.
1797 * Style Elements:: Parameters used for defining styles.
1800 @node Markup Functions, Markup Regexps, , Common Elements
1801 @comment node-name, next, previous, up
1802 @subsection Specifying functions to mark up text
1803 @cindex publishing, markup functions
1805 @anchor{muse-publish-markup-functions}
1806 @code{muse-publish-markup-functions}
1808 An alist of style types to custom functions for that kind of text.
1810 This is used by publishing styles to attempt to minimize the amount of
1811 custom regexps that each has to define. @file{muse-publish} provides
1812 rules for the most common types of markup.
1814 Each member of the list is of the following form.
1822 Describes the type of text to associate with this rule.
1823 @code{muse-publish-markup-regexps} maps regexps to these symbols.
1826 Function to use to mark up this kind of rule if no suitable function is
1827 found through the @option{:functions} tag of the current style.
1830 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
1831 @comment node-name, next, previous, up
1832 @subsection Markup rules for publishing
1833 @cindex publishing, markup regexps
1834 @cindex publishing, rules
1836 @anchor{muse-publish-markup-regexps}
1837 @code{muse-publish-markup-regexps}
1839 List of markup rules for publishing a page with Muse.
1841 The rules given in this variable are invoked first, followed by whatever
1842 rules are specified by the current style.
1844 Each member of the list is either a function, or a list of the following
1848 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1853 A regular expression, or symbol whose value is a regular expression,
1854 which is searched for using `re-search-forward'.
1856 @item TEXT-BEGIN-GROUP
1857 The matching group within that regexp which denotes the beginning of the
1858 actual text to be marked up.
1860 @item REPLACEMENT-TEXT
1861 A string that will be passed to `replace-match'.
1863 If it is not a string, but a function, it will be called to determine
1864 what the replacement text should be (it must return a string). If it is
1865 a symbol, the value of that symbol should be a string.
1868 The replacements are done in order, one rule at a time. Writing
1869 the regular expressions can be a tricky business. Note that case
1870 is never ignored. `case-fold-search' is always bound to nil
1871 while processing the markup rules.
1873 @subsubheading Publishing order
1875 This is the order that the publishing rules are consulted, by default.
1876 This may be changed by customizing @code{muse-publish-markup-regexps}.
1880 @item trailing and leading whitespace
1881 Remove trailing and leading whitespace from a file.
1886 This is only recognized at the beginning of a file.
1897 @item explicit links
1898 Prevent emphasis characters in explicit links from being marked up.
1900 Don't actually publish them here, just add a special no-emphasis text
1904 Whitespace-delimited word, possibly with emphasis characters
1906 This function is responsible for marking up emphasis and escaping some
1917 Outline-mode style headings.
1922 These are ellipses with a dot at end.
1932 Horizontal rule or section separator.
1937 beginning of footnotes section
1942 Footnote definition or reference. If at beginning of line, it is a
1957 Numbered list, item list, or term definition list.
1960 spaces before beginning of text
1968 @samp{table | cells}
1971 @samp{[[explicit][links]]}
1974 @samp{http://example.com/}
1977 @samp{bare-email@@example.com}
1981 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
1982 @comment node-name, next, previous, up
1983 @subsection Strings specific to a publishing style
1984 @cindex publishing, markup strings
1986 @dfn{Markup strings} are strings used for marking up text for a
1989 These cover the most basic kinds of markup, the handling of which
1990 differs little between the various styles.
1992 @subsubheading Available markup strings
1996 @item image-with-desc
1997 An image and a description.
1999 Argument 1: image. Argument 2: description.
2004 Argument 1: image link.
2006 @item url-with-image
2007 A URL with an image.
2009 Argument 1: link. Argument 2: image.
2012 A link with a description.
2014 Argument 1: link. Argument 2: description if one exists, or the
2015 original link otherwise.
2018 A link that refers to an internal anchor.
2020 Argument 1: internal link. Argument 2: description if one exists, or
2021 the original link otherwise.
2024 A link to an email address.
2026 Argument 1: email address. Argument 2: email address.
2032 A horizontal line or space.
2035 Beginning of footnote.
2041 Mark a reference for the current footnote.
2043 Argument 1: number of this footnote.
2046 Indicate the text of the current footnote.
2048 Argument 1: number of this footnote.
2050 @item footnotetext-end
2051 End of a footnote text line.
2054 Text used to replace ``Footnotes:'' line.
2063 Beginning of a part indicator line. This is used by book publishing.
2066 End of a part indicator line. This is used by book publishing.
2069 Beginning of a chapter indicator line. This is used by book publishing.
2072 End of a chapter indicator line. This is used by book publishing.
2075 Beginning of level 1 section indicator line.
2077 Argument 1: level of section; always 1.
2080 End of level 1 section indicator line.
2082 Argument 1: level of section; always 1.
2085 Beginning of level 2 section indicator line.
2087 Argument 1: level of section; always 2.
2089 @item subsection-end
2090 End of level 2 section indicator line.
2092 Argument 1: level of section; always 2.
2095 Beginning of level 3 section indicator line.
2097 Argument 1: level of section; always 3.
2099 @item subsubsection-end
2100 End of level 3 section indicator line.
2102 Argument 1: level of section; always 3.
2105 Beginning of section indicator line, where level is greater than 3.
2107 Argument 1: level of section.
2109 @item section-other-end
2110 Beginning of section indicator line, where level is greater than 3.
2112 Argument 1: level of section.
2114 @item begin-underline
2115 Beginning of underlined text.
2118 End of underlined text.
2121 Beginning of verbatim text. This includes @verb{|<code>|} tags and
2125 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2129 Beginning of the first level of emphasized text.
2132 End of the first level of emphasized text.
2134 @item begin-more-emph
2135 Beginning of the second level of emphasized text.
2138 End of the second level of emphasized text.
2140 @item begin-most-emph
2141 Beginning of the third (and final) level of emphasized text.
2144 End of the third (and final) level of emphasized text.
2147 Beginning of verse text.
2150 String used to each space that is further indented than the beginning of
2153 @item begin-verse-line
2154 Beginning of a line of verse.
2156 @item empty-verse-line
2157 End of a line of verse.
2159 @item begin-last-stanza-line
2160 Beginning of the last line of a verse stanza.
2162 @item end-last-stanza-line
2163 End of the last line of a verse stanza.
2169 Beginning of an example region. To make use of this, an
2170 @samp{<example>} tag is needed.
2173 End of an example region. To make use of this, an @samp{</example>} tag
2177 Begin a centered line.
2180 End a centered line.
2183 Begin a quoted region.
2186 End a quoted region.
2189 Begin an unordered list.
2192 End an unordered list.
2195 Begin an ordered list.
2198 End an ordered list.
2201 Begin a definition list.
2204 Begin a term in a definition list.
2207 End a definition list.
2211 @node Markup Tags, Style Elements, Markup Strings, Common Elements
2212 @comment node-name, next, previous, up
2213 @subsection Tag specifications for special markup
2214 @cindex publishing, markup tags
2216 @anchor{muse-publish-markup-tags}
2217 @code{muse-publish-markup-tags}
2219 A list of tag specifications, for specially marking up text.
2221 XML-style tags are the best way to add custom markup to Muse. This is
2222 easily accomplished by customizing this list of markup tags.
2224 For each entry, the name of the tag is given, whether it expects a
2225 closing tag and/or an optional set of attributes, and a function that
2226 performs whatever action is desired within the delimited region.
2228 The tags themselves are deleted during publishing, before the function
2229 is called. The function is called with three arguments, the beginning
2230 and end of the region surrounded by the tags. If properties are
2231 allowed, they are passed as a third argument in the form of an alist.
2232 The `end' argument to the function is always a marker.
2234 Point is always at the beginning of the region within the tags, when the
2235 function is called. Wherever point is when the function finishes is
2236 where tag markup will resume.
2238 These tag rules are processed once at the beginning of markup, and once
2239 at the end, to catch any tags which may have been inserted in-between.
2241 @node Style Elements, , Markup Tags, Common Elements
2242 @comment node-name, next, previous, up
2243 @subsection Parameters used for defining styles
2244 @cindex publishing, style elements
2246 Style elements are tags that define a style. Use
2247 @code{muse-define-style} to create a new style.
2250 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2253 @subsubheading Usable elements
2258 File extension to use for publishing files with this style.
2261 File extension to use for publishing links to Muse files with this
2265 File extension to use for publishing second-stage files with this style.
2267 For example, PDF publishing generates a LaTeX file first, then a PDF
2268 from that LaTeX file.
2271 List of markup rules for publishing a page with Muse.
2272 @xref{muse-publish-markup-regexps}.
2275 An alist of style types to custom functions for that kind of text.
2276 @xref{muse-publish-markup-functions}.
2279 Strings used for marking up text with this style.
2281 These cover the most basic kinds of markup, the handling of which
2282 differs little between the various styles.
2285 A list of tag specifications, used for handling extra tags.
2286 @xref{muse-publish-markup-tags}.
2289 A table of characters which must be represented specially.
2292 A function that is to be executed on the newly-created publishing buffer
2293 (or the current region) before any publishing occurs.
2295 This is used to set extra parameters that direct the publishing process.
2298 A function that is to be executed on the publishing buffer (or the
2299 current region) immediately after applying all of the markup regexps.
2301 This is used to fix the order of table elements (header, footer, body)
2305 A function that is to be executed on the publishing buffer after
2306 :before-end, and immediately after inserting the header and footer.
2308 This is used for generating the table of contents as well as setting the
2312 A function that is to be executed after saving the published file, but
2313 while still in its buffer.
2315 This is used for generating second-stage documents like PDF files from
2316 just-published LaTeX files.
2319 Header used for publishing files of this style.
2321 This may be text or a filename. It is inserted at the beginning of a
2322 file, after evaluating the publishing markup.
2325 Footer used for publishing files of this style.
2327 This may be text or a filename. It is inserted at the end of a file,
2328 after evaluating the publishing markup.
2331 The function used to browse the published result of files of this style.
2335 @node Deriving Styles, , Common Elements, Extending Muse
2336 @comment node-name, next, previous, up
2337 @section Deriving a new style from an existing one
2338 @cindex publishing styles, deriving
2340 To create a new style from an existing one, use @code{muse-derive-style}
2341 as follows. This is a good way to fix something you don't like about a
2342 particular publishing style, or to personalize it.
2345 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2348 The derived name is a string defining the new style, such as "my-html".
2349 The base name must identify an existing style, such as "html" -- if you
2350 have loaded @file{muse-html}. The style parameters are the same as
2351 those used to create a style, except that they override whatever
2352 definitions exist in the base style. However, some definitions only
2353 partially override. The following parameters support partial
2356 @xref{Style Elements}, for a complete list of all parameters.
2361 If a markup function is not found in the derived style's function list,
2362 the base style's function list will be queried.
2365 All regexps in the current style and the base style(s) will be used.
2368 If a markup string is not found in the derived style's string list, the
2369 base style's string list will be queried.
2374 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
2375 @comment node-name, next, previous, up
2376 @chapter Getting Help and Reporting Bugs
2377 @cindex help, getting
2378 @cindex bugs, reporting
2380 After you have read this guide, if you still have questions about
2381 Muse, or if you have bugs to report, there are several places you can
2387 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
2388 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2392 @uref{http://www.mwolson.org/projects/EmacsMuse.html} is the web page
2393 that Michael Olson (the current maintainer) made for Muse.
2396 You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
2397 using the subscription form at
2398 @uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
2399 This mailing list provides support for Muse, @command{Planner} and
2400 @command{emacs-wiki}, which is the predecessor of Muse.
2402 There are additional methods for accessing the mailing list, adding
2403 content to it, and searching it. Consult
2404 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
2408 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2409 contributors are frequently around and willing to answer your
2410 questions. The @samp{#muse} channel is also available for
2411 Muse-specific help, and its current maintainer hangs out there.
2414 The maintainer of Emacs Muse, Michael Olson, may be contacted at
2415 @email{mwolson@@gnu.org}.
2419 @node History, Contributors, Getting Help and Reporting Bugs, Top
2420 @comment node-name, next, previous, up
2421 @chapter History of This Document
2422 @cindex history, of Muse
2426 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2427 limitations. Around February 2004, he started making "emacs-wiki version
2428 3.00 APLHA", which eventually became known as Muse.
2430 Most of those who frequent the emacs-wiki mailing list continued to use
2431 emacs-wiki, mainly because Planner hasn't been ported over to it.
2433 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2434 John Wiegley's request.
2437 Michael Olson overhauled this document and added many new sections in
2438 preparation for the first release of Muse (3.01).
2442 @node Contributors, GNU General Public License, History, Top
2443 @comment node-name, next, previous, up
2444 @chapter Contributors to This Documentation
2445 @cindex contributors
2447 The first draft of this document was taken from the emacs-wiki texinfo
2448 manual. Michael Olson adapted it for Muse and added most of its
2451 John Sullivan did a majority of the work on the emacs-wiki texinfo
2454 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2455 emacs-wiki texinfo manual.
2457 @node GNU General Public License, Concept Index, Contributors, Top
2458 @comment node-name, next, previous, up
2459 @appendix GNU GENERAL PUBLIC LICENSE
2460 @center Version 2, June 1991
2462 @cindex GNU General Public License
2464 @c This file is intended to be included in another file.
2467 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2468 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2470 Everyone is permitted to copy and distribute verbatim copies
2471 of this license document, but changing it is not allowed.
2474 @appendixsec Preamble
2476 The licenses for most software are designed to take away your
2477 freedom to share and change it. By contrast, the GNU General Public
2478 License is intended to guarantee your freedom to share and change free
2479 software---to make sure the software is free for all its users. This
2480 General Public License applies to most of the Free Software
2481 Foundation's software and to any other program whose authors commit to
2482 using it. (Some other Free Software Foundation software is covered by
2483 the GNU Library General Public License instead.) You can apply it to
2486 When we speak of free software, we are referring to freedom, not
2487 price. Our General Public Licenses are designed to make sure that you
2488 have the freedom to distribute copies of free software (and charge for
2489 this service if you wish), that you receive source code or can get it
2490 if you want it, that you can change the software or use pieces of it
2491 in new free programs; and that you know you can do these things.
2493 To protect your rights, we need to make restrictions that forbid
2494 anyone to deny you these rights or to ask you to surrender the rights.
2495 These restrictions translate to certain responsibilities for you if you
2496 distribute copies of the software, or if you modify it.
2498 For example, if you distribute copies of such a program, whether
2499 gratis or for a fee, you must give the recipients all the rights that
2500 you have. You must make sure that they, too, receive or can get the
2501 source code. And you must show them these terms so they know their
2504 We protect your rights with two steps: (1) copyright the software, and
2505 (2) offer you this license which gives you legal permission to copy,
2506 distribute and/or modify the software.
2508 Also, for each author's protection and ours, we want to make certain
2509 that everyone understands that there is no warranty for this free
2510 software. If the software is modified by someone else and passed on, we
2511 want its recipients to know that what they have is not the original, so
2512 that any problems introduced by others will not reflect on the original
2513 authors' reputations.
2515 Finally, any free program is threatened constantly by software
2516 patents. We wish to avoid the danger that redistributors of a free
2517 program will individually obtain patent licenses, in effect making the
2518 program proprietary. To prevent this, we have made it clear that any
2519 patent must be licensed for everyone's free use or not licensed at all.
2521 The precise terms and conditions for copying, distribution and
2522 modification follow.
2525 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2528 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2533 This License applies to any program or other work which contains
2534 a notice placed by the copyright holder saying it may be distributed
2535 under the terms of this General Public License. The ``Program'', below,
2536 refers to any such program or work, and a ``work based on the Program''
2537 means either the Program or any derivative work under copyright law:
2538 that is to say, a work containing the Program or a portion of it,
2539 either verbatim or with modifications and/or translated into another
2540 language. (Hereinafter, translation is included without limitation in
2541 the term ``modification''.) Each licensee is addressed as ``you''.
2543 Activities other than copying, distribution and modification are not
2544 covered by this License; they are outside its scope. The act of
2545 running the Program is not restricted, and the output from the Program
2546 is covered only if its contents constitute a work based on the
2547 Program (independent of having been made by running the Program).
2548 Whether that is true depends on what the Program does.
2551 You may copy and distribute verbatim copies of the Program's
2552 source code as you receive it, in any medium, provided that you
2553 conspicuously and appropriately publish on each copy an appropriate
2554 copyright notice and disclaimer of warranty; keep intact all the
2555 notices that refer to this License and to the absence of any warranty;
2556 and give any other recipients of the Program a copy of this License
2557 along with the Program.
2559 You may charge a fee for the physical act of transferring a copy, and
2560 you may at your option offer warranty protection in exchange for a fee.
2563 You may modify your copy or copies of the Program or any portion
2564 of it, thus forming a work based on the Program, and copy and
2565 distribute such modifications or work under the terms of Section 1
2566 above, provided that you also meet all of these conditions:
2570 You must cause the modified files to carry prominent notices
2571 stating that you changed the files and the date of any change.
2574 You must cause any work that you distribute or publish, that in
2575 whole or in part contains or is derived from the Program or any
2576 part thereof, to be licensed as a whole at no charge to all third
2577 parties under the terms of this License.
2580 If the modified program normally reads commands interactively
2581 when run, you must cause it, when started running for such
2582 interactive use in the most ordinary way, to print or display an
2583 announcement including an appropriate copyright notice and a
2584 notice that there is no warranty (or else, saying that you provide
2585 a warranty) and that users may redistribute the program under
2586 these conditions, and telling the user how to view a copy of this
2587 License. (Exception: if the Program itself is interactive but
2588 does not normally print such an announcement, your work based on
2589 the Program is not required to print an announcement.)
2592 These requirements apply to the modified work as a whole. If
2593 identifiable sections of that work are not derived from the Program,
2594 and can be reasonably considered independent and separate works in
2595 themselves, then this License, and its terms, do not apply to those
2596 sections when you distribute them as separate works. But when you
2597 distribute the same sections as part of a whole which is a work based
2598 on the Program, the distribution of the whole must be on the terms of
2599 this License, whose permissions for other licensees extend to the
2600 entire whole, and thus to each and every part regardless of who wrote it.
2602 Thus, it is not the intent of this section to claim rights or contest
2603 your rights to work written entirely by you; rather, the intent is to
2604 exercise the right to control the distribution of derivative or
2605 collective works based on the Program.
2607 In addition, mere aggregation of another work not based on the Program
2608 with the Program (or with a work based on the Program) on a volume of
2609 a storage or distribution medium does not bring the other work under
2610 the scope of this License.
2613 You may copy and distribute the Program (or a work based on it,
2614 under Section 2) in object code or executable form under the terms of
2615 Sections 1 and 2 above provided that you also do one of the following:
2619 Accompany it with the complete corresponding machine-readable
2620 source code, which must be distributed under the terms of Sections
2621 1 and 2 above on a medium customarily used for software interchange; or,
2624 Accompany it with a written offer, valid for at least three
2625 years, to give any third party, for a charge no more than your
2626 cost of physically performing source distribution, a complete
2627 machine-readable copy of the corresponding source code, to be
2628 distributed under the terms of Sections 1 and 2 above on a medium
2629 customarily used for software interchange; or,
2632 Accompany it with the information you received as to the offer
2633 to distribute corresponding source code. (This alternative is
2634 allowed only for noncommercial distribution and only if you
2635 received the program in object code or executable form with such
2636 an offer, in accord with Subsection b above.)
2639 The source code for a work means the preferred form of the work for
2640 making modifications to it. For an executable work, complete source
2641 code means all the source code for all modules it contains, plus any
2642 associated interface definition files, plus the scripts used to
2643 control compilation and installation of the executable. However, as a
2644 special exception, the source code distributed need not include
2645 anything that is normally distributed (in either source or binary
2646 form) with the major components (compiler, kernel, and so on) of the
2647 operating system on which the executable runs, unless that component
2648 itself accompanies the executable.
2650 If distribution of executable or object code is made by offering
2651 access to copy from a designated place, then offering equivalent
2652 access to copy the source code from the same place counts as
2653 distribution of the source code, even though third parties are not
2654 compelled to copy the source along with the object code.
2657 You may not copy, modify, sublicense, or distribute the Program
2658 except as expressly provided under this License. Any attempt
2659 otherwise to copy, modify, sublicense or distribute the Program is
2660 void, and will automatically terminate your rights under this License.
2661 However, parties who have received copies, or rights, from you under
2662 this License will not have their licenses terminated so long as such
2663 parties remain in full compliance.
2666 You are not required to accept this License, since you have not
2667 signed it. However, nothing else grants you permission to modify or
2668 distribute the Program or its derivative works. These actions are
2669 prohibited by law if you do not accept this License. Therefore, by
2670 modifying or distributing the Program (or any work based on the
2671 Program), you indicate your acceptance of this License to do so, and
2672 all its terms and conditions for copying, distributing or modifying
2673 the Program or works based on it.
2676 Each time you redistribute the Program (or any work based on the
2677 Program), the recipient automatically receives a license from the
2678 original licensor to copy, distribute or modify the Program subject to
2679 these terms and conditions. You may not impose any further
2680 restrictions on the recipients' exercise of the rights granted herein.
2681 You are not responsible for enforcing compliance by third parties to
2685 If, as a consequence of a court judgment or allegation of patent
2686 infringement or for any other reason (not limited to patent issues),
2687 conditions are imposed on you (whether by court order, agreement or
2688 otherwise) that contradict the conditions of this License, they do not
2689 excuse you from the conditions of this License. If you cannot
2690 distribute so as to satisfy simultaneously your obligations under this
2691 License and any other pertinent obligations, then as a consequence you
2692 may not distribute the Program at all. For example, if a patent
2693 license would not permit royalty-free redistribution of the Program by
2694 all those who receive copies directly or indirectly through you, then
2695 the only way you could satisfy both it and this License would be to
2696 refrain entirely from distribution of the Program.
2698 If any portion of this section is held invalid or unenforceable under
2699 any particular circumstance, the balance of the section is intended to
2700 apply and the section as a whole is intended to apply in other
2703 It is not the purpose of this section to induce you to infringe any
2704 patents or other property right claims or to contest validity of any
2705 such claims; this section has the sole purpose of protecting the
2706 integrity of the free software distribution system, which is
2707 implemented by public license practices. Many people have made
2708 generous contributions to the wide range of software distributed
2709 through that system in reliance on consistent application of that
2710 system; it is up to the author/donor to decide if he or she is willing
2711 to distribute software through any other system and a licensee cannot
2714 This section is intended to make thoroughly clear what is believed to
2715 be a consequence of the rest of this License.
2718 If the distribution and/or use of the Program is restricted in
2719 certain countries either by patents or by copyrighted interfaces, the
2720 original copyright holder who places the Program under this License
2721 may add an explicit geographical distribution limitation excluding
2722 those countries, so that distribution is permitted only in or among
2723 countries not thus excluded. In such case, this License incorporates
2724 the limitation as if written in the body of this License.
2727 The Free Software Foundation may publish revised and/or new versions
2728 of the General Public License from time to time. Such new versions will
2729 be similar in spirit to the present version, but may differ in detail to
2730 address new problems or concerns.
2732 Each version is given a distinguishing version number. If the Program
2733 specifies a version number of this License which applies to it and ``any
2734 later version'', you have the option of following the terms and conditions
2735 either of that version or of any later version published by the Free
2736 Software Foundation. If the Program does not specify a version number of
2737 this License, you may choose any version ever published by the Free Software
2741 If you wish to incorporate parts of the Program into other free
2742 programs whose distribution conditions are different, write to the author
2743 to ask for permission. For software which is copyrighted by the Free
2744 Software Foundation, write to the Free Software Foundation; we sometimes
2745 make exceptions for this. Our decision will be guided by the two goals
2746 of preserving the free status of all derivatives of our free software and
2747 of promoting the sharing and reuse of software generally.
2750 @heading NO WARRANTY
2757 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2758 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2759 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2760 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2761 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2762 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2763 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2764 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2765 REPAIR OR CORRECTION.
2768 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2769 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2770 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2771 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2772 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2773 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2774 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2775 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2776 POSSIBILITY OF SUCH DAMAGES.
2780 @heading END OF TERMS AND CONDITIONS
2783 @center END OF TERMS AND CONDITIONS
2787 @appendixsec Appendix: How to Apply These Terms to Your New Programs
2789 If you develop a new program, and you want it to be of the greatest
2790 possible use to the public, the best way to achieve this is to make it
2791 free software which everyone can redistribute and change under these terms.
2793 To do so, attach the following notices to the program. It is safest
2794 to attach them to the start of each source file to most effectively
2795 convey the exclusion of warranty; and each file should have at least
2796 the ``copyright'' line and a pointer to where the full notice is found.
2799 @var{one line to give the program's name and a brief idea of what it does.}
2800 Copyright (C) @var{yyyy} @var{name of author}
2802 This program is free software; you can redistribute it and/or modify
2803 it under the terms of the GNU General Public License as published by
2804 the Free Software Foundation; either version 2 of the License, or
2805 (at your option) any later version.
2807 This program is distributed in the hope that it will be useful,
2808 but WITHOUT ANY WARRANTY; without even the implied warranty of
2809 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2810 GNU General Public License for more details.
2812 You should have received a copy of the GNU General Public License along
2813 with this program; if not, write to the Free Software Foundation, Inc.,
2814 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2817 Also add information on how to contact you by electronic and paper mail.
2819 If the program is interactive, make it output a short notice like this
2820 when it starts in an interactive mode:
2823 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2824 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2825 This is free software, and you are welcome to redistribute it
2826 under certain conditions; type `show c' for details.
2829 The hypothetical commands @samp{show w} and @samp{show c} should show
2830 the appropriate parts of the General Public License. Of course, the
2831 commands you use may be called something other than @samp{show w} and
2832 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2835 You should also get your employer (if you work as a programmer) or your
2836 school, if any, to sign a ``copyright disclaimer'' for the program, if
2837 necessary. Here is a sample; alter the names:
2840 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2841 `Gnomovision' (which makes passes at compilers) written by James Hacker.
2843 @var{signature of Ty Coon}, 1 April 1989
2844 Ty Coon, President of Vice
2847 This General Public License does not permit incorporating your program into
2848 proprietary programs. If your program is a subroutine library, you may
2849 consider it more useful to permit linking proprietary applications with the
2850 library. If this is what you want to do, use the GNU Library General
2851 Public License instead of this License.
2854 @node Concept Index, , GNU General Public License, Top
2855 @comment node-name, next, previous, up