1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for the Emacs Muse version 3.01.
17 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU General Public License.
27 @subtitle an authoring and publishing environment
28 @subtitle for GNU Emacs and XEmacs
30 @c The following two commands
31 @c start the copyright page.
33 @vskip 0pt plus 1filll
37 @c So the toc is printed at the start
41 @node Top, Preface, (dir), (dir)
42 @comment node-name, next, previous, up
49 * Preface:: About the documentation.
50 * Introduction:: What is Muse?
51 * Obtaining Muse:: How to get Muse releases and development
53 * Installation:: Compiling and installing Muse.
54 * Getting Started:: Settings for Muse.
55 * Projects:: Creating and managing Muse projects.
56 * Keystroke Summary:: Keys used in Muse mode.
57 * Markup Rules:: Rules for using markup.
58 * Publishing Styles:: Publishing various types of documents.
59 * Getting Help and Reporting Bugs::
60 * History:: History of this document.
61 * Contributors:: Contributors to this documentation.
62 * GNU General Public License:: The license for this manual and Muse.
63 * Concept Index:: Search for terms.
66 --- The Detailed Node Listing ---
68 How to Get Muse Releases and Development Changes
70 * Releases:: Released versions of Muse.
71 * Development:: Latest unreleased development changes.
73 Rules for Using Markup
75 * Paragraphs:: Paragraphs: centering and quoting.
76 * Headings:: Levels of headings.
77 * Emphasizing Text:: Bold, italicized, and underlined text.
78 * Footnotes:: Making notes to be shown at the end.
79 * Verse:: Indicating poetic stanzas.
80 * Lists:: Lists of items.
81 * Tables:: Generation of data tables.
82 * Links:: Hyperlinks and email addresses.
83 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
84 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
87 Publishing Various Types of Documents
89 * Blosxom:: Integrating Muse and pyblosxom.cgi.
90 * Book:: Publishing entries into a compilation.
91 * DocBook:: Publishing in DocBook XML form.
92 * HTML:: Publishing in HTML or XHTML form.
93 * Journal:: Keeping a journal or blog.
94 * LaTeX:: Publishing LaTeX documents.
95 * Poem:: Publish a poem to LaTex or PDF.
96 * Texinfo:: Publish entries to Texinfo format or PDF.
97 * Common Elements:: Common functionality shared by styles.
98 * Deriving Styles:: Deriving a new style from an existing
101 Integrating Muse and pyblosxom.cgi
103 * Blosxom Requirements:: Other tools needed to the Blosxom style.
104 * Blosxom Entries:: Format of a Blosxom entry and automation.
105 * Blosxom Options:: Blosxom styles and options provided.
110 @node Preface, Introduction, Top, Top
111 @comment node-name, next, previous, up
112 @chapter About the documentation
114 This document describes Muse, which was written by John Wiegley
115 and is now maintained by Michael Olson. Several versions of it are
119 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
120 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
121 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
124 @node Introduction, Obtaining Muse, Preface, Top
125 @comment node-name, next, previous, up
126 @chapter What is Muse?
128 Emacs Muse is an authoring and publishing environment for Emacs. It
129 simplifies the process of writing documents and publishing them to
130 various output formats.
132 Muse consists of two main parts: an enhanced text-mode for authoring
133 documents and navigating within Muse projects, and a set of publishing
134 styles for generating different kinds of output.
136 This idea is not in any way new. Numerous systems exist -- even one
137 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
138 more modular environment, with a rather simple core, in which "styles"
139 are derived from to create new styles. Much of Muse's overall
140 functionality is optional. For example, you can use the publisher
141 without the major-mode, or the mode without doing any publishing; or if
142 you don't load the Texinfo or LaTeX modules, those styles won't be
145 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
146 code has been restructured and rewritten, especially its publishing
147 functions. The focus in this revision is on the authoring and publishing
148 aspects, and the "wikiness" has been removed as a default behavior (to
149 be offered again as an optional module). CamelCase words are no longer
152 @node Obtaining Muse, Installation, Introduction, Top
153 @comment node-name, next, previous, up
154 @chapter How to Get Muse Releases and Development Changes
157 * Releases:: Released versions of Muse.
158 * Development:: Latest unreleased development changes.
161 @node Releases, Development, Obtaining Muse, Obtaining Muse
162 @comment node-name, next, previous, up
163 @section Released versions of Muse
165 Choose to install a release if you want to minimize risk.
167 Errors are corrected in development first. User-visible changes will be
168 announced on the @email{emacs-wiki-discuss@@nongnu.org} mailing list.
169 This mailing list also provides support for @command{Planner} and
170 @command{emacs-wiki}, which is the predecessor of Muse.
171 @pxref{Getting Help and Reporting Bugs}.
173 @cindex releases, Debian package
174 @cindex Debian package for Muse
175 Debian users can get Muse via apt-get. The @file{muse} package will be
176 made available at Michael Olson's Debian repository. To make use of it,
177 add the following line to your @file{/etc/apt/sources.list} file and run
178 @code{apt-get install muse}.
181 deb http://www.mwolson.org/debian/ ./
184 @cindex releases, from source
185 Alternatively, you can download the latest release from
186 @uref{http://www.mwolson.org/static/dist/muse/} .
188 @node Development, , Releases, Obtaining Muse
189 @comment node-name, next, previous, up
190 @section Latest unreleased development changes
193 Choose the development version if you want to live on the bleeding edge
194 of Muse development or try out new features before release.
196 @cindex arch revision control system, using
197 The Arch revision control system allows you to retrieve previous
198 versions and select specific features and bug fixes. If you would like
199 to contribute to Muse development, it is highly recommended that you use
200 Arch, but this is not a requirement.
202 If you are new to Arch, you might find this tutorial helpful:
203 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
205 Downloading the Muse module with Arch and staying up-to-date involves
212 @item Debian: @kbd{apt-get install tla}.
213 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
216 @item Register the archive.
218 tla register-archive -f http://www.mwolson.org/archives/2005
221 @item Download the Muse package.
223 # Download Muse into the @file{muse} directory.
224 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
227 @item List upstream changes that are missing from your local copy.
228 Do this whenever you want to see whether new changes have been committed
232 # Change to the source directory you are interested in.
235 # Display the summary of changes
236 tla missing --summary
239 @cindex updating Muse with Arch
240 @item Update to the latest version by replaying missing changes.
248 There are other ways to interact with the Muse archive.
251 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
252 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
255 The latest development snapshot will be kept up-to-date since it is
256 updated at the same time as the Arch repository.
258 @node Installation, Getting Started, Obtaining Muse, Top
259 @comment node-name, next, previous, up
260 @chapter Compiling and Installing Muse
262 Muse may be compiled and installed on your machine.
266 This is an optional step, since Emacs Lisp source code does not
267 necessarily have to be byte-compiled. It will yield a speed increase,
270 A working copy of Emacs or XEmacs is needed in order to compile the
271 Emacs Muse. By default, the program that is installed with the name
272 @command{emacs} will be used.
274 If you want to use the @command{xemacs} binary to perform the
275 compilation, you would need to edit @file{Makefile.defs} in the
276 top-level directory as follows. You can put either a full path to an
277 Emacs or XEmacs binary or just the command name, as long as it is in the
282 SITEFLAG = -no-site-file
285 Running @code{make} should compile the Muse source files in the
286 @file{lisp} directory.
290 Muse may be installed into your file hierarchy by doing the following.
292 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
293 where you want the source and compiled Muse files to be installed and
294 @env{INFODIR} indicates where to put the Muse manual. Of course, you
295 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
296 Compilation section if you are using XEmacs.
298 Run @code{make} as a normal user.
300 Run @code{make install} as the root user if you have chosen installation
301 locations that require this.
304 @node Getting Started, Projects, Installation, Top
305 @comment node-name, next, previous, up
306 @chapter Getting Started
309 To use Muse, add the directory containing its files to your
310 @code{load-path} variable, in your @file{.emacs} file. Then, load in
311 the authoring mode, and the styles you wish to publish to. An example
315 (add-to-list 'load-path "<path to Muse>")
317 (require 'muse-mode) ; load authoring mode
319 (require 'muse-html) ; load publishing styles I use
320 (require 'muse-latex)
321 (require 'muse-texinfo)
322 (require 'muse-docbook)
325 Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
326 an input document to any available style. If you enable
327 @file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
328 command will be bound to @kbd{C-c C-t}.
330 If the currently opened file is part of a defined project in
331 @code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
333 You should also type @kbd{M-x customize-group}, and give the name
334 @samp{muse}. Change it to suit your preferences. Each of the
335 options has its own documentation.
338 @node Projects, Keystroke Summary, Getting Started, Top
339 @comment node-name, next, previous, up
340 @chapter Creating and Managing Muse Projects
343 Often you will want to publish all the files within a directory to a
344 particular set of output styles automatically. To support, Muse
345 allows for the creations of "projects". Here is a sample project, to
346 be defined in your @file{.emacs} file.
349 (require 'muse-project)
351 (setq muse-project-alist
352 '(("website" ; my various writings
353 ("~/Pages" :default "index")
354 (:base "html" :path "~/public_html")
355 (:base "pdf" :path "~/public_html/pdf"))))
358 The above defines a project named "website", whose files are located
359 in the directory @file{~/Pages}. The default page to visit is
360 @file{index}. When this project is published, each page will be
361 output as HTML to the directory @file{~/public_html}, and as PDF to
362 the directory @file{~/public_html/pdf}. Within any project page, you
363 may create a link to other pages using the syntax @samp{[[pagename]]}.
366 @node Keystroke Summary, Markup Rules, Projects, Top
367 @comment node-name, next, previous, up
368 @chapter Keys Used in Muse Mode
371 This is a summary of keystrokes available in every Muse buffer.
375 @item C-c C-a (`muse-index')
376 Display an index of all known Muse pages.
378 @item C-c C-b (`muse-browse-result')
379 Show the published result of this page.
381 @item C-c C-e (`muse-edit-link-at-point')
384 @item C-c C-f (`muse-project-find-file'), also C-c C-v
385 Open another Muse page. Prompt for the name.
387 @item C-c C-l (`font-lock-mode')
388 Highlight/refresh the current buffer.
390 @item C-c C-p (`muse-project-publish')
391 Publish any Muse pages that have changed.
393 @item C-c C-v (`muse-project-find-file'), also C-c C-f
394 Open another Muse page. Prompt for the name.
396 @item C-c = (`muse-what-changed')
397 Diff this page against the last backup version.
399 @item C-c TAB (`muse-insert-tag')
400 Insert a tag interactively.
403 Move to the next Wiki reference.
406 Move to the previous Wiki reference.
411 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
412 @comment node-name, next, previous, up
413 @chapter Rules for Using Markup
416 A Muse document uses special, contextual markup rules to determine how
417 to format the output result. For example, if a paragraph is indented,
418 Muse assumes it should be quoted.
420 There are not too many markup rules, and all of them strive to be as
421 simple as possible so that you can focus on document creation, rather
425 * Paragraphs:: Paragraphs: centering and quoting.
426 * Headings:: Levels of headings.
427 * Emphasizing Text:: Bold, italicized, and underlined text.
428 * Footnotes:: Making notes to be shown at the end.
429 * Verse:: Indicating poetic stanzas.
430 * Lists:: Lists of items.
431 * Tables:: Generation of data tables.
432 * Links:: Hyperlinks and email addresses.
433 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
434 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
438 @node Paragraphs, Headings, Markup Rules, Markup Rules
439 @comment node-name, next, previous, up
440 @section Paragraphs: centering and quoting
443 Paragraphs in Muse must be separated by a blank line.
445 @cindex paragraphs, centered
446 @strong{Centered paragraphs and quotations}
448 A line that begins with six or more columns of whitespace (either tabs
449 or spaces) indicates a centered paragraph.
451 @cindex paragraphs, quoted
453 But if a line begins with whitespace, though less than six columns, it
454 indicates a quoted paragraph.
457 @cindex monospace, rendering blocks
458 @cindex HTML, rendering blocks in monospace
459 @strong{Literal paragraphs}
461 The @verb{|<example>|} tag is used for examples, where whitespace should
462 be preserved, the text rendered in monospace, and any characters special
463 to the output style escaped.
466 @cindex HTML, inserting a raw block
467 There is also the @verb{|<literal>|} tag, which causes a marked block to
468 be entirely left alone. This can be used for inserting a hand-coded
469 HTML blocks into HTML output, for example.
471 @node Headings, Emphasizing Text, Paragraphs, Markup Rules
472 @comment node-name, next, previous, up
473 @section Levels of headings
476 A heading becomes a chapter or section in printed output -- depending on
477 the style. To indicate a heading, start a new paragraph with one to
478 three asterices, followed by a space and the heading title. Then begin
479 another paragraph to enter the text for that section.
481 Only 3 levels of headings will be published as headings. A fourth level
482 of headings will be marked up, but displayed as plain text.
492 @node Emphasizing Text, Footnotes, Headings, Markup Rules
493 @comment node-name, next, previous, up
494 @section Bold, italicized, and underlined text
495 @cindex emphasizing text
496 @cindex underlining text
497 @cindex italicizing text
498 @cindex verbatim text
499 @cindex monospace, rendering words
501 To emphasize text, surround it with certain specially recognized
507 ***very strong emphasis***
509 =verbatim and monospace=
513 While editing a Muse document in Muse mode, these forms of emphasis will
514 be highlighted in a WYSIWYG manner. Each of these forms may span
515 multiple lines, with the exception of the verbatim and monospace form.
517 @node Footnotes, Verse, Emphasizing Text, Markup Rules
518 @comment node-name, next, previous, up
519 @section Making notes to be shown at the end
522 A footnote reference is simply a number in square brackets. To define
523 the footnote, place this definition at the bottom of your file.
524 @samp{footnote-mode} can be used to greatly facilitate the creation of
525 these kinds of footnotes.
527 Footnotes are defined by the same number in brackets occurring at the
528 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
529 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
530 the point of insertion.
532 @node Verse, Lists, Footnotes, Markup Rules
533 @comment node-name, next, previous, up
534 @section Indicating poetic stanzas
538 Poetry requires that whitespace be preserved, but without resorting to
539 monospace. To indicate this, use the following markup, reminiscent of
543 > A line of Emacs verse;
544 > forgive its being so terse.
547 You can also use the @verb{|<verse>|} tag, if you prefer.
551 A line of Emacs verse;
552 forgive its being so terse.
556 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
559 @cindex verses, multiple stanzas
562 A line of Emacs verse;
563 forgive its being so terse.
565 This a second stanza:
566 Something longer should go here,
567 But the author is out of ideas.
571 @node Lists, Tables, Verse, Markup Rules
572 @comment node-name, next, previous, up
573 @section Lists of items
576 Lists are given using special characters at the beginning of a line.
577 Whitespace must occur before bullets or numbered items, to distinguish
578 from the possibility of those characters occurring in a real sentence.
580 @cindex lists, bullets
581 These are rendered as a bullet list.
588 @cindex lists, enumerated
589 An enumerated list follows.
596 @cindex lists, definitions
597 Here is a definition list.
601 This is a first definition
602 And it has two lines;
606 This is a second definition
609 @node Tables, Links, Lists, Markup Rules
610 @comment node-name, next, previous, up
611 @section Generation of data tables
614 @cindex tables, simple
615 Only very simple tables are supported. The syntax is as follows.
618 Double bars || Separate header fields
620 Single bars | Separate body fields
621 Here are more | body fields
623 Triple bars ||| Separate footer fields
626 @node Links, Horizontal Rules and Anchors, Tables, Markup Rules
627 @comment node-name, next, previous, up
628 @section Hyperlinks and email addresses
631 @cindex links, explicit
633 A hyperlink can reference a URL, or another page within a Muse
634 project. In addition, descriptive text can be specified, which should
635 be displayed rather than the link text in output styles that supports
636 link descriptions. The syntax is as follows.
639 [[link target][link description]]
640 [[link target without description]]
643 Thus, the current maintainer's homepage for Muse can be found
644 @samp{[[http://www.mwolson.org/projects/MuseMode.html][here]]},
645 or at @samp{[[http://www.mwolson.org/projects/MuseMode.html]]}.
648 @cindex links, with images
651 Links to images may be used in either the target or the description, or
652 both. Thus, the following code will publish as a clickable image that
653 points to @url{http://www.mwolson.org/}.
656 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
659 @cindex images, local
660 @cindex images, displaying
661 If a link to a locally-available image is encountered in the link
662 description, Muse mode will attempt to display it if your version of
663 Emacs permits this. The following example will display correctly and
664 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
665 exists in the @file{../pics/} directory.
668 [[TestPage][../pics/TestLogo.png]]
671 @cindex images, without a description
672 An image link is not required to have a description. The link
673 @samp{[[../myimage.png]]} will display and publish as expected.
677 @cindex Email addresses
678 @cindex images, inlined
679 @strong{Bare URLs and Email addresses}
681 A URL or email address encountered in the input text is published as
682 a hyperlink if the output style supports it. If it is an image URL,
683 it will be inlined if possible.
685 @node Horizontal Rules and Anchors, Embedded Lisp, Links, Markup Rules
686 @comment node-name, next, previous, up
687 @section Inserting a horizontal line or anchor
689 @cindex horizontal rules
691 @strong{Horizontal Rules}
693 Four or more dashes indicate a horizontal rule. Be sure to put blank
694 lines around it, or it will be considered part of the proceeding or
698 @cindex links, with target on same page
701 If you begin a line with "#anchor" -- where "anchor" can be any word
702 that doesn't contain whitespace -- it defines an anchor at that point
703 into the document. This point can be referenced using "page#anchor" as
704 the target in a Muse link.
706 @node Embedded Lisp, , Horizontal Rules and Anchors, Markup Rules
707 @comment node-name, next, previous, up
708 @section Evaluating Emacs Lisp code in documents for extensibility
709 @cindex lisp, embedded
711 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
712 which is the only Muse tag supported in a style's header and footer
713 text. With the @verb{|<lisp>|} tag, you may generated whatever output
714 text you wish. The inserted output will get marked up, if the
715 @verb{|<lisp>|} tag appears within the main text of the document.
718 <lisp>(concat "This form gets " "inserted")</lisp>
721 @cindex lisp, and insert command
722 Note that you should not use the @code{insert} command within a set of
723 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
724 tags will be automatically inserted into the document.
726 @node Publishing Styles, Getting Help and Reporting Bugs, Markup Rules, Top
727 @comment node-name, next, previous, up
728 @chapter Publishing Various Types of Documents
729 @cindex publishing styles
731 One of the principle features of Muse is the ability to publish a simple
732 input text to a variety of different output styles. Muse also makes it
733 easy to create new styles, or derive from an existing style.
736 * Blosxom:: Integrating Muse and pyblosxom.cgi.
737 * Book:: Publishing entries into a compilation.
738 * DocBook:: Publishing in DocBook XML form.
739 * HTML:: Publishing in HTML or XHTML form.
740 * Journal:: Keeping a journal or blog.
741 * LaTeX:: Publishing LaTeX documents.
742 * Poem:: Publish a poem to LaTex or PDF.
743 * Texinfo:: Publish entries to Texinfo format or PDF.
744 * Common Elements:: Common functionality shared by styles.
745 * Deriving Styles:: Deriving a new style from an existing
749 @node Blosxom, Book, Publishing Styles, Publishing Styles
750 @comment node-name, next, previous, up
751 @section Integrating Muse and pyblosxom.cgi
752 @cindex blog, one-file-per-entry style
754 The Blosxom publishing style publishes a tree of categorised files to a
755 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
756 In other words, each blog entry corresponds with one file.
759 * Blosxom Requirements:: Other tools needed to the Blosxom style.
760 * Blosxom Entries:: Format of a Blosxom entry and automation.
761 * Blosxom Options:: Blosxom styles and options provided.
764 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
765 @comment node-name, next, previous, up
766 @subsection Other tools needed to the Blosxom style
768 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
769 installed on a machine that you have upload access to.
771 The following additional components are required in order to make the
772 date of blog entries display as something sensible.
776 A script to gather date directives from the entire blog tree into a
777 single file. The file must associate a blog entry with a date.
780 A plugin for (py)blosxom that reads this file.
783 These 2 things are provided for @command{pyblosxom.cgi} in the
784 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
785 former service, while @file{hardcodedates.py} provides the latter
786 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
787 script will be found/written.
789 Here is a sample listing from my @file{timestamps} file, which maps
790 each file to a date. This can really be in any format, as long as your
791 date-gathering script and your plugin can both understand it.
794 2005-04-01-14-16 personal/paper_cranes
795 2005-03-21 personal/spring_break_over
796 2004-10-24 personal/finished_free_culture
799 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
800 @comment node-name, next, previous, up
801 @subsection Format of a Blosxom entry and automation
803 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
804 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
805 plus whatever normal content is desired.
807 The date directive is not used directly by @command{pyblosxom.cgi} or
808 this program. You need to have the two additional items from the former
809 section to make use of this feature.
811 There is a function called @code{muse-blosxom-new-entry} that will
812 automate the process of making a new blog entry. To make use of it, do
817 Customize @code{muse-blosxom-base-directory} to the location that your
818 blog entries are stored.
821 Assign the @code{muse-blosxom-base-directory} function to a key
822 sequence. I use the following code to assign this function to
826 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
830 You should create your directory structure ahead of time under your base
831 directory. These directories, which correspond with category names, may
835 When you enter this key sequence, you will be prompted for the category
836 of your entry and its title. Upon entering this information, a new file
837 will be created that corresponds with the title, but in lowercase
838 letters and having special characters converted to underscores. The
839 title and date directives will be inserted automatically.
842 @node Blosxom Options, , Blosxom Entries, Blosxom
843 @comment node-name, next, previous, up
844 @subsection Blosxom styles and options provided
846 The following styles and options are available in the Blosxom publishing
849 @emph{Styles provided}
853 @cindex publishing styles, blosxom-html
855 Publish Blosxom entries in HTML form.
857 @cindex publishing styles, blosxom-xhtml
859 Publish Blosxom entries in XHTML form.
863 @emph{Options provided}
867 @item muse-blosxom-extension
868 Default file extension for publishing Blosxom files.
870 @item muse-blosxom-header
871 Header used for publishing Blosxom files.
873 @item muse-blosxom-footer
874 Footer used for publishing Blosxom files.
876 @item muse-blosxom-base-directory
877 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
879 This is the top-level directory where your blog entries may be found
884 @node Book, DocBook, Blosxom, Publishing Styles
885 @comment node-name, next, previous, up
886 @section Publishing entries into a compilation
888 This publishing style is used to output ``books'' in LaTeX or PDF
891 Each page will become a separate chapter in the book, unless the style
892 keyword @option{:nochapters} is used, in which case they are all run
893 together as if one giant chapter.
895 You will need to call the @code{muse-book-publish-project} function in
896 order to publish this style. An example of this may be found in John
897 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
899 @emph{Styles provided}
903 @cindex publishing styles, book-latex
905 Publish a book in LaTeX form. The header and footer are different than
906 the normal LaTeX publishing mode.
908 @cindex publishing styles, book-pdf
910 Publish a book in PDF form. The header and footer are different than
911 the normal PDF publishing mode.
915 @emph{Options provided}
919 @item muse-book-before-publish-hook
920 A hook run in the book buffer before it is marked up.
922 @item muse-book-after-publish-hook
923 A hook run in the book buffer after it is marked up.
925 @item muse-book-latex-header
926 Header used for publishing books to LaTeX.
928 @item muse-book-latex-footer
929 Footer used for publishing books to LaTeX.
933 @node DocBook, HTML, Book, Publishing Styles
934 @comment node-name, next, previous, up
935 @section Publishing in DocBook XML form
937 This publishing style is used to generate DocBook XML files.
939 @emph{Styles provided}
943 @cindex publishing styles, docbook
948 @emph{Options provided}
952 @item muse-docbook-extension
953 Default file extension for publishing DocBook XML files.
955 @item muse-docbook-header
956 Header used for publishing DocBook XML files.
958 @item muse-docbook-footer
959 Footer used for publishing DocBook XML files.
961 @item muse-docbook-publishing-regexps
962 List of markup rules for publishing a Muse page to DocBook XML.
964 @item muse-docbook-markup-function
965 An alist of style types to custom functions for that kind of text.
967 @item muse-docbook-publishing-strings
968 Strings used for marking up text.
970 These cover the most basic kinds of markup, the handling of which
971 differs little between the various styles.
973 @item muse-docbook-markup-specials
974 A table of characters which must be represented specially.
978 @node HTML, Journal, DocBook, Publishing Styles
979 @comment node-name, next, previous, up
980 @section Publishing in HTML or XHTML form
982 This publishing style is capable of producing HTML or XHTML documents.
984 @emph{Styles provided}
988 @cindex publishing styles, html
990 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
993 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
997 @emph{Options provided}
999 If an HTML option does not have a corresponding XHTML option, it will
1000 be used for both of these publishing styles.
1004 @item muse-html-extension
1005 Default file extension for publishing HTML files.
1007 @item muse-html-style-sheet
1008 Store your stylesheet definitions here.
1010 This is used in @code{muse-html-header}. You can put raw CSS in here or
1011 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1012 @verb{|<lisp>|} markup tags.
1014 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1017 @item muse-html-header
1018 Header used for publishing HTML files.
1020 @item muse-html-footer
1021 Footer used for publishing HTML files.
1023 @item muse-xhtml-header
1024 Header used for publishing XHTML files.
1026 @item muse-xhtml-footer
1027 Footer used for publishing XHTML files.
1029 @item muse-html-anchor-on-word
1030 When true, anchors surround the closest word.
1032 This allows you to select them in a browser (i.e. for pasting), but has
1033 the side-effect of marking up headers in multiple colors if your header
1034 style is different from your link style.
1036 @item muse-html-table-attributes
1037 The attribute to be used with HTML @verb{|<table>|} tags.
1039 Note that since Muse supports direct insertion of HTML tags, you can
1040 easily create any kind of table you want, as long as each line begins at
1041 column 0 (to prevent it from being blockquoted).
1043 @item muse-html-markup-regexps
1044 List of markup rules for publishing a Muse page to HTML.
1046 @item muse-html-markup-functions
1047 An alist of style types to custom functions for that kind of text.
1049 @item muse-html-markup-strings
1050 Strings used for marking up text as HTML.
1052 These cover the most basic kinds of markup, the handling of which
1053 differs little between the various styles.
1055 @item muse-xhtml-markup-strings
1056 Strings used for marking up text as XHTML.
1058 These cover the most basic kinds of markup, the handling of which
1059 differs little between the various styles.
1061 @item muse-html-markup-tags
1062 A list of tag specifications, for specially marking up HTML.
1063 @xref{muse-publish-markup-tags}, for more information.
1065 @item muse-html-markup-specials
1066 A table of characters which must be represented specially. By default,
1067 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1069 @item muse-html-meta-http-equiv
1070 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1072 @item muse-html-meta-content-type
1073 The content type used for the HTML @verb{|<meta>|} tag.
1075 If you are striving for XHTML 1.1 compliance, you may want to change
1076 this to ``application/xhtml+xml''.
1078 @item muse-html-meta-content-encoding
1079 The charset to append to the HTML @verb{|<meta>|} tag.
1081 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1082 and determine the HTML charset from emacs's coding. If set to a string,
1083 this string will be used to force a particular charset.
1085 @item muse-html-charset-default
1086 The default HTML meta charset to use if no translation is found in
1087 @code{muse-html-encoding-map}.
1089 @item muse-html-encoding-default
1090 The default Emacs buffer encoding to use in published files.
1091 This will be used if no special characters are found.
1093 @item muse-html-encoding-map
1094 An alist mapping emacs coding systems to appropriate HTML charsets.
1095 Use the base name of the coding system (i.e. without the -unix).
1099 @node Journal, LaTeX, HTML, Publishing Styles
1100 @comment node-name, next, previous, up
1101 @section Keeping a journal or blog
1103 @cindex blog, journal style
1105 The module facilitates the keeping and publication of a journal. When
1106 publishing to HTML, it assumes the form of a web log, or blog.
1108 The input format for each entry is as follows.
1111 * 20040317: Title of entry
1116 "You know who you are. It comes down to a simple gut check: You
1117 either love what you do or you don't. Period." -- P. Bronson
1121 The "qotd", or Quote of the Day, is entirely optional. When generated
1122 to HTML, this entry is rendered as the following.
1126 <div id="entry-qotd">
1127 <h3>Quote of the Day:</h3>
1128 <p>"You know who you are. It comes down to a simple gut
1129 check: You either love what you do or you don't. Period."
1132 <div id="entry-body">
1133 <div id="entry-head">
1134 <div id="entry-date">
1135 <span class="date">March 17, 2004</span>
1137 <div id="entry-title">
1138 <h2>Title of entry</h2>
1141 <div id="entry-text">
1142 <p>Text for the entry.</p>
1148 The plurality of "div" tags makes it possible to display the entries in
1149 any form you wish, using a CSS style.
1151 Also, an .RDF file can be generated from your journal by publishing it
1152 with the "rdf" style. It uses the first two sentences of the first
1153 paragraph of each entry as its "description", and auto-generates tags
1154 for linking to the various entries.
1156 @emph{Styles provided}
1160 @cindex publishing styles, journal-html
1162 Publish journal entries as an HTML document.
1164 @cindex publishing styles, journal-xhtml
1166 Publish journal entries as an XHTML document.
1168 @cindex publishing styles, journal-latex
1170 Publish journal entries as a LaTeX document.
1172 @cindex publishing styles, journal-pdf
1174 Publish journal entries as a PDF document.
1176 @cindex publishing styles, journal-book-latex
1177 @item journal-book-latex
1178 Publish journal entries as a LaTeX book.
1180 @cindex publishing styles, journal-book-pdf
1181 @item journal-book-pdf
1182 Publish journal entries as a PDF book.
1184 @cindex publishing styles, journal-rdf
1185 @cindex publishing styles, RSS 1.0
1187 Publish journal entries as an RDF file (RSS 1.0).
1189 @cindex publishing styles, journal-rss
1190 @cindex publishing styles, RSS 2.0
1192 Publish journal entries as an RSS file (RSS 2.0).
1196 @emph{Options provided}
1200 @item muse-journal-heading-regexp
1201 A regexp that matches a journal heading.
1203 Paren group 1 is the ISO date, group 2 is the optional category, and
1204 group 3 is the optional heading for the entry.
1206 @item muse-journal-date-format
1207 Date format to use for journal entries.
1209 @item muse-journal-html-heading-regexp
1210 A regexp that matches a journal heading from an HTML document.
1212 Paren group 1 is the ISO date, group 2 is the optional category, and
1213 group 3 is the optional heading for the entry.
1215 @item muse-journal-html-entry-template
1216 Template used to publish individual journal entries as HTML.
1218 @item muse-journal-latex-section
1219 Template used to publish a LaTeX section.
1221 @item muse-journal-latex-subsection
1222 Template used to publish a LaTeX subsection.
1224 @item muse-journal-latex-markup-tags
1225 A list of tag specifications, for specially marking up LaTeX.
1227 @xref{muse-publish-markup-tags}, for more information.
1229 @item muse-journal-rdf-extension
1230 Default file extension for publishing RDF (RSS 1.0) files.
1232 @item muse-journal-rdf-base-url
1233 The base URL of the website referenced by the RDF file.
1235 @item muse-journal-rdf-header
1236 Header used for publishing RDF (RSS 1.0) files.
1238 @item muse-journal-rdf-footer
1239 Footer used for publishing RDF (RSS 1.0) files.
1241 @item muse-journal-rdf-date-format
1242 Date format to use for RDF entries.
1244 @item muse-journal-rdf-entry-template
1245 Template used to publish individual journal entries as RDF.
1247 @item muse-journal-rdf-summarize-entries
1248 If non-nil, include only summaries in the RDF file, not the full data.
1250 @item muse-journal-rss-extension
1251 Default file extension for publishing RSS 2.0 files.
1253 @item muse-journal-rss-base-url
1254 The base URL of the website referenced by the RSS file.
1256 @item muse-journal-rss-header
1257 Header used for publishing RSS 2.0 files.
1259 @item muse-journal-rss-footer
1260 Footer used for publishing RSS 2.0 files.
1262 @item muse-journal-rss-date-format
1263 Date format to use for RSS 2.0 entries.
1265 @item muse-journal-rss-entry-template
1266 Template used to publish individual journal entries as RSS 2.0.
1268 @item muse-journal-rss-enclosure-types-alist
1269 File types that are accepted as RSS enclosures.
1271 This is an alist that maps file extension to content type.
1273 Useful for podcasting.
1275 @item muse-journal-rss-summarize-entries
1276 If non-nil, include only summaries in the RSS file, not the full data.
1278 Many RSS subscribers find this annoying.
1280 @item muse-journal-rss-markup-regexps
1281 List of markup rules for publishing a Muse journal page to RSS.
1283 For more information on the structure of this list,
1284 @xref{muse-publish-markup-regexps}.
1286 @item muse-journal-rss-markup-functions
1287 An alist of style types to custom functions for that kind of text.
1289 For more on the structure of this list,
1290 @xref{muse-publish-markup-functions}.
1294 @node LaTeX, Poem, Journal, Publishing Styles
1295 @comment node-name, next, previous, up
1296 @section Publishing LaTeX documents
1298 This publishing style is capable of producing LaTeX or PDF documents.
1300 If you wish to publish PDF documents, you will need to have a good TeX
1301 installation. For Debian, this can be accomplished by installing the
1302 ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1304 @emph{Styles provided}
1308 @cindex publishing styles, latex
1310 Publish a LaTeX document.
1312 @cindex publishing styles, pdf
1314 Publish a PDF document, using an external LaTeX document conversion
1317 @cindex publishing styles, latexcjk
1319 Publish a LaTeX document with CJK (Chinese) encodings.
1321 @cindex publishing styles, pdfcjk
1323 Publish a PDF document with CJK (Chinese) encodings, using an external
1324 LaTeX document conversion tool.
1328 @emph{Options provided}
1332 @item muse-latex-extension
1333 Default file extension for publishing LaTeX files.
1335 @item muse-latex-pdf-extension
1336 Default file extension for publishing LaTeX files to PDF.
1338 @item muse-latex-header
1339 Header used for publishing LaTeX files.
1341 @item muse-latex-footer
1342 Footer used for publishing LaTeX files.
1344 @item muse-latexcjk-header
1345 Header used for publishing LaTeX files (CJK).
1347 @item muse-latexcjk-footer
1348 Footer used for publishing LaTeX files (CJK).
1350 @item muse-latex-markup-regexps
1351 List of markup regexps for identifying regions in a Muse page.
1353 For more on the structure of this list,
1354 @xref{muse-publish-markup-regexps}.
1356 @item muse-latex-markup-functions
1357 An alist of style types to custom functions for that kind of text.
1359 For more on the structure of this list,
1360 @xref{muse-publish-markup-functions}.
1362 @item muse-latex-markup-strings
1363 Strings used for marking up text.
1365 These cover the most basic kinds of markup, the handling of which
1366 differs little between the various styles.
1368 @item muse-latexcjk-encoding-map
1369 An alist mapping emacs coding systems to appropriate CJK codings.
1370 Use the base name of the coding system (ie, without the -unix).
1372 @item muse-latexcjk-encoding-default
1373 The default Emacs buffer encoding to use in published files.
1375 This will be used if no special characters are found.
1377 @item muse-latex-markup-specials
1378 A table of characters which must be represented specially.
1382 @node Poem, Texinfo, LaTeX, Publishing Styles
1383 @comment node-name, next, previous, up
1384 @section Publish a poem to LaTex or PDF
1386 The @code{muse-poem} module makes it easy to attractively publish and
1387 reference poems in the following format, using the "memoir" module for
1388 LaTeX publishing. It will also markup poems for every other output
1389 style, though none are nearly as pretty.
1398 Annotations, history, notes, etc.
1401 Once a poem is written in this format, just publish it to PDF using the
1402 @code{poem-pdf} style. To make an inlined reference to a poem that
1403 you've written -- for example, from a blog page -- there is a "poem" tag
1404 defined by this module.
1407 <poem title="name.of.poem.page">
1410 Let's assume the template above was called @file{name.of.poem.page};
1411 then the above tag would result in this inclusion.
1419 John Wiegley uses this module for publishing all of the poems on his
1420 website, which are at
1421 @uref{http://www.newartisans.com/johnw/poems.html}.
1423 @emph{Styles provided}
1427 @cindex publishing styles, poem-latex
1429 Publish a poem in LaTeX form.
1431 @cindex publishing styles, poem-pdf
1433 Publish a poem to a PDF document.
1435 @cindex publishing styles, chapbook-latex
1436 @item chapbook-latex
1437 Publish a book of poems in LaTeX form.
1439 @cindex publishing styles, chapbook-pdf
1441 Publish a book of poems to a PDF document.
1445 @emph{Options provided}
1449 @item muse-poem-latex-header
1450 Header used for publishing LaTeX poems.
1452 @item muse-poem-latex-footer
1453 Footer used for publishing LaTeX files.
1455 @item muse-poem-markup-strings
1456 Strings used for marking up poems.
1458 These cover the most basic kinds of markup, the handling of which
1459 differs little between the various styles.
1461 @item muse-chapbook-latex-header
1462 Header used for publishing a book of poems in LaTeX form.
1464 @item muse-chapbook-latex-footer
1465 Footer used for publishing a book of poems in LaTeX form.
1467 @item muse-poem-chapbook-strings
1468 Strings used for marking up books of poems.
1470 These cover the most basic kinds of markup, the handling of which
1471 differs little between the various styles.
1475 @node Texinfo, Common Elements, Poem, Publishing Styles
1476 @comment node-name, next, previous, up
1477 @section Publish entries to Texinfo format or PDF
1479 Rules for publishing a Muse file as a Texinfo article.
1481 @emph{Styles provided}
1485 @cindex publishing styles, texi
1487 Publish a file in Texinfo form.
1489 @cindex publishing styles, texi
1491 Generate an Info file from a Muse file.
1493 @cindex publishing styles, info-pdf
1495 Publish a file in PDF form.
1499 @emph{Options provided}
1503 @item muse-texinfo-process-natively
1504 If non-nil, use the Emacs `texinfmt' module to make Info files.
1506 @item muse-texinfo-extension
1507 Default file extension for publishing Texinfo files.
1509 @item muse-texinfo-info-extension
1510 Default file extension for publishing Info files.
1512 @item muse-texinfo-pdf-extension
1513 Default file extension for publishing PDF files.
1515 @item muse-texinfo-header
1516 Text to prepend to a Muse page being published as Texinfo.
1518 This text may contain @verb{|<lisp>|} markup tags.
1520 @item muse-texinfo-footer
1521 Text to append to a Muse page being published as Texinfo.
1523 This text may contain @verb{|<lisp>|} markup tags.
1525 @item muse-texinfo-markup-regexps
1526 List of markup rules for publishing a Muse page to Texinfo.
1528 For more on the structure of this list,
1529 @xref{muse-publish-markup-regexps}.
1531 @item muse-texinfo-markup-functions
1532 An alist of style types to custom functions for that kind of text.
1534 For more on the structure of this list, see
1535 @xref{muse-publish-markup-functions}.
1537 @item muse-texinfo-markup-strings
1538 Strings used for marking up text.
1540 These cover the most basic kinds of markup, the handling of which
1541 differs little between the various styles.
1543 @item muse-texinfo-markup-specials
1544 A table of characters which must be represented specially.
1548 @node Common Elements, Deriving Styles, Texinfo, Publishing Styles
1549 @comment node-name, next, previous, up
1550 @section Common functionality shared by styles
1551 @cindex publishing styles, common
1555 @cindex publishing, markup functions
1556 @anchor{muse-publish-markup-functions}
1557 @item muse-publish-markup-functions
1558 An alist of style types to custom functions for that kind of text.
1560 This is used by publishing styles to attempt to minimize the amount of
1561 custom regexps that each has to define. @file{muse-publish} provides
1562 rules for the most common types of markup.
1564 Each member of the list is of the following form.
1572 Describes the type of text to associate with this rule.
1573 @code{muse-publish-markup-regexps} maps regexps to these symbols.
1576 Function to use to mark up this kind of rule if no suitable function is
1577 found through the @option{:functions} tag of the current style.
1580 @cindex publishing, markup regexps
1581 @anchor{muse-publish-markup-regexps}
1582 @item muse-publish-markup-regexps
1583 List of markup rules for publishing a page with Muse.
1585 The rules given in this variable are invoked first, followed by whatever
1586 rules are specified by the current style.
1588 Each member of the list is either a function, or a list of the following
1592 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1597 A regular expression, or symbol whose value is a regular expression,
1598 which is searched for using `re-search-forward'.
1600 @item TEXT-BEGIN-GROUP
1601 The matching group within that regexp which denotes the beginning of the
1602 actual text to be marked up.
1604 @item REPLACEMENT-TEXT
1605 A string that will be passed to `replace-match'.
1607 If it is not a string, but a function, it will be called to determine
1608 what the replacement text should be (it must return a string). If it is
1609 a symbol, the value of that symbol should be a string.
1612 The replacements are done in order, one rule at a time. Writing
1613 the regular expressions can be a tricky business. Note that case
1614 is never ignored. `case-fold-search' is always bound to nil
1615 while processing the markup rules.
1617 @cindex publishing, markup tags
1618 @anchor{muse-publish-markup-tags}
1619 @item muse-publish-markup-tags
1620 A list of tag specifications, for specially marking up text.
1622 XML-style tags are the best way to add custom markup to Muse. This is
1623 easily accomplished by customizing this list of markup tags.
1625 For each entry, the name of the tag is given, whether it expects a
1626 closing tag and/or an optional set of attributes, and a function that
1627 performs whatever action is desired within the delimited region.
1629 The tags themselves are deleted during publishing, before the function
1630 is called. The function is called with three arguments, the beginning
1631 and end of the region surrounded by the tags. If properties are
1632 allowed, they are passed as a third argument in the form of an alist.
1633 The `end' argument to the function is always a marker.
1635 Point is always at the beginning of the region within the tags, when the
1636 function is called. Wherever point is when the function finishes is
1637 where tag markup will resume.
1639 These tag rules are processed once at the beginning of markup, and once
1640 at the end, to catch any tags which may have been inserted in-between.
1644 @node Deriving Styles, , Common Elements, Publishing Styles
1645 @comment node-name, next, previous, up
1646 @section Deriving a new style from an existing one
1647 @cindex publishing styles, deriving
1649 To create a new style from an existing one, use @code{muse-derive-style}
1650 as follows. This is a good way to fix something you don't like about a
1651 particular publishing style, or to personalize it.
1654 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
1657 The derived name is a string defining the new style, such as "my-html".
1658 The base name must identify an existing style, such as "html" -- if you
1659 have loaded @file{muse-html}. The style parameters are the same as
1660 those used to create a style, except that they override whatever
1661 definitions exist in the base style. However, some definitions only
1662 partially override. The following parameters support partial
1668 If a markup function is not found in the derived style's function list,
1669 the base style's function list will be queried.
1672 If a markup string is not found in the derived style's string list, the
1673 base style's string list will be queried.
1676 If this option is specified, it will be consulted rather than the
1677 corresponding value in the derived style. This applies to the following
1687 @node Getting Help and Reporting Bugs, History, Publishing Styles, Top
1688 @comment node-name, next, previous, up
1689 @chapter Getting Help and Reporting Bugs
1690 @cindex help, getting
1691 @cindex bugs, reporting
1693 After you have read this guide, if you still have questions about
1694 Muse, or if you have bugs to report, there are several places you can
1700 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
1701 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
1705 @uref{http://www.mwolson.org/projects/MuseMode.html} is the web page
1706 that Michael Olson (the current maintainer) made for Muse.
1709 You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
1710 using the subscription form at
1711 @uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
1712 This mailing list provides support for Muse, @command{Planner} and
1713 @command{emacs-wiki}, which is the predecessor of Muse.
1715 There are additional methods for accessing the mailing list, adding
1716 content to it, and searching it. Consult
1717 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
1721 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
1722 contributors are frequently around and willing to answer your
1723 questions. The @samp{#muse} channel is also available for
1724 Muse-specific help, and its current maintainer hangs out there.
1727 The maintainer of MuseMode, Michael Olson, may be contacted at
1728 @email{mwolson@@gnu.org}.
1732 @node History, Contributors, Getting Help and Reporting Bugs, Top
1733 @comment node-name, next, previous, up
1734 @chapter History of This Document
1735 @cindex history, of Muse
1739 John Wiegley started Muse upon realizing that EmacsWiki had some serious
1740 limitations. Around February 2004, he started making "emacs-wiki version
1741 3.00 APLHA", which eventually became known as Muse.
1743 Most of those who frequent the emacs-wiki mailing list continued to use
1744 emacs-wiki, mainly because Planner hasn't been ported over to it.
1746 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
1747 John Wiegley's request.
1750 Michael Olson overhauled this document and added many new sections in
1751 preparation for the first release of Muse (3.01).
1755 @node Contributors, GNU General Public License, History, Top
1756 @comment node-name, next, previous, up
1757 @chapter Contributors to This Documentation
1758 @cindex contributors
1760 The first draft of this document was taken from the emacs-wiki texinfo
1761 manual. Michael Olson adapted it for Muse and added most of its
1764 John Sullivan did a majority of the work on the emacs-wiki texinfo
1767 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
1768 emacs-wiki texinfo manual.
1770 @node GNU General Public License, Concept Index, Contributors, Top
1771 @comment node-name, next, previous, up
1772 @appendix GNU GENERAL PUBLIC LICENSE
1773 @center Version 2, June 1991
1775 @cindex GNU General Public License
1777 @c This file is intended to be included in another file.
1780 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
1781 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
1783 Everyone is permitted to copy and distribute verbatim copies
1784 of this license document, but changing it is not allowed.
1787 @appendixsec Preamble
1789 The licenses for most software are designed to take away your
1790 freedom to share and change it. By contrast, the GNU General Public
1791 License is intended to guarantee your freedom to share and change free
1792 software---to make sure the software is free for all its users. This
1793 General Public License applies to most of the Free Software
1794 Foundation's software and to any other program whose authors commit to
1795 using it. (Some other Free Software Foundation software is covered by
1796 the GNU Library General Public License instead.) You can apply it to
1799 When we speak of free software, we are referring to freedom, not
1800 price. Our General Public Licenses are designed to make sure that you
1801 have the freedom to distribute copies of free software (and charge for
1802 this service if you wish), that you receive source code or can get it
1803 if you want it, that you can change the software or use pieces of it
1804 in new free programs; and that you know you can do these things.
1806 To protect your rights, we need to make restrictions that forbid
1807 anyone to deny you these rights or to ask you to surrender the rights.
1808 These restrictions translate to certain responsibilities for you if you
1809 distribute copies of the software, or if you modify it.
1811 For example, if you distribute copies of such a program, whether
1812 gratis or for a fee, you must give the recipients all the rights that
1813 you have. You must make sure that they, too, receive or can get the
1814 source code. And you must show them these terms so they know their
1817 We protect your rights with two steps: (1) copyright the software, and
1818 (2) offer you this license which gives you legal permission to copy,
1819 distribute and/or modify the software.
1821 Also, for each author's protection and ours, we want to make certain
1822 that everyone understands that there is no warranty for this free
1823 software. If the software is modified by someone else and passed on, we
1824 want its recipients to know that what they have is not the original, so
1825 that any problems introduced by others will not reflect on the original
1826 authors' reputations.
1828 Finally, any free program is threatened constantly by software
1829 patents. We wish to avoid the danger that redistributors of a free
1830 program will individually obtain patent licenses, in effect making the
1831 program proprietary. To prevent this, we have made it clear that any
1832 patent must be licensed for everyone's free use or not licensed at all.
1834 The precise terms and conditions for copying, distribution and
1835 modification follow.
1838 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1841 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1846 This License applies to any program or other work which contains
1847 a notice placed by the copyright holder saying it may be distributed
1848 under the terms of this General Public License. The ``Program'', below,
1849 refers to any such program or work, and a ``work based on the Program''
1850 means either the Program or any derivative work under copyright law:
1851 that is to say, a work containing the Program or a portion of it,
1852 either verbatim or with modifications and/or translated into another
1853 language. (Hereinafter, translation is included without limitation in
1854 the term ``modification''.) Each licensee is addressed as ``you''.
1856 Activities other than copying, distribution and modification are not
1857 covered by this License; they are outside its scope. The act of
1858 running the Program is not restricted, and the output from the Program
1859 is covered only if its contents constitute a work based on the
1860 Program (independent of having been made by running the Program).
1861 Whether that is true depends on what the Program does.
1864 You may copy and distribute verbatim copies of the Program's
1865 source code as you receive it, in any medium, provided that you
1866 conspicuously and appropriately publish on each copy an appropriate
1867 copyright notice and disclaimer of warranty; keep intact all the
1868 notices that refer to this License and to the absence of any warranty;
1869 and give any other recipients of the Program a copy of this License
1870 along with the Program.
1872 You may charge a fee for the physical act of transferring a copy, and
1873 you may at your option offer warranty protection in exchange for a fee.
1876 You may modify your copy or copies of the Program or any portion
1877 of it, thus forming a work based on the Program, and copy and
1878 distribute such modifications or work under the terms of Section 1
1879 above, provided that you also meet all of these conditions:
1883 You must cause the modified files to carry prominent notices
1884 stating that you changed the files and the date of any change.
1887 You must cause any work that you distribute or publish, that in
1888 whole or in part contains or is derived from the Program or any
1889 part thereof, to be licensed as a whole at no charge to all third
1890 parties under the terms of this License.
1893 If the modified program normally reads commands interactively
1894 when run, you must cause it, when started running for such
1895 interactive use in the most ordinary way, to print or display an
1896 announcement including an appropriate copyright notice and a
1897 notice that there is no warranty (or else, saying that you provide
1898 a warranty) and that users may redistribute the program under
1899 these conditions, and telling the user how to view a copy of this
1900 License. (Exception: if the Program itself is interactive but
1901 does not normally print such an announcement, your work based on
1902 the Program is not required to print an announcement.)
1905 These requirements apply to the modified work as a whole. If
1906 identifiable sections of that work are not derived from the Program,
1907 and can be reasonably considered independent and separate works in
1908 themselves, then this License, and its terms, do not apply to those
1909 sections when you distribute them as separate works. But when you
1910 distribute the same sections as part of a whole which is a work based
1911 on the Program, the distribution of the whole must be on the terms of
1912 this License, whose permissions for other licensees extend to the
1913 entire whole, and thus to each and every part regardless of who wrote it.
1915 Thus, it is not the intent of this section to claim rights or contest
1916 your rights to work written entirely by you; rather, the intent is to
1917 exercise the right to control the distribution of derivative or
1918 collective works based on the Program.
1920 In addition, mere aggregation of another work not based on the Program
1921 with the Program (or with a work based on the Program) on a volume of
1922 a storage or distribution medium does not bring the other work under
1923 the scope of this License.
1926 You may copy and distribute the Program (or a work based on it,
1927 under Section 2) in object code or executable form under the terms of
1928 Sections 1 and 2 above provided that you also do one of the following:
1932 Accompany it with the complete corresponding machine-readable
1933 source code, which must be distributed under the terms of Sections
1934 1 and 2 above on a medium customarily used for software interchange; or,
1937 Accompany it with a written offer, valid for at least three
1938 years, to give any third party, for a charge no more than your
1939 cost of physically performing source distribution, a complete
1940 machine-readable copy of the corresponding source code, to be
1941 distributed under the terms of Sections 1 and 2 above on a medium
1942 customarily used for software interchange; or,
1945 Accompany it with the information you received as to the offer
1946 to distribute corresponding source code. (This alternative is
1947 allowed only for noncommercial distribution and only if you
1948 received the program in object code or executable form with such
1949 an offer, in accord with Subsection b above.)
1952 The source code for a work means the preferred form of the work for
1953 making modifications to it. For an executable work, complete source
1954 code means all the source code for all modules it contains, plus any
1955 associated interface definition files, plus the scripts used to
1956 control compilation and installation of the executable. However, as a
1957 special exception, the source code distributed need not include
1958 anything that is normally distributed (in either source or binary
1959 form) with the major components (compiler, kernel, and so on) of the
1960 operating system on which the executable runs, unless that component
1961 itself accompanies the executable.
1963 If distribution of executable or object code is made by offering
1964 access to copy from a designated place, then offering equivalent
1965 access to copy the source code from the same place counts as
1966 distribution of the source code, even though third parties are not
1967 compelled to copy the source along with the object code.
1970 You may not copy, modify, sublicense, or distribute the Program
1971 except as expressly provided under this License. Any attempt
1972 otherwise to copy, modify, sublicense or distribute the Program is
1973 void, and will automatically terminate your rights under this License.
1974 However, parties who have received copies, or rights, from you under
1975 this License will not have their licenses terminated so long as such
1976 parties remain in full compliance.
1979 You are not required to accept this License, since you have not
1980 signed it. However, nothing else grants you permission to modify or
1981 distribute the Program or its derivative works. These actions are
1982 prohibited by law if you do not accept this License. Therefore, by
1983 modifying or distributing the Program (or any work based on the
1984 Program), you indicate your acceptance of this License to do so, and
1985 all its terms and conditions for copying, distributing or modifying
1986 the Program or works based on it.
1989 Each time you redistribute the Program (or any work based on the
1990 Program), the recipient automatically receives a license from the
1991 original licensor to copy, distribute or modify the Program subject to
1992 these terms and conditions. You may not impose any further
1993 restrictions on the recipients' exercise of the rights granted herein.
1994 You are not responsible for enforcing compliance by third parties to
1998 If, as a consequence of a court judgment or allegation of patent
1999 infringement or for any other reason (not limited to patent issues),
2000 conditions are imposed on you (whether by court order, agreement or
2001 otherwise) that contradict the conditions of this License, they do not
2002 excuse you from the conditions of this License. If you cannot
2003 distribute so as to satisfy simultaneously your obligations under this
2004 License and any other pertinent obligations, then as a consequence you
2005 may not distribute the Program at all. For example, if a patent
2006 license would not permit royalty-free redistribution of the Program by
2007 all those who receive copies directly or indirectly through you, then
2008 the only way you could satisfy both it and this License would be to
2009 refrain entirely from distribution of the Program.
2011 If any portion of this section is held invalid or unenforceable under
2012 any particular circumstance, the balance of the section is intended to
2013 apply and the section as a whole is intended to apply in other
2016 It is not the purpose of this section to induce you to infringe any
2017 patents or other property right claims or to contest validity of any
2018 such claims; this section has the sole purpose of protecting the
2019 integrity of the free software distribution system, which is
2020 implemented by public license practices. Many people have made
2021 generous contributions to the wide range of software distributed
2022 through that system in reliance on consistent application of that
2023 system; it is up to the author/donor to decide if he or she is willing
2024 to distribute software through any other system and a licensee cannot
2027 This section is intended to make thoroughly clear what is believed to
2028 be a consequence of the rest of this License.
2031 If the distribution and/or use of the Program is restricted in
2032 certain countries either by patents or by copyrighted interfaces, the
2033 original copyright holder who places the Program under this License
2034 may add an explicit geographical distribution limitation excluding
2035 those countries, so that distribution is permitted only in or among
2036 countries not thus excluded. In such case, this License incorporates
2037 the limitation as if written in the body of this License.
2040 The Free Software Foundation may publish revised and/or new versions
2041 of the General Public License from time to time. Such new versions will
2042 be similar in spirit to the present version, but may differ in detail to
2043 address new problems or concerns.
2045 Each version is given a distinguishing version number. If the Program
2046 specifies a version number of this License which applies to it and ``any
2047 later version'', you have the option of following the terms and conditions
2048 either of that version or of any later version published by the Free
2049 Software Foundation. If the Program does not specify a version number of
2050 this License, you may choose any version ever published by the Free Software
2054 If you wish to incorporate parts of the Program into other free
2055 programs whose distribution conditions are different, write to the author
2056 to ask for permission. For software which is copyrighted by the Free
2057 Software Foundation, write to the Free Software Foundation; we sometimes
2058 make exceptions for this. Our decision will be guided by the two goals
2059 of preserving the free status of all derivatives of our free software and
2060 of promoting the sharing and reuse of software generally.
2063 @heading NO WARRANTY
2070 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2071 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2072 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2073 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2074 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2075 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2076 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2077 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2078 REPAIR OR CORRECTION.
2081 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2082 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2083 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2084 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2085 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2086 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2087 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2088 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2089 POSSIBILITY OF SUCH DAMAGES.
2093 @heading END OF TERMS AND CONDITIONS
2096 @center END OF TERMS AND CONDITIONS
2100 @appendixsec Appendix: How to Apply These Terms to Your New Programs
2102 If you develop a new program, and you want it to be of the greatest
2103 possible use to the public, the best way to achieve this is to make it
2104 free software which everyone can redistribute and change under these terms.
2106 To do so, attach the following notices to the program. It is safest
2107 to attach them to the start of each source file to most effectively
2108 convey the exclusion of warranty; and each file should have at least
2109 the ``copyright'' line and a pointer to where the full notice is found.
2112 @var{one line to give the program's name and a brief idea of what it does.}
2113 Copyright (C) @var{yyyy} @var{name of author}
2115 This program is free software; you can redistribute it and/or modify
2116 it under the terms of the GNU General Public License as published by
2117 the Free Software Foundation; either version 2 of the License, or
2118 (at your option) any later version.
2120 This program is distributed in the hope that it will be useful,
2121 but WITHOUT ANY WARRANTY; without even the implied warranty of
2122 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2123 GNU General Public License for more details.
2125 You should have received a copy of the GNU General Public License along
2126 with this program; if not, write to the Free Software Foundation, Inc.,
2127 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2130 Also add information on how to contact you by electronic and paper mail.
2132 If the program is interactive, make it output a short notice like this
2133 when it starts in an interactive mode:
2136 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2137 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2138 This is free software, and you are welcome to redistribute it
2139 under certain conditions; type `show c' for details.
2142 The hypothetical commands @samp{show w} and @samp{show c} should show
2143 the appropriate parts of the General Public License. Of course, the
2144 commands you use may be called something other than @samp{show w} and
2145 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2148 You should also get your employer (if you work as a programmer) or your
2149 school, if any, to sign a ``copyright disclaimer'' for the program, if
2150 necessary. Here is a sample; alter the names:
2153 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2154 `Gnomovision' (which makes passes at compilers) written by James Hacker.
2156 @var{signature of Ty Coon}, 1 April 1989
2157 Ty Coon, President of Vice
2160 This General Public License does not permit incorporating your program into
2161 proprietary programs. If your program is a subroutine library, you may
2162 consider it more useful to permit linking proprietary applications with the
2163 library. If this is what you want to do, use the GNU Library General
2164 Public License instead of this License.
2167 @node Concept Index, , GNU General Public License, Top
2168 @comment node-name, next, previous, up
2176 @c ispell-local-pdict: "ispell-dict"