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.91 (3.03 RC2).
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.
94 * Tag Summary:: Tags that Muse recognizes.
96 Publishing Various Types of Documents
98 * Blosxom:: Integrating Muse and pyblosxom.cgi.
99 * Book:: Publishing entries into a compilation.
100 * DocBook:: Publishing in DocBook XML form.
101 * HTML:: Publishing in HTML or XHTML form.
102 * Journal:: Keeping a journal or blog.
103 * LaTeX:: Publishing LaTeX documents.
104 * Poem:: Publish a poem to LaTex or PDF.
105 * Texinfo:: Publish entries to Texinfo format or PDF.
107 Integrating Muse and pyblosxom.cgi
109 * Blosxom Requirements:: Other tools needed to the Blosxom style.
110 * Blosxom Entries:: Format of a Blosxom entry and automation.
111 * Blosxom Options:: Blosxom styles and options provided.
113 Making your own publishing styles
115 * Common Elements:: Common functionality shared by styles.
116 * Deriving Styles:: Deriving a new style from an existing
119 Common functionality shared by styles
121 * Markup Functions:: Specifying functions to marking up text.
122 * Markup Regexps:: Markup rules for publishing.
123 * Markup Strings:: Strings specific to a publishing style.
124 * Markup Tags:: Tag specifications for special markup.
125 * Style Elements:: Parameters used for defining styles.
130 @node Preface, Introduction, Top, Top
131 @comment node-name, next, previous, up
132 @chapter About the documentation
134 This document describes Muse, which was written by John Wiegley
135 and is now maintained by Michael Olson. Several versions of it are
139 @item PDF: http://www.mwolson.org/static/doc/muse.pdf
140 @item HTML (single file): http://www.mwolson.org/static/doc/muse.html
141 @item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
144 @node Introduction, Obtaining Muse, Preface, Top
145 @comment node-name, next, previous, up
146 @chapter What is Muse?
148 Emacs Muse is an authoring and publishing environment for Emacs. It
149 simplifies the process of writing documents and publishing them to
150 various output formats.
152 Muse consists of two main parts: an enhanced text-mode for authoring
153 documents and navigating within Muse projects, and a set of publishing
154 styles for generating different kinds of output.
156 This idea is not in any way new. Numerous systems exist -- even one
157 other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
158 more modular environment, with a rather simple core, in which "styles"
159 are derived from to create new styles. Much of Muse's overall
160 functionality is optional. For example, you can use the publisher
161 without the major-mode, or the mode without doing any publishing; or if
162 you don't load the Texinfo or LaTeX modules, those styles won't be
165 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
166 code has been restructured and rewritten, especially its publishing
167 functions. The focus in this revision is on the authoring and publishing
168 aspects, and the "wikiness" has been removed as a default behavior
169 (available in the optional @file{muse-wiki} module). CamelCase words are
170 no longer special by default.
172 @node Obtaining Muse, Installation, Introduction, Top
173 @comment node-name, next, previous, up
174 @chapter How to Get Muse Releases and Development Changes
177 * Releases:: Released versions of Muse.
178 * Development:: Latest unreleased development changes.
181 @node Releases, Development, Obtaining Muse, Obtaining Muse
182 @comment node-name, next, previous, up
183 @section Released versions of Muse
185 Choose to install a release if you want to minimize risk.
187 Errors are corrected in development first. User-visible changes will be
188 announced on the @email{muse-el-discuss@@gna.org} mailing list.
189 @xref{Getting Help and Reporting Bugs}.
191 @cindex releases, Debian package
192 @cindex Debian package for Muse
193 Debian and Ubuntu users can get Muse via apt-get. The @file{muse-el}
194 package is available both at Michael Olson's APT repository and the
195 official Debian and Ubuntu repositories. To make use of the former, add
196 the following line to your @file{/etc/apt/sources.list} file and run
197 @code{apt-get install muse}.
200 deb http://www.mwolson.org/debian/ ./
203 @cindex releases, from source
204 Alternatively, you can download the latest release from
205 @uref{http://www.mwolson.org/static/dist/muse/} .
207 @node Development, , Releases, Obtaining Muse
208 @comment node-name, next, previous, up
209 @section Latest unreleased development changes
212 Choose the development version if you want to live on the bleeding edge
213 of Muse development or try out new features before release.
215 @cindex arch revision control system, using
216 The Arch revision control system allows you to retrieve previous
217 versions and select specific features and bug fixes. If you would like
218 to contribute to Muse development, it is highly recommended that you use
219 Arch, but this is not a requirement.
221 If you are new to Arch, you might find this tutorial helpful:
222 @uref{http://www.mwolson.org/projects/ArchTutorial.html}.
224 Downloading the Muse module with Arch and staying up-to-date involves
231 @item Debian and Ubuntu: @kbd{apt-get install tla}.
232 @item Other distributions: see @uref{http://regexps.srparish.net/www/}.
235 @item Register the archive.
237 tla register-archive -f http://www.mwolson.org/archives/2005
240 @item Download the Muse package.
242 # Download Muse into the @file{muse} directory.
243 tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
246 @item List upstream changes that are missing from your local copy.
247 Do this whenever you want to see whether new changes have been committed
251 # Change to the source directory you are interested in.
254 # Display the summary of changes
255 tla missing --summary
258 @cindex updating Muse with Arch
259 @item Update to the latest version by replaying missing changes.
267 There are other ways to interact with the Muse archive.
270 @item Browse arch repository: @uref{http://www.mwolson.org/archives/}
271 @item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
274 The latest development snapshot will be kept up-to-date since it is
275 updated at the same time as the Arch repository.
277 @node Installation, Getting Started, Obtaining Muse, Top
278 @comment node-name, next, previous, up
279 @chapter Compiling and Installing Muse
281 Muse may be compiled and installed on your machine.
283 @subheading Compilation
285 This is an optional step, since Emacs Lisp source code does not
286 necessarily have to be byte-compiled. It will yield a speed increase,
289 A working copy of Emacs or XEmacs is needed in order to compile the
290 Emacs Muse. By default, the program that is installed with the name
291 @command{emacs} will be used.
293 If you want to use the @command{xemacs} binary to perform the
294 compilation, you would need to edit @file{Makefile.defs} in the
295 top-level directory as follows. You can put either a full path to an
296 Emacs or XEmacs binary or just the command name, as long as it is in the
301 SITEFLAG = -no-site-file
304 Running @code{make} should compile the Muse source files in the
305 @file{lisp} directory.
307 @subheading Installation
309 Muse may be installed into your file hierarchy by doing the following.
311 Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
312 where you want the source and compiled Muse files to be installed and
313 @env{INFODIR} indicates where to put the Muse manual. Of course, you
314 will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
315 Compilation section if you are using XEmacs.
317 If you are installing Muse on a Debian or Ubuntu system, you might want
318 to change the value of @env{INSTALLINFO} as specified in
319 @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 If you would like to include only some files from a directory in a Muse
408 project, you may use a regexp in place of @file{~/Pages} in the example.
410 @c PRE3_03: Give more examples
411 @c PRE3_03: Describe :set and other options fully
413 @node Keystroke Summary, Markup Rules, Projects, Top
414 @comment node-name, next, previous, up
415 @chapter Keys Used in Muse Mode
418 This is a summary of keystrokes available in every Muse buffer.
422 @item C-c C-a (`muse-index')
423 Display an index of all known Muse pages.
425 @item C-c C-b (`muse-find-backlinks')
426 Find all pages that link to this page.
428 @item C-c C-c (`muse-follow-name-at-point')
429 Visit the link at point.
431 @item C-c C-e (`muse-edit-link-at-point')
434 @item C-c C-f (`muse-project-find-file')
435 Open another Muse page. Prompt for the name.
437 @item C-c C-i (`muse-insert-tag')
438 Insert a tag interactively.
440 @item C-c C-l (`font-lock-mode')
441 Toggle font lock / highlighting for the current buffer.
443 @item C-c C-p (`muse-project-publish')
444 Publish any Muse pages that have changed.
446 @item C-c C-s (`muse-search')
447 Find text in all files of the current project.
449 @item C-c C-t (`muse-project-publish-this-file')
450 Publish the currently-visited file. Prompt for the style if the current
451 file can be published using more than one style.
453 @item C-c C-T (`muse-publish-this-file')
454 Publish the currently-visited file. Prompt for both the style and
457 @item C-c C-v (`muse-browse-result')
458 Show the published result of this page.
460 @item C-c = (`muse-what-changed')
461 Diff this page against the last backup version.
463 @item C-c TAB l (`muse-insert-relative-link-to-file')
464 Insert a link to a file interactively.
466 @item C-c TAB t (`muse-insert-tag')
467 Insert a tag interactively.
469 @item C-c TAB u (`muse-insert-url')
470 Insert a URL interactively.
473 Move to the next Wiki reference.
476 Move to the previous Wiki reference.
479 Complete the name of a page from the current project at point.
482 Insert a new list item at point, indenting properly.
485 Decrease the indentation of the list item at point.
488 Increase the indentation of the list item at point.
493 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
494 @comment node-name, next, previous, up
495 @chapter Rules for Using Markup
498 A Muse document uses special, contextual markup rules to determine how
499 to format the output result. For example, if a paragraph is indented,
500 Muse assumes it should be quoted.
502 There are not too many markup rules, and all of them strive to be as
503 simple as possible so that you can focus on document creation, rather
507 * Paragraphs:: Paragraphs: centering and quoting.
508 * Headings:: Levels of headings.
509 * Directives:: Directives at the beginning of a
511 * Emphasizing Text:: Bold, italicized, and underlined text.
512 * Footnotes:: Making notes to be shown at the end.
513 * Verse:: Indicating poetic stanzas.
514 * Lists:: Lists of items.
515 * Tables:: Generation of data tables.
516 * Explicit Links:: Hyperlinks and email addresses with
518 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
520 * Images:: Publishing and displaying images.
521 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
522 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
524 * Comments:: Lines to omit from published output.
525 * Tag Summary:: Tags that Muse recognizes.
528 @node Paragraphs, Headings, Markup Rules, Markup Rules
529 @comment node-name, next, previous, up
530 @section Paragraphs: centering and quoting
533 Paragraphs in Muse must be separated by a blank line.
535 @cindex paragraphs, centered
536 @subheading Centered paragraphs and quotations
538 A line that begins with six or more columns of whitespace (either tabs
539 or spaces) indicates a centered paragraph. Alternatively, you can use
540 the @verb{|<center>|} tag to surround regions that are to be published as
543 @cindex paragraphs, quoted
545 But if a line begins with whitespace, though less than six columns, it
546 indicates a quoted paragraph. Alternatively, you can use the
547 @verb{|<quote>|} tag to surround regions that are to be published as
551 @cindex monospace, rendering blocks
552 @cindex HTML, rendering blocks in monospace
553 @subheading Literal paragraphs
555 The @verb{|<example>|} tag is used for examples, where whitespace should
556 be preserved, the text rendered in monospace, and any characters special
557 to the output style escaped.
560 @cindex HTML, inserting a raw block
561 There is also the @verb{|<literal>|} tag, which causes a marked block to
562 be entirely left alone. This can be used for inserting a hand-coded
563 HTML blocks into HTML output, for example.
565 @node Headings, Directives, Paragraphs, Markup Rules
566 @comment node-name, next, previous, up
567 @section Levels of headings
570 A heading becomes a chapter or section in printed output -- depending on
571 the style. To indicate a heading, start a new paragraph with one or
572 more asterices, followed by a space and the heading title. Then begin
573 another paragraph to enter the text for that section.
575 All levels of headings will be published. Most publishing styles only
576 distinguish the between the first 4 levels, however.
588 @node Directives, Emphasizing Text, Headings, Markup Rules
589 @comment node-name, next, previous, up
590 @section Directives at the beginning of a document
593 Directives are lines beginning with the @samp{#} character that come
594 before any paragraphs or sections in the document. Directives are of
595 the form ``#directive content of directive''. You can use any
596 combination of uppercase and lowercase letters for directives, even if
597 the directive is not in the list below.
599 The @code{muse-publishing-directive} function may be used in header and
600 footer text to access directives. For example, to access the
601 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
603 The following is a list of directives that Muse uses.
608 The author of this document.
610 If this is not specified, Muse will attempt to figure it out from the
611 @code{user-full-name} variable.
615 The date that the document was last modified.
617 This is used by publishing styles that are able to embed the date
622 A short description of this document.
624 This is used by the @code{journal} publishing style to embed information
625 inside of an RSS/RDF feed.
629 The title of this document.
631 If this is not specified, the name of the file is used.
635 @node Emphasizing Text, Footnotes, Directives, Markup Rules
636 @comment node-name, next, previous, up
637 @section Bold, italicized, and underlined text
638 @cindex emphasizing text
639 @cindex underlining text
640 @cindex italicizing text
641 @cindex verbatim text
642 @cindex monospace, rendering words
644 To emphasize text, surround it with certain specially recognized
650 ***very strong emphasis***
652 =verbatim and monospace=
656 While editing a Muse document in Muse mode, these forms of emphasis will
657 be highlighted in a WYSIWYG manner. Each of these forms may span
660 Verbatim text will be colored as gray by default. To change this,
661 customize @code{muse-verbatim-face}.
663 You can also use the @verb{|<code>|} tag to indicate verbatim and
664 monospace text. This is handy for regions that have an ``='' in them.
666 @node Footnotes, Verse, Emphasizing Text, Markup Rules
667 @comment node-name, next, previous, up
668 @section Making notes to be shown at the end
671 A footnote reference is simply a number in square brackets. To define
672 the footnote, place this definition at the bottom of your file.
673 @samp{footnote-mode} can be used to greatly facilitate the creation of
674 these kinds of footnotes.
676 Footnotes are defined by the same number in brackets occurring at the
677 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
678 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
679 the point of insertion.
681 @node Verse, Lists, Footnotes, Markup Rules
682 @comment node-name, next, previous, up
683 @section Indicating poetic stanzas
687 Poetry requires that whitespace be preserved, but without resorting to
688 monospace. To indicate this, use the following markup, reminiscent of
692 > A line of Emacs verse;
693 > forgive its being so terse.
696 You can also use the @verb{|<verse>|} tag, if you prefer.
700 A line of Emacs verse;
701 forgive its being so terse.
705 @cindex verses, multiple stanzas
706 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
711 A line of Emacs verse;
712 forgive its being so terse.
714 In terms of terse verse,
719 @node Lists, Tables, Verse, Markup Rules
720 @comment node-name, next, previous, up
721 @section Lists of items
724 Lists are given using special characters at the beginning of a line.
725 Whitespace must occur before bullets or numbered items, to distinguish
726 from the possibility of those characters occurring in a real sentence.
728 @cindex lists, bullets
729 These are rendered as a bullet list.
736 @cindex lists, enumerated
737 An enumerated list follows.
744 @cindex lists, definitions
745 Here is a definition list.
749 This is a first definition
750 And it has two lines;
754 This is a second definition
757 @node Tables, Explicit Links, Lists, Markup Rules
758 @comment node-name, next, previous, up
759 @section Generation of data tables
762 @cindex tables, simple
763 Only very simple tables are supported. The syntax is as follows.
766 Double bars || Separate header fields
768 Single bars | Separate body fields
769 Here are more | body fields
771 Triple bars ||| Separate footer fields
774 Some publishing styles require header fields to come first, then footer
775 fields, and then the body fields. You can use any order for these
776 sections that you like, and Muse will re-order them for you at
779 If you wish to disable table generation for one Muse file, add the
780 directive @samp{#disable-tables t} to the top of the file.
782 @node Explicit Links, Implicit Links, Tables, Markup Rules
783 @comment node-name, next, previous, up
784 @section Hyperlinks and email addresses with descriptions
785 @cindex links, explicit
787 A hyperlink can reference a URL, or another page within a Muse
788 project. In addition, descriptive text can be specified, which should
789 be displayed rather than the link text in output styles that supports
790 link descriptions. The syntax is as follows.
793 [[link target][link description]]
794 [[link target without description]]
797 Thus, the current maintainer's homepage for Muse can be found
798 @samp{[[http://www.mwolson.org/projects/EmacsMuse.html][here]]},
799 or at @samp{[[http://www.mwolson.org/projects/EmacsMuse.html]]}.
801 @node Implicit Links, Images, Explicit Links, Markup Rules
802 @comment node-name, next, previous, up
803 @section Bare URLs, WikiNames, and InterWiki links
804 @cindex links, implicit
807 @cindex Email addresses
809 A URL or email address encountered in the input text is published as a
810 hyperlink. These kind of links are called @dfn{implicit links} because
811 they are not separated from the rest of the Muse document in any way.
814 If the @command{muse-wiki} module is loaded, another form of implicit
815 link will be made available. WikiNames, which are typed in CamelCase,
816 are highlighted and published as links, provided that the file they
819 Customization of WikiName recognition may be accomplished by editing the
820 @code{muse-wiki-wikiword-regexp} option and subsequently running
821 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
822 If you use the Customize interface, the latter will be done
825 @cindex InterWiki links
826 @cindex inter-project links
827 The @command{muse-wiki} module also allows for InterWiki links. These
828 are similar to WikiWords, but they specify both the project and page of
829 a file. The names of your project entries in @code{muse-project-alist}
830 will be used as InterWiki names by default. Several examples follow.
833 Blog::DocumentingMuse
838 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
839 the project name, and @samp{DocumentingMuse} is the page name. In the
840 second example, @samp{#} is the interwiki delimiter. If the name of a
841 project occurs by itself in text, like the third case, it will be
842 colorized and published as a link to the default page of the given
845 Customization of interwiki links may be accomplished by editing the
846 @code{muse-wiki-interwiki-alist} option.
848 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
849 @comment node-name, next, previous, up
850 @section Publishing and displaying images
852 @cindex links, with images
853 @subheading Image links
855 Links to images may be used in either the target or the description, or
856 both. Thus, the following code will publish as a clickable image that
857 points to @url{http://www.mwolson.org/}.
860 [[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
863 @cindex images, displaying
864 @cindex images, inlined
865 @cindex images, local
866 If a link to a locally-available image is encountered in the link
867 description, Muse mode will attempt to display it if your version of
868 Emacs permits this. The following example will display correctly and
869 publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
870 exists in the @file{../pics/} directory.
873 [[TestPage][../pics/TestLogo.png]]
876 @cindex images, without a description
877 An image link is not required to have a description. The link
878 @samp{[[../myimage.png]]} will display and publish as expected.
880 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
881 @comment node-name, next, previous, up
882 @section Inserting a horizontal line or anchor
884 @cindex horizontal rules
886 @subheading Horizontal Rules
888 Four or more dashes indicate a horizontal rule. Be sure to put blank
889 lines around it, or it will be considered part of the proceeding or
893 @cindex links, with target on same page
896 If you begin a line with "#anchor" -- where "anchor" can be any word
897 that doesn't contain whitespace -- it defines an anchor at that point
898 into the document. This point can be referenced using "page#anchor" as
899 the target in a Muse link.
901 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
902 @comment node-name, next, previous, up
903 @section Evaluating Emacs Lisp code in documents for extensibility
904 @cindex lisp, embedded
906 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
907 which is the only Muse tag supported in a style's header and footer
908 text. With the @verb{|<lisp>|} tag, you may generated whatever output
909 text you wish. The inserted output will get marked up, if the
910 @verb{|<lisp>|} tag appears within the main text of the document.
913 <lisp>(concat "This form gets " "inserted")</lisp>
916 @cindex lisp, and insert command
917 Note that you should not use the @code{insert} command within a set of
918 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
919 tags will be automatically inserted into the document.
921 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
922 @comment node-name, next, previous, up
923 @section Lines to omit from published output
925 @cindex publishing, omitting lines
927 Use the following syntax to indicate a comment. Comments will not be
931 ; Comment text goes here.
934 That is, only a semi-colon at the beginning of a line, followed by a
935 literal space, will cause that line to be treated as a comment.
937 @node Tag Summary, , Comments, Markup Rules
938 @comment node-name, next, previous, up
939 @section Tags that Muse recognizes
941 @cindex inserting files at publish time
942 @cindex publishing, including markup in headers and footers
943 @cindex publishing, inserting files
945 Muse has several built-in tags that may prove useful during publishing.
946 @xref{muse-publish-markup-tags}, to see how to customize the tags that
947 Muse uses, as well as make your own tags.
951 If a tag takes arguments, it will look like this, where ``tagname'' is
955 <tagname arg1="string1" arg2="string2">
958 If you want the tag to look like it came straight from an XHTML
959 document, you can alternatively do the following.
962 <tagname arg1="string1" arg2="string2" />
965 If a tag surrounds some text, it will look like this.
968 <tagname>Some text</tagname>
971 If a tag surrounds a large region, it will look like this.
980 @subheading Tag listing
982 This is the complete list of tags that Muse accepts, including those
983 that were mentioned in previous sections.
988 If publishing to HTML, surround the given text with a @verb{|<span>|}
989 tag. It takes one argument called ``name'' that specifies the class
990 attribute of the @verb{|<span>|} tag.
992 If publishing to a different format, do nothing extra to the text.
995 Treat the text surrounded by the tag as if they were enclosed in equal
996 signs, that is, make it monospace.
999 Run a command on the region, replacing the region with the result of the
1000 command. The command is specified with the ``interp'' argument. If no
1001 value for ``interp'' is given, pass the entire region to the shell.
1003 The ``markup'' argument controls how this section is marked up.
1005 If it is omitted, publish the region with the normal Muse rules.
1007 If "nil", do not mark up the region at all, but prevent Muse from
1008 further interpreting it.
1010 If "example", treat the region as if it was surrounded by the
1011 @verb{|<example>|} tag.
1013 If "verse", treat the region as if it was surrounded by the
1014 @verb{|<verse>|} tag, to preserve newlines.
1016 Otherwise, it should be the name of a function to call, with the buffer
1017 narrowed to the region.
1020 Treat the entire region as a comment. If the option
1021 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1022 publish it using the comment syntax of the current publishing style.
1025 Publish a Table of Contents. This will either be inserted in-place or
1026 at the beginning of the document, depending on your publishing style.
1027 It does not have a delimiting tag.
1029 By default, only 2 levels of headings will be included in the generated
1030 Table of Contents. To change this globally, customize the
1031 @var{muse-publish-contents-depth} option. To change this only for the
1032 current tag, use the ``depth'' argument.
1035 Publish the region in monospace, preserving the newlines in the region.
1036 This is useful for snippets of code.
1039 Insert the given file at the current location during publishing. The
1040 basic use of this tag is as follows, replacing ``included_file'' with
1041 the name of the file that you want to include.
1044 <include file="included_file">
1047 The ``markup'' argument controls how this section is marked up.
1049 If it is omitted, publish the included text with the normal Muse
1052 If "nil", do not mark up the included text at all.
1054 If "example", treat the included text as if it was surrounded by the
1055 @verb{|<example>|} tag.
1057 If "verse", treat the included text as if it was surrounded by the
1058 @verb{|<verse>|} tag, to preserve newlines.
1060 Otherwise, it should be the name of a function to call after inserting
1061 the file with the buffer narrowed to the section inserted.
1064 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1065 The result is then inserted into the document, so you do not need to
1066 explicitly call @code{insert}. All text properties are removed from the
1069 This tag takes the ``markup'' argument. See the description of
1070 @verb{|<command>|} for details.
1073 Make sure that the text enclosed by this tag is published without
1074 escaping it in any way. This is useful for inserting markup directly
1075 into the published document, when Muse does not provide the desired
1079 Mark up the text between the initial and ending tags. The markup
1080 command to use may be specified by the ``function'' argument. The
1081 standard Muse markup routines are used by default if no ``function''
1082 argument is provided.
1084 This is useful for marking up regions in headers and footers. One
1085 example that comes to mind is generating a published index of all of the
1086 files in the current project by doing the following.
1089 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1093 Run the @command{perl} language interpreter on the region, replacing the
1094 region with the result of the command.
1096 This tag takes the ``markup'' argument. See the description of
1097 @verb{|<command>|} for details.
1100 Run the @command{python} language interpreter on the region, replacing
1101 the region with the result of the command.
1103 This tag takes the ``markup'' argument. See the description of
1104 @verb{|<command>|} for details.
1107 Publish the region as a blockquote. This will either be inserted
1108 in-place or at the beginning of the document, depending on your
1109 publishing style. It does not have a delimiting tag.
1112 Run the @command{ruby} language interpreter on the region, replacing the
1113 region with the result of the command.
1115 This tag takes the ``markup'' argument. See the description of
1116 @verb{|<command>|} for details.
1119 This is used when you want to prevent Muse from trying to interpret some
1120 markup. Surround the markup in @verb{|<verbatim>|} and
1121 @verb{|</verbatim>|}, and it will not be interpreted.
1123 This tag was used often in previous versions of Muse because they did
1124 not support whole-document escaping of specials. Now, it will only be
1125 needed for other tags, and perhaps footnotes as well.
1128 Preserve the newlines in the region. In formats like HTML, newlines are
1129 removed by default, hence the need for this tag. In other publishing
1130 styles, this tag may cause the text to be indented slightly in a way
1131 that looks nice for poetry and prose.
1135 @node Publishing Styles, Extending Muse, Markup Rules, Top
1136 @comment node-name, next, previous, up
1137 @chapter Publishing Various Types of Documents
1138 @cindex publishing styles
1140 One of the principle features of Muse is the ability to publish a simple
1141 input text to a variety of different output styles. Muse also makes it
1142 easy to create new styles, or derive from an existing style.
1145 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1146 * Book:: Publishing entries into a compilation.
1147 * DocBook:: Publishing in DocBook XML form.
1148 * HTML:: Publishing in HTML or XHTML form.
1149 * Journal:: Keeping a journal or blog.
1150 * LaTeX:: Publishing LaTeX documents.
1151 * Poem:: Publish a poem to LaTex or PDF.
1152 * Texinfo:: Publish entries to Texinfo format or PDF.
1155 @node Blosxom, Book, Publishing Styles, Publishing Styles
1156 @comment node-name, next, previous, up
1157 @section Integrating Muse and pyblosxom.cgi
1158 @cindex blog, one-file-per-entry style
1160 The Blosxom publishing style publishes a tree of categorised files to a
1161 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1162 In other words, each blog entry corresponds with one file.
1165 * Blosxom Requirements:: Other tools needed to the Blosxom style.
1166 * Blosxom Entries:: Format of a Blosxom entry and automation.
1167 * Blosxom Options:: Blosxom styles and options provided.
1170 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1171 @comment node-name, next, previous, up
1172 @subsection Other tools needed to the Blosxom style
1174 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1175 installed on a machine that you have upload access to.
1177 The following additional components are required in order to make the
1178 date of blog entries display as something sensible.
1182 A script to gather date directives from the entire blog tree into a
1183 single file. The file must associate a blog entry with a date.
1186 A plugin for (py)blosxom that reads this file.
1189 These 2 things are provided for @command{pyblosxom.cgi} in the
1190 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1191 former service, while @file{hardcodedates.py} provides the latter
1192 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1193 script will be found/written.
1195 Here is a sample listing from my @file{timestamps} file, which maps
1196 each file to a date. This can really be in any format, as long as your
1197 date-gathering script and your plugin can both understand it.
1200 2005-04-01-14-16 personal/paper_cranes
1201 2005-03-21 personal/spring_break_over
1202 2004-10-24 personal/finished_free_culture
1205 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1206 @file{getstamps.py}. Note that you will need to set the current
1207 directory to where your Muse files are, execute @file{getstamps.py}, and
1208 then move the generated timestamps file to your publishing directory.
1210 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1211 @comment node-name, next, previous, up
1212 @subsection Format of a Blosxom entry and automation
1214 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1215 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1216 plus whatever normal content is desired.
1218 The date directive is not used directly by @command{pyblosxom.cgi} or
1219 this program. You need to have the two additional items from the former
1220 section to make use of this feature.
1222 There is a function called @code{muse-blosxom-new-entry} that will
1223 automate the process of making a new blog entry. To make use of it, do
1228 Customize @code{muse-blosxom-base-directory} to the location that your
1229 blog entries are stored.
1232 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1233 use the following code to assign this function to @kbd{C-c p l'}.
1236 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1240 You should create your directory structure ahead of time under your base
1241 directory. These directories, which correspond with category names, may
1245 When you enter this key sequence, you will be prompted for the category
1246 of your entry and its title. Upon entering this information, a new file
1247 will be created that corresponds with the title, but in lowercase
1248 letters and having special characters converted to underscores. The
1249 title and date directives will be inserted automatically.
1252 @node Blosxom Options, , Blosxom Entries, Blosxom
1253 @comment node-name, next, previous, up
1254 @subsection Blosxom styles and options provided
1256 The following styles and options are available in the Blosxom publishing
1259 @subheading Styles provided
1263 @cindex publishing styles, blosxom-html
1265 Publish Blosxom entries in HTML form.
1267 @cindex publishing styles, blosxom-xhtml
1269 Publish Blosxom entries in XHTML form.
1273 @subheading Options provided
1277 @item muse-blosxom-extension
1278 Default file extension for publishing Blosxom files.
1280 @item muse-blosxom-header
1281 Header used for publishing Blosxom files.
1283 This may be text or a filename.
1285 @item muse-blosxom-footer
1286 Footer used for publishing Blosxom files.
1288 This may be text or a filename.
1290 @item muse-blosxom-base-directory
1291 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1293 This is the top-level directory where your blog entries may be found
1298 @node Book, DocBook, Blosxom, Publishing Styles
1299 @comment node-name, next, previous, up
1300 @section Publishing entries into a compilation
1302 This publishing style is used to output ``books'' in LaTeX or PDF
1305 Each page will become a separate chapter in the book, unless the style
1306 keyword @option{:nochapters} is used, in which case they are all run
1307 together as if one giant chapter.
1309 You will need to call the @code{muse-book-publish-project} function in
1310 order to publish this style. An example of this may be found in John
1311 Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1313 @subheading Styles provided
1317 @cindex publishing styles, book-latex
1319 Publish a book in LaTeX form. The header and footer are different than
1320 the normal LaTeX publishing mode.
1322 @cindex publishing styles, book-pdf
1324 Publish a book in PDF form. The header and footer are different than
1325 the normal PDF publishing mode.
1329 @subheading Options provided
1333 @item muse-book-before-publish-hook
1334 A hook run in the book buffer before it is marked up.
1336 @item muse-book-after-publish-hook
1337 A hook run in the book buffer after it is marked up.
1339 @item muse-book-latex-header
1340 Header used for publishing books to LaTeX.
1342 This may be text or a filename.
1344 @item muse-book-latex-footer
1345 Footer used for publishing books to LaTeX.
1347 This may be text or a filename.
1351 @node DocBook, HTML, Book, Publishing Styles
1352 @comment node-name, next, previous, up
1353 @section Publishing in DocBook XML form
1355 This publishing style is used to generate DocBook XML files.
1357 @subheading Styles provided
1361 @cindex publishing styles, docbook
1366 @subheading Options provided
1370 @item muse-docbook-extension
1371 Default file extension for publishing DocBook XML files.
1373 @item muse-docbook-header
1374 Header used for publishing DocBook XML files.
1376 This may be text or a filename.
1378 @item muse-docbook-footer
1379 Footer used for publishing DocBook XML files.
1381 This may be text or a filename.
1383 @item muse-docbook-markup-regexps
1384 List of markup rules for publishing a Muse page to DocBook XML.
1386 @item muse-docbook-markup-functions
1387 An alist of style types to custom functions for that kind of text.
1389 @item muse-docbook-markup-strings
1390 Strings used for marking up text.
1392 These cover the most basic kinds of markup, the handling of which
1393 differs little between the various styles.
1395 @item muse-docbook-markup-specials
1396 A table of characters which must be represented specially.
1398 @item muse-docbook-encoding-default
1399 The default Emacs buffer encoding to use in published files.
1400 This will be used if no special characters are found.
1402 @item muse-docbook-charset-default
1403 The default DocBook XML charset to use if no translation is
1404 found in @code{muse-docbook-encoding-map}.
1406 @item muse-docbook-encoding-map
1407 An alist mapping emacs coding systems to appropriate DocBook charsets.
1408 Use the base name of the coding system (i.e. without the -unix).
1412 @node HTML, Journal, DocBook, Publishing Styles
1413 @comment node-name, next, previous, up
1414 @section Publishing in HTML or XHTML form
1416 This publishing style is capable of producing HTML or XHTML documents.
1418 @subheading Styles provided
1422 @cindex publishing styles, html
1424 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1427 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1431 @subheading Options provided
1433 If an HTML option does not have a corresponding XHTML option, it will
1434 be used for both of these publishing styles.
1438 @item muse-html-extension
1439 Default file extension for publishing HTML files.
1441 @item muse-xhtml-extension
1442 Default file extension for publishing XHTML files.
1444 @item muse-html-style-sheet
1445 Store your stylesheet definitions here.
1447 This is used in @code{muse-html-header}. You can put raw CSS in here or
1448 a @verb{|<link>|} tag to an external stylesheet. This text may contain
1449 @verb{|<lisp>|} markup tags.
1451 If you are using XHTML, make sure to close the @verb{|<link>|} tag
1454 @item muse-html-header
1455 Header used for publishing HTML files.
1457 This may be text or a filename.
1459 @item muse-html-footer
1460 Footer used for publishing HTML files.
1462 This may be text or a filename.
1464 @item muse-xhtml-header
1465 Header used for publishing XHTML files.
1467 This may be text or a filename.
1469 @item muse-xhtml-footer
1470 Footer used for publishing XHTML files.
1472 This may be text or a filename.
1474 @item muse-html-anchor-on-word
1475 When true, anchors surround the closest word.
1477 This allows you to select them in a browser (i.e. for pasting), but has
1478 the side-effect of marking up headers in multiple colors if your header
1479 style is different from your link style.
1481 @item muse-html-table-attributes
1482 The attribute to be used with HTML @verb{|<table>|} tags.
1484 If you want to make more-complicated tables in HTML, surround the HTML
1485 with the @verb{|literal|} tag, so that it does not get escaped.
1487 @item muse-html-markup-regexps
1488 List of markup rules for publishing a Muse page to HTML.
1490 @item muse-html-markup-functions
1491 An alist of style types to custom functions for that kind of text.
1493 @item muse-html-markup-strings
1494 Strings used for marking up text as HTML.
1496 These cover the most basic kinds of markup, the handling of which
1497 differs little between the various styles.
1499 @item muse-xhtml-markup-strings
1500 Strings used for marking up text as XHTML.
1502 These cover the most basic kinds of markup, the handling of which
1503 differs little between the various styles.
1505 @item muse-html-markup-tags
1506 A list of tag specifications, for specially marking up HTML.
1507 @xref{muse-publish-markup-tags}, for more information.
1509 @item muse-html-markup-specials
1510 A table of characters which must be represented specially. By default,
1511 this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1513 @item muse-html-meta-http-equiv
1514 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1516 @item muse-html-meta-content-type
1517 The content type used for the HTML @verb{|<meta>|} tag.
1519 If you are striving for XHTML 1.1 compliance, you may want to change
1520 this to ``application/xhtml+xml''.
1522 @item muse-html-meta-content-encoding
1523 The charset to append to the HTML @verb{|<meta>|} tag.
1525 If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1526 and determine the HTML charset from emacs's coding. If set to a string,
1527 this string will be used to force a particular charset.
1529 @item muse-html-charset-default
1530 The default HTML meta charset to use if no translation is found in
1531 @code{muse-html-encoding-map}.
1533 @item muse-html-encoding-default
1534 The default Emacs buffer encoding to use in published files.
1535 This will be used if no special characters are found.
1537 @item muse-html-encoding-map
1538 An alist mapping emacs coding systems to appropriate HTML charsets.
1539 Use the base name of the coding system (i.e. without the -unix).
1543 @node Journal, LaTeX, HTML, Publishing Styles
1544 @comment node-name, next, previous, up
1545 @section Keeping a journal or blog
1547 @cindex blog, journal style
1549 The module facilitates the keeping and publication of a journal. When
1550 publishing to HTML, it assumes the form of a web log, or blog.
1552 The input format for each entry is as follows.
1555 * 20040317: Title of entry
1560 "You know who you are. It comes down to a simple gut check: You
1561 either love what you do or you don't. Period." -- P. Bronson
1565 The "qotd", or Quote of the Day, is entirely optional. When generated
1566 to HTML, this entry is rendered as the following.
1570 <div class="entry-qotd">
1571 <h3>Quote of the Day:</h3>
1572 <p>"You know who you are. It comes down to a simple gut
1573 check: You either love what you do or you don't. Period."
1576 <div class="entry-body">
1577 <div class="entry-head">
1578 <div class="entry-date">
1579 <span class="date">March 17, 2004</span>
1581 <div class="entry-title">
1582 <h2>Title of entry</h2>
1585 <div class="entry-text">
1586 <p>Text for the entry.</p>
1592 The plurality of "div" tags makes it possible to display the entries in
1593 any form you wish, using a CSS style.
1595 Also, an .RDF file can be generated from your journal by publishing it
1596 with the "rdf" style. It uses the first two sentences of the first
1597 paragraph of each entry as its "description", and auto-generates tags
1598 for linking to the various entries.
1600 @subheading Styles provided
1604 @cindex publishing styles, journal-html
1606 Publish journal entries as an HTML document.
1608 @cindex publishing styles, journal-xhtml
1610 Publish journal entries as an XHTML document.
1612 @cindex publishing styles, journal-latex
1614 Publish journal entries as a LaTeX document.
1616 @cindex publishing styles, journal-pdf
1618 Publish journal entries as a PDF document.
1620 @cindex publishing styles, journal-book-latex
1621 @item journal-book-latex
1622 Publish journal entries as a LaTeX book.
1624 @cindex publishing styles, journal-book-pdf
1625 @item journal-book-pdf
1626 Publish journal entries as a PDF book.
1628 @cindex publishing styles, journal-rdf
1629 @cindex publishing styles, RSS 1.0
1631 Publish journal entries as an RDF file (RSS 1.0).
1633 @cindex publishing styles, journal-rss
1634 @cindex publishing styles, RSS 2.0
1636 Publish journal entries as an RSS file (RSS 2.0).
1640 @subheading Options provided
1644 @item muse-journal-heading-regexp
1645 A regexp that matches a journal heading.
1647 Paren group 1 is the ISO date, group 2 is the optional category, and
1648 group 3 is the optional heading for the entry.
1650 @item muse-journal-date-format
1651 Date format to use for journal entries.
1653 @item muse-journal-html-heading-regexp
1654 A regexp that matches a journal heading from an HTML document.
1656 Paren group 1 is the ISO date, group 2 is the optional category, and
1657 group 3 is the optional heading for the entry.
1659 @item muse-journal-html-entry-template
1660 Template used to publish individual journal entries as HTML.
1662 @item muse-journal-latex-section
1663 Template used to publish a LaTeX section.
1665 @item muse-journal-latex-subsection
1666 Template used to publish a LaTeX subsection.
1668 @item muse-journal-latex-markup-tags
1669 A list of tag specifications, for specially marking up LaTeX.
1671 @xref{muse-publish-markup-tags}, for more information.
1673 @item muse-journal-rdf-extension
1674 Default file extension for publishing RDF (RSS 1.0) files.
1676 @item muse-journal-rdf-base-url
1677 The base URL of the website referenced by the RDF file.
1679 @item muse-journal-rdf-header
1680 Header used for publishing RDF (RSS 1.0) files.
1682 This may be text or a filename.
1684 @item muse-journal-rdf-footer
1685 Footer used for publishing RDF (RSS 1.0) files.
1687 This may be text or a filename.
1689 @item muse-journal-rdf-date-format
1690 Date format to use for RDF entries.
1692 @item muse-journal-rdf-entry-template
1693 Template used to publish individual journal entries as RDF.
1695 @item muse-journal-rdf-summarize-entries
1696 If non-nil, include only summaries in the RDF file, not the full data.
1698 @item muse-journal-rss-extension
1699 Default file extension for publishing RSS 2.0 files.
1701 @item muse-journal-rss-base-url
1702 The base URL of the website referenced by the RSS file.
1704 @item muse-journal-rss-header
1705 Header used for publishing RSS 2.0 files.
1707 This may be text or a filename.
1709 @item muse-journal-rss-footer
1710 Footer used for publishing RSS 2.0 files.
1712 This may be text or a filename.
1714 @item muse-journal-rss-date-format
1715 Date format to use for RSS 2.0 entries.
1717 @item muse-journal-rss-entry-template
1718 Template used to publish individual journal entries as RSS 2.0.
1720 @item muse-journal-rss-enclosure-types-alist
1721 File types that are accepted as RSS enclosures.
1723 This is an alist that maps file extension to content type.
1725 Useful for podcasting.
1727 @item muse-journal-rss-summarize-entries
1728 If non-nil, include only summaries in the RSS file, not the full data.
1730 Many RSS subscribers find this annoying.
1732 @item muse-journal-rss-markup-regexps
1733 List of markup rules for publishing a Muse journal page to RSS.
1735 For more information on the structure of this list,
1736 @xref{muse-publish-markup-regexps}.
1738 @item muse-journal-rss-markup-functions
1739 An alist of style types to custom functions for that kind of text.
1741 For more on the structure of this list,
1742 @xref{muse-publish-markup-functions}.
1746 @node LaTeX, Poem, Journal, Publishing Styles
1747 @comment node-name, next, previous, up
1748 @section Publishing LaTeX documents
1750 This publishing style is capable of producing LaTeX or PDF documents.
1752 If you wish to publish PDF documents, you will need to have a good TeX
1753 installation. For Debian and Ubuntu, this can be accomplished by
1754 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
1757 @subheading Styles provided
1761 @cindex publishing styles, latex
1763 Publish a LaTeX document.
1765 @cindex publishing styles, pdf
1767 Publish a PDF document, using an external LaTeX document conversion
1770 @cindex publishing styles, latexcjk
1772 Publish a LaTeX document with CJK (Chinese) encodings.
1774 @cindex publishing styles, pdfcjk
1776 Publish a PDF document with CJK (Chinese) encodings, using an external
1777 LaTeX document conversion tool.
1781 @subheading Options provided
1785 @item muse-latex-extension
1786 Default file extension for publishing LaTeX files.
1788 @item muse-latex-pdf-extension
1789 Default file extension for publishing LaTeX files to PDF.
1791 @item muse-latex-header
1792 Header used for publishing LaTeX files.
1794 This may be text or a filename.
1796 @item muse-latex-footer
1797 Footer used for publishing LaTeX files.
1799 This may be text or a filename.
1801 @item muse-latexcjk-header
1802 Header used for publishing LaTeX files (CJK).
1804 This may be text or a filename.
1806 @item muse-latexcjk-footer
1807 Footer used for publishing LaTeX files (CJK).
1809 This may be text or a filename.
1811 @item muse-latex-markup-regexps
1812 List of markup regexps for identifying regions in a Muse page.
1814 For more on the structure of this list,
1815 @xref{muse-publish-markup-regexps}.
1817 @item muse-latex-markup-functions
1818 An alist of style types to custom functions for that kind of text.
1820 For more on the structure of this list,
1821 @xref{muse-publish-markup-functions}.
1823 @item muse-latex-markup-strings
1824 Strings used for marking up text.
1826 These cover the most basic kinds of markup, the handling of which
1827 differs little between the various styles.
1829 @item muse-latexcjk-encoding-map
1830 An alist mapping emacs coding systems to appropriate CJK codings.
1831 Use the base name of the coding system (ie, without the -unix).
1833 @item muse-latexcjk-encoding-default
1834 The default Emacs buffer encoding to use in published files.
1836 This will be used if no special characters are found.
1838 @item muse-latex-markup-specials-example
1839 A table of characters which must be represented specially.
1840 These are applied to @verb{|example>|} regions.
1842 With the default interpretation of @verb{|<example>|} regions, no
1843 specials need to be escaped.
1845 @item muse-latex-markup-specials-document
1846 A table of characters which must be represented specially.
1847 These are applied to the entire document, sans already-escaped
1850 @item muse-latex-markup-specials-literal
1851 A table of characters which must be represented specially.
1852 This applies to =monospaced text= and @verb{|<code>|} regions.
1854 @item muse-latex-markup-specials-url
1855 A table of characters which must be represented specially.
1856 These are applied to URLs.
1858 @item muse-latex-permit-contents-tag
1859 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
1862 Most of the time, it is best to have a table of contents on the
1863 first page, with a new page immediately following. To make this
1864 work with documents published in both HTML and LaTeX, we need to
1865 ignore the @verb{|<contents>|} tag.
1867 If you don't agree with this, then set this option to non-nil,
1868 and it will do what you expect.
1872 @node Poem, Texinfo, LaTeX, Publishing Styles
1873 @comment node-name, next, previous, up
1874 @section Publish a poem to LaTex or PDF
1876 The @code{muse-poem} module makes it easy to attractively publish and
1877 reference poems in the following format, using the "memoir" module for
1878 LaTeX publishing. It will also markup poems for every other output
1879 style, though none are nearly as pretty.
1888 Annotations, history, notes, etc.
1891 Once a poem is written in this format, just publish it to PDF using the
1892 @code{poem-pdf} style. To make an inlined reference to a poem that
1893 you've written -- for example, from a blog page -- there is a "poem" tag
1894 defined by this module.
1897 <poem title="name.of.poem.page">
1900 Let's assume the template above was called @file{name.of.poem.page};
1901 then the above tag would result in this inclusion.
1909 John Wiegley uses this module for publishing all of the poems on his
1910 website, which are at
1911 @uref{http://www.newartisans.com/johnw/poems.html}.
1913 @subheading Styles provided
1917 @cindex publishing styles, poem-latex
1919 Publish a poem in LaTeX form.
1921 @cindex publishing styles, poem-pdf
1923 Publish a poem to a PDF document.
1925 @cindex publishing styles, chapbook-latex
1926 @item chapbook-latex
1927 Publish a book of poems in LaTeX form.
1929 @cindex publishing styles, chapbook-pdf
1931 Publish a book of poems to a PDF document.
1935 @subheading Options provided
1939 @item muse-poem-latex-header
1940 Header used for publishing LaTeX poems.
1942 This may be text or a filename.
1944 @item muse-poem-latex-footer
1945 Footer used for publishing LaTeX files.
1947 This may be text or a filename.
1949 @item muse-poem-markup-strings
1950 Strings used for marking up poems.
1952 These cover the most basic kinds of markup, the handling of which
1953 differs little between the various styles.
1955 @item muse-chapbook-latex-header
1956 Header used for publishing a book of poems in LaTeX form.
1958 This may be text or a filename.
1960 @item muse-chapbook-latex-footer
1961 Footer used for publishing a book of poems in LaTeX form.
1963 This may be text or a filename.
1965 @item muse-poem-chapbook-strings
1966 Strings used for marking up books of poems.
1968 These cover the most basic kinds of markup, the handling of which
1969 differs little between the various styles.
1973 @node Texinfo, , Poem, Publishing Styles
1974 @comment node-name, next, previous, up
1975 @section Publish entries to Texinfo format or PDF
1977 Rules for publishing a Muse file as a Texinfo article.
1979 @subheading Styles provided
1983 @cindex publishing styles, texi
1985 Publish a file in Texinfo form.
1987 @cindex publishing styles, texi
1989 Generate an Info file from a Muse file.
1991 @cindex publishing styles, info-pdf
1993 Publish a file in PDF form.
1997 @subheading Options provided
2001 @item muse-texinfo-process-natively
2002 If non-nil, use the Emacs `texinfmt' module to make Info files.
2004 @item muse-texinfo-extension
2005 Default file extension for publishing Texinfo files.
2007 @item muse-texinfo-info-extension
2008 Default file extension for publishing Info files.
2010 @item muse-texinfo-pdf-extension
2011 Default file extension for publishing PDF files.
2013 @item muse-texinfo-header
2014 Text to prepend to a Muse page being published as Texinfo.
2016 This may be text or a filename.
2017 It may contain @verb{|<lisp>|} markup tags.
2019 @item muse-texinfo-footer
2020 Text to append to a Muse page being published as Texinfo.
2022 This may be text or a filename.
2023 It may contain @verb{|<lisp>|} markup tags.
2025 @item muse-texinfo-markup-regexps
2026 List of markup rules for publishing a Muse page to Texinfo.
2028 For more on the structure of this list,
2029 @xref{muse-publish-markup-regexps}.
2031 @item muse-texinfo-markup-functions
2032 An alist of style types to custom functions for that kind of text.
2034 For more on the structure of this list, see
2035 @xref{muse-publish-markup-functions}.
2037 @item muse-texinfo-markup-strings
2038 Strings used for marking up text.
2040 These cover the most basic kinds of markup, the handling of which
2041 differs little between the various styles.
2043 @item muse-texinfo-markup-specials
2044 A table of characters which must be represented specially.
2049 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
2050 @comment node-name, next, previous, up
2051 @chapter Making your own publishing styles
2054 * Common Elements:: Common functionality shared by styles.
2055 * Deriving Styles:: Deriving a new style from an existing
2059 @node Common Elements, Deriving Styles, , Extending Muse
2060 @comment node-name, next, previous, up
2061 @section Common functionality shared by styles
2062 @cindex publishing styles, common
2065 * Markup Functions:: Specifying functions to marking up text.
2066 * Markup Regexps:: Markup rules for publishing.
2067 * Markup Strings:: Strings specific to a publishing style.
2068 * Markup Tags:: Tag specifications for special markup.
2069 * Style Elements:: Parameters used for defining styles.
2072 @node Markup Functions, Markup Regexps, , Common Elements
2073 @comment node-name, next, previous, up
2074 @subsection Specifying functions to mark up text
2075 @cindex publishing, markup functions
2077 @anchor{muse-publish-markup-functions}
2078 @code{muse-publish-markup-functions}
2080 An alist of style types to custom functions for that kind of text.
2082 This is used by publishing styles to attempt to minimize the amount of
2083 custom regexps that each has to define. @file{muse-publish} provides
2084 rules for the most common types of markup.
2086 Each member of the list is of the following form.
2094 Describes the type of text to associate with this rule.
2095 @code{muse-publish-markup-regexps} maps regexps to these symbols.
2098 Function to use to mark up this kind of rule if no suitable function is
2099 found through the @option{:functions} tag of the current style.
2102 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
2103 @comment node-name, next, previous, up
2104 @subsection Markup rules for publishing
2105 @cindex publishing, markup regexps
2106 @cindex publishing, rules
2108 @anchor{muse-publish-markup-regexps}
2109 @code{muse-publish-markup-regexps}
2111 List of markup rules for publishing a page with Muse.
2113 The rules given in this variable are invoked first, followed by whatever
2114 rules are specified by the current style.
2116 Each member of the list is either a function, or a list of the following
2120 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
2125 A regular expression, or symbol whose value is a regular expression,
2126 which is searched for using `re-search-forward'.
2128 @item TEXT-BEGIN-GROUP
2129 The matching group within that regexp which denotes the beginning of the
2130 actual text to be marked up.
2132 @item REPLACEMENT-TEXT
2133 A string that will be passed to `replace-match'.
2135 If it is not a string, but a function, it will be called to determine
2136 what the replacement text should be (it must return a string). If it is
2137 a symbol, the value of that symbol should be a string.
2140 The replacements are done in order, one rule at a time. Writing
2141 the regular expressions can be a tricky business. Note that case
2142 is never ignored. `case-fold-search' is always bound to nil
2143 while processing the markup rules.
2145 @subheading Publishing order
2147 This is the order that the publishing rules are consulted, by default.
2148 This may be changed by customizing @code{muse-publish-markup-regexps}.
2152 @item trailing and leading whitespace
2153 Remove trailing and leading whitespace from a file.
2158 This is only recognized at the beginning of a file.
2169 @item explicit links
2170 Prevent emphasis characters in explicit links from being marked up.
2172 Don't actually publish them here, just add a special no-emphasis text
2176 Whitespace-delimited word, possibly with emphasis characters
2178 This function is responsible for marking up emphasis and escaping some
2189 Outline-mode style headings.
2194 These are ellipses with a dot at end.
2204 Horizontal rule or section separator.
2209 beginning of footnotes section
2214 Footnote definition or reference. If at beginning of line, it is a
2229 Numbered list, item list, or term definition list.
2232 spaces before beginning of text
2240 @samp{table | cells}
2243 @samp{[[explicit][links]]}
2246 @samp{http://example.com/}
2249 @samp{bare-email@@example.com}
2253 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
2254 @comment node-name, next, previous, up
2255 @subsection Strings specific to a publishing style
2256 @cindex publishing, markup strings
2258 @dfn{Markup strings} are strings used for marking up text for a
2261 These cover the most basic kinds of markup, the handling of which
2262 differs little between the various styles.
2264 @subheading Available markup strings
2268 @item image-with-desc
2269 An image and a description.
2271 Argument 1: image. Argument 2: description.
2276 Argument 1: image link.
2278 @item url-with-image
2279 A URL with an image.
2281 Argument 1: link. Argument 2: image.
2284 A link with a description.
2286 Argument 1: link. Argument 2: description if one exists, or the
2287 original link otherwise.
2290 A link that refers to an internal anchor.
2292 Argument 1: internal link. Argument 2: description if one exists, or
2293 the original link otherwise.
2296 A link to an email address.
2298 Argument 1: email address. Argument 2: email address.
2304 A horizontal line or space.
2307 Beginning of footnote.
2313 Mark a reference for the current footnote.
2315 Argument 1: number of this footnote.
2318 Indicate the text of the current footnote.
2320 Argument 1: number of this footnote.
2322 @item footnotetext-end
2323 End of a footnote text line.
2326 Text used to replace ``Footnotes:'' line.
2335 Beginning of a part indicator line. This is used by book publishing.
2338 End of a part indicator line. This is used by book publishing.
2341 Beginning of a chapter indicator line. This is used by book publishing.
2344 End of a chapter indicator line. This is used by book publishing.
2347 Beginning of level 1 section indicator line.
2349 Argument 1: level of section; always 1.
2352 End of level 1 section indicator line.
2354 Argument 1: level of section; always 1.
2357 Beginning of level 2 section indicator line.
2359 Argument 1: level of section; always 2.
2361 @item subsection-end
2362 End of level 2 section indicator line.
2364 Argument 1: level of section; always 2.
2367 Beginning of level 3 section indicator line.
2369 Argument 1: level of section; always 3.
2371 @item subsubsection-end
2372 End of level 3 section indicator line.
2374 Argument 1: level of section; always 3.
2377 Beginning of section indicator line, where level is greater than 3.
2379 Argument 1: level of section.
2381 @item section-other-end
2382 Beginning of section indicator line, where level is greater than 3.
2384 Argument 1: level of section.
2386 @item begin-underline
2387 Beginning of underlined text.
2390 End of underlined text.
2393 Beginning of verbatim text. This includes @verb{|<code>|} tags and
2397 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2401 Beginning of the first level of emphasized text.
2404 End of the first level of emphasized text.
2406 @item begin-more-emph
2407 Beginning of the second level of emphasized text.
2410 End of the second level of emphasized text.
2412 @item begin-most-emph
2413 Beginning of the third (and final) level of emphasized text.
2416 End of the third (and final) level of emphasized text.
2419 Beginning of verse text.
2422 String used to each space that is further indented than the beginning of
2425 @item begin-verse-line
2426 Beginning of a line of verse.
2428 @item empty-verse-line
2429 End of a line of verse.
2431 @item begin-last-stanza-line
2432 Beginning of the last line of a verse stanza.
2434 @item end-last-stanza-line
2435 End of the last line of a verse stanza.
2441 Beginning of an example region. To make use of this, an
2442 @samp{<example>} tag is needed.
2445 End of an example region. To make use of this, an @samp{</example>} tag
2449 Begin a centered line.
2452 End a centered line.
2455 Begin a quoted region.
2458 End a quoted region.
2461 Begin an unordered list.
2464 End an unordered list.
2467 Begin an ordered list.
2470 End an ordered list.
2473 Begin a definition list.
2476 Begin a term in a definition list.
2479 End a definition list.
2483 @node Markup Tags, Style Elements, Markup Strings, Common Elements
2484 @comment node-name, next, previous, up
2485 @subsection Tag specifications for special markup
2486 @cindex publishing, markup tags
2488 @anchor{muse-publish-markup-tags}
2489 @code{muse-publish-markup-tags}
2491 A list of tag specifications, for specially marking up text.
2493 XML-style tags are the best way to add custom markup to Muse. This is
2494 easily accomplished by customizing this list of markup tags.
2496 For each entry, the name of the tag is given, whether it expects a
2497 closing tag and/or an optional set of attributes, and a function that
2498 performs whatever action is desired within the delimited region.
2500 The tags themselves are deleted during publishing, before the function
2501 is called. The function is called with three arguments, the beginning
2502 and end of the region surrounded by the tags. If properties are
2503 allowed, they are passed as a third argument in the form of an alist.
2504 The `end' argument to the function is always a marker.
2506 Point is always at the beginning of the region within the tags, when the
2507 function is called. Wherever point is when the function finishes is
2508 where tag markup will resume.
2510 These tag rules are processed once at the beginning of markup, and once
2511 at the end, to catch any tags which may have been inserted in-between.
2513 @node Style Elements, , Markup Tags, Common Elements
2514 @comment node-name, next, previous, up
2515 @subsection Parameters used for defining styles
2516 @cindex publishing, style elements
2518 Style elements are tags that define a style. Use
2519 @code{muse-define-style} to create a new style.
2522 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2525 @subheading Usable elements
2530 File extension to use for publishing files with this style.
2533 File extension to use for publishing links to Muse files with this
2537 File extension to use for publishing second-stage files with this style.
2539 For example, PDF publishing generates a LaTeX file first, then a PDF
2540 from that LaTeX file.
2543 List of markup rules for publishing a page with Muse.
2544 @xref{muse-publish-markup-regexps}.
2547 An alist of style types to custom functions for that kind of text.
2548 @xref{muse-publish-markup-functions}.
2551 Strings used for marking up text with this style.
2553 These cover the most basic kinds of markup, the handling of which
2554 differs little between the various styles.
2557 A list of tag specifications, used for handling extra tags.
2558 @xref{muse-publish-markup-tags}.
2561 A table of characters which must be represented specially.
2564 A function that is to be executed on the newly-created publishing buffer
2565 (or the current region) before any publishing occurs.
2567 This is used to set extra parameters that direct the publishing process.
2570 A function that is to be executed on the publishing buffer (or the
2571 current region) immediately after applying all of the markup regexps.
2573 This is used to fix the order of table elements (header, footer, body)
2577 A function that is to be executed on the publishing buffer after
2578 :before-end, and immediately after inserting the header and footer.
2580 This is used for generating the table of contents as well as setting the
2584 A function that is to be executed after saving the published file, but
2585 while still in its buffer.
2587 This is used for generating second-stage documents like PDF files from
2588 just-published LaTeX files.
2591 Header used for publishing files of this style.
2593 This may be a variable, text, or a filename. It is inserted at the
2594 beginning of a file, after evaluating the publishing markup.
2597 Footer used for publishing files of this style.
2599 This may be a variable, text, or a filename. It is inserted at the end
2600 of a file, after evaluating the publishing markup.
2603 Style sheet used for publishing files of this style.
2605 This may be a variable or text. It is used in the header of HTML and
2606 XHTML based publishing styles.
2609 The function used to browse the published result of files of this style.
2613 @node Deriving Styles, , Common Elements, Extending Muse
2614 @comment node-name, next, previous, up
2615 @section Deriving a new style from an existing one
2616 @cindex publishing styles, deriving
2618 To create a new style from an existing one, use @code{muse-derive-style}
2619 as follows. This is a good way to fix something you don't like about a
2620 particular publishing style, or to personalize it.
2623 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2626 The derived name is a string defining the new style, such as "my-html".
2627 The base name must identify an existing style, such as "html" -- if you
2628 have loaded @file{muse-html}. The style parameters are the same as
2629 those used to create a style, except that they override whatever
2630 definitions exist in the base style. However, some definitions only
2631 partially override. The following parameters support partial
2634 @xref{Style Elements}, for a complete list of all parameters.
2639 If a markup function is not found in the derived style's function list,
2640 the base style's function list will be queried.
2643 All regexps in the current style and the base style(s) will be used.
2646 If a markup string is not found in the derived style's string list, the
2647 base style's string list will be queried.
2652 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
2653 @comment node-name, next, previous, up
2654 @chapter Getting Help and Reporting Bugs
2655 @cindex help, getting
2656 @cindex bugs, reporting
2658 After you have read this guide, if you still have questions about
2659 Muse, or if you have bugs to report, there are several places you can
2665 @uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
2666 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2670 @uref{http://www.mwolson.org/projects/EmacsMuse.html} is the web page
2671 that Michael Olson (the current maintainer) made for Muse.
2674 Muse has three mailing lists.
2678 @item muse-el-announce
2679 Low-traffic list for Muse-related announcements.
2681 You can join this mailing list (@email{muse-el-announce@@gna.org})
2682 using the subscription form at
2683 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
2684 mailing list is also available via Gmane (@url{http://gmane.org/}). The
2685 group is called @samp{gmane.emacs.muse.announce}.
2687 @item muse-el-discuss
2688 Discussion, bugfixes, suggestions, tips, and the like for Muse.
2689 This mailing list also includes the content of muse-el-announce.
2691 You can join this mailing list (@email{muse-el-discuss@@gna.org})
2692 using the subscription form at
2693 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
2694 list is also available via Gmane with the identifier
2695 @samp{gmane.emacs.muse.general}.
2697 @item muse-el-commits
2698 Log messages for changes committed to Muse.
2700 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
2701 the subscription form at
2702 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
2703 is also available via Gmane with the identifier
2704 @samp{gmane.emacs.muse.cvs}.
2709 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2710 contributors are frequently around and willing to answer your
2711 questions. The @samp{#muse} channel is also available for
2712 Muse-specific help, and its current maintainer hangs out there.
2715 The maintainer of Emacs Muse, Michael Olson, may be contacted at
2716 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
2717 it is often better to use the muse-el-discuss mailing list.
2721 @node History, Contributors, Getting Help and Reporting Bugs, Top
2722 @comment node-name, next, previous, up
2723 @chapter History of This Document
2724 @cindex history, of Muse
2728 John Wiegley started Muse upon realizing that EmacsWiki had some serious
2729 limitations. Around February 2004, he started making "emacs-wiki version
2730 3.00 APLHA", which eventually became known as Muse.
2732 Most of those who frequent the emacs-wiki mailing list continued to use
2733 emacs-wiki, mainly because Planner hasn't been ported over to it.
2735 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2736 John Wiegley's request.
2739 Michael Olson overhauled this document and added many new sections in
2740 preparation for the first release of Muse (3.01).
2744 @node Contributors, GNU General Public License, History, Top
2745 @comment node-name, next, previous, up
2746 @chapter Contributors to This Documentation
2747 @cindex contributors
2749 The first draft of this document was taken from the emacs-wiki texinfo
2750 manual. Michael Olson adapted it for Muse and added most of its
2753 John Sullivan did a majority of the work on the emacs-wiki texinfo
2756 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2757 emacs-wiki texinfo manual.
2759 @node GNU General Public License, Concept Index, Contributors, Top
2760 @comment node-name, next, previous, up
2761 @appendix GNU GENERAL PUBLIC LICENSE
2762 @center Version 2, June 1991
2764 @cindex GNU General Public License
2766 @c This file is intended to be included in another file.
2769 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2770 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2772 Everyone is permitted to copy and distribute verbatim copies
2773 of this license document, but changing it is not allowed.
2776 @appendixsec Preamble
2778 The licenses for most software are designed to take away your
2779 freedom to share and change it. By contrast, the GNU General Public
2780 License is intended to guarantee your freedom to share and change free
2781 software---to make sure the software is free for all its users. This
2782 General Public License applies to most of the Free Software
2783 Foundation's software and to any other program whose authors commit to
2784 using it. (Some other Free Software Foundation software is covered by
2785 the GNU Library General Public License instead.) You can apply it to
2788 When we speak of free software, we are referring to freedom, not
2789 price. Our General Public Licenses are designed to make sure that you
2790 have the freedom to distribute copies of free software (and charge for
2791 this service if you wish), that you receive source code or can get it
2792 if you want it, that you can change the software or use pieces of it
2793 in new free programs; and that you know you can do these things.
2795 To protect your rights, we need to make restrictions that forbid
2796 anyone to deny you these rights or to ask you to surrender the rights.
2797 These restrictions translate to certain responsibilities for you if you
2798 distribute copies of the software, or if you modify it.
2800 For example, if you distribute copies of such a program, whether
2801 gratis or for a fee, you must give the recipients all the rights that
2802 you have. You must make sure that they, too, receive or can get the
2803 source code. And you must show them these terms so they know their
2806 We protect your rights with two steps: (1) copyright the software, and
2807 (2) offer you this license which gives you legal permission to copy,
2808 distribute and/or modify the software.
2810 Also, for each author's protection and ours, we want to make certain
2811 that everyone understands that there is no warranty for this free
2812 software. If the software is modified by someone else and passed on, we
2813 want its recipients to know that what they have is not the original, so
2814 that any problems introduced by others will not reflect on the original
2815 authors' reputations.
2817 Finally, any free program is threatened constantly by software
2818 patents. We wish to avoid the danger that redistributors of a free
2819 program will individually obtain patent licenses, in effect making the
2820 program proprietary. To prevent this, we have made it clear that any
2821 patent must be licensed for everyone's free use or not licensed at all.
2823 The precise terms and conditions for copying, distribution and
2824 modification follow.
2827 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2830 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2835 This License applies to any program or other work which contains
2836 a notice placed by the copyright holder saying it may be distributed
2837 under the terms of this General Public License. The ``Program'', below,
2838 refers to any such program or work, and a ``work based on the Program''
2839 means either the Program or any derivative work under copyright law:
2840 that is to say, a work containing the Program or a portion of it,
2841 either verbatim or with modifications and/or translated into another
2842 language. (Hereinafter, translation is included without limitation in
2843 the term ``modification''.) Each licensee is addressed as ``you''.
2845 Activities other than copying, distribution and modification are not
2846 covered by this License; they are outside its scope. The act of
2847 running the Program is not restricted, and the output from the Program
2848 is covered only if its contents constitute a work based on the
2849 Program (independent of having been made by running the Program).
2850 Whether that is true depends on what the Program does.
2853 You may copy and distribute verbatim copies of the Program's
2854 source code as you receive it, in any medium, provided that you
2855 conspicuously and appropriately publish on each copy an appropriate
2856 copyright notice and disclaimer of warranty; keep intact all the
2857 notices that refer to this License and to the absence of any warranty;
2858 and give any other recipients of the Program a copy of this License
2859 along with the Program.
2861 You may charge a fee for the physical act of transferring a copy, and
2862 you may at your option offer warranty protection in exchange for a fee.
2865 You may modify your copy or copies of the Program or any portion
2866 of it, thus forming a work based on the Program, and copy and
2867 distribute such modifications or work under the terms of Section 1
2868 above, provided that you also meet all of these conditions:
2872 You must cause the modified files to carry prominent notices
2873 stating that you changed the files and the date of any change.
2876 You must cause any work that you distribute or publish, that in
2877 whole or in part contains or is derived from the Program or any
2878 part thereof, to be licensed as a whole at no charge to all third
2879 parties under the terms of this License.
2882 If the modified program normally reads commands interactively
2883 when run, you must cause it, when started running for such
2884 interactive use in the most ordinary way, to print or display an
2885 announcement including an appropriate copyright notice and a
2886 notice that there is no warranty (or else, saying that you provide
2887 a warranty) and that users may redistribute the program under
2888 these conditions, and telling the user how to view a copy of this
2889 License. (Exception: if the Program itself is interactive but
2890 does not normally print such an announcement, your work based on
2891 the Program is not required to print an announcement.)
2894 These requirements apply to the modified work as a whole. If
2895 identifiable sections of that work are not derived from the Program,
2896 and can be reasonably considered independent and separate works in
2897 themselves, then this License, and its terms, do not apply to those
2898 sections when you distribute them as separate works. But when you
2899 distribute the same sections as part of a whole which is a work based
2900 on the Program, the distribution of the whole must be on the terms of
2901 this License, whose permissions for other licensees extend to the
2902 entire whole, and thus to each and every part regardless of who wrote it.
2904 Thus, it is not the intent of this section to claim rights or contest
2905 your rights to work written entirely by you; rather, the intent is to
2906 exercise the right to control the distribution of derivative or
2907 collective works based on the Program.
2909 In addition, mere aggregation of another work not based on the Program
2910 with the Program (or with a work based on the Program) on a volume of
2911 a storage or distribution medium does not bring the other work under
2912 the scope of this License.
2915 You may copy and distribute the Program (or a work based on it,
2916 under Section 2) in object code or executable form under the terms of
2917 Sections 1 and 2 above provided that you also do one of the following:
2921 Accompany it with the complete corresponding machine-readable
2922 source code, which must be distributed under the terms of Sections
2923 1 and 2 above on a medium customarily used for software interchange; or,
2926 Accompany it with a written offer, valid for at least three
2927 years, to give any third party, for a charge no more than your
2928 cost of physically performing source distribution, a complete
2929 machine-readable copy of the corresponding source code, to be
2930 distributed under the terms of Sections 1 and 2 above on a medium
2931 customarily used for software interchange; or,
2934 Accompany it with the information you received as to the offer
2935 to distribute corresponding source code. (This alternative is
2936 allowed only for noncommercial distribution and only if you
2937 received the program in object code or executable form with such
2938 an offer, in accord with Subsection b above.)
2941 The source code for a work means the preferred form of the work for
2942 making modifications to it. For an executable work, complete source
2943 code means all the source code for all modules it contains, plus any
2944 associated interface definition files, plus the scripts used to
2945 control compilation and installation of the executable. However, as a
2946 special exception, the source code distributed need not include
2947 anything that is normally distributed (in either source or binary
2948 form) with the major components (compiler, kernel, and so on) of the
2949 operating system on which the executable runs, unless that component
2950 itself accompanies the executable.
2952 If distribution of executable or object code is made by offering
2953 access to copy from a designated place, then offering equivalent
2954 access to copy the source code from the same place counts as
2955 distribution of the source code, even though third parties are not
2956 compelled to copy the source along with the object code.
2959 You may not copy, modify, sublicense, or distribute the Program
2960 except as expressly provided under this License. Any attempt
2961 otherwise to copy, modify, sublicense or distribute the Program is
2962 void, and will automatically terminate your rights under this License.
2963 However, parties who have received copies, or rights, from you under
2964 this License will not have their licenses terminated so long as such
2965 parties remain in full compliance.
2968 You are not required to accept this License, since you have not
2969 signed it. However, nothing else grants you permission to modify or
2970 distribute the Program or its derivative works. These actions are
2971 prohibited by law if you do not accept this License. Therefore, by
2972 modifying or distributing the Program (or any work based on the
2973 Program), you indicate your acceptance of this License to do so, and
2974 all its terms and conditions for copying, distributing or modifying
2975 the Program or works based on it.
2978 Each time you redistribute the Program (or any work based on the
2979 Program), the recipient automatically receives a license from the
2980 original licensor to copy, distribute or modify the Program subject to
2981 these terms and conditions. You may not impose any further
2982 restrictions on the recipients' exercise of the rights granted herein.
2983 You are not responsible for enforcing compliance by third parties to
2987 If, as a consequence of a court judgment or allegation of patent
2988 infringement or for any other reason (not limited to patent issues),
2989 conditions are imposed on you (whether by court order, agreement or
2990 otherwise) that contradict the conditions of this License, they do not
2991 excuse you from the conditions of this License. If you cannot
2992 distribute so as to satisfy simultaneously your obligations under this
2993 License and any other pertinent obligations, then as a consequence you
2994 may not distribute the Program at all. For example, if a patent
2995 license would not permit royalty-free redistribution of the Program by
2996 all those who receive copies directly or indirectly through you, then
2997 the only way you could satisfy both it and this License would be to
2998 refrain entirely from distribution of the Program.
3000 If any portion of this section is held invalid or unenforceable under
3001 any particular circumstance, the balance of the section is intended to
3002 apply and the section as a whole is intended to apply in other
3005 It is not the purpose of this section to induce you to infringe any
3006 patents or other property right claims or to contest validity of any
3007 such claims; this section has the sole purpose of protecting the
3008 integrity of the free software distribution system, which is
3009 implemented by public license practices. Many people have made
3010 generous contributions to the wide range of software distributed
3011 through that system in reliance on consistent application of that
3012 system; it is up to the author/donor to decide if he or she is willing
3013 to distribute software through any other system and a licensee cannot
3016 This section is intended to make thoroughly clear what is believed to
3017 be a consequence of the rest of this License.
3020 If the distribution and/or use of the Program is restricted in
3021 certain countries either by patents or by copyrighted interfaces, the
3022 original copyright holder who places the Program under this License
3023 may add an explicit geographical distribution limitation excluding
3024 those countries, so that distribution is permitted only in or among
3025 countries not thus excluded. In such case, this License incorporates
3026 the limitation as if written in the body of this License.
3029 The Free Software Foundation may publish revised and/or new versions
3030 of the General Public License from time to time. Such new versions will
3031 be similar in spirit to the present version, but may differ in detail to
3032 address new problems or concerns.
3034 Each version is given a distinguishing version number. If the Program
3035 specifies a version number of this License which applies to it and ``any
3036 later version'', you have the option of following the terms and conditions
3037 either of that version or of any later version published by the Free
3038 Software Foundation. If the Program does not specify a version number of
3039 this License, you may choose any version ever published by the Free Software
3043 If you wish to incorporate parts of the Program into other free
3044 programs whose distribution conditions are different, write to the author
3045 to ask for permission. For software which is copyrighted by the Free
3046 Software Foundation, write to the Free Software Foundation; we sometimes
3047 make exceptions for this. Our decision will be guided by the two goals
3048 of preserving the free status of all derivatives of our free software and
3049 of promoting the sharing and reuse of software generally.
3052 @heading NO WARRANTY
3059 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
3060 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
3061 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
3062 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
3063 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
3064 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
3065 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
3066 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
3067 REPAIR OR CORRECTION.
3070 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
3071 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
3072 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
3073 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
3074 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
3075 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
3076 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
3077 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
3078 POSSIBILITY OF SUCH DAMAGES.
3082 @heading END OF TERMS AND CONDITIONS
3085 @center END OF TERMS AND CONDITIONS
3089 @appendixsec Appendix: How to Apply These Terms to Your New Programs
3091 If you develop a new program, and you want it to be of the greatest
3092 possible use to the public, the best way to achieve this is to make it
3093 free software which everyone can redistribute and change under these terms.
3095 To do so, attach the following notices to the program. It is safest
3096 to attach them to the start of each source file to most effectively
3097 convey the exclusion of warranty; and each file should have at least
3098 the ``copyright'' line and a pointer to where the full notice is found.
3101 @var{one line to give the program's name and a brief idea of what it does.}
3102 Copyright (C) @var{yyyy} @var{name of author}
3104 This program is free software; you can redistribute it and/or modify
3105 it under the terms of the GNU General Public License as published by
3106 the Free Software Foundation; either version 2 of the License, or
3107 (at your option) any later version.
3109 This program is distributed in the hope that it will be useful,
3110 but WITHOUT ANY WARRANTY; without even the implied warranty of
3111 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3112 GNU General Public License for more details.
3114 You should have received a copy of the GNU General Public License along
3115 with this program; if not, write to the Free Software Foundation, Inc.,
3116 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
3119 Also add information on how to contact you by electronic and paper mail.
3121 If the program is interactive, make it output a short notice like this
3122 when it starts in an interactive mode:
3125 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
3126 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
3127 This is free software, and you are welcome to redistribute it
3128 under certain conditions; type `show c' for details.
3131 The hypothetical commands @samp{show w} and @samp{show c} should show
3132 the appropriate parts of the General Public License. Of course, the
3133 commands you use may be called something other than @samp{show w} and
3134 @samp{show c}; they could even be mouse-clicks or menu items---whatever
3137 You should also get your employer (if you work as a programmer) or your
3138 school, if any, to sign a ``copyright disclaimer'' for the program, if
3139 necessary. Here is a sample; alter the names:
3142 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
3143 `Gnomovision' (which makes passes at compilers) written by James Hacker.
3145 @var{signature of Ty Coon}, 1 April 1989
3146 Ty Coon, President of Vice
3149 This General Public License does not permit incorporating your program into
3150 proprietary programs. If your program is a subroutine library, you may
3151 consider it more useful to permit linking proprietary applications with the
3152 library. If this is what you want to do, use the GNU Library General
3153 Public License instead of this License.
3156 @node Concept Index, , GNU General Public License, Top
3157 @comment node-name, next, previous, up