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.90 (3.03 RC1).
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 @subheading 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 @subheading 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 add the following
400 to your Muse settings file.
403 (setq muse-file-extension nil
407 @c PRE3_03: Give more examples
408 @c PRE3_03: Describe :set and other options fully
410 @node Keystroke Summary, Markup Rules, Projects, Top
411 @comment node-name, next, previous, up
412 @chapter Keys Used in Muse Mode
415 This is a summary of keystrokes available in every Muse buffer.
419 @item C-c C-a (`muse-index')
420 Display an index of all known Muse pages.
422 @item C-c C-b (`muse-find-backlinks')
423 Find all pages that link to this page.
425 @item C-c C-e (`muse-edit-link-at-point')
428 @item C-c C-f (`muse-project-find-file')
429 Open another Muse page. Prompt for the name.
431 @item C-c C-i (`muse-insert-tag')
432 Insert a tag interactively.
434 @item C-c C-l (`font-lock-mode')
435 Toggle font lock / highlighting for the current buffer.
437 @item C-c C-p (`muse-project-publish')
438 Publish any Muse pages that have changed.
440 @item C-c C-s (`muse-search')
441 Find text in all files of the current project.
443 @item C-c C-v (`muse-browse-result')
444 Show the published result of this page.
446 @item C-c i l (`muse-insert-relative-link-to-file')
447 Insert a link to a file interactively.
449 @item C-c i t (`muse-insert-tag'), also C-c TAB
450 Insert a tag interactively.
452 @item C-c = (`muse-what-changed')
453 Diff this page against the last backup version.
455 @item C-c TAB (`muse-insert-tag'), also C-c i t
456 Insert a tag interactively.
459 Move to the next Wiki reference.
462 Move to the previous Wiki reference.
465 Complete the name of a page from the current project at point.
468 Insert a new list item at point, indenting properly.
471 Decrease the indentation of the list item at point.
474 Increase the indentation of the list item at point.
479 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
480 @comment node-name, next, previous, up
481 @chapter Rules for Using Markup
484 A Muse document uses special, contextual markup rules to determine how
485 to format the output result. For example, if a paragraph is indented,
486 Muse assumes it should be quoted.
488 There are not too many markup rules, and all of them strive to be as
489 simple as possible so that you can focus on document creation, rather
493 * Paragraphs:: Paragraphs: centering and quoting.
494 * Headings:: Levels of headings.
495 * Directives:: Directives at the beginning of a
497 * Emphasizing Text:: Bold, italicized, and underlined text.
498 * Footnotes:: Making notes to be shown at the end.
499 * Verse:: Indicating poetic stanzas.
500 * Lists:: Lists of items.
501 * Tables:: Generation of data tables.
502 * Explicit Links:: Hyperlinks and email addresses with
504 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
506 * Images:: Publishing and displaying images.
507 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
508 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
510 * Comments:: Lines to omit from published output.
513 @node Paragraphs, Headings, Markup Rules, Markup Rules
514 @comment node-name, next, previous, up
515 @section Paragraphs: centering and quoting
518 Paragraphs in Muse must be separated by a blank line.
520 @cindex paragraphs, centered
521 @subheading Centered paragraphs and quotations
523 A line that begins with six or more columns of whitespace (either tabs
524 or spaces) indicates a centered paragraph.
526 @cindex paragraphs, quoted
528 But if a line begins with whitespace, though less than six columns, it
529 indicates a quoted paragraph.
532 @cindex monospace, rendering blocks
533 @cindex HTML, rendering blocks in monospace
534 @subheading Literal paragraphs
536 The @verb{|<example>|} tag is used for examples, where whitespace should
537 be preserved, the text rendered in monospace, and any characters special
538 to the output style escaped.
541 @cindex HTML, inserting a raw block
542 There is also the @verb{|<literal>|} tag, which causes a marked block to
543 be entirely left alone. This can be used for inserting a hand-coded
544 HTML blocks into HTML output, for example.
546 @node Headings, Directives, Paragraphs, Markup Rules
547 @comment node-name, next, previous, up
548 @section Levels of headings
551 A heading becomes a chapter or section in printed output -- depending on
552 the style. To indicate a heading, start a new paragraph with one or
553 more asterices, followed by a space and the heading title. Then begin
554 another paragraph to enter the text for that section.
556 All levels of headings will be published. Most publishing styles only
557 distinguish the between the first 4 levels, however.
569 @node Directives, Emphasizing Text, Headings, Markup Rules
570 @comment node-name, next, previous, up
571 @section Directives at the beginning of a document
574 Directives are lines beginning with the @samp{#} character that come
575 before any paragraphs or sections in the document. Directives are of
576 the form ``#directive content of directive''. You can use any
577 combination of uppercase and lowercase letters for directives, even if
578 the directive is not in the list below.
580 The @code{muse-publishing-directive} function may be used in header and
581 footer text to access directives. For example, to access the
582 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
584 The following is a list of directives that Muse uses.
589 The author of this document.
591 If this is not specified, Muse will attempt to figure it out from the
592 @code{user-full-name} variable.
596 The date that the document was last modified.
598 This is used by publishing styles that are able to embed the date
603 A short description of this document.
605 This is used by the @code{journal} publishing style to embed information
606 inside of an RSS/RDF feed.
610 The title of this document.
612 If this is not specified, the name of the file is used.
616 @node Emphasizing Text, Footnotes, Directives, Markup Rules
617 @comment node-name, next, previous, up
618 @section Bold, italicized, and underlined text
619 @cindex emphasizing text
620 @cindex underlining text
621 @cindex italicizing text
622 @cindex verbatim text
623 @cindex monospace, rendering words
625 To emphasize text, surround it with certain specially recognized
631 ***very strong emphasis***
633 =verbatim and monospace=
637 While editing a Muse document in Muse mode, these forms of emphasis will
638 be highlighted in a WYSIWYG manner. Each of these forms may span
641 Verbatim text will be colored as gray by default. To change this,
642 customize @code{muse-verbatim-face}.
644 You can also use the @verb{|<code>|} tag to indicate verbatim and
645 monospace text. This is handy for regions that have an ``='' in them.
647 @node Footnotes, Verse, Emphasizing Text, Markup Rules
648 @comment node-name, next, previous, up
649 @section Making notes to be shown at the end
652 A footnote reference is simply a number in square brackets. To define
653 the footnote, place this definition at the bottom of your file.
654 @samp{footnote-mode} can be used to greatly facilitate the creation of
655 these kinds of footnotes.
657 Footnotes are defined by the same number in brackets occurring at the
658 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
659 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
660 the point of insertion.
662 @node Verse, Lists, Footnotes, Markup Rules
663 @comment node-name, next, previous, up
664 @section Indicating poetic stanzas
668 Poetry requires that whitespace be preserved, but without resorting to
669 monospace. To indicate this, use the following markup, reminiscent of
673 > A line of Emacs verse;
674 > forgive its being so terse.
677 You can also use the @verb{|<verse>|} tag, if you prefer.
681 A line of Emacs verse;
682 forgive its being so terse.
686 @cindex verses, multiple stanzas
687 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
692 A line of Emacs verse;
693 forgive its being so terse.
695 In terms of terse verse,
700 @node Lists, Tables, Verse, Markup Rules
701 @comment node-name, next, previous, up
702 @section Lists of items
705 Lists are given using special characters at the beginning of a line.
706 Whitespace must occur before bullets or numbered items, to distinguish
707 from the possibility of those characters occurring in a real sentence.
709 @cindex lists, bullets
710 These are rendered as a bullet list.
717 @cindex lists, enumerated
718 An enumerated list follows.
725 @cindex lists, definitions
726 Here is a definition list.
730 This is a first definition
731 And it has two lines;
735 This is a second definition
738 @node Tables, Explicit Links, Lists, Markup Rules
739 @comment node-name, next, previous, up
740 @section Generation of data tables
743 @cindex tables, simple
744 Only very simple tables are supported. The syntax is as follows.
747 Double bars || Separate header fields
749 Single bars | Separate body fields
750 Here are more | body fields
752 Triple bars ||| Separate footer fields
755 Some publishing styles require header fields to come first, then footer
756 fields, and then the body fields. You can use any order for these
757 sections that you like, and Muse will re-order them for you at
760 If you wish to disable table generation for one Muse file, add the
761 directive @samp{#disable-tables t} to the top of the file.
763 @node Explicit Links, Implicit Links, Tables, Markup Rules
764 @comment node-name, next, previous, up
765 @section Hyperlinks and email addresses with descriptions
766 @cindex links, explicit
768 A hyperlink can reference a URL, or another page within a Muse
769 project. In addition, descriptive text can be specified, which should
770 be displayed rather than the link text in output styles that supports
771 link descriptions. The syntax is as follows.
774 [[link target][link description]]
775 [[link target without description]]
778 Thus, the current maintainer's homepage for Muse can be found
779 @samp{[[http://www.mwolson.org/projects/EmacsMuse.html][here]]},
780 or at @samp{[[http://www.mwolson.org/projects/EmacsMuse.html]]}.
782 @node Implicit Links, Images, Explicit Links, Markup Rules
783 @comment node-name, next, previous, up
784 @section Bare URLs, WikiNames, and InterWiki links
785 @cindex links, implicit
788 @cindex Email addresses
790 A URL or email address encountered in the input text is published as a
791 hyperlink. These kind of links are called @dfn{implicit links} because
792 they are not separated from the rest of the Muse document in any way.
795 If the @command{muse-wiki} module is loaded, another form of implicit
796 link will be made available. WikiNames, which are typed in camelcase,
797 will be highlighted and published as links, provided that the file they
800 Customization of WikiName recognition may be accomplished by editing the
801 @code{muse-wiki-wikiword-regexp} option and subsequently running
802 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
803 If you use the Customize interface, the latter will be done
806 @cindex InterWiki links
807 @cindex inter-project links
808 The @command{muse-wiki} module also allows for InterWiki links. These
809 are similar to WikiWords, but they specify both the project and page of
810 a file. The names of your project entries in @code{muse-project-alist}
811 will be used as InterWiki names by default. Several examples follow.
814 Blog::DocumentingMuse
819 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
820 the project name, and @samp{DocumentingMuse} is the page name. In the
821 second example, @samp{#} is the interwiki delimiter. If the name of a
822 project occurs by itself in text, like the third case, it will be
823 colorized and published as a link to the default page of the given
826 Customization of interwiki links may be accomplished by editing the
827 @code{muse-wiki-interwiki-alist} option.
829 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
830 @comment node-name, next, previous, up
831 @section Publishing and displaying images
833 @cindex links, with images
834 @subheading Image links
836 Links to images may be used in either the target or the description, or
837 both. Thus, the following code will publish as a clickable image that
838 points to @url{http://www.mwolson.org/}.
841 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
844 @cindex images, displaying
845 @cindex images, inlined
846 @cindex images, local
847 If a link to a locally-available image is encountered in the link
848 description, Muse mode will attempt to display it if your version of
849 Emacs permits this. The following example will display correctly and
850 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
851 exists in the @file{../pics/} directory.
854 [[TestPage][../pics/TestLogo.png]]
857 @cindex images, without a description
858 An image link is not required to have a description. The link
859 @samp{[[../myimage.png]]} will display and publish as expected.
861 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
862 @comment node-name, next, previous, up
863 @section Inserting a horizontal line or anchor
865 @cindex horizontal rules
867 @subheading Horizontal Rules
869 Four or more dashes indicate a horizontal rule. Be sure to put blank
870 lines around it, or it will be considered part of the proceeding or
874 @cindex links, with target on same page
877 If you begin a line with "#anchor" -- where "anchor" can be any word
878 that doesn't contain whitespace -- it defines an anchor at that point
879 into the document. This point can be referenced using "page#anchor" as
880 the target in a Muse link.
882 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
883 @comment node-name, next, previous, up
884 @section Evaluating Emacs Lisp code in documents for extensibility
885 @cindex lisp, embedded
887 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
888 which is the only Muse tag supported in a style's header and footer
889 text. With the @verb{|<lisp>|} tag, you may generated whatever output
890 text you wish. The inserted output will get marked up, if the
891 @verb{|<lisp>|} tag appears within the main text of the document.
894 <lisp>(concat "This form gets " "inserted")</lisp>
897 @cindex lisp, and insert command
898 Note that you should not use the @code{insert} command within a set of
899 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
900 tags will be automatically inserted into the document.
902 @node Comments, , Embedded Lisp, Markup Rules
903 @comment node-name, next, previous, up
904 @section Lines to omit from published output
906 @cindex publishing, omitting lines
908 Use the following syntax to indicate a comment. Comments will not be
912 ; Comment text goes here.
915 That is, only a semi-colon at the beginning of a line, followed by a
916 literal space, will cause that line to be treated as a comment.
918 @node Publishing Styles, Extending Muse, Markup Rules, Top
919 @comment node-name, next, previous, up
920 @chapter Publishing Various Types of Documents
921 @cindex publishing styles
923 One of the principle features of Muse is the ability to publish a simple
924 input text to a variety of different output styles. Muse also makes it
925 easy to create new styles, or derive from an existing style.
928 * Blosxom:: Integrating Muse and pyblosxom.cgi.
929 * Book:: Publishing entries into a compilation.
930 * DocBook:: Publishing in DocBook XML form.
931 * HTML:: Publishing in HTML or XHTML form.
932 * Journal:: Keeping a journal or blog.
933 * LaTeX:: Publishing LaTeX documents.
934 * Poem:: Publish a poem to LaTex or PDF.
935 * Texinfo:: Publish entries to Texinfo format or PDF.
938 @node Blosxom, Book, Publishing Styles, Publishing Styles
939 @comment node-name, next, previous, up
940 @section Integrating Muse and pyblosxom.cgi
941 @cindex blog, one-file-per-entry style
943 The Blosxom publishing style publishes a tree of categorised files to a
944 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
945 In other words, each blog entry corresponds with one file.
948 * Blosxom Requirements:: Other tools needed to the Blosxom style.
949 * Blosxom Entries:: Format of a Blosxom entry and automation.
950 * Blosxom Options:: Blosxom styles and options provided.
953 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
954 @comment node-name, next, previous, up
955 @subsection Other tools needed to the Blosxom style
957 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
958 installed on a machine that you have upload access to.
960 The following additional components are required in order to make the
961 date of blog entries display as something sensible.
965 A script to gather date directives from the entire blog tree into a
966 single file. The file must associate a blog entry with a date.
969 A plugin for (py)blosxom that reads this file.
972 These 2 things are provided for @command{pyblosxom.cgi} in the
973 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
974 former service, while @file{hardcodedates.py} provides the latter
975 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
976 script will be found/written.
978 Here is a sample listing from my @file{timestamps} file, which maps
979 each file to a date. This can really be in any format, as long as your
980 date-gathering script and your plugin can both understand it.
983 2005-04-01-14-16 personal/paper_cranes
984 2005-03-21 personal/spring_break_over
985 2004-10-24 personal/finished_free_culture
988 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
989 @file{getstamps.py}. Note that you will need to set the current
990 directory to where your Muse files are, execute @file{getstamps.py}, and
991 then move the generated timestamps file to your publishing directory.
993 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
994 @comment node-name, next, previous, up
995 @subsection Format of a Blosxom entry and automation
997 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
998 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
999 plus whatever normal content is desired.
1001 The date directive is not used directly by @command{pyblosxom.cgi} or
1002 this program. You need to have the two additional items from the former
1003 section to make use of this feature.
1005 There is a function called @code{muse-blosxom-new-entry} that will
1006 automate the process of making a new blog entry. To make use of it, do
1011 Customize @code{muse-blosxom-base-directory} to the location that your
1012 blog entries are stored.
1015 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1016 use the following code to assign this function to @kbd{C-c p l'}.
1019 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1023 You should create your directory structure ahead of time under your base
1024 directory. These directories, which correspond with category names, may
1028 When you enter this key sequence, you will be prompted for the category
1029 of your entry and its title. Upon entering this information, a new file
1030 will be created that corresponds with the title, but in lowercase
1031 letters and having special characters converted to underscores. The
1032 title and date directives will be inserted automatically.
1035 @node Blosxom Options, , Blosxom Entries, Blosxom
1036 @comment node-name, next, previous, up
1037 @subsection Blosxom styles and options provided
1039 The following styles and options are available in the Blosxom publishing
1042 @subheading Styles provided
1046 @cindex publishing styles, blosxom-html
1048 Publish Blosxom entries in HTML form.
1050 @cindex publishing styles, blosxom-xhtml
1052 Publish Blosxom entries in XHTML form.
1056 @subheading Options provided
1060 @item muse-blosxom-extension
1061 Default file extension for publishing Blosxom files.
1063 @item muse-blosxom-header
1064 Header used for publishing Blosxom files.
1066 This may be text or a filename.
1068 @item muse-blosxom-footer
1069 Footer used for publishing Blosxom files.
1071 This may be text or a filename.
1073 @item muse-blosxom-base-directory
1074 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1076 This is the top-level directory where your blog entries may be found
1081 @node Book, DocBook, Blosxom, Publishing Styles
1082 @comment node-name, next, previous, up
1083 @section Publishing entries into a compilation
1085 This publishing style is used to output ``books'' in LaTeX or PDF
1088 Each page will become a separate chapter in the book, unless the style
1089 keyword @option{:nochapters} is used, in which case they are all run
1090 together as if one giant chapter.
1092 You will need to call the @code{muse-book-publish-project} function in
1093 order to publish this style. An example of this may be found in John
1094 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1096 @subheading Styles provided
1100 @cindex publishing styles, book-latex
1102 Publish a book in LaTeX form. The header and footer are different than
1103 the normal LaTeX publishing mode.
1105 @cindex publishing styles, book-pdf
1107 Publish a book in PDF form. The header and footer are different than
1108 the normal PDF publishing mode.
1112 @subheading Options provided
1116 @item muse-book-before-publish-hook
1117 A hook run in the book buffer before it is marked up.
1119 @item muse-book-after-publish-hook
1120 A hook run in the book buffer after it is marked up.
1122 @item muse-book-latex-header
1123 Header used for publishing books to LaTeX.
1125 This may be text or a filename.
1127 @item muse-book-latex-footer
1128 Footer used for publishing books to LaTeX.
1130 This may be text or a filename.
1134 @node DocBook, HTML, Book, Publishing Styles
1135 @comment node-name, next, previous, up
1136 @section Publishing in DocBook XML form
1138 This publishing style is used to generate DocBook XML files.
1140 @subheading Styles provided
1144 @cindex publishing styles, docbook
1149 @subheading Options provided
1153 @item muse-docbook-extension
1154 Default file extension for publishing DocBook XML files.
1156 @item muse-docbook-header
1157 Header used for publishing DocBook XML files.
1159 This may be text or a filename.
1161 @item muse-docbook-footer
1162 Footer used for publishing DocBook XML files.
1164 This may be text or a filename.
1166 @item muse-docbook-markup-regexps
1167 List of markup rules for publishing a Muse page to DocBook XML.
1169 @item muse-docbook-markup-functions
1170 An alist of style types to custom functions for that kind of text.
1172 @item muse-docbook-markup-strings
1173 Strings used for marking up text.
1175 These cover the most basic kinds of markup, the handling of which
1176 differs little between the various styles.
1178 @item muse-docbook-markup-specials
1179 A table of characters which must be represented specially.
1181 @item muse-docbook-encoding-default
1182 The default Emacs buffer encoding to use in published files.
1183 This will be used if no special characters are found.
1185 @item muse-docbook-charset-default
1186 The default DocBook XML charset to use if no translation is
1187 found in @code{muse-docbook-encoding-map}.
1189 @item muse-docbook-encoding-map
1190 An alist mapping emacs coding systems to appropriate DocBook charsets.
1191 Use the base name of the coding system (i.e. without the -unix).
1195 @node HTML, Journal, DocBook, Publishing Styles
1196 @comment node-name, next, previous, up
1197 @section Publishing in HTML or XHTML form
1199 This publishing style is capable of producing HTML or XHTML documents.
1201 @subheading Styles provided
1205 @cindex publishing styles, html
1207 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1210 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1214 @subheading Options provided
1216 If an HTML option does not have a corresponding XHTML option, it will
1217 be used for both of these publishing styles.
1221 @item muse-html-extension
1222 Default file extension for publishing HTML files.
1224 @item muse-xhtml-extension
1225 Default file extension for publishing XHTML files.
1227 @item muse-html-style-sheet
1228 Store your stylesheet definitions here.
1230 This is used in @code{muse-html-header}. You can put raw CSS in here or
1231 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1232 @verb{|<lisp>|} markup tags.
1234 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1237 @item muse-html-header
1238 Header used for publishing HTML files.
1240 This may be text or a filename.
1242 @item muse-html-footer
1243 Footer used for publishing HTML files.
1245 This may be text or a filename.
1247 @item muse-xhtml-header
1248 Header used for publishing XHTML files.
1250 This may be text or a filename.
1252 @item muse-xhtml-footer
1253 Footer used for publishing XHTML files.
1255 This may be text or a filename.
1257 @item muse-html-anchor-on-word
1258 When true, anchors surround the closest word.
1260 This allows you to select them in a browser (i.e. for pasting), but has
1261 the side-effect of marking up headers in multiple colors if your header
1262 style is different from your link style.
1264 @item muse-html-table-attributes
1265 The attribute to be used with HTML @verb{|<table>|} tags.
1267 Note that since Muse supports direct insertion of HTML tags, you can
1268 easily create any kind of table you want, as long as each line begins at
1269 column 0 (to prevent it from being blockquoted).
1271 @item muse-html-markup-regexps
1272 List of markup rules for publishing a Muse page to HTML.
1274 @item muse-html-markup-functions
1275 An alist of style types to custom functions for that kind of text.
1277 @item muse-html-markup-strings
1278 Strings used for marking up text as HTML.
1280 These cover the most basic kinds of markup, the handling of which
1281 differs little between the various styles.
1283 @item muse-xhtml-markup-strings
1284 Strings used for marking up text as XHTML.
1286 These cover the most basic kinds of markup, the handling of which
1287 differs little between the various styles.
1289 @item muse-html-markup-tags
1290 A list of tag specifications, for specially marking up HTML.
1291 @xref{muse-publish-markup-tags}, for more information.
1293 @item muse-html-markup-specials
1294 A table of characters which must be represented specially. By default,
1295 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1297 @item muse-html-meta-http-equiv
1298 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1300 @item muse-html-meta-content-type
1301 The content type used for the HTML @verb{|<meta>|} tag.
1303 If you are striving for XHTML 1.1 compliance, you may want to change
1304 this to ``application/xhtml+xml''.
1306 @item muse-html-meta-content-encoding
1307 The charset to append to the HTML @verb{|<meta>|} tag.
1309 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1310 and determine the HTML charset from emacs's coding. If set to a string,
1311 this string will be used to force a particular charset.
1313 @item muse-html-charset-default
1314 The default HTML meta charset to use if no translation is found in
1315 @code{muse-html-encoding-map}.
1317 @item muse-html-encoding-default
1318 The default Emacs buffer encoding to use in published files.
1319 This will be used if no special characters are found.
1321 @item muse-html-encoding-map
1322 An alist mapping emacs coding systems to appropriate HTML charsets.
1323 Use the base name of the coding system (i.e. without the -unix).
1327 @node Journal, LaTeX, HTML, Publishing Styles
1328 @comment node-name, next, previous, up
1329 @section Keeping a journal or blog
1331 @cindex blog, journal style
1333 The module facilitates the keeping and publication of a journal. When
1334 publishing to HTML, it assumes the form of a web log, or blog.
1336 The input format for each entry is as follows.
1339 * 20040317: Title of entry
1344 "You know who you are. It comes down to a simple gut check: You
1345 either love what you do or you don't. Period." -- P. Bronson
1349 The "qotd", or Quote of the Day, is entirely optional. When generated
1350 to HTML, this entry is rendered as the following.
1354 <div class="entry-qotd">
1355 <h3>Quote of the Day:</h3>
1356 <p>"You know who you are. It comes down to a simple gut
1357 check: You either love what you do or you don't. Period."
1360 <div class="entry-body">
1361 <div class="entry-head">
1362 <div class="entry-date">
1363 <span class="date">March 17, 2004</span>
1365 <div class="entry-title">
1366 <h2>Title of entry</h2>
1369 <div class="entry-text">
1370 <p>Text for the entry.</p>
1376 The plurality of "div" tags makes it possible to display the entries in
1377 any form you wish, using a CSS style.
1379 Also, an .RDF file can be generated from your journal by publishing it
1380 with the "rdf" style. It uses the first two sentences of the first
1381 paragraph of each entry as its "description", and auto-generates tags
1382 for linking to the various entries.
1384 @subheading Styles provided
1388 @cindex publishing styles, journal-html
1390 Publish journal entries as an HTML document.
1392 @cindex publishing styles, journal-xhtml
1394 Publish journal entries as an XHTML document.
1396 @cindex publishing styles, journal-latex
1398 Publish journal entries as a LaTeX document.
1400 @cindex publishing styles, journal-pdf
1402 Publish journal entries as a PDF document.
1404 @cindex publishing styles, journal-book-latex
1405 @item journal-book-latex
1406 Publish journal entries as a LaTeX book.
1408 @cindex publishing styles, journal-book-pdf
1409 @item journal-book-pdf
1410 Publish journal entries as a PDF book.
1412 @cindex publishing styles, journal-rdf
1413 @cindex publishing styles, RSS 1.0
1415 Publish journal entries as an RDF file (RSS 1.0).
1417 @cindex publishing styles, journal-rss
1418 @cindex publishing styles, RSS 2.0
1420 Publish journal entries as an RSS file (RSS 2.0).
1424 @subheading Options provided
1428 @item muse-journal-heading-regexp
1429 A regexp that matches a journal heading.
1431 Paren group 1 is the ISO date, group 2 is the optional category, and
1432 group 3 is the optional heading for the entry.
1434 @item muse-journal-date-format
1435 Date format to use for journal entries.
1437 @item muse-journal-html-heading-regexp
1438 A regexp that matches a journal heading from an HTML document.
1440 Paren group 1 is the ISO date, group 2 is the optional category, and
1441 group 3 is the optional heading for the entry.
1443 @item muse-journal-html-entry-template
1444 Template used to publish individual journal entries as HTML.
1446 @item muse-journal-latex-section
1447 Template used to publish a LaTeX section.
1449 @item muse-journal-latex-subsection
1450 Template used to publish a LaTeX subsection.
1452 @item muse-journal-latex-markup-tags
1453 A list of tag specifications, for specially marking up LaTeX.
1455 @xref{muse-publish-markup-tags}, for more information.
1457 @item muse-journal-rdf-extension
1458 Default file extension for publishing RDF (RSS 1.0) files.
1460 @item muse-journal-rdf-base-url
1461 The base URL of the website referenced by the RDF file.
1463 @item muse-journal-rdf-header
1464 Header used for publishing RDF (RSS 1.0) files.
1466 This may be text or a filename.
1468 @item muse-journal-rdf-footer
1469 Footer used for publishing RDF (RSS 1.0) files.
1471 This may be text or a filename.
1473 @item muse-journal-rdf-date-format
1474 Date format to use for RDF entries.
1476 @item muse-journal-rdf-entry-template
1477 Template used to publish individual journal entries as RDF.
1479 @item muse-journal-rdf-summarize-entries
1480 If non-nil, include only summaries in the RDF file, not the full data.
1482 @item muse-journal-rss-extension
1483 Default file extension for publishing RSS 2.0 files.
1485 @item muse-journal-rss-base-url
1486 The base URL of the website referenced by the RSS file.
1488 @item muse-journal-rss-header
1489 Header used for publishing RSS 2.0 files.
1491 This may be text or a filename.
1493 @item muse-journal-rss-footer
1494 Footer used for publishing RSS 2.0 files.
1496 This may be text or a filename.
1498 @item muse-journal-rss-date-format
1499 Date format to use for RSS 2.0 entries.
1501 @item muse-journal-rss-entry-template
1502 Template used to publish individual journal entries as RSS 2.0.
1504 @item muse-journal-rss-enclosure-types-alist
1505 File types that are accepted as RSS enclosures.
1507 This is an alist that maps file extension to content type.
1509 Useful for podcasting.
1511 @item muse-journal-rss-summarize-entries
1512 If non-nil, include only summaries in the RSS file, not the full data.
1514 Many RSS subscribers find this annoying.
1516 @item muse-journal-rss-markup-regexps
1517 List of markup rules for publishing a Muse journal page to RSS.
1519 For more information on the structure of this list,
1520 @xref{muse-publish-markup-regexps}.
1522 @item muse-journal-rss-markup-functions
1523 An alist of style types to custom functions for that kind of text.
1525 For more on the structure of this list,
1526 @xref{muse-publish-markup-functions}.
1530 @node LaTeX, Poem, Journal, Publishing Styles
1531 @comment node-name, next, previous, up
1532 @section Publishing LaTeX documents
1534 This publishing style is capable of producing LaTeX or PDF documents.
1536 If you wish to publish PDF documents, you will need to have a good TeX
1537 installation. For Debian, this can be accomplished by installing the
1538 ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1540 @subheading Styles provided
1544 @cindex publishing styles, latex
1546 Publish a LaTeX document.
1548 @cindex publishing styles, pdf
1550 Publish a PDF document, using an external LaTeX document conversion
1553 @cindex publishing styles, latexcjk
1555 Publish a LaTeX document with CJK (Chinese) encodings.
1557 @cindex publishing styles, pdfcjk
1559 Publish a PDF document with CJK (Chinese) encodings, using an external
1560 LaTeX document conversion tool.
1564 @subheading Options provided
1568 @item muse-latex-extension
1569 Default file extension for publishing LaTeX files.
1571 @item muse-latex-pdf-extension
1572 Default file extension for publishing LaTeX files to PDF.
1574 @item muse-latex-header
1575 Header used for publishing LaTeX files.
1577 This may be text or a filename.
1579 @item muse-latex-footer
1580 Footer used for publishing LaTeX files.
1582 This may be text or a filename.
1584 @item muse-latexcjk-header
1585 Header used for publishing LaTeX files (CJK).
1587 This may be text or a filename.
1589 @item muse-latexcjk-footer
1590 Footer used for publishing LaTeX files (CJK).
1592 This may be text or a filename.
1594 @item muse-latex-markup-regexps
1595 List of markup regexps for identifying regions in a Muse page.
1597 For more on the structure of this list,
1598 @xref{muse-publish-markup-regexps}.
1600 @item muse-latex-markup-functions
1601 An alist of style types to custom functions for that kind of text.
1603 For more on the structure of this list,
1604 @xref{muse-publish-markup-functions}.
1606 @item muse-latex-markup-strings
1607 Strings used for marking up text.
1609 These cover the most basic kinds of markup, the handling of which
1610 differs little between the various styles.
1612 @item muse-latexcjk-encoding-map
1613 An alist mapping emacs coding systems to appropriate CJK codings.
1614 Use the base name of the coding system (ie, without the -unix).
1616 @item muse-latexcjk-encoding-default
1617 The default Emacs buffer encoding to use in published files.
1619 This will be used if no special characters are found.
1621 @item muse-latex-markup-specials
1622 A table of characters which must be represented specially.
1626 @node Poem, Texinfo, LaTeX, Publishing Styles
1627 @comment node-name, next, previous, up
1628 @section Publish a poem to LaTex or PDF
1630 The @code{muse-poem} module makes it easy to attractively publish and
1631 reference poems in the following format, using the "memoir" module for
1632 LaTeX publishing. It will also markup poems for every other output
1633 style, though none are nearly as pretty.
1642 Annotations, history, notes, etc.
1645 Once a poem is written in this format, just publish it to PDF using the
1646 @code{poem-pdf} style. To make an inlined reference to a poem that
1647 you've written -- for example, from a blog page -- there is a "poem" tag
1648 defined by this module.
1651 <poem title="name.of.poem.page">
1654 Let's assume the template above was called @file{name.of.poem.page};
1655 then the above tag would result in this inclusion.
1663 John Wiegley uses this module for publishing all of the poems on his
1664 website, which are at
1665 @uref{http://www.newartisans.com/johnw/poems.html}.
1667 @subheading Styles provided
1671 @cindex publishing styles, poem-latex
1673 Publish a poem in LaTeX form.
1675 @cindex publishing styles, poem-pdf
1677 Publish a poem to a PDF document.
1679 @cindex publishing styles, chapbook-latex
1680 @item chapbook-latex
1681 Publish a book of poems in LaTeX form.
1683 @cindex publishing styles, chapbook-pdf
1685 Publish a book of poems to a PDF document.
1689 @subheading Options provided
1693 @item muse-poem-latex-header
1694 Header used for publishing LaTeX poems.
1696 This may be text or a filename.
1698 @item muse-poem-latex-footer
1699 Footer used for publishing LaTeX files.
1701 This may be text or a filename.
1703 @item muse-poem-markup-strings
1704 Strings used for marking up poems.
1706 These cover the most basic kinds of markup, the handling of which
1707 differs little between the various styles.
1709 @item muse-chapbook-latex-header
1710 Header used for publishing a book of poems in LaTeX form.
1712 This may be text or a filename.
1714 @item muse-chapbook-latex-footer
1715 Footer used for publishing a book of poems in LaTeX form.
1717 This may be text or a filename.
1719 @item muse-poem-chapbook-strings
1720 Strings used for marking up books of poems.
1722 These cover the most basic kinds of markup, the handling of which
1723 differs little between the various styles.
1727 @node Texinfo, , Poem, Publishing Styles
1728 @comment node-name, next, previous, up
1729 @section Publish entries to Texinfo format or PDF
1731 Rules for publishing a Muse file as a Texinfo article.
1733 @subheading Styles provided
1737 @cindex publishing styles, texi
1739 Publish a file in Texinfo form.
1741 @cindex publishing styles, texi
1743 Generate an Info file from a Muse file.
1745 @cindex publishing styles, info-pdf
1747 Publish a file in PDF form.
1751 @subheading Options provided
1755 @item muse-texinfo-process-natively
1756 If non-nil, use the Emacs `texinfmt' module to make Info files.
1758 @item muse-texinfo-extension
1759 Default file extension for publishing Texinfo files.
1761 @item muse-texinfo-info-extension
1762 Default file extension for publishing Info files.
1764 @item muse-texinfo-pdf-extension
1765 Default file extension for publishing PDF files.
1767 @item muse-texinfo-header
1768 Text to prepend to a Muse page being published as Texinfo.
1770 This may be text or a filename.
1771 It may contain @verb{|<lisp>|} markup tags.
1773 @item muse-texinfo-footer
1774 Text to append to a Muse page being published as Texinfo.
1776 This may be text or a filename.
1777 It may contain @verb{|<lisp>|} markup tags.
1779 @item muse-texinfo-markup-regexps
1780 List of markup rules for publishing a Muse page to Texinfo.
1782 For more on the structure of this list,
1783 @xref{muse-publish-markup-regexps}.
1785 @item muse-texinfo-markup-functions
1786 An alist of style types to custom functions for that kind of text.
1788 For more on the structure of this list, see
1789 @xref{muse-publish-markup-functions}.
1791 @item muse-texinfo-markup-strings
1792 Strings used for marking up text.
1794 These cover the most basic kinds of markup, the handling of which
1795 differs little between the various styles.
1797 @item muse-texinfo-markup-specials
1798 A table of characters which must be represented specially.
1803 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
1804 @comment node-name, next, previous, up
1805 @chapter Making your own publishing styles
1808 * Common Elements:: Common functionality shared by styles.
1809 * Deriving Styles:: Deriving a new style from an existing
1813 @node Common Elements, Deriving Styles, , Extending Muse
1814 @comment node-name, next, previous, up
1815 @section Common functionality shared by styles
1816 @cindex publishing styles, common
1819 * Markup Functions:: Specifying functions to marking up text.
1820 * Markup Regexps:: Markup rules for publishing.
1821 * Markup Strings:: Strings specific to a publishing style.
1822 * Markup Tags:: Tag specifications for special markup.
1823 * Style Elements:: Parameters used for defining styles.
1826 @node Markup Functions, Markup Regexps, , Common Elements
1827 @comment node-name, next, previous, up
1828 @subsection Specifying functions to mark up text
1829 @cindex publishing, markup functions
1831 @anchor{muse-publish-markup-functions}
1832 @code{muse-publish-markup-functions}
1834 An alist of style types to custom functions for that kind of text.
1836 This is used by publishing styles to attempt to minimize the amount of
1837 custom regexps that each has to define. @file{muse-publish} provides
1838 rules for the most common types of markup.
1840 Each member of the list is of the following form.
1848 Describes the type of text to associate with this rule.
1849 @code{muse-publish-markup-regexps} maps regexps to these symbols.
1852 Function to use to mark up this kind of rule if no suitable function is
1853 found through the @option{:functions} tag of the current style.
1856 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
1857 @comment node-name, next, previous, up
1858 @subsection Markup rules for publishing
1859 @cindex publishing, markup regexps
1860 @cindex publishing, rules
1862 @anchor{muse-publish-markup-regexps}
1863 @code{muse-publish-markup-regexps}
1865 List of markup rules for publishing a page with Muse.
1867 The rules given in this variable are invoked first, followed by whatever
1868 rules are specified by the current style.
1870 Each member of the list is either a function, or a list of the following
1874 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1879 A regular expression, or symbol whose value is a regular expression,
1880 which is searched for using `re-search-forward'.
1882 @item TEXT-BEGIN-GROUP
1883 The matching group within that regexp which denotes the beginning of the
1884 actual text to be marked up.
1886 @item REPLACEMENT-TEXT
1887 A string that will be passed to `replace-match'.
1889 If it is not a string, but a function, it will be called to determine
1890 what the replacement text should be (it must return a string). If it is
1891 a symbol, the value of that symbol should be a string.
1894 The replacements are done in order, one rule at a time. Writing
1895 the regular expressions can be a tricky business. Note that case
1896 is never ignored. `case-fold-search' is always bound to nil
1897 while processing the markup rules.
1899 @subheading Publishing order
1901 This is the order that the publishing rules are consulted, by default.
1902 This may be changed by customizing @code{muse-publish-markup-regexps}.
1906 @item trailing and leading whitespace
1907 Remove trailing and leading whitespace from a file.
1912 This is only recognized at the beginning of a file.
1923 @item explicit links
1924 Prevent emphasis characters in explicit links from being marked up.
1926 Don't actually publish them here, just add a special no-emphasis text
1930 Whitespace-delimited word, possibly with emphasis characters
1932 This function is responsible for marking up emphasis and escaping some
1943 Outline-mode style headings.
1948 These are ellipses with a dot at end.
1958 Horizontal rule or section separator.
1963 beginning of footnotes section
1968 Footnote definition or reference. If at beginning of line, it is a
1983 Numbered list, item list, or term definition list.
1986 spaces before beginning of text
1994 @samp{table | cells}
1997 @samp{[[explicit][links]]}
2000 @samp{http://example.com/}
2003 @samp{bare-email@@example.com}
2007 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
2008 @comment node-name, next, previous, up
2009 @subsection Strings specific to a publishing style
2010 @cindex publishing, markup strings
2012 @dfn{Markup strings} are strings used for marking up text for a
2015 These cover the most basic kinds of markup, the handling of which
2016 differs little between the various styles.
2018 @subheading Available markup strings
2022 @item image-with-desc
2023 An image and a description.
2025 Argument 1: image. Argument 2: description.
2030 Argument 1: image link.
2032 @item url-with-image
2033 A URL with an image.
2035 Argument 1: link. Argument 2: image.
2038 A link with a description.
2040 Argument 1: link. Argument 2: description if one exists, or the
2041 original link otherwise.
2044 A link that refers to an internal anchor.
2046 Argument 1: internal link. Argument 2: description if one exists, or
2047 the original link otherwise.
2050 A link to an email address.
2052 Argument 1: email address. Argument 2: email address.
2058 A horizontal line or space.
2061 Beginning of footnote.
2067 Mark a reference for the current footnote.
2069 Argument 1: number of this footnote.
2072 Indicate the text of the current footnote.
2074 Argument 1: number of this footnote.
2076 @item footnotetext-end
2077 End of a footnote text line.
2080 Text used to replace ``Footnotes:'' line.
2089 Beginning of a part indicator line. This is used by book publishing.
2092 End of a part indicator line. This is used by book publishing.
2095 Beginning of a chapter indicator line. This is used by book publishing.
2098 End of a chapter indicator line. This is used by book publishing.
2101 Beginning of level 1 section indicator line.
2103 Argument 1: level of section; always 1.
2106 End of level 1 section indicator line.
2108 Argument 1: level of section; always 1.
2111 Beginning of level 2 section indicator line.
2113 Argument 1: level of section; always 2.
2115 @item subsection-end
2116 End of level 2 section indicator line.
2118 Argument 1: level of section; always 2.
2121 Beginning of level 3 section indicator line.
2123 Argument 1: level of section; always 3.
2125 @item subsubsection-end
2126 End of level 3 section indicator line.
2128 Argument 1: level of section; always 3.
2131 Beginning of section indicator line, where level is greater than 3.
2133 Argument 1: level of section.
2135 @item section-other-end
2136 Beginning of section indicator line, where level is greater than 3.
2138 Argument 1: level of section.
2140 @item begin-underline
2141 Beginning of underlined text.
2144 End of underlined text.
2147 Beginning of verbatim text. This includes @verb{|<code>|} tags and
2151 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2155 Beginning of the first level of emphasized text.
2158 End of the first level of emphasized text.
2160 @item begin-more-emph
2161 Beginning of the second level of emphasized text.
2164 End of the second level of emphasized text.
2166 @item begin-most-emph
2167 Beginning of the third (and final) level of emphasized text.
2170 End of the third (and final) level of emphasized text.
2173 Beginning of verse text.
2176 String used to each space that is further indented than the beginning of
2179 @item begin-verse-line
2180 Beginning of a line of verse.
2182 @item empty-verse-line
2183 End of a line of verse.
2185 @item begin-last-stanza-line
2186 Beginning of the last line of a verse stanza.
2188 @item end-last-stanza-line
2189 End of the last line of a verse stanza.
2195 Beginning of an example region. To make use of this, an
2196 @samp{<example>} tag is needed.
2199 End of an example region. To make use of this, an @samp{</example>} tag
2203 Begin a centered line.
2206 End a centered line.
2209 Begin a quoted region.
2212 End a quoted region.
2215 Begin an unordered list.
2218 End an unordered list.
2221 Begin an ordered list.
2224 End an ordered list.
2227 Begin a definition list.
2230 Begin a term in a definition list.
2233 End a definition list.
2237 @node Markup Tags, Style Elements, Markup Strings, Common Elements
2238 @comment node-name, next, previous, up
2239 @subsection Tag specifications for special markup
2240 @cindex publishing, markup tags
2242 @anchor{muse-publish-markup-tags}
2243 @code{muse-publish-markup-tags}
2245 A list of tag specifications, for specially marking up text.
2247 XML-style tags are the best way to add custom markup to Muse. This is
2248 easily accomplished by customizing this list of markup tags.
2250 For each entry, the name of the tag is given, whether it expects a
2251 closing tag and/or an optional set of attributes, and a function that
2252 performs whatever action is desired within the delimited region.
2254 The tags themselves are deleted during publishing, before the function
2255 is called. The function is called with three arguments, the beginning
2256 and end of the region surrounded by the tags. If properties are
2257 allowed, they are passed as a third argument in the form of an alist.
2258 The `end' argument to the function is always a marker.
2260 Point is always at the beginning of the region within the tags, when the
2261 function is called. Wherever point is when the function finishes is
2262 where tag markup will resume.
2264 These tag rules are processed once at the beginning of markup, and once
2265 at the end, to catch any tags which may have been inserted in-between.
2267 @node Style Elements, , Markup Tags, Common Elements
2268 @comment node-name, next, previous, up
2269 @subsection Parameters used for defining styles
2270 @cindex publishing, style elements
2272 Style elements are tags that define a style. Use
2273 @code{muse-define-style} to create a new style.
2276 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2279 @subheading Usable elements
2284 File extension to use for publishing files with this style.
2287 File extension to use for publishing links to Muse files with this
2291 File extension to use for publishing second-stage files with this style.
2293 For example, PDF publishing generates a LaTeX file first, then a PDF
2294 from that LaTeX file.
2297 List of markup rules for publishing a page with Muse.
2298 @xref{muse-publish-markup-regexps}.
2301 An alist of style types to custom functions for that kind of text.
2302 @xref{muse-publish-markup-functions}.
2305 Strings used for marking up text with this style.
2307 These cover the most basic kinds of markup, the handling of which
2308 differs little between the various styles.
2311 A list of tag specifications, used for handling extra tags.
2312 @xref{muse-publish-markup-tags}.
2315 A table of characters which must be represented specially.
2318 A function that is to be executed on the newly-created publishing buffer
2319 (or the current region) before any publishing occurs.
2321 This is used to set extra parameters that direct the publishing process.
2324 A function that is to be executed on the publishing buffer (or the
2325 current region) immediately after applying all of the markup regexps.
2327 This is used to fix the order of table elements (header, footer, body)
2331 A function that is to be executed on the publishing buffer after
2332 :before-end, and immediately after inserting the header and footer.
2334 This is used for generating the table of contents as well as setting the
2338 A function that is to be executed after saving the published file, but
2339 while still in its buffer.
2341 This is used for generating second-stage documents like PDF files from
2342 just-published LaTeX files.
2345 Header used for publishing files of this style.
2347 This may be a variable, text, or a filename. It is inserted at the
2348 beginning of a file, after evaluating the publishing markup.
2351 Footer used for publishing files of this style.
2353 This may be a variable, text, or a filename. It is inserted at the end
2354 of a file, after evaluating the publishing markup.
2357 Style sheet used for publishing files of this style.
2359 This may be a variable or text. It is used in the header of HTML and
2360 XHTML based publishing styles.
2363 The function used to browse the published result of files of this style.
2367 @node Deriving Styles, , Common Elements, Extending Muse
2368 @comment node-name, next, previous, up
2369 @section Deriving a new style from an existing one
2370 @cindex publishing styles, deriving
2372 To create a new style from an existing one, use @code{muse-derive-style}
2373 as follows. This is a good way to fix something you don't like about a
2374 particular publishing style, or to personalize it.
2377 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2380 The derived name is a string defining the new style, such as "my-html".
2381 The base name must identify an existing style, such as "html" -- if you
2382 have loaded @file{muse-html}. The style parameters are the same as
2383 those used to create a style, except that they override whatever
2384 definitions exist in the base style. However, some definitions only
2385 partially override. The following parameters support partial
2388 @xref{Style Elements}, for a complete list of all parameters.
2393 If a markup function is not found in the derived style's function list,
2394 the base style's function list will be queried.
2397 All regexps in the current style and the base style(s) will be used.
2400 If a markup string is not found in the derived style's string list, the
2401 base style's string list will be queried.
2406 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
2407 @comment node-name, next, previous, up
2408 @chapter Getting Help and Reporting Bugs
2409 @cindex help, getting
2410 @cindex bugs, reporting
2412 After you have read this guide, if you still have questions about
2413 Muse, or if you have bugs to report, there are several places you can
2419 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
2420 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2424 @uref{http://www.mwolson.org/projects/EmacsMuse.html} is the web page
2425 that Michael Olson (the current maintainer) made for Muse.
2428 You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
2429 using the subscription form at
2430 @uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
2431 This mailing list provides support for Muse, @command{Planner} and
2432 @command{emacs-wiki}, which is the predecessor of Muse.
2434 There are additional methods for accessing the mailing list, adding
2435 content to it, and searching it. Consult
2436 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
2440 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2441 contributors are frequently around and willing to answer your
2442 questions. The @samp{#muse} channel is also available for
2443 Muse-specific help, and its current maintainer hangs out there.
2446 The maintainer of Emacs Muse, Michael Olson, may be contacted at
2447 @email{mwolson@@gnu.org}.
2451 @node History, Contributors, Getting Help and Reporting Bugs, Top
2452 @comment node-name, next, previous, up
2453 @chapter History of This Document
2454 @cindex history, of Muse
2458 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2459 limitations. Around February 2004, he started making "emacs-wiki version
2460 3.00 APLHA", which eventually became known as Muse.
2462 Most of those who frequent the emacs-wiki mailing list continued to use
2463 emacs-wiki, mainly because Planner hasn't been ported over to it.
2465 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2466 John Wiegley's request.
2469 Michael Olson overhauled this document and added many new sections in
2470 preparation for the first release of Muse (3.01).
2474 @node Contributors, GNU General Public License, History, Top
2475 @comment node-name, next, previous, up
2476 @chapter Contributors to This Documentation
2477 @cindex contributors
2479 The first draft of this document was taken from the emacs-wiki texinfo
2480 manual. Michael Olson adapted it for Muse and added most of its
2483 John Sullivan did a majority of the work on the emacs-wiki texinfo
2486 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2487 emacs-wiki texinfo manual.
2489 @node GNU General Public License, Concept Index, Contributors, Top
2490 @comment node-name, next, previous, up
2491 @appendix GNU GENERAL PUBLIC LICENSE
2492 @center Version 2, June 1991
2494 @cindex GNU General Public License
2496 @c This file is intended to be included in another file.
2499 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2500 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2502 Everyone is permitted to copy and distribute verbatim copies
2503 of this license document, but changing it is not allowed.
2506 @appendixsec Preamble
2508 The licenses for most software are designed to take away your
2509 freedom to share and change it. By contrast, the GNU General Public
2510 License is intended to guarantee your freedom to share and change free
2511 software---to make sure the software is free for all its users. This
2512 General Public License applies to most of the Free Software
2513 Foundation's software and to any other program whose authors commit to
2514 using it. (Some other Free Software Foundation software is covered by
2515 the GNU Library General Public License instead.) You can apply it to
2518 When we speak of free software, we are referring to freedom, not
2519 price. Our General Public Licenses are designed to make sure that you
2520 have the freedom to distribute copies of free software (and charge for
2521 this service if you wish), that you receive source code or can get it
2522 if you want it, that you can change the software or use pieces of it
2523 in new free programs; and that you know you can do these things.
2525 To protect your rights, we need to make restrictions that forbid
2526 anyone to deny you these rights or to ask you to surrender the rights.
2527 These restrictions translate to certain responsibilities for you if you
2528 distribute copies of the software, or if you modify it.
2530 For example, if you distribute copies of such a program, whether
2531 gratis or for a fee, you must give the recipients all the rights that
2532 you have. You must make sure that they, too, receive or can get the
2533 source code. And you must show them these terms so they know their
2536 We protect your rights with two steps: (1) copyright the software, and
2537 (2) offer you this license which gives you legal permission to copy,
2538 distribute and/or modify the software.
2540 Also, for each author's protection and ours, we want to make certain
2541 that everyone understands that there is no warranty for this free
2542 software. If the software is modified by someone else and passed on, we
2543 want its recipients to know that what they have is not the original, so
2544 that any problems introduced by others will not reflect on the original
2545 authors' reputations.
2547 Finally, any free program is threatened constantly by software
2548 patents. We wish to avoid the danger that redistributors of a free
2549 program will individually obtain patent licenses, in effect making the
2550 program proprietary. To prevent this, we have made it clear that any
2551 patent must be licensed for everyone's free use or not licensed at all.
2553 The precise terms and conditions for copying, distribution and
2554 modification follow.
2557 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2560 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2565 This License applies to any program or other work which contains
2566 a notice placed by the copyright holder saying it may be distributed
2567 under the terms of this General Public License. The ``Program'', below,
2568 refers to any such program or work, and a ``work based on the Program''
2569 means either the Program or any derivative work under copyright law:
2570 that is to say, a work containing the Program or a portion of it,
2571 either verbatim or with modifications and/or translated into another
2572 language. (Hereinafter, translation is included without limitation in
2573 the term ``modification''.) Each licensee is addressed as ``you''.
2575 Activities other than copying, distribution and modification are not
2576 covered by this License; they are outside its scope. The act of
2577 running the Program is not restricted, and the output from the Program
2578 is covered only if its contents constitute a work based on the
2579 Program (independent of having been made by running the Program).
2580 Whether that is true depends on what the Program does.
2583 You may copy and distribute verbatim copies of the Program's
2584 source code as you receive it, in any medium, provided that you
2585 conspicuously and appropriately publish on each copy an appropriate
2586 copyright notice and disclaimer of warranty; keep intact all the
2587 notices that refer to this License and to the absence of any warranty;
2588 and give any other recipients of the Program a copy of this License
2589 along with the Program.
2591 You may charge a fee for the physical act of transferring a copy, and
2592 you may at your option offer warranty protection in exchange for a fee.
2595 You may modify your copy or copies of the Program or any portion
2596 of it, thus forming a work based on the Program, and copy and
2597 distribute such modifications or work under the terms of Section 1
2598 above, provided that you also meet all of these conditions:
2602 You must cause the modified files to carry prominent notices
2603 stating that you changed the files and the date of any change.
2606 You must cause any work that you distribute or publish, that in
2607 whole or in part contains or is derived from the Program or any
2608 part thereof, to be licensed as a whole at no charge to all third
2609 parties under the terms of this License.
2612 If the modified program normally reads commands interactively
2613 when run, you must cause it, when started running for such
2614 interactive use in the most ordinary way, to print or display an
2615 announcement including an appropriate copyright notice and a
2616 notice that there is no warranty (or else, saying that you provide
2617 a warranty) and that users may redistribute the program under
2618 these conditions, and telling the user how to view a copy of this
2619 License. (Exception: if the Program itself is interactive but
2620 does not normally print such an announcement, your work based on
2621 the Program is not required to print an announcement.)
2624 These requirements apply to the modified work as a whole. If
2625 identifiable sections of that work are not derived from the Program,
2626 and can be reasonably considered independent and separate works in
2627 themselves, then this License, and its terms, do not apply to those
2628 sections when you distribute them as separate works. But when you
2629 distribute the same sections as part of a whole which is a work based
2630 on the Program, the distribution of the whole must be on the terms of
2631 this License, whose permissions for other licensees extend to the
2632 entire whole, and thus to each and every part regardless of who wrote it.
2634 Thus, it is not the intent of this section to claim rights or contest
2635 your rights to work written entirely by you; rather, the intent is to
2636 exercise the right to control the distribution of derivative or
2637 collective works based on the Program.
2639 In addition, mere aggregation of another work not based on the Program
2640 with the Program (or with a work based on the Program) on a volume of
2641 a storage or distribution medium does not bring the other work under
2642 the scope of this License.
2645 You may copy and distribute the Program (or a work based on it,
2646 under Section 2) in object code or executable form under the terms of
2647 Sections 1 and 2 above provided that you also do one of the following:
2651 Accompany it with the complete corresponding machine-readable
2652 source code, which must be distributed under the terms of Sections
2653 1 and 2 above on a medium customarily used for software interchange; or,
2656 Accompany it with a written offer, valid for at least three
2657 years, to give any third party, for a charge no more than your
2658 cost of physically performing source distribution, a complete
2659 machine-readable copy of the corresponding source code, to be
2660 distributed under the terms of Sections 1 and 2 above on a medium
2661 customarily used for software interchange; or,
2664 Accompany it with the information you received as to the offer
2665 to distribute corresponding source code. (This alternative is
2666 allowed only for noncommercial distribution and only if you
2667 received the program in object code or executable form with such
2668 an offer, in accord with Subsection b above.)
2671 The source code for a work means the preferred form of the work for
2672 making modifications to it. For an executable work, complete source
2673 code means all the source code for all modules it contains, plus any
2674 associated interface definition files, plus the scripts used to
2675 control compilation and installation of the executable. However, as a
2676 special exception, the source code distributed need not include
2677 anything that is normally distributed (in either source or binary
2678 form) with the major components (compiler, kernel, and so on) of the
2679 operating system on which the executable runs, unless that component
2680 itself accompanies the executable.
2682 If distribution of executable or object code is made by offering
2683 access to copy from a designated place, then offering equivalent
2684 access to copy the source code from the same place counts as
2685 distribution of the source code, even though third parties are not
2686 compelled to copy the source along with the object code.
2689 You may not copy, modify, sublicense, or distribute the Program
2690 except as expressly provided under this License. Any attempt
2691 otherwise to copy, modify, sublicense or distribute the Program is
2692 void, and will automatically terminate your rights under this License.
2693 However, parties who have received copies, or rights, from you under
2694 this License will not have their licenses terminated so long as such
2695 parties remain in full compliance.
2698 You are not required to accept this License, since you have not
2699 signed it. However, nothing else grants you permission to modify or
2700 distribute the Program or its derivative works. These actions are
2701 prohibited by law if you do not accept this License. Therefore, by
2702 modifying or distributing the Program (or any work based on the
2703 Program), you indicate your acceptance of this License to do so, and
2704 all its terms and conditions for copying, distributing or modifying
2705 the Program or works based on it.
2708 Each time you redistribute the Program (or any work based on the
2709 Program), the recipient automatically receives a license from the
2710 original licensor to copy, distribute or modify the Program subject to
2711 these terms and conditions. You may not impose any further
2712 restrictions on the recipients' exercise of the rights granted herein.
2713 You are not responsible for enforcing compliance by third parties to
2717 If, as a consequence of a court judgment or allegation of patent
2718 infringement or for any other reason (not limited to patent issues),
2719 conditions are imposed on you (whether by court order, agreement or
2720 otherwise) that contradict the conditions of this License, they do not
2721 excuse you from the conditions of this License. If you cannot
2722 distribute so as to satisfy simultaneously your obligations under this
2723 License and any other pertinent obligations, then as a consequence you
2724 may not distribute the Program at all. For example, if a patent
2725 license would not permit royalty-free redistribution of the Program by
2726 all those who receive copies directly or indirectly through you, then
2727 the only way you could satisfy both it and this License would be to
2728 refrain entirely from distribution of the Program.
2730 If any portion of this section is held invalid or unenforceable under
2731 any particular circumstance, the balance of the section is intended to
2732 apply and the section as a whole is intended to apply in other
2735 It is not the purpose of this section to induce you to infringe any
2736 patents or other property right claims or to contest validity of any
2737 such claims; this section has the sole purpose of protecting the
2738 integrity of the free software distribution system, which is
2739 implemented by public license practices. Many people have made
2740 generous contributions to the wide range of software distributed
2741 through that system in reliance on consistent application of that
2742 system; it is up to the author/donor to decide if he or she is willing
2743 to distribute software through any other system and a licensee cannot
2746 This section is intended to make thoroughly clear what is believed to
2747 be a consequence of the rest of this License.
2750 If the distribution and/or use of the Program is restricted in
2751 certain countries either by patents or by copyrighted interfaces, the
2752 original copyright holder who places the Program under this License
2753 may add an explicit geographical distribution limitation excluding
2754 those countries, so that distribution is permitted only in or among
2755 countries not thus excluded. In such case, this License incorporates
2756 the limitation as if written in the body of this License.
2759 The Free Software Foundation may publish revised and/or new versions
2760 of the General Public License from time to time. Such new versions will
2761 be similar in spirit to the present version, but may differ in detail to
2762 address new problems or concerns.
2764 Each version is given a distinguishing version number. If the Program
2765 specifies a version number of this License which applies to it and ``any
2766 later version'', you have the option of following the terms and conditions
2767 either of that version or of any later version published by the Free
2768 Software Foundation. If the Program does not specify a version number of
2769 this License, you may choose any version ever published by the Free Software
2773 If you wish to incorporate parts of the Program into other free
2774 programs whose distribution conditions are different, write to the author
2775 to ask for permission. For software which is copyrighted by the Free
2776 Software Foundation, write to the Free Software Foundation; we sometimes
2777 make exceptions for this. Our decision will be guided by the two goals
2778 of preserving the free status of all derivatives of our free software and
2779 of promoting the sharing and reuse of software generally.
2782 @heading NO WARRANTY
2789 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2790 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2791 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2792 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2793 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2794 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2795 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2796 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2797 REPAIR OR CORRECTION.
2800 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2801 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2802 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2803 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2804 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2805 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2806 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2807 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2808 POSSIBILITY OF SUCH DAMAGES.
2812 @heading END OF TERMS AND CONDITIONS
2815 @center END OF TERMS AND CONDITIONS
2819 @appendixsec Appendix: How to Apply These Terms to Your New Programs
2821 If you develop a new program, and you want it to be of the greatest
2822 possible use to the public, the best way to achieve this is to make it
2823 free software which everyone can redistribute and change under these terms.
2825 To do so, attach the following notices to the program. It is safest
2826 to attach them to the start of each source file to most effectively
2827 convey the exclusion of warranty; and each file should have at least
2828 the ``copyright'' line and a pointer to where the full notice is found.
2831 @var{one line to give the program's name and a brief idea of what it does.}
2832 Copyright (C) @var{yyyy} @var{name of author}
2834 This program is free software; you can redistribute it and/or modify
2835 it under the terms of the GNU General Public License as published by
2836 the Free Software Foundation; either version 2 of the License, or
2837 (at your option) any later version.
2839 This program is distributed in the hope that it will be useful,
2840 but WITHOUT ANY WARRANTY; without even the implied warranty of
2841 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2842 GNU General Public License for more details.
2844 You should have received a copy of the GNU General Public License along
2845 with this program; if not, write to the Free Software Foundation, Inc.,
2846 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2849 Also add information on how to contact you by electronic and paper mail.
2851 If the program is interactive, make it output a short notice like this
2852 when it starts in an interactive mode:
2855 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2856 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2857 This is free software, and you are welcome to redistribute it
2858 under certain conditions; type `show c' for details.
2861 The hypothetical commands @samp{show w} and @samp{show c} should show
2862 the appropriate parts of the General Public License. Of course, the
2863 commands you use may be called something other than @samp{show w} and
2864 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2867 You should also get your employer (if you work as a programmer) or your
2868 school, if any, to sign a ``copyright disclaimer'' for the program, if
2869 necessary. Here is a sample; alter the names:
2872 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2873 `Gnomovision' (which makes passes at compilers) written by James Hacker.
2875 @var{signature of Ty Coon}, 1 April 1989
2876 Ty Coon, President of Vice
2879 This General Public License does not permit incorporating your program into
2880 proprietary programs. If your program is a subroutine library, you may
2881 consider it more useful to permit linking proprietary applications with the
2882 library. If this is what you want to do, use the GNU Library General
2883 Public License instead of this License.
2886 @node Concept Index, , GNU General Public License, Top
2887 @comment node-name, next, previous, up