1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.03.
17 Copyright @copyright{} 2004, 2005, 2006,
18 2007 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU
25 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
26 license is included in the section entitled ``GNU Free Documentation
27 License'' in this manual.
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software. Copies published by the Free
31 Software Foundation raise funds for GNU development.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License. If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
38 All Emacs Lisp code contained in this document may be used, distributed,
39 and modified without restriction.
45 @subtitle an authoring and publishing environment
46 @subtitle for GNU Emacs and XEmacs
48 @c The following two commands
49 @c start the copyright page.
51 @vskip 0pt plus 1filll
55 @c So the toc is printed at the start
59 @node Top, Preface, (dir), (dir)
60 @comment node-name, next, previous, up
67 * Preface:: About the documentation.
68 * Introduction:: What is Muse?
69 * Obtaining Muse:: How to get Muse releases and development
71 * Installation:: Compiling and installing Muse.
72 * Getting Started:: Setting up Muse and editing files.
73 * Projects:: Creating and managing Muse projects.
74 * Keystroke Summary:: Keys used in Muse mode.
75 * Markup Rules:: Rules for using markup.
76 * Publishing Styles:: Publishing various types of documents.
77 * Extending Muse:: Making your own publishing styles.
78 * Getting Help and Reporting Bugs::
79 * History:: History of this document.
80 * Contributors:: Contributors to this documentation.
81 * GNU Free Documentation License:: The license for this documentation.
82 * Concept Index:: Search for terms.
85 --- The Detailed Node Listing ---
87 How to Get Muse Releases and Development Changes
89 * Releases:: Released versions of Muse.
90 * Development:: Latest unreleased development changes.
94 * Loading Muse:: How to load Muse.
95 * Using Muse Mode:: How to edit files in Muse.
96 * Publishing Files Overview:: Publishing a single file or project.
97 * File Extensions:: Using a different file extension.
99 Creating and Managing Muse Projects
101 * Single Project:: A single-project example.
102 * Multiple Projects:: A multiple-project example.
103 * Projects and Subdirectories:: Publishing subdirectories in projects.
104 * Options for Projects:: Listing of available options for projects.
106 Rules for Using Markup
108 * Paragraphs:: Paragraphs: centering and quoting.
109 * Headings:: Levels of headings.
110 * Directives:: Directives at the beginning of a
112 * Emphasizing Text:: Bold, italicized, and underlined text.
113 * Footnotes:: Making notes to be shown at the end.
114 * Verse:: Indicating poetic stanzas.
115 * Lists:: Lists of items.
116 * Tables:: Generation of data tables.
117 * Explicit Links:: Hyperlinks and email addresses with
119 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
121 * Images:: Publishing and displaying images.
122 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
123 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
125 * Comments:: Lines to omit from published output.
126 * Tag Summary:: Tags that Muse recognizes.
128 Publishing Various Types of Documents
130 * Blosxom:: Integrating Muse and pyblosxom.cgi.
131 * Book:: Publishing entries into a compilation.
132 * ConTeXt:: Publishing ConTeXt documents.
133 * DocBook:: Publishing in DocBook XML form.
134 * HTML:: Publishing in HTML or XHTML form.
135 * Journal:: Keeping a journal or blog.
136 * LaTeX:: Publishing LaTeX documents.
137 * Poem:: Publish a poem to LaTex or PDF.
138 * Texinfo:: Publish entries to Texinfo format or PDF.
139 * XML:: Publish entries to XML.
141 Integrating Muse and pyblosxom.cgi
143 * Blosxom Requirements:: Other tools needed for the Blosxom style.
144 * Blosxom Entries:: Format of a Blosxom entry and automation.
145 * Blosxom Options:: Blosxom styles and options provided.
147 Making your own publishing styles
149 * Common Elements:: Common functionality shared by styles.
150 * Deriving Styles:: Deriving a new style from an existing
153 Common functionality shared by styles
155 * Markup Functions:: Specifying functions to mark up text.
156 * Markup Regexps:: Markup rules for publishing.
157 * Markup Strings:: Strings specific to a publishing style.
158 * Markup Tags:: Tag specifications for special markup.
159 * Style Elements:: Parameters used for defining styles.
164 @node Preface, Introduction, Top, Top
165 @comment node-name, next, previous, up
166 @chapter About the documentation
168 This document describes Muse, which was written by John Wiegley and is
169 now maintained by Michael Olson. Several versions of this manual are
173 @item PDF: http://mwolson.org/static/doc/muse.pdf
174 @item HTML (single file): http://mwolson.org/static/doc/muse.html
175 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
178 @node Introduction, Obtaining Muse, Preface, Top
179 @comment node-name, next, previous, up
180 @chapter What is Muse?
182 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
183 and publishing environment for Emacs. It simplifies the process of
184 writing documents and publishing them to various output formats.
186 Muse consists of two main parts: an enhanced text-mode for authoring
187 documents and navigating within Muse projects, and a set of publishing
188 styles for generating different kinds of output.
190 What makes Muse distinct from other text-publishing systems is a modular
191 environment, with a rather simple core, in which "styles" are derived
192 from to create new styles. Much of Muse's overall functionality is
193 optional. For example, you can use the publisher without the
194 major-mode, or the mode without doing any publishing; or if you don't
195 load the Texinfo or LaTeX modules, those styles won't be available.
197 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
198 code has been restructured and rewritten, especially its publishing
199 functions. The focus in this revision is on the authoring and
200 publishing aspects, and the "wikiness" has been removed as a default
201 behavior (available in the optional @file{muse-wiki} module). CamelCase
202 words are no longer special by default.
204 One of the principal aims in the development of Muse is to make it very
205 easy to produce good-looking, standards-compliant documents.
207 @node Obtaining Muse, Installation, Introduction, Top
208 @comment node-name, next, previous, up
209 @chapter How to Get Muse Releases and Development Changes
212 * Releases:: Released versions of Muse.
213 * Development:: Latest unreleased development changes.
216 @node Releases, Development, Obtaining Muse, Obtaining Muse
217 @comment node-name, next, previous, up
218 @section Released versions of Muse
220 Choose to install a release if you want to minimize risk.
222 Errors are corrected in development first. User-visible changes will be
223 announced on the @email{muse-el-discuss@@gna.org} mailing list.
224 @xref{Getting Help and Reporting Bugs}.
226 @cindex releases, Debian package
227 @cindex Debian package for Muse
228 Debian users can get Muse via apt-get. The @file{muse-el} package is
229 available both at Michael Olson's APT repository and the official Debian
230 repository. To make use of the former, add the following line to your
231 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
234 deb http://mwolson.org/debian/ ./
237 @cindex releases, Ubuntu package
238 @cindex Ubuntu package for Muse
239 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
240 is available both at Michael Olson's APT repository and the official
241 Ubuntu repository. To make use of the former, add the following line to
242 your @file{/etc/apt/sources.list} file and run @code{apt-get install
246 deb http://mwolson.org/ubuntu/ ./
249 The reason for making separate Debian and Ubuntu packages is that this
250 manual is under the GFDL, and Debian will not allow it to be distributed
251 in its main repository. Ubuntu, on the other hand, permits this manual
252 to be included with the @file{muse-el} package.
254 @cindex releases, from source
255 Alternatively, you can download the latest release from
256 @uref{http://download.gna.org/muse-el/} .
258 @node Development, , Releases, Obtaining Muse
259 @comment node-name, next, previous, up
260 @section Latest unreleased development changes
263 Choose the development version if you want to live on the bleeding edge
264 of Muse development or try out new features before release.
266 @cindex git version control system, using
267 The git version control system allows you to keep up-to-date with the
268 latest changes to the development version of Muse. It also allows you
269 to contribute changes (via commits, if you are have developer access to
270 the repository, or via patches, otherwise). If you would like to
271 contribute to Muse development, it is highly recommended that you use
274 If you are new to git, you might find this tutorial helpful:
275 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
277 Downloading the Muse module with git and staying up-to-date involves
284 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
285 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
286 @item Other operating systems: download, compile, and install the source
287 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
288 package for your operating system.
291 @item Download the Muse development branch.
293 If you have developer access to Muse, do:
296 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
302 git clone git://repo.or.cz/muse-el.git muse
305 If you are behind a restrictive firewall, and do not have developer
306 access, then do the following instead:
309 git clone http://repo.or.cz/r/muse-el.git muse
312 @item List upstream changes that are missing from your local copy.
313 Do this whenever you want to see whether new changes have been committed
314 to Muse. If you wish, you may skip this step and proceed directly to
318 # Change to the source directory you are interested in.
321 # Fetch new changes from the repository, but don't apply them yet
324 # Display log messages for the new changes
328 ``origin'' is git's name for the location where you originally got Muse
329 from. You can change this location at any time by editing the
330 @file{.git/config} file in the directory where the Muse source was
333 @cindex updating Muse with git
334 @item Update to the latest version by pulling in any missing changes.
341 git will show how many files changed, and will provide a visual display
342 for how many lines were changed in each file.
346 There are other ways to interact with the Muse repository.
349 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
350 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
351 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
354 The latest development snapshot can lag behind the git repo by as much
355 as 20 minutes, but never more than that.
357 @subheading Becoming a Muse developer
358 @cindex developer, becoming
360 If you want commit access to the shared Muse repository, then register
361 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
362 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
363 best to send some patches to the @email{muse-el-discuss@@gna.org}
364 mailing list first, so that he knows that you know what you are doing.
365 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
368 You must also be willing to sign a copyright assignment for your changes
369 to Muse, since Muse is a GNU project. The current maintainer will
370 assist you in this process if you contact him.
372 @node Installation, Getting Started, Obtaining Muse, Top
373 @comment node-name, next, previous, up
374 @chapter Compiling and Installing Muse
376 Muse may be compiled and installed on your machine.
378 @subheading Compilation
379 @cindex compiling Muse
381 This is an optional step, since Emacs Lisp source code does not
382 necessarily have to be byte-compiled. Byte-compilation may yield a very
383 slight speed increase.
385 A working copy of Emacs or XEmacs is needed in order to compile Emacs
386 Muse. By default, the program that is installed with the name
387 @command{emacs} will be used.
389 If you want to use the @command{xemacs} binary to perform the
390 compilation, you must copy @file{Makefile.defs.default} to
391 @file{Makefile.defs} in the top-level directory, and then edit
392 @file{Makefile.defs} as follows. You can put either a full path to an
393 Emacs or XEmacs binary or just the command name, as long as it is in the
394 @env{PATH}. Depending on your setup, changes to the @option{PREFIX},
395 @option{ELISPDIR}, and/or @option{INFODIR} variables may also need to be
400 SITEFLAG = -no-site-file
401 # Edit the section as necessary
402 install_info = install-info --section "XEmacs 21.4" $(1).info \
406 Running @code{make} in the top-level directory should compile the Muse
407 source files in the @file{lisp} directory, and generate an autoloads
408 file in @file{lisp/muse-autoloads.el}.
410 @subheading Installation
411 @cindex installing Muse
413 Muse may be installed into your file hierarchy by doing the following.
415 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
416 top-level directory, if you haven't done so already. Then edit the
417 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
418 want the source and compiled Muse files to be installed and
419 @env{INFODIR} indicates where to put the Muse manual. As mentioned
420 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
421 in the Compilation section if you are using XEmacs.
423 If you are installing Muse on a Debian or Ubuntu system, you might want
424 to change the value of @env{INSTALLINFO} as specified in
425 @file{Makefile.defs}.
427 If you wish to install Muse to different locations than the defaults
428 specify, edit @file{Makefile.defs} accordingly.
430 Run @code{make} as a normal user, if you haven't done so already.
432 Run @code{make install} as the root user if you have chosen installation
433 locations that require root permissions.
436 @cindex ELPA package for Muse
438 For those used to installing software packages, there will be a
439 @code{muse} package available in the Emacs Lisp Package Archive
440 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
441 will be compiled and installed automatically in a user-specific
442 location. For more information on ELPA, see
443 @uref{http://tromey.com/elpa/}.
445 @node Getting Started, Projects, Installation, Top
446 @comment node-name, next, previous, up
447 @chapter Getting Started
451 * Loading Muse:: How to load Muse.
452 * Using Muse Mode:: How to edit files in Muse.
453 * Publishing Files Overview:: Publishing a single file or project.
454 * File Extensions:: Using a different file extension.
457 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
458 @comment node-name, next, previous, up
459 @section How to Load Muse
460 @cindex settings, init file
462 To use Muse, add the directory containing its files to your
463 @code{load-path} variable, in your @file{.emacs} file. Then, load in
464 the authoring mode, and the styles you wish to publish to. An example
468 (add-to-list 'load-path "<path to Muse>")
470 (require 'muse-mode) ; load authoring mode
472 (require 'muse-html) ; load publishing styles I use
473 (require 'muse-latex)
474 (require 'muse-texinfo)
475 (require 'muse-docbook)
477 (require 'muse-project) ; publish files in projects
480 An easy way of seeing which settings are available and changing settings
481 is to use the Muse customization interface. To do this, type
482 @kbd{M-x customize-group muse RET}. Each of the options has its own
483 documentation. Options are grouped logically according to what effect
486 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
487 @comment node-name, next, previous, up
488 @section How to Edit Files in Muse
489 @cindex editing Muse files
491 Muse Mode should automatically be activated when you visit a file with a
492 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
493 available in the @file{examples} directory of the Muse distribution.
494 You can tell that Muse Mose has been activated by checking for the text
495 ``Muse'' in your mode line. If Muse Mode has not been activated, you
496 may activate it by type @kbd{M-x muse-mode RET}.
498 You will notice that Muse files are highlighted very simply. Links are
499 colored blue, headings are large and bold text, and @verb{|<example>|}
500 tags are colored in grey.
502 There are several different ways to edit things like links, which hide
503 the underlying Muse markup. One way is to toggle font-locking off by
504 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
505 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
506 on. Another way is just to move into the text and edit it. Markup can
507 also be removed by normal deletion methods, though some side effects
508 might require a second deletion.
510 For the particular case of editing links, it is easiest to move to the
511 link and do @kbd{C-c C-e}, which is also @kbd{M-x
512 muse-edit-link-at-point}. This prompts you for the link and its
513 description, using the previous contents of the link as initial values.
514 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
515 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
516 followed by hitting @kbd{RET} on them.
518 If you want to add a new list item, this may by accomplished by hitting
519 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
520 dash is the Muse markup that indicates a list item. It is also possible
521 to created ``nested'' lists with this command, by adjusting the number
522 of spaces in front of the dashes. If you have lists with long lines,
523 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
526 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
527 @comment node-name, next, previous, up
528 @section Publishing a Single File or Project
529 @cindex editing Muse files
531 The command @kbd{M-x muse-project-publish-this-file} will publish the
532 current document to any available publishing style (a publishing style
533 is an output format, like HTML or Docbook), placing the output in the
534 current directory. If you are in Muse Mode, this command will be bound
535 to @kbd{C-c C-t}. If the file has been published recently, and its
536 contents have not changed, running @kbd{C-c C-t} again will not publish
537 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
539 If you have set up projects and are visiting a file that is part of a
540 project, then @kbd{C-c C-t} will restrict the output formats to those
541 which are used by the project, and will automatically publish to the
542 output directory defined by the project. If you want to publish to a
543 different directory or use a different format, then use @kbd{C-c M-C-t},
544 which is also @kbd{M-x muse-publish-this-file}.
546 If the currently opened file is part of a defined project in
547 @code{muse-project-alist}, it (and the rest of the changed files in a
548 project) may be published using @kbd{C-c C-p}.
550 @node File Extensions, , Publishing Files Overview, Getting Started
551 @comment node-name, next, previous, up
552 @section Using a Different File Extension
553 @cindex file extension, specifying
555 By default, Muse expects all project files to have the file extension
556 @file{.muse}. Files without this extension will not be associated with
557 Muse mode and will not be considered part of any project, even if they
558 are within a project directory.
560 If you don't want to use @file{.muse}, you can customize the extension
561 by setting the value of @code{muse-file-extension}.
563 If you don't want to use any extension at all, and want Muse to
564 autodetect project files based on their location, then add the following
565 to your Muse settings file.
568 (setq muse-file-extension nil
572 Note that if you chose to have @code{muse-file-extension} set to
573 @code{nil}, you may have trouble if your @file{.emacs} file or other
574 init scripts attempt to visit a Muse file. (A very common example of
575 this is if you use Planner with Muse and run @code{(plan)} from your
576 @file{.emacs}.) If you wish to visit Muse files from your
577 @file{.emacs}, be sure to also add the following additional code before
578 any such visits happen:
581 (add-hook 'find-file-hooks 'muse-mode-maybe)
585 @node Projects, Keystroke Summary, Getting Started, Top
586 @comment node-name, next, previous, up
587 @chapter Creating and Managing Muse Projects
590 Often you will want to publish all the files within a directory to a
591 particular set of output styles automatically. To support, Muse
592 allows for the creation of "projects".
595 * Single Project:: A single-project example.
596 * Multiple Projects:: A multiple-project example.
597 * Projects and Subdirectories:: Publishing subdirectories in projects.
598 * Options for Projects:: Listing of available options for projects.
601 @node Single Project, Multiple Projects, Projects, Projects
602 @comment node-name, next, previous, up
603 @section A Single-Project Example
604 @cindex projects, single
606 Here is a sample project, which may be defined in your @file{.emacs}
610 (setq muse-project-alist
611 '(("Website" ("~/Pages" :default "index")
612 (:base "html" :path "~/public_html")
613 (:base "pdf" :path "~/public_html/pdf"))))
616 The above defines a project named "website", whose files are located
617 in the directory @file{~/Pages}. The default page to visit is
618 @file{index}. When this project is published, each page will be
619 output as HTML to the directory @file{~/public_html}, and as PDF to
620 the directory @file{~/public_html/pdf}. Within any project page, you
621 may create a link to other pages using the syntax @samp{[[pagename]]}.
623 If you would like to include only some files from a directory in a Muse
624 project, you may use a regexp in place of @file{~/Pages} in the example.
626 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
627 @comment node-name, next, previous, up
628 @section A Multiple-Project Example
629 @cindex projects, multiple
631 It is possible to specify multiple projects. Here is an example of
632 three projects: a generic website, a projects area, and a day-planner
633 (the day-planner part requires Planner Mode---see
634 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
637 (setq muse-project-alist
638 '(("Website" ("~/Pages" :default "index")
639 (:base "html" :path "~/public_html"))
640 (("Projects" ("~/Projects" :default "index")
642 :path "~/public_html/projects"
643 :exclude "/TopSecret")
645 :path "~/public_html/projects/pdf"
646 :exclude "/TopSecret")))
649 :major-mode planner-mode
650 :visit-link planner-visit-link)
651 (:base "planner-xhtml"
652 :path "~/public_html/plans"))))
655 The @option{:major-mode} attribute specifies which major to use when
656 visiting files in this directory.
658 The @option{:visit-link} attribute specifies the function to call when
661 The @option{:exclude} attribute has a regexp that matches files to never
664 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
665 @comment node-name, next, previous, up
666 @section Publishing Subdirectories in Projects
667 @cindex projects, subdirectories
669 If you want to publish a directory and all of its subdirectories, Muse
670 provides two convenience functions that together generate the proper
671 rules for you. Note that we use the backtick to begin this
672 muse-project-alist definition, rather than a single quote.
675 (setq muse-project-alist
676 `(("Website" ("~/Pages" :default "index")
677 (:base "html" :path "~/public_html"))
678 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
680 ;; Publish this directory and its subdirectories. Arguments
681 ;; are as follows. The above `muse-project-alist-dirs' part
683 ;; 1. Source directory
684 ;; 2. Output directory
685 ;; 3. Publishing style
686 ;; remainder: Other things to put in every generated style
687 ,@@(muse-project-alist-styles "~/Blog"
692 The @code{muse-project-alist-dirs} function takes a directory and
693 returns it and all of its subdirectories in a list.
695 The @code{muse-project-alist-styles} function is explained by the
698 The ``blosxom'' text is the name of another publishing style, much like
699 ``html''. @xref{Blosxom}, for further information about it. You can
700 use any publishing style you like for the third argument to
701 @code{muse-project-alist-styles}.
703 @node Options for Projects, , Projects and Subdirectories, Projects
704 @comment node-name, next, previous, up
705 @section Listing of Available Options for Projects
706 @cindex projects, options
707 @cindex muse-project-alist, reference
709 This is a listing of all of the various options (or, more accurately:
710 attributes) that may be specified in @code{muse-project-alist}.
712 Each muse-project-alist entry looks like this:
715 (PROJECT-NAME (SOURCES)
719 We refer to these names below.
721 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
722 The first value is a keyword, like @option{:default}. The second part
723 is the value associated with that keyword, such as the text ``index''.
724 If you are familiar with Emacs Lisp property lists, the concept is
725 similar to that, except that in the SOURCES section, single directories
726 can be interspersed with two-value attributes.
728 @subheading Project Name
730 This is a string that indicates the name of the project. It is
731 primarily used for publishing interwiki links with the
732 @file{muse-wiki.el} module.
736 This part of a muse-project-alist entry consists of two-value
737 attributes, and also directory names. If you are publishing a book, the
738 order of directories and attributes is significant.
740 The minimal content for the sources section is a list of directories.
745 Indicates a new chapter of a book. The text of the title of the chapter
746 comes immediately after this keyword.
749 Indicates the end of a book. Directories listed after this one are
750 ignored when publishing a book. The value ``t'' (without quotes) should
751 come immediately after this keyword.
754 A function to call while publishing a book. This is useful for doing
755 something just after a particular chapter.
758 Indicates the beginning of a new part of the book. The text of the
759 title should come immediately after this keyword.
762 Indicate a particular publishing style to use for this part of the book.
763 If this is specified, it should come just after a @option{:part}
767 The default page to visit when browsing a project. Also, if you are
768 using the @file{muse-wiki.el} module, publishing a link to just a
769 project's name will cause it to link to this default file.
772 This specifies a list of pages which should be published every time a
773 project is published (by using @kbd{C-c C-p}, for example), regardless
774 of whether their contents have changed. This is useful for updating
775 Index pages, pages that use the @verb{|<include>|} tag, and other pages
776 that have dynamically-generated content.
779 This specifies the major mode to use when visiting files in this
780 project. The default is @code{muse-mode}.
783 This indicates that while publishing a book, do not automatically create
784 chapters. Values which may follow this are nil (the default, which
785 means that we automatically create chapters), or non-nil, which means
786 that we manually specify chapters with the @option{:book-chapter}
789 @item :publish-project
790 Indicates which function we should call when publishing a project.
793 This specifies a list of variables and values to set when publishing a
794 project. The list should be a property list, which is in the form:
797 (VAR1 VALUE1 VAR2 VALUE2 ...)
801 Specifies the function to call when visiting a link. The default is
802 @code{muse-visit-link-default}. The arguments for that function should
803 be (1) the link and (2) whether to visit the link in a new window.
809 This part of a muse-project-alist entry is composed of lists of
810 attributes. Each list is called an ``output style''.
812 The minimal content for an output style is a @option{:base} attribute
813 and a @option{:path} attribute.
818 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
821 An external URL which can be used to access published files. This is
822 mainly used by the @file{muse-wiki} module when publishing links between
823 two separate projects, if the projects are served on different domains.
825 It is also used by the @file{muse-journal} module to create the RSS or
829 Exclude items matching a regexp from being published. The regexp should
830 usually begin with "/".
833 Only include items matching a regexp when publishing. The regexp should
834 usually begin with "/".
837 The directory in which to store published files.
840 A file containing the timestamps (that is, time of creation) for files
841 in this project. It might eventually used by the @file{muse-blosxom}
842 module, but this option is not currently in use by any Muse code.
847 @node Keystroke Summary, Markup Rules, Projects, Top
848 @comment node-name, next, previous, up
849 @chapter Keys Used in Muse Mode
852 This is a summary of keystrokes available in every Muse buffer.
856 @item C-c C-a (`muse-index')
857 Display an index of all known Muse pages.
859 @item C-c C-b (`muse-find-backlinks')
860 Find all pages that link to this page.
862 @item C-c C-e (`muse-edit-link-at-point')
865 @item C-c C-f (`muse-project-find-file')
866 Open another Muse page. Prompt for the name.
868 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
869 Insert a link to a file interactively.
871 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
872 Insert a tag interactively.
874 @item C-c C-i u, C-c TAB u (`muse-insert-url')
875 Insert a URL interactively.
877 @item C-c C-l (`font-lock-mode')
878 Toggle font lock / highlighting for the current buffer.
880 @item C-c C-p (`muse-project-publish')
881 Publish any Muse pages that have changed.
883 @item C-c C-s (`muse-search')
884 Find text in all files of the current project.
886 @item C-c C-t (`muse-project-publish-this-file')
887 Publish the currently-visited file. Prompt for the style if the current
888 file can be published using more than one style.
890 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
891 Publish the currently-visited file. Prompt for both the style and
894 @item C-c C-v (`muse-browse-result')
895 Show the published result of this page.
897 @item C-c = (`muse-what-changed')
898 Diff this page against the last backup version.
901 Move to the next Wiki reference.
904 Move to the previous Wiki reference.
907 Complete the name of a page from the current project at point.
910 Insert a new list item at point, indenting properly.
913 Decrease the indentation of the list item at point.
916 Increase the indentation of the list item at point.
918 @item M-x muse-colors-toggle-inline-images RET
919 Toggle display of inlined images on/off.
924 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
925 @comment node-name, next, previous, up
926 @chapter Rules for Using Markup
929 A Muse document uses special, contextual markup rules to determine how
930 to format the output result. For example, if a paragraph is indented,
931 Muse assumes it should be quoted.
933 There are not too many markup rules, and all of them strive to be as
934 simple as possible so that you can focus on document creation, rather
938 * Paragraphs:: Paragraphs: centering and quoting.
939 * Headings:: Levels of headings.
940 * Directives:: Directives at the beginning of a
942 * Emphasizing Text:: Bold, italicized, and underlined text.
943 * Footnotes:: Making notes to be shown at the end.
944 * Verse:: Indicating poetic stanzas.
945 * Lists:: Lists of items.
946 * Tables:: Generation of data tables.
947 * Explicit Links:: Hyperlinks and email addresses with
949 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
951 * Images:: Publishing and displaying images.
952 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
953 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
955 * Comments:: Lines to omit from published output.
956 * Tag Summary:: Tags that Muse recognizes.
959 @node Paragraphs, Headings, Markup Rules, Markup Rules
960 @comment node-name, next, previous, up
961 @section Paragraphs: centering and quoting
964 Paragraphs in Muse must be separated by a blank line.
966 @cindex paragraphs, centered
967 @subheading Centered paragraphs and quotations
969 A line that begins with six or more columns of whitespace (either tabs
970 or spaces) indicates a centered paragraph. Alternatively, you can use
971 the @verb{|<center>|} tag to surround regions that are to be published as
974 @cindex paragraphs, quoted
976 But if a line begins with whitespace, though less than six columns, it
977 indicates a quoted paragraph. Alternatively, you can use the
978 @verb{|<quote>|} tag to surround regions that are to be published as
982 @cindex monospace, rendering blocks
983 @cindex HTML, rendering blocks in monospace
984 @subheading Literal paragraphs
986 The @verb{|<example>|} tag is used for examples, where whitespace should
987 be preserved, the text rendered in monospace, and any characters special
988 to the output style escaped.
991 @cindex HTML, inserting a raw block
992 There is also the @verb{|<literal>|} tag, which causes a marked block to
993 be entirely left alone. This can be used for inserting a hand-coded
994 HTML blocks into HTML output, for example.
996 If you want some text to only be inserted when publishing to a
997 particular publishing style, use the @option{style} attribute for the
998 @verb{|<literal>|} tag. An example follows.
1001 <literal style="latex">
1002 A LaTeX-based style was used in the publishing of this document.
1006 This will leave the region alone if the current publishing style is
1007 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
1008 otherwise. It is also possible to leave the text alone only for one
1009 particular style, rather than its derivations, by adding
1010 @code{exact="t"} to the tag.
1012 @node Headings, Directives, Paragraphs, Markup Rules
1013 @comment node-name, next, previous, up
1014 @section Levels of headings
1017 A heading becomes a chapter or section in printed output -- depending on
1018 the style. To indicate a heading, start a new paragraph with one or
1019 more asterices, followed by a space and the heading title. Then begin
1020 another paragraph to enter the text for that section.
1022 All levels of headings will be published. Most publishing styles only
1023 distinguish the between the first 4 levels, however.
1035 @node Directives, Emphasizing Text, Headings, Markup Rules
1036 @comment node-name, next, previous, up
1037 @section Directives at the beginning of a document
1040 Directives are lines beginning with the @samp{#} character that come
1041 before any paragraphs or sections in the document. Directives are of
1042 the form ``#directive content of directive''. You can use any
1043 combination of uppercase and lowercase letters for directives, even if
1044 the directive is not in the list below.
1046 The @code{muse-publishing-directive} function may be used in header and
1047 footer text to access directives. For example, to access the
1048 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
1050 The following is a list of directives that Muse uses.
1055 The author of this document.
1057 If this is not specified, Muse will attempt to figure it out from the
1058 @code{user-full-name} variable.
1062 The date that the document was last modified.
1064 This is used by publishing styles that are able to embed the date
1069 A short description of this document.
1071 This is used by the @code{journal} publishing style to embed information
1072 inside of an RSS/RDF feed.
1076 The title of this document.
1078 If this is not specified, the name of the file is used.
1082 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1083 @comment node-name, next, previous, up
1084 @section Bold, italicized, and underlined text
1085 @cindex emphasizing text
1086 @cindex underlining text
1087 @cindex italicizing text
1088 @cindex verbatim text
1089 @cindex monospace, rendering words
1091 To emphasize text, surround it with certain specially recognized
1097 ***very strong emphasis***
1099 =verbatim and monospace=
1103 While editing a Muse document in Muse mode, these forms of emphasis will
1104 be highlighted in a WYSIWYG manner. Each of these forms may span
1107 Verbatim text will be colored as gray by default. To change this,
1108 customize @code{muse-verbatim-face}.
1110 You can also use the @verb{|<code>|} tag to indicate verbatim and
1111 monospace text. This is handy for regions that have an ``='' in them.
1113 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1114 @comment node-name, next, previous, up
1115 @section Making notes to be shown at the end
1118 A footnote reference is simply a number in square brackets. To define
1119 the footnote, place this definition at the bottom of your file.
1120 @samp{footnote-mode} can be used to greatly facilitate the creation of
1121 these kinds of footnotes.
1123 Footnotes are defined by the same number in brackets occurring at the
1124 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1125 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1126 the point of insertion.
1128 @node Verse, Lists, Footnotes, Markup Rules
1129 @comment node-name, next, previous, up
1130 @section Indicating poetic stanzas
1134 Poetry requires that whitespace be preserved, but without resorting to
1135 monospace. To indicate this, use the following markup, reminiscent of
1139 > A line of Emacs verse;
1140 > forgive its being so terse.
1143 You can also use the @verb{|<verse>|} tag, if you prefer.
1147 A line of Emacs verse;
1148 forgive its being so terse.
1152 @cindex verses, multiple stanzas
1153 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1158 A line of Emacs verse;
1159 forgive its being so terse.
1161 In terms of terse verse,
1166 @node Lists, Tables, Verse, Markup Rules
1167 @comment node-name, next, previous, up
1168 @section Lists of items
1171 Lists are given using special characters at the beginning of a line.
1172 Whitespace must occur before bullets or numbered items, to distinguish
1173 from the possibility of those characters occurring in a real sentence.
1175 @cindex lists, bullets
1176 These are rendered as a bullet list.
1185 @cindex lists, enumerated
1186 An enumerated list follows.
1195 @cindex lists, definitions
1196 Here is a definition list.
1200 This is a first definition
1201 And it has two lines;
1202 no, make that three.
1204 Term2 :: This is a second definition
1207 @subheading Nested lists
1209 @cindex lists, nested
1210 It is possible to nest lists of the same or different kinds. The
1211 ``level'' of the list is determined by the amount of initial whitespace.
1216 - Level 1, bullet item one
1217 1. Level 2, enum item one
1218 2. Level 2, enum item two
1219 - Level 1, bullet item two
1220 1. Level 2, enum item three
1221 2. Level 2, enum item four
1225 @subheading Breaking list items
1227 @cindex lists, breaking lines
1228 If you want to break up a line within any list type, just put one blank
1229 line between the end of the previous line and the beginning of the next
1230 line, using the same amount of initial indentation.
1233 - bullet item 1, line 1
1235 bullet item 1, line 2
1241 - bullet item 2, line 1
1243 bullet item 2, line 2
1246 @node Tables, Explicit Links, Lists, Markup Rules
1247 @comment node-name, next, previous, up
1248 @section Generation of data tables
1251 @cindex tables, simple
1252 Only very simple tables are supported. The syntax is as follows.
1255 Double bars || Separate header fields
1257 Single bars | Separate body fields
1258 Here are more | body fields
1260 Triple bars ||| Separate footer fields
1263 Some publishing styles require header fields to come first, then footer
1264 fields, and then the body fields. You can use any order for these
1265 sections that you like, and Muse will re-order them for you at
1268 If you wish to disable table generation for one Muse file, add the
1269 directive @samp{#disable-tables t} to the top of the file.
1271 @subheading Other table formats
1273 @cindex tables, orgtbl-mode style
1274 It is possible to publish very basic Orgtbl-mode style tables.
1277 | org | style | table |
1278 |------+-------+-------|
1282 |------+-------+-------|
1286 If you are used to the way that Org Mode publishes these tables, then
1287 customize `muse-html-table-attributes' to the following, in order to get
1288 a similar kind of output.
1291 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1294 @cindex tables, table.el style
1295 @file{table.el} style tables are also supported, as long as
1296 @file{table.el} itself supports outputting tables for a particular
1297 publishing style. At the time of this writing, the ``html'', ``latex'',
1298 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1299 from these styles will also work.
1311 @node Explicit Links, Implicit Links, Tables, Markup Rules
1312 @comment node-name, next, previous, up
1313 @section Hyperlinks and email addresses with descriptions
1314 @cindex links, explicit
1316 A hyperlink can reference a URL, or another page within a Muse
1317 project. In addition, descriptive text can be specified, which should
1318 be displayed rather than the link text in output styles that supports
1319 link descriptions. The syntax is as follows.
1322 [[link target][link description]]
1323 [[link target without description]]
1326 Thus, the current maintainer's homepage for Muse can be found
1327 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1328 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1330 @node Implicit Links, Images, Explicit Links, Markup Rules
1331 @comment node-name, next, previous, up
1332 @section Bare URLs, WikiNames, and InterWiki links
1333 @cindex links, implicit
1337 @cindex Email addresses
1339 A URL or email address encountered in the input text is published as a
1340 hyperlink. These kind of links are called @dfn{implicit links} because
1341 they are not separated from the rest of the Muse document in any way.
1343 Some characters in URLs will prevent Muse from recognizing them as
1344 implicit links. If you want to link to a URL containing spaces or any of
1345 the characters ``][,"'`()<>^'', you will have to make the link
1346 explicit. The punctuation characters ``.,;:'' are also not recognized as
1347 part of a URL when they appear at its end. For information on how to
1348 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1349 addresses with descriptions}.
1352 If the @command{muse-wiki} module is loaded, another form of implicit
1353 link will be made available. WikiNames, which are typed in CamelCase,
1354 are highlighted and published as links, provided that the file they
1357 Customization of WikiName recognition may be accomplished by editing the
1358 @code{muse-wiki-wikiword-regexp} option and subsequently running
1359 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1360 If you use the Customize interface, the latter will be done
1363 @cindex InterWiki links
1364 @cindex inter-project links
1365 The @command{muse-wiki} module also allows for InterWiki links. These
1366 are similar to WikiWords, but they specify both the project and page of
1367 a file. The names of your project entries in @code{muse-project-alist}
1368 will be used as InterWiki names by default. Several examples follow.
1371 Blog::DocumentingMuse
1376 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1377 the project name, and @samp{DocumentingMuse} is the page name. In the
1378 second example, @samp{#} is the interwiki delimiter. If the name of a
1379 project occurs by itself in text, like the third case, it will be
1380 colorized and published as a link to the default page of the given
1383 Customization of interwiki links may be accomplished by editing the
1384 @code{muse-wiki-interwiki-alist} option.
1386 It is also possible to link to an anchor in an interwiki document. This
1387 is called a ``three-part link''. Examples of this follow.
1390 Blog::DocumentingMuse#anchor1
1391 Projects#EmacsMuse#anchor2
1394 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1395 @comment node-name, next, previous, up
1396 @section Publishing and displaying images
1398 @cindex links, with images
1399 @subheading Image links
1401 Links to images may be used in either the target or the description, or
1402 both. Thus, the following code will publish as a clickable image that
1403 points to @url{http://mwolson.org/}.
1406 [[http://mwolson.org/][/static/logos/site-logo.png]]
1409 Normally, images in the link part will be inlined.
1411 If you want these images to be published as links instead, place the
1412 text ``URL:'' immediately in front of the link text. An example
1416 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1419 @cindex images, displaying
1420 @cindex images, local
1421 @subheading Displaying images in Muse mode
1422 If a link to a locally-available image is encountered in the link
1423 description, Muse mode will attempt to display it if your version of
1426 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1427 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1429 The method for finding images may be altered by customizing the
1430 @code{muse-colors-inline-image-method} option. One useful value for
1431 this option is @code{muse-colors-use-publishing-directory}, which tells
1432 Muse mode to look in the directory where the current file will be
1433 published. The default is to look in the current directory. Relative
1434 paths like @samp{../pics/} should work for either setting.
1436 Eventually, it is hoped that Muse will be able to copy images from the a
1437 ``source'' directory to a publishing directory by customizing
1438 @code{muse-project-alist}, but this has not been implemented yet.
1440 @cindex images, without descriptions
1441 @cindex images, inlined
1442 @subheading Publishing simple images
1443 The following example will display correctly and publish correctly if a
1444 @acronym{PNG} file called @file{TestLogo.png} exists in the
1445 @file{../pics/} directory. If text is on the same line as the picture,
1446 it will remain so in the output.
1452 @cindex images, captions
1453 @subheading Publishing images with captions
1454 If you want to add a caption to an image, use the following syntax.
1455 This will center the image (if the output format supports it) and add a
1456 centered caption below the picture. Formats that do not support
1457 centering the image will instead leave it against the left margin.
1460 [[../pics/mycat.png][My cat Dexter]]
1463 Images with captions may only occur in their own paragraphs, with no
1464 text on the same line. Otherwise, the published output will not be
1465 syntactically correct.
1467 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1468 @comment node-name, next, previous, up
1469 @section Inserting a horizontal line or anchor
1471 @cindex horizontal rules
1473 @subheading Horizontal Rules
1475 Four or more dashes indicate a horizontal rule. Be sure to put blank
1476 lines around it, or it will be considered part of the proceeding or
1477 following paragraph!
1480 @cindex links, with target on same page
1483 If you begin a line with "#anchor" -- where "anchor" can be any word
1484 that doesn't contain whitespace -- it defines an anchor at that point
1485 into the document. This point can be referenced using "page#anchor" as
1486 the target in a Muse link.
1488 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
1489 @comment node-name, next, previous, up
1490 @section Evaluating Emacs Lisp code in documents for extensibility
1491 @cindex lisp, embedded
1493 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1494 which is the only Muse tag supported in a style's header and footer
1495 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1496 text you wish. The inserted output will get marked up, if the
1497 @verb{|<lisp>|} tag appears within the main text of the document.
1500 <lisp>(concat "This form gets " "inserted")</lisp>
1503 @cindex lisp, and insert command
1504 Note that you should not use the @code{insert} command within a set of
1505 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1506 tags will be automatically inserted into the document.
1508 It is also possible to treat the output as if it were surrounded by the
1509 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1510 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1511 attribute of the @verb{|<lisp>|} tag.
1514 <lisp markup="example">
1515 (concat "Insert" " me")
1519 Other languages also have tags that cause source code to be evaluated.
1520 @xref{Tag Summary}, for details.
1522 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
1523 @comment node-name, next, previous, up
1524 @section Lines to omit from published output
1526 @cindex publishing, omitting lines
1528 Use the following syntax to indicate a comment. Comments will not be
1532 ; Comment text goes here.
1535 That is, only a semi-colon at the beginning of a line, followed by a
1536 literal space, will cause that line to be treated as a comment.
1538 You can alternatively surround the region with the @verb{|<comment>|}
1541 If you wish the comment to be published, but just commented out using
1542 the comment syntax of the output format, then set
1543 @option{muse-publish-comments-p} to non-nil.
1545 @node Tag Summary, , Comments, Markup Rules
1546 @comment node-name, next, previous, up
1547 @section Tags that Muse recognizes
1549 @cindex inserting files at publish time
1550 @cindex publishing, including markup in headers and footers
1551 @cindex publishing, inserting files
1553 Muse has several built-in tags that may prove useful during publishing.
1554 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1555 Muse uses, as well as make your own tags.
1559 If a tag takes arguments, it will look like this, where ``tagname'' is
1560 the name of the tag.
1563 <tagname arg1="string1" arg2="string2">
1566 If you want the tag to look like it came straight from an XHTML
1567 document, you can alternatively do the following.
1570 <tagname arg1="string1" arg2="string2" />
1573 If a tag surrounds some text, it will look like this.
1576 <tagname>Some text</tagname>
1579 If a tag surrounds a large region, it will look like this.
1588 @subheading Tag listing
1590 This is the complete list of tags that Muse accepts, including those
1591 that were mentioned in previous sections.
1596 If publishing to HTML, surround the given text with a @verb{|<span>|}
1597 tag. It takes one argument called ``name'' that specifies the class
1598 attribute of the @verb{|<span>|} tag.
1600 If publishing to a different format, do nothing extra to the text.
1603 Treat the text surrounded by the tag as if they were enclosed in equal
1604 signs, that is, make it monospace.
1607 Run a command on the region, replacing the region with the result of the
1608 command. The command is specified with the ``interp'' argument. If no
1609 value for ``interp'' is given, pass the entire region to the shell.
1611 The ``markup'' argument controls how this section is marked up.
1613 If it is omitted, publish the region with the normal Muse rules.
1615 If "nil", do not mark up the region at all, but prevent Muse from
1616 further interpreting it.
1618 If "example", treat the region as if it was surrounded by the
1619 @verb{|<example>|} tag.
1621 If "src", treat the included text as if it was surrounded by the
1622 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1625 If "verse", treat the region as if it was surrounded by the
1626 @verb{|<verse>|} tag, to preserve newlines.
1628 Otherwise, it should be the name of a function to call, with the buffer
1629 narrowed to the region.
1632 Treat the entire region as a comment. If the option
1633 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1634 publish it using the comment syntax of the current publishing style.
1637 Publish a Table of Contents. This will either be inserted in-place or
1638 at the beginning of the document, depending on your publishing style.
1639 It does not have a delimiting tag.
1641 By default, only 2 levels of headings will be included in the generated
1642 Table of Contents. To change this globally, customize the
1643 @var{muse-publish-contents-depth} option. To change this only for the
1644 current tag, use the ``depth'' argument.
1647 Publish the region in monospace, preserving the newlines in the region.
1648 This is useful for snippets of code.
1651 Insert the given file at the current location during publishing. The
1652 basic use of this tag is as follows, replacing ``included_file'' with
1653 the name of the file that you want to include.
1656 <include file="included_file">
1659 The ``markup'' argument controls how this section is marked up.
1661 If it is omitted, publish the included text with the normal Muse
1664 If "nil", do not mark up the included text at all.
1666 If "example", treat the included text as if it was surrounded by the
1667 @verb{|<example>|} tag.
1669 If "src", treat the included text as if it was surrounded by the
1670 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1673 If "verse", treat the included text as if it was surrounded by the
1674 @verb{|<verse>|} tag, to preserve newlines.
1676 Otherwise, it should be the name of a function to call after inserting
1677 the file with the buffer narrowed to the section inserted.
1680 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1681 The result is then inserted into the document, so you do not need to
1682 explicitly call @code{insert}. All text properties are removed from the
1685 This tag takes the ``markup'' argument. See the description of
1686 @verb{|<command>|} for details.
1689 Make sure that the text enclosed by this tag is published without
1690 escaping it in any way. This is useful for inserting markup directly
1691 into the published document, when Muse does not provide the desired
1695 Mark up the text between the initial and ending tags. The markup
1696 command to use may be specified by the ``function'' argument. The
1697 standard Muse markup routines are used by default if no ``function''
1698 argument is provided.
1700 This is useful for marking up regions in headers and footers. One
1701 example that comes to mind is generating a published index of all of the
1702 files in the current project by doing the following.
1705 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1709 Run the @command{perl} language interpreter on the region, replacing the
1710 region with the result of the command.
1712 This tag takes the ``markup'' argument. See the description of
1713 @verb{|<command>|} for details.
1716 Run the @command{python} language interpreter on the region, replacing
1717 the region with the result of the command.
1719 This tag takes the ``markup'' argument. See the description of
1720 @verb{|<command>|} for details.
1723 Publish the region as a blockquote. This will either be inserted
1724 in-place or at the beginning of the document, depending on your
1725 publishing style. It does not have a delimiting tag.
1728 Run the @command{ruby} language interpreter on the region, replacing the
1729 region with the result of the command.
1731 This tag takes the ``markup'' argument. See the description of
1732 @verb{|<command>|} for details.
1735 Publish the region using htmlize.
1736 The language to use may be specified by the ``lang'' attribute.
1738 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1739 the value of the ``lang'' attribute.
1741 This tag requires htmlize 1.34 or later in order to work. If this is
1742 not satisfied, or the current publishing style is not HTML-based, Muse
1743 will publish the region like an @verb{|<example>|} tag.
1746 This is used when you want to prevent Muse from trying to interpret some
1747 markup. Surround the markup in @verb{|<verbatim>|} and
1748 @verb{|</verbatim>|}, and it will not be interpreted.
1750 This tag was used often in previous versions of Muse because they did
1751 not support whole-document escaping of specials. Now, it will only be
1752 needed for other tags, and perhaps footnotes as well.
1755 Preserve the newlines in the region. In formats like HTML, newlines are
1756 removed by default, hence the need for this tag. In other publishing
1757 styles, this tag may cause the text to be indented slightly in a way
1758 that looks nice for poetry and prose.
1762 @node Publishing Styles, Extending Muse, Markup Rules, Top
1763 @comment node-name, next, previous, up
1764 @chapter Publishing Various Types of Documents
1765 @cindex publishing styles
1767 One of the principle features of Muse is the ability to publish a simple
1768 input text to a variety of different output styles. Muse also makes it
1769 easy to create new styles, or derive from an existing style.
1772 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1773 * Book:: Publishing entries into a compilation.
1774 * ConTeXt:: Publishing ConTeXt documents.
1775 * DocBook:: Publishing in DocBook XML form.
1776 * HTML:: Publishing in HTML or XHTML form.
1777 * Journal:: Keeping a journal or blog.
1778 * LaTeX:: Publishing LaTeX documents.
1779 * Poem:: Publish a poem to LaTex or PDF.
1780 * Texinfo:: Publish entries to Texinfo format or PDF.
1781 * XML:: Publish entries to XML.
1784 @node Blosxom, Book, Publishing Styles, Publishing Styles
1785 @comment node-name, next, previous, up
1786 @section Integrating Muse and pyblosxom.cgi
1787 @cindex blog, one-file-per-entry style
1789 The Blosxom publishing style publishes a tree of categorised files to a
1790 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1791 In other words, each blog entry corresponds with one file.
1794 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1795 * Blosxom Entries:: Format of a Blosxom entry and automation.
1796 * Blosxom Options:: Blosxom styles and options provided.
1799 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1800 @comment node-name, next, previous, up
1801 @subsection Other tools needed for the Blosxom style
1803 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1804 installed on a machine that you have upload access to.
1806 The following additional components are required in order to make the
1807 date of blog entries display as something sensible.
1811 A script to gather date directives from the entire blog tree into a
1812 single file. The file must associate a blog entry with a date.
1815 A plugin for (py)blosxom that reads this file.
1818 These 2 things are provided for @command{pyblosxom.cgi} in the
1819 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1820 former service, while @file{hardcodedates.py} provides the latter
1821 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1822 script will be found/written.
1824 Here is a sample listing from my @file{timestamps} file, which maps
1825 each file to a date. This can really be in any format, as long as your
1826 date-gathering script and your plugin can both understand it.
1829 2005-04-01-14-16 personal/paper_cranes
1830 2005-03-21 personal/spring_break_over
1831 2004-10-24 personal/finished_free_culture
1834 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1835 @file{getstamps.py}. Note that you will need to set the current
1836 directory to where your Muse files are, execute @file{getstamps.py}, and
1837 then move the generated timestamps file to your publishing directory.
1839 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1840 @comment node-name, next, previous, up
1841 @subsection Format of a Blosxom entry and automation
1843 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1844 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1845 plus whatever normal content is desired.
1847 The date directive is not used directly by @command{pyblosxom.cgi} or
1848 this program. You need to have the two additional items from the former
1849 section to make use of this feature.
1851 There is a function called @code{muse-blosxom-new-entry} that will
1852 automate the process of making a new blog entry. To make use of it, do
1857 Customize @code{muse-blosxom-base-directory} to the location that your
1858 blog entries are stored.
1861 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1862 use the following code to assign this function to @kbd{C-c p l'}.
1865 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1869 You should create your directory structure ahead of time under your base
1870 directory. These directories, which correspond with category names, may
1874 When you enter this key sequence, you will be prompted for the category
1875 of your entry and its title. Upon entering this information, a new file
1876 will be created that corresponds with the title, but in lowercase
1877 letters and having special characters converted to underscores. The
1878 title and date directives will be inserted automatically.
1881 @node Blosxom Options, , Blosxom Entries, Blosxom
1882 @comment node-name, next, previous, up
1883 @subsection Blosxom styles and options provided
1885 The following styles and options are available in the Blosxom publishing
1888 @subheading Styles provided
1892 @cindex publishing styles, blosxom-html
1894 Publish Blosxom entries in HTML form.
1896 @cindex publishing styles, blosxom-xhtml
1898 Publish Blosxom entries in XHTML form.
1902 @subheading Options provided
1906 @item muse-blosxom-extension
1907 Default file extension for publishing Blosxom files.
1909 @item muse-blosxom-header
1910 Header used for publishing Blosxom files.
1912 This may be text or a filename.
1914 @item muse-blosxom-footer
1915 Footer used for publishing Blosxom files.
1917 This may be text or a filename.
1919 @item muse-blosxom-base-directory
1920 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1922 This is the top-level directory where your blog entries may be found
1927 @node Book, ConTeXt, Blosxom, Publishing Styles
1928 @comment node-name, next, previous, up
1929 @section Publishing entries into a compilation
1931 This publishing style is used to output ``books'' in LaTeX or PDF
1934 Each page will become a separate chapter in the book, unless the style
1935 keyword @option{:nochapters} is used, in which case they are all run
1936 together as if one giant chapter.
1938 One way of publishing a book is to make a project for it, add the
1939 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1940 with a very specific @option{:include} value to specify some page whose
1941 contents will be checked for the values of @code{#title} and
1942 @code{#date}, and whose name will be used in the output file. Then to
1943 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1944 @kbd{C-c C-p} to trigger the publishing process. An example
1945 @code{muse-project-alist} for this method follows.
1948 (setq muse-project-alist
1949 '(("MyNotes" (:nochapters t ; do automatically add chapters
1950 :book-chapter "Computer Science"
1952 :book-chapter "Mathematics"
1954 :book-chapter "Emacs"
1956 :book-end t ; the rest will not be placed in the book
1957 "~/Notes" ; so we can find the notes-anthology page
1959 :force-publish ("index")
1962 :include "/notes-anthology[^/]*$"
1963 :path "~/public_html/notes")
1964 ;; other publishing styles for each directory go here,
1969 In this example, there would be a file called
1970 @file{~/Notes/notes-anthology.muse}, which would contain just the
1971 following. The resulting book would be published to
1972 @file{~/public_html/notes/notes-anthology.pdf}.
1975 #title My Technology Ramblings
1978 Another way is to call the @code{muse-book-publish-project} function
1979 manually, with a custom project entry. An example of this may be found
1980 in John Wiegley's configuration file at
1981 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
1984 @subheading Styles provided
1988 @cindex publishing styles, book-latex
1990 Publish a book in LaTeX form. The header and footer are different than
1991 the normal LaTeX publishing mode.
1993 @cindex publishing styles, book-pdf
1995 Publish a book in PDF form. The header and footer are different than
1996 the normal PDF publishing mode.
2000 @subheading Options provided
2004 @item muse-book-before-publish-hook
2005 A hook run in the book buffer before it is marked up.
2007 @item muse-book-after-publish-hook
2008 A hook run in the book buffer after it is marked up.
2010 @item muse-book-latex-header
2011 Header used for publishing books to LaTeX.
2013 This may be text or a filename.
2015 @item muse-book-latex-footer
2016 Footer used for publishing books to LaTeX.
2018 This may be text or a filename.
2021 @node ConTeXt, DocBook, Book, Publishing Styles
2022 @comment node-name, next, previous, up
2023 @section Publishing ConTeXt documents
2025 This publishing style is capable of producing ConTeXt or PDF documents.
2027 If you wish to publish PDF documents based on ConTeXt, you will need to
2028 have it installed. For Debian and Ubuntu, this can be accomplished by
2029 installing the ``texlive'' package.
2031 @subheading Styles provided
2035 @cindex publishing styles, context
2037 Publish a ConTeXt document.
2039 @cindex publishing styles, context-pdf
2041 Publish a PDF document, using an external ConTeXt document conversion
2044 @cindex publishing styles, context-slides
2045 @item context-slides
2046 Produce slides from a ConTeXt document.
2048 Here is an example of a slide.
2053 [[Some-sort-of-cute-image.png]]
2058 - Another bullet point.
2065 @cindex publishing styles, context-slides-pdf
2066 @item context-slides-pdf
2067 Publish a PDF document of ConTeXt slides.
2071 @subheading Options provided
2075 @item muse-context-extension
2076 Default file extension for publishing ConTeXt files.
2078 @item muse-context-pdf-extension
2079 Default file extension for publishing ConTeXt files to PDF.
2081 @item muse-context-pdf-program
2082 The program that is called to generate PDF content from ConTeXt content.
2084 @item muse-context-pdf-cruft
2085 Extensions of files to remove after generating PDF output successfully.
2087 @item muse-context-header
2088 Header used for publishing ConTeXt files.
2090 This may be text or a filename.
2092 @item muse-context-footer
2093 Footer used for publishing ConTeXt files.
2095 This may be text or a filename.
2097 @item muse-context-markup-regexps
2098 List of markup regexps for identifying regions in a Muse page.
2100 For more on the structure of this list,
2101 @xref{muse-publish-markup-regexps}.
2103 @item muse-context-markup-functions
2104 An alist of style types to custom functions for that kind of text.
2106 For more on the structure of this list,
2107 @xref{muse-publish-markup-functions}.
2109 @item muse-context-markup-strings
2110 Strings used for marking up text.
2112 These cover the most basic kinds of markup, the handling of which
2113 differs little between the various styles.
2115 @item muse-context-slides-header
2116 Header for publishing a presentation (slides) using ConTeXt.
2118 You can use any of the predefined modules, which are available in the
2119 tex/context/base of your distribution, provided it has TitlePage and
2120 Topic defined. Alternatively, you can use your own style (mystyle) by
2121 replacing ``\\usemodule[]'' with ``\\input mystyle''.
2123 This may be text or a filename.
2125 @item muse-context-slides-markup-strings
2126 Strings used for marking up text in ConTeXt slides.
2128 @item muse-context-markup-specials-document
2129 A table of characters which must be represented specially.
2130 These are applied to the entire document, sans already-escaped
2133 @item muse-context-markup-specials-example
2134 A table of characters which must be represented specially.
2135 These are applied to @verb{|example>|} regions.
2137 With the default interpretation of @verb{|<example>|} regions, no
2138 specials need to be escaped.
2140 @item muse-context-markup-specials-literal
2141 A table of characters which must be represented specially.
2142 This applies to =monospaced text= and @verb{|<code>|} regions.
2144 @item muse-context-markup-specials-url
2145 A table of characters which must be represented specially.
2146 These are applied to URLs.
2148 @item muse-context-markup-specials-image
2149 A table of characters which must be represented specially.
2150 These are applied to image filenames.
2152 @item muse-context-permit-contents-tag
2153 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2156 Most of the time, it is best to have a table of contents on the
2157 first page, with a new page immediately following. To make this
2158 work with documents published in both HTML and ConTeXt, we need to
2159 ignore the @verb{|<contents>|} tag.
2161 If you don't agree with this, then set this option to non-nil,
2162 and it will do what you expect.
2166 @node DocBook, HTML, ConTeXt, Publishing Styles
2167 @comment node-name, next, previous, up
2168 @section Publishing in DocBook XML form
2170 This publishing style is used to generate DocBook XML files.
2172 @subheading Styles provided
2176 @cindex publishing styles, docbook
2178 Publish a file in Docbook form.
2182 @subheading Options provided
2184 This publishing style uses the same options for markup up special
2185 characters as the ``xml'' publishing style. @xref{XML}, for details.
2189 @item muse-docbook-extension
2190 Default file extension for publishing DocBook XML files.
2192 @item muse-docbook-header
2193 Header used for publishing DocBook XML files.
2195 This may be text or a filename.
2197 @item muse-docbook-footer
2198 Footer used for publishing DocBook XML files.
2200 This may be text or a filename.
2202 @item muse-docbook-markup-regexps
2203 List of markup rules for publishing a Muse page to DocBook XML.
2205 @item muse-docbook-markup-functions
2206 An alist of style types to custom functions for that kind of text.
2208 @item muse-docbook-markup-strings
2209 Strings used for marking up text.
2211 These cover the most basic kinds of markup, the handling of which
2212 differs little between the various styles.
2214 @item muse-docbook-encoding-default
2215 The default Emacs buffer encoding to use in published files.
2216 This will be used if no special characters are found.
2218 @item muse-docbook-charset-default
2219 The default DocBook XML charset to use if no translation is
2220 found in @code{muse-xml-encoding-map}.
2224 @node HTML, Journal, DocBook, Publishing Styles
2225 @comment node-name, next, previous, up
2226 @section Publishing in HTML or XHTML form
2228 This publishing style is capable of producing HTML or XHTML documents.
2230 @subheading Styles provided
2234 @cindex publishing styles, html
2236 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2239 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2243 @subheading Options provided
2245 If an HTML option does not have a corresponding XHTML option, it will
2246 be used for both of these publishing styles.
2248 These publishing styles use the same options for markup up special
2249 characters as the ``xml'' publishing style. @xref{XML}, for details.
2253 @item muse-html-extension
2254 Default file extension for publishing HTML files.
2256 @item muse-xhtml-extension
2257 Default file extension for publishing XHTML files.
2259 @item muse-html-style-sheet
2260 Store your stylesheet definitions here.
2262 This is used in @code{muse-html-header}. You can put raw CSS in here or
2263 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2264 @verb{|<lisp>|} markup tags.
2266 If you are publishing to XHTML, then customize the
2267 @code{muse-xhtml-style-sheet} option instead.
2269 @item muse-xhtml-style-sheet
2270 Store your stylesheet definitions here.
2272 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2273 or a @verb{|<link>|} tag to an external stylesheet. This text may
2274 contain @verb{|<lisp>|} markup tags.
2276 @item muse-html-header
2277 Header used for publishing HTML files.
2279 This may be text or a filename.
2281 @item muse-html-footer
2282 Footer used for publishing HTML files.
2284 This may be text or a filename.
2286 @item muse-xhtml-header
2287 Header used for publishing XHTML files.
2289 This may be text or a filename.
2291 @item muse-xhtml-footer
2292 Footer used for publishing XHTML files.
2294 This may be text or a filename.
2296 @item muse-html-anchor-on-word
2297 When true, anchors surround the closest word.
2299 This allows you to select them in a browser (i.e. for pasting), but has
2300 the side-effect of marking up headers in multiple colors if your header
2301 style is different from your link style.
2303 @item muse-html-table-attributes
2304 The attribute to be used with HTML @verb{|<table>|} tags.
2306 If you want to make more-complicated tables in HTML, surround the HTML
2307 with the @verb{|literal|} tag, so that it does not get escaped.
2309 @item muse-html-markup-regexps
2310 List of markup rules for publishing a Muse page to HTML.
2312 @item muse-html-markup-functions
2313 An alist of style types to custom functions for that kind of text.
2315 @item muse-html-markup-strings
2316 Strings used for marking up text as HTML.
2318 These cover the most basic kinds of markup, the handling of which
2319 differs little between the various styles.
2321 @item muse-xhtml-markup-strings
2322 Strings used for marking up text as XHTML.
2324 These cover the most basic kinds of markup, the handling of which
2325 differs little between the various styles.
2327 @item muse-html-markup-tags
2328 A list of tag specifications, for specially marking up HTML.
2329 @xref{muse-publish-markup-tags}, for more information.
2331 @item muse-html-meta-http-equiv
2332 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2334 @item muse-html-meta-content-type
2335 The content type used for the HTML @verb{|<meta>|} tag.
2337 If you are striving for XHTML 1.1 compliance, you may want to change
2338 this to ``application/xhtml+xml''.
2340 @item muse-html-meta-content-encoding
2341 The charset to append to the HTML @verb{|<meta>|} tag.
2343 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2344 and determine the HTML charset from emacs's coding. If set to a string,
2345 this string will be used to force a particular charset.
2347 @item muse-html-charset-default
2348 The default HTML meta charset to use if no translation is found in
2349 @code{muse-xml-encoding-map}.
2351 @item muse-html-encoding-default
2352 The default Emacs buffer encoding to use in published files.
2353 This will be used if no special characters are found.
2357 @node Journal, LaTeX, HTML, Publishing Styles
2358 @comment node-name, next, previous, up
2359 @section Keeping a journal or blog
2361 @cindex blog, journal style
2363 The module facilitates the keeping and publication of a journal. When
2364 publishing to HTML, it assumes the form of a web log, or blog.
2366 The input format for each entry is as follows.
2369 * 20040317: Title of entry
2374 "You know who you are. It comes down to a simple gut check: You
2375 either love what you do or you don't. Period." -- P. Bronson
2379 The "qotd", or Quote of the Day, is entirely optional. When generated
2380 to HTML, this entry is rendered as the following.
2384 <div class="entry-qotd">
2385 <h3>Quote of the Day:</h3>
2386 <p>"You know who you are. It comes down to a simple gut
2387 check: You either love what you do or you don't. Period."
2390 <div class="entry-body">
2391 <div class="entry-head">
2392 <div class="entry-date">
2393 <span class="date">March 17, 2004</span>
2395 <div class="entry-title">
2396 <h2>Title of entry</h2>
2399 <div class="entry-text">
2400 <p>Text for the entry.</p>
2406 The plurality of "div" tags makes it possible to display the entries in
2407 any form you wish, using a CSS style.
2409 Also, an .RDF file can be generated from your journal by publishing it
2410 with the "rdf" style. It uses the first two sentences of the first
2411 paragraph of each entry as its "description", and auto-generates tags
2412 for linking to the various entries.
2414 @subheading muse-project-alist considerations
2416 If you wish to publish an RDF or RSS feed, it is important to include
2417 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2418 for your Journal projects. An example follows.
2421 (setq muse-project-alist
2422 '(("Journal" ("~/Journal/"
2424 (:base "journal-rss"
2425 :base-url "http://example.org/journal/"
2426 :path "~/public_html/journal"))))
2429 @subheading Styles provided
2433 @cindex publishing styles, journal-html
2435 Publish journal entries as an HTML document.
2437 @cindex publishing styles, journal-xhtml
2439 Publish journal entries as an XHTML document.
2441 @cindex publishing styles, journal-latex
2443 Publish journal entries as a LaTeX document.
2445 @cindex publishing styles, journal-pdf
2447 Publish journal entries as a PDF document.
2449 @cindex publishing styles, journal-book-latex
2450 @item journal-book-latex
2451 Publish journal entries as a LaTeX book.
2453 @cindex publishing styles, journal-book-pdf
2454 @item journal-book-pdf
2455 Publish journal entries as a PDF book.
2457 @cindex publishing styles, journal-rdf
2458 @cindex publishing styles, RSS 1.0
2460 Publish journal entries as an RDF file (RSS 1.0).
2462 @cindex publishing styles, journal-rss
2463 @cindex publishing styles, RSS 2.0
2465 Publish journal entries as an RSS file (RSS 2.0).
2467 @cindex publishing styles, journal-rss-entry
2468 @item journal-rss-entry
2469 Used internally by @code{journal-rss} and @code{journal-rdf} for
2470 publishing individual entries.
2474 @subheading Options provided
2478 @item muse-journal-heading-regexp
2479 A regexp that matches a journal heading.
2481 Paren group 1 is the ISO date, group 2 is the optional category, and
2482 group 3 is the optional heading for the entry.
2484 @item muse-journal-date-format
2485 Date format to use for journal entries.
2487 @item muse-journal-html-heading-regexp
2488 A regexp that matches a journal heading from an HTML document.
2490 Paren group 1 is the ISO date, group 2 is the optional category, and
2491 group 3 is the optional heading for the entry.
2493 @item muse-journal-html-entry-template
2494 Template used to publish individual journal entries as HTML.
2496 This may be text or a filename.
2498 @item muse-journal-latex-section
2499 Template used to publish a LaTeX section.
2501 @item muse-journal-latex-subsection
2502 Template used to publish a LaTeX subsection.
2504 @item muse-journal-markup-tags
2505 A list of tag specifications, for specially marking up Journal entries.
2507 @xref{muse-publish-markup-tags}, for more information.
2509 This is used by @code{journal-latex} and its related styles, as well as
2510 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2511 @code{journal-rss} use.
2513 @item muse-journal-rdf-extension
2514 Default file extension for publishing RDF (RSS 1.0) files.
2516 @item muse-journal-rdf-base-url
2517 The base URL of the website referenced by the RDF file.
2519 @item muse-journal-rdf-header
2520 Header used for publishing RDF (RSS 1.0) files.
2522 This may be text or a filename.
2524 @item muse-journal-rdf-footer
2525 Footer used for publishing RDF (RSS 1.0) files.
2527 This may be text or a filename.
2529 @item muse-journal-rdf-date-format
2530 Date format to use for RDF entries.
2532 @item muse-journal-rdf-entry-template
2533 Template used to publish individual journal entries as RDF.
2535 This may be text or a filename.
2537 @item muse-journal-rdf-summarize-entries
2538 If non-nil, include only summaries in the RDF file, not the full data.
2540 The default is nil, because this annoys some subscribers.
2542 @item muse-journal-rss-heading-regexp
2543 A regexp that matches a journal heading from an HTML document.
2545 Paren group 1 is the ISO date, group 2 is the optional category,
2546 and group 3 is the optional heading for the entry.
2548 @item muse-journal-rss-extension
2549 Default file extension for publishing RSS 2.0 files.
2551 @item muse-journal-rss-base-url
2552 The base URL of the website referenced by the RSS file.
2554 @item muse-journal-rss-header
2555 Header used for publishing RSS 2.0 files.
2557 This may be text or a filename.
2559 @item muse-journal-rss-footer
2560 Footer used for publishing RSS 2.0 files.
2562 This may be text or a filename.
2564 @item muse-journal-rss-date-format
2565 Date format to use for RSS 2.0 entries.
2567 @item muse-journal-rss-entry-template
2568 Template used to publish individual journal entries as RSS 2.0.
2570 This may be text or a filename.
2572 @item muse-journal-rss-enclosure-types-alist
2573 File types that are accepted as RSS enclosures.
2575 This is an alist that maps file extension to content type.
2577 Useful for podcasting.
2579 @item muse-journal-rss-summarize-entries
2580 If non-nil, include only summaries in the RSS file, not the full data.
2582 The default is nil, because this annoys some subscribers.
2584 @item muse-journal-rss-markup-regexps
2585 List of markup rules for publishing a Muse journal page to RSS.
2587 For more information on the structure of this list,
2588 @xref{muse-publish-markup-regexps}.
2590 @item muse-journal-rss-markup-functions
2591 An alist of style types to custom functions for that kind of text.
2593 For more on the structure of this list,
2594 @xref{muse-publish-markup-functions}.
2598 @node LaTeX, Poem, Journal, Publishing Styles
2599 @comment node-name, next, previous, up
2600 @section Publishing LaTeX documents
2602 This publishing style is capable of producing LaTeX or PDF documents.
2604 If you wish to publish PDF documents, you will need to have a good TeX
2605 installation. For Debian and Ubuntu, this can be accomplished by
2606 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2609 @subheading Styles provided
2613 @cindex publishing styles, latex
2615 Publish a LaTeX document.
2617 @cindex publishing styles, pdf
2619 Publish a PDF document, using an external LaTeX document conversion
2622 @cindex publishing styles, latexcjk
2624 Publish a LaTeX document with CJK (Chinese) encodings.
2626 @cindex publishing styles, pdfcjk
2628 Publish a PDF document with CJK (Chinese) encodings, using an external
2629 LaTeX document conversion tool.
2631 @cindex publishing styles, slides
2633 Publish a LaTeX document that uses the Beamer extension. This is
2634 suitable for producing slides.
2636 Here is an example of a slide.
2639 <slide title="First Slide">
2640 Everything between the slide tags composes this slide.
2642 [[Some-sort-of-cute-image.png]]
2645 - Another bullet point.
2649 @cindex publishing styles, slides-pdf
2651 Publish a PDF document of slides, using the Beamer extension.
2653 @cindex publishing styles, lecture-notes
2655 Publish a LaTeX document that uses the Beamer extension. This is
2656 suitable for producing lecture notes.
2658 This can also use the @verb{|<slide>|} tag.
2660 @cindex publishing styles, lecture-notes-pdf
2661 @item lecture-notes-pdf
2662 Publish a PDF document of lecture notes, using the Beamer extension.
2666 @subheading Options provided
2670 @item muse-latex-extension
2671 Default file extension for publishing LaTeX files.
2673 @item muse-latex-pdf-extension
2674 Default file extension for publishing LaTeX files to PDF.
2676 @item muse-latex-pdf-program
2677 The program that is called to generate PDF content from LaTeX content.
2679 @item muse-latex-pdf-cruft
2680 Extensions of files to remove after generating PDF output successfully.
2682 @item muse-latex-header
2683 Header used for publishing LaTeX files.
2685 This may be text or a filename.
2687 @item muse-latex-footer
2688 Footer used for publishing LaTeX files.
2690 This may be text or a filename.
2692 @item muse-latexcjk-header
2693 Header used for publishing LaTeX files (CJK).
2695 This may be text or a filename.
2697 @item muse-latexcjk-footer
2698 Footer used for publishing LaTeX files (CJK).
2700 This may be text or a filename.
2702 @item muse-latex-slides-header
2703 Header for publishing of slides using LaTeX.
2705 This may be text or a filename.
2707 You must have the Beamer extension for LaTeX installed for this to work.
2709 @item muse-latex-lecture-notes-header
2710 Header publishing of lecture notes using LaTeX.
2712 This may be text or a filename.
2714 You must have the Beamer extension for LaTeX installed for this to work.
2716 @item muse-latex-markup-regexps
2717 List of markup regexps for identifying regions in a Muse page.
2719 For more on the structure of this list,
2720 @xref{muse-publish-markup-regexps}.
2722 @item muse-latex-markup-functions
2723 An alist of style types to custom functions for that kind of text.
2725 For more on the structure of this list,
2726 @xref{muse-publish-markup-functions}.
2728 @item muse-latex-markup-strings
2729 Strings used for marking up text.
2731 These cover the most basic kinds of markup, the handling of which
2732 differs little between the various styles.
2734 @item muse-latex-slides-markup-tags
2735 A list of tag specifications, for specially marking up LaTeX slides.
2737 @item muse-latexcjk-encoding-map
2738 An alist mapping emacs coding systems to appropriate CJK codings.
2739 Use the base name of the coding system (ie, without the -unix).
2741 @item muse-latexcjk-encoding-default
2742 The default Emacs buffer encoding to use in published files.
2744 This will be used if no special characters are found.
2746 @item muse-latex-markup-specials-document
2747 A table of characters which must be represented specially.
2748 These are applied to the entire document, sans already-escaped
2751 @item muse-latex-markup-specials-example
2752 A table of characters which must be represented specially.
2753 These are applied to @verb{|example>|} regions.
2755 With the default interpretation of @verb{|<example>|} regions, no
2756 specials need to be escaped.
2758 @item muse-latex-markup-specials-literal
2759 A table of characters which must be represented specially.
2760 This applies to =monospaced text= and @verb{|<code>|} regions.
2762 @item muse-latex-markup-specials-url
2763 A table of characters which must be represented specially.
2764 These are applied to URLs.
2766 @item muse-latex-markup-specials-image
2767 A table of characters which must be represented specially.
2768 These are applied to image filenames.
2770 @item muse-latex-permit-contents-tag
2771 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2774 Most of the time, it is best to have a table of contents on the
2775 first page, with a new page immediately following. To make this
2776 work with documents published in both HTML and LaTeX, we need to
2777 ignore the @verb{|<contents>|} tag.
2779 If you don't agree with this, then set this option to non-nil,
2780 and it will do what you expect.
2784 @node Poem, Texinfo, LaTeX, Publishing Styles
2785 @comment node-name, next, previous, up
2786 @section Publish a poem to LaTex or PDF
2788 The @code{muse-poem} module makes it easy to attractively publish and
2789 reference poems in the following format, using the "memoir" module for
2790 LaTeX publishing. It will also markup poems for every other output
2791 style, though none are nearly as pretty.
2800 Annotations, history, notes, etc.
2803 Once a poem is written in this format, just publish it to PDF using the
2804 @code{poem-pdf} style. To make an inlined reference to a poem that
2805 you've written -- for example, from a blog page -- there is a "poem" tag
2806 defined by this module.
2809 <poem title="name.of.poem.page">
2812 Let's assume the template above was called @file{name.of.poem.page};
2813 then the above tag would result in this inclusion.
2821 John Wiegley uses this module for publishing all of the poems on his
2822 website, which are at
2823 @uref{http://www.newartisans.com/johnw/poems.html}.
2825 @subheading Styles provided
2829 @cindex publishing styles, poem-latex
2831 Publish a poem in LaTeX form.
2833 @cindex publishing styles, poem-pdf
2835 Publish a poem to a PDF document.
2837 @cindex publishing styles, chapbook-latex
2838 @item chapbook-latex
2839 Publish a book of poems in LaTeX form.
2841 @cindex publishing styles, chapbook-pdf
2843 Publish a book of poems to a PDF document.
2847 @subheading Options provided
2851 @item muse-poem-latex-header
2852 Header used for publishing LaTeX poems.
2854 This may be text or a filename.
2856 @item muse-poem-latex-footer
2857 Footer used for publishing LaTeX files.
2859 This may be text or a filename.
2861 @item muse-poem-markup-strings
2862 Strings used for marking up poems.
2864 These cover the most basic kinds of markup, the handling of which
2865 differs little between the various styles.
2867 @item muse-chapbook-latex-header
2868 Header used for publishing a book of poems in LaTeX form.
2870 This may be text or a filename.
2872 @item muse-chapbook-latex-footer
2873 Footer used for publishing a book of poems in LaTeX form.
2875 This may be text or a filename.
2877 @item muse-poem-chapbook-strings
2878 Strings used for marking up books of poems.
2880 These cover the most basic kinds of markup, the handling of which
2881 differs little between the various styles.
2885 @node Texinfo, XML, Poem, Publishing Styles
2886 @comment node-name, next, previous, up
2887 @section Publish entries to Texinfo format or PDF
2889 Rules for publishing a Muse file as a Texinfo article.
2891 @subheading Styles provided
2895 @cindex publishing styles, texi
2897 Publish a file in Texinfo form.
2899 @cindex publishing styles, texi
2901 Generate an Info file from a Muse file.
2903 @cindex publishing styles, info-pdf
2905 Publish a file in PDF form.
2909 @subheading Options provided
2913 @item muse-texinfo-process-natively
2914 If non-nil, use the Emacs `texinfmt' module to make Info files.
2916 @item muse-texinfo-extension
2917 Default file extension for publishing Texinfo files.
2919 @item muse-texinfo-info-extension
2920 Default file extension for publishing Info files.
2922 @item muse-texinfo-pdf-extension
2923 Default file extension for publishing PDF files.
2925 @item muse-texinfo-header
2926 Text to prepend to a Muse page being published as Texinfo.
2928 This may be text or a filename.
2929 It may contain @verb{|<lisp>|} markup tags.
2931 @item muse-texinfo-footer
2932 Text to append to a Muse page being published as Texinfo.
2934 This may be text or a filename.
2935 It may contain @verb{|<lisp>|} markup tags.
2937 @item muse-texinfo-markup-regexps
2938 List of markup rules for publishing a Muse page to Texinfo.
2940 For more on the structure of this list,
2941 @xref{muse-publish-markup-regexps}.
2943 @item muse-texinfo-markup-functions
2944 An alist of style types to custom functions for that kind of text.
2946 For more on the structure of this list,
2947 @xref{muse-publish-markup-functions}.
2949 @item muse-texinfo-markup-strings
2950 Strings used for marking up text.
2952 These cover the most basic kinds of markup, the handling of which
2953 differs little between the various styles.
2955 @item muse-texinfo-markup-specials
2956 A table of characters which must be represented specially.
2958 @item muse-texinfo-markup-specials
2959 A table of characters which must be represented specially.
2960 These are applied to URLs.
2964 @node XML, , Texinfo, Publishing Styles
2965 @comment node-name, next, previous, up
2966 @section Publish entries to XML
2968 Muse is capable of publishing XML documents, with the help of the
2969 @file{muse-xml.el} module.
2971 A RelaxNG schema is available as part of the Muse distribution in the
2972 @file{etc/muse.rnc} file.
2974 @subheading Styles provided
2978 @cindex publishing styles, xml
2980 Publish a file in XML form.
2984 @subheading Options provided
2988 @cindex muse-xml-encoding-map
2989 @item muse-xml-encoding-map
2990 An alist mapping Emacs coding systems to appropriate XML charsets.
2991 Use the base name of the coding system (i.e. without the -unix).
2993 @item muse-xml-markup-specials
2994 A table of characters which must be represented specially in all
2995 XML-like markup formats.
2997 @item muse-xml-markup-specials-url-extra
2998 A table of characters which must be represented specially in all
2999 XML-like markup formats.
3001 These are extra characters that are escaped within URLs.
3003 @item muse-xml-extension
3004 Default file extension used for publishing XML files.
3006 @item muse-xml-header
3007 Header used for publishing XML files.
3009 This may be text or a filename.
3011 @item muse-xml-footer
3012 Footer used for publishing XML files.
3014 This may be text or a filename.
3016 @item muse-xml-markup-regexps
3017 List of markup rules for publishing a Muse page to XML.
3019 For more on the structure of this list,
3020 @xref{muse-publish-markup-regexps}.
3022 @item muse-xml-markup-functions
3023 An alist of style types to custom functions for that kind of text.
3025 For more on the structure of this list,
3026 @xref{muse-publish-markup-functions}.
3028 @item muse-xml-markup-strings
3029 Strings used for marking up text.
3031 These cover the most basic kinds of markup, the handling of which
3032 differs little between the various styles.
3034 @item muse-xml-encoding-default
3035 The default Emacs buffer encoding to use in published files.
3037 This will be used if no special characters are found.
3039 @item muse-xml-charset-default
3040 The default XML charset to use if no translation is found in
3041 @code{muse-xml-encoding-map}.
3046 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
3047 @comment node-name, next, previous, up
3048 @chapter Making your own publishing styles
3051 * Common Elements:: Common functionality shared by styles.
3052 * Deriving Styles:: Deriving a new style from an existing
3056 @node Common Elements, Deriving Styles, , Extending Muse
3057 @comment node-name, next, previous, up
3058 @section Common functionality shared by styles
3059 @cindex publishing styles, common
3062 * Markup Functions:: Specifying functions to mark up text.
3063 * Markup Regexps:: Markup rules for publishing.
3064 * Markup Strings:: Strings specific to a publishing style.
3065 * Markup Tags:: Tag specifications for special markup.
3066 * Style Elements:: Parameters used for defining styles.
3069 @node Markup Functions, Markup Regexps, , Common Elements
3070 @comment node-name, next, previous, up
3071 @subsection Specifying functions to mark up text
3072 @cindex publishing, markup functions
3074 @anchor{muse-publish-markup-functions}
3075 @code{muse-publish-markup-functions}
3077 An alist of style types to custom functions for that kind of text.
3079 This is used by publishing styles to attempt to minimize the amount of
3080 custom regexps that each has to define. @file{muse-publish} provides
3081 rules for the most common types of markup.
3083 Each member of the list is of the following form.
3091 Describes the type of text to associate with this rule.
3092 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3095 Function to use to mark up this kind of rule if no suitable function is
3096 found through the @option{:functions} tag of the current style.
3099 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3100 @comment node-name, next, previous, up
3101 @subsection Markup rules for publishing
3102 @cindex publishing, markup regexps
3103 @cindex publishing, rules
3105 @anchor{muse-publish-markup-regexps}
3106 @code{muse-publish-markup-regexps}
3108 List of markup rules for publishing a page with Muse.
3110 The rules given in this variable are invoked first, followed by whatever
3111 rules are specified by the current style.
3113 Each member of the list is either a function, or a list of the following
3117 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3122 A regular expression, or symbol whose value is a regular expression,
3123 which is searched for using `re-search-forward'.
3125 @item TEXT-BEGIN-GROUP
3126 The matching group within that regexp which denotes the beginning of the
3127 actual text to be marked up.
3129 @item REPLACEMENT-TEXT
3130 A string that will be passed to `replace-match'.
3132 If it is not a string, but a function, it will be called to determine
3133 what the replacement text should be (it must return a string). If it is
3134 a symbol, the value of that symbol should be a string.
3137 The replacements are done in order, one rule at a time. Writing
3138 the regular expressions can be a tricky business. Note that case
3139 is never ignored. `case-fold-search' is always bound to nil
3140 while processing the markup rules.
3142 @subheading Publishing order
3144 This is the order that the publishing rules are consulted, by default.
3145 This may be changed by customizing @code{muse-publish-markup-regexps}.
3149 @item trailing and leading whitespace
3150 Remove trailing and leading whitespace from a file.
3155 This is only recognized at the beginning of a file.
3158 @samp{; a commented line}
3166 @item explicit links
3167 Prevent emphasis characters in explicit links from being marked up.
3169 Don't actually publish them here, just add a special no-emphasis text
3173 Whitespace-delimited word, possibly with emphasis characters
3175 This function is responsible for marking up emphasis and escaping some
3181 Outline-mode style headings.
3186 These are ellipses with a dot at end.
3196 Horizontal rule or section separator.
3198 @item no-break-space
3201 Prevent lines from being split before or after these characters.
3206 beginning of footnotes section
3211 Footnote definition or reference. If at beginning of line, it is a
3226 Numbered list, item list, or term definition list.
3230 @file{table.el} style tables
3233 @samp{table | cells}
3235 Muse tables or orgtbl-mode style tables.
3238 spaces before beginning of text
3254 @samp{[[explicit][links]]}
3257 @samp{http://example.com/}
3260 @samp{bare-email@@example.com}
3264 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3265 @comment node-name, next, previous, up
3266 @subsection Strings specific to a publishing style
3267 @cindex publishing, markup strings
3269 @dfn{Markup strings} are strings used for marking up text for a
3272 These cover the most basic kinds of markup, the handling of which
3273 differs little between the various styles.
3275 @subheading Available markup strings
3279 @item image-with-desc
3280 An image and a description.
3282 Argument 1: image without extension. Argument 2: image extension.
3283 Argument 3: description.
3288 Argument 1: image without extension. Argument 2: image extension.
3291 An image with a link around it.
3293 Argument 1: link. Argument 2: image without extension.
3294 Argument 3: image extension.
3297 A reference to an anchor on the current page.
3299 Argument 1: anchor name. Argument 2: description if one exists, or the
3300 original link otherwise.
3303 A URL without a description.
3308 A link to a Muse page with a description.
3310 Argument 1: link. Argument 2: description if one exists, or the
3311 original link otherwise.
3313 @item link-and-anchor
3314 A link to a Muse page with an anchor, and a description.
3316 Argument 1: link. Argument 2: anchor name.
3317 Argument 3: description if one exists, or the original link otherwise.
3318 Argument 4: link without an extension.
3321 A link to an email address.
3323 Argument 1: email address. Argument 2: email address.
3328 Argument 1: name of anchor.
3333 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3336 Beginning of a comment.
3342 A horizontal line or space.
3344 @item no-break-space
3345 A space that separates two words which are not to be separated.
3348 Beginning of footnote.
3354 Mark a reference for the current footnote.
3356 Argument 1: number of this footnote.
3358 @item footnotemark-end
3359 End of a reference for the current footnote.
3362 Indicate the text of the current footnote.
3364 Argument 1: number of this footnote.
3366 @item footnotetext-end
3367 End of a footnote text line.
3370 Text used to replace ``Footnotes:'' line.
3379 Beginning of a part indicator line. This is used by book publishing.
3382 End of a part indicator line. This is used by book publishing.
3385 Beginning of a chapter indicator line. This is used by book publishing.
3388 End of a chapter indicator line. This is used by book publishing.
3391 Beginning of level 1 section indicator line.
3393 Argument 1: level of section; always 1.
3396 End of level 1 section indicator line.
3398 Argument 1: level of section; always 1.
3401 Beginning of level 2 section indicator line.
3403 Argument 1: level of section; always 2.
3405 @item subsection-end
3406 End of level 2 section indicator line.
3408 Argument 1: level of section; always 2.
3411 Beginning of level 3 section indicator line.
3413 Argument 1: level of section; always 3.
3415 @item subsubsection-end
3416 End of level 3 section indicator line.
3418 Argument 1: level of section; always 3.
3421 Beginning of section indicator line, where level is greater than 3.
3423 Argument 1: level of section.
3425 @item section-other-end
3426 End of section indicator line, where level is greater than 3.
3428 Argument 1: level of section.
3430 @item begin-underline
3431 Beginning of underlined text.
3434 End of underlined text.
3437 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3441 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3445 Beginning of the first level of emphasized text.
3448 End of the first level of emphasized text.
3450 @item begin-more-emph
3451 Beginning of the second level of emphasized text.
3454 End of the second level of emphasized text.
3456 @item begin-most-emph
3457 Beginning of the third (and final) level of emphasized text.
3460 End of the third (and final) level of emphasized text.
3463 Beginning of verse text.
3466 String used to each space that is further indented than the beginning of
3469 @item begin-verse-line
3470 Beginning of a line of verse.
3472 @item empty-verse-line
3473 End of a line of verse.
3475 @item begin-last-stanza-line
3476 Beginning of the last line of a verse stanza.
3478 @item end-last-stanza-line
3479 End of the last line of a verse stanza.
3485 Beginning of an example region. To make use of this, an
3486 @samp{<example>} tag is needed.
3489 End of an example region. To make use of this, an @samp{</example>} tag
3493 Begin a centered line.
3496 End a centered line.
3499 Begin a quoted region.
3502 End a quoted region.
3504 @item begin-quote-item
3505 Begin a quote paragraph.
3507 @item end-quote-item
3508 End a quote paragraph.
3511 Begin an unordered list.
3514 End an unordered list.
3516 @item begin-uli-item
3517 Begin an unordered list item.
3520 End an unordered list item.
3523 Begin an ordered list.
3526 End an ordered list.
3528 @item begin-oli-item
3529 Begin an ordered list item.
3532 End an ordered list item.
3535 Begin a definition list.
3538 End a definition list.
3541 Begin a definition list item.
3544 End a definition list item.
3547 Begin a definition list term.
3550 End a definition list term.
3553 Begin a definition list entry.
3556 End a definition list entry.
3564 @item begin-table-group
3565 Begin a table grouping.
3567 @item end-table-group
3568 End a table grouping.
3570 @item begin-table-row
3576 @item begin-table-entry
3577 Begin a table entry.
3579 @item end-table-entry
3584 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3585 @comment node-name, next, previous, up
3586 @subsection Tag specifications for special markup
3587 @cindex publishing, markup tags
3589 @anchor{muse-publish-markup-tags}
3590 @code{muse-publish-markup-tags}
3592 A list of tag specifications, for specially marking up text.
3594 XML-style tags are the best way to add custom markup to Muse. This is
3595 easily accomplished by customizing this list of markup tags.
3597 For each entry, the name of the tag is given, whether it expects a
3598 closing tag and/or an optional set of attributes, whether it is
3599 nestable, and a function that performs whatever action is desired within
3600 the delimited region.
3602 The tags themselves are deleted during publishing, before the function
3603 is called. The function is called with three arguments, the beginning
3604 and end of the region surrounded by the tags. If properties are
3605 allowed, they are passed as a third argument in the form of an alist.
3606 The `end' argument to the function is always a marker.
3608 Point is always at the beginning of the region within the tags, when the
3609 function is called. Wherever point is when the function finishes is
3610 where tag markup will resume.
3612 These tag rules are processed once at the beginning of markup, and once
3613 at the end, to catch any tags which may have been inserted in-between.
3615 @node Style Elements, , Markup Tags, Common Elements
3616 @comment node-name, next, previous, up
3617 @subsection Parameters used for defining styles
3618 @cindex publishing, style elements
3620 Style elements are tags that define a style. Use
3621 @code{muse-define-style} to create a new style.
3624 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3627 @subheading Usable elements
3632 File extension to use for publishing files with this style.
3635 File extension to use for publishing links to Muse files with this
3639 File extension to use for publishing second-stage files with this style.
3641 For example, PDF publishing generates a LaTeX file first, then a PDF
3642 from that LaTeX file.
3645 List of markup rules for publishing a page with Muse.
3646 @xref{muse-publish-markup-regexps}.
3649 An alist of style types to custom functions for that kind of text.
3650 @xref{muse-publish-markup-functions}.
3653 Strings used for marking up text with this style.
3655 These cover the most basic kinds of markup, the handling of which
3656 differs little between the various styles.
3659 A list of tag specifications, used for handling extra tags.
3660 @xref{muse-publish-markup-tags}.
3663 A table of characters which must be represented specially.
3666 A function that is to be executed on the newly-created publishing buffer
3667 (or the current region) before any publishing occurs.
3669 This is used to set extra parameters that direct the publishing process.
3672 A function that is to be executed on the publishing buffer (or the
3673 current region) immediately after applying all of the markup regexps.
3675 This is used to fix the order of table elements (header, footer, body)
3679 A function that is to be executed on the publishing buffer after
3680 :before-end, and immediately after inserting the header and footer.
3682 This is used for generating the table of contents as well as setting the
3686 A function that is to be executed after saving the published file, but
3687 while still in its buffer.
3689 This is used for generating second-stage documents like PDF files from
3690 just-published LaTeX files.
3693 Header used for publishing files of this style.
3695 This may be a variable, text, or a filename. It is inserted at the
3696 beginning of a file, after evaluating the publishing markup.
3699 Footer used for publishing files of this style.
3701 This may be a variable, text, or a filename. It is inserted at the end
3702 of a file, after evaluating the publishing markup.
3705 Style sheet used for publishing files of this style.
3707 This may be a variable or text. It is used in the header of HTML and
3708 XHTML based publishing styles.
3711 The function used to browse the published result of files of this style.
3715 @node Deriving Styles, , Common Elements, Extending Muse
3716 @comment node-name, next, previous, up
3717 @section Deriving a new style from an existing one
3718 @cindex publishing styles, deriving
3720 To create a new style from an existing one, use @code{muse-derive-style}
3721 as follows. This is a good way to fix something you don't like about a
3722 particular publishing style, or to personalize it.
3725 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3728 The derived name is a string defining the new style, such as "my-html".
3729 The base name must identify an existing style, such as "html" -- if you
3730 have loaded @file{muse-html}. The style parameters are the same as
3731 those used to create a style, except that they override whatever
3732 definitions exist in the base style. However, some definitions only
3733 partially override. The following parameters support partial
3736 @xref{Style Elements}, for a complete list of all parameters.
3741 If a markup function is not found in the derived style's function list,
3742 the base style's function list will be queried.
3745 All regexps in the current style and the base style(s) will be used.
3748 If a markup string is not found in the derived style's string list, the
3749 base style's string list will be queried.
3754 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
3755 @comment node-name, next, previous, up
3756 @chapter Getting Help and Reporting Bugs
3757 @cindex help, getting
3758 @cindex bugs, reporting
3760 After you have read this guide, if you still have questions about
3761 Muse, or if you have bugs to report, there are several places you can
3767 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
3768 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
3772 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
3773 that Michael Olson (the current maintainer) made for Muse.
3776 Muse has several different mailing lists.
3780 @item muse-el-announce
3781 Low-traffic list for Muse-related announcements.
3783 You can join this mailing list (@email{muse-el-announce@@gna.org})
3784 using the subscription form at
3785 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
3786 mailing list is also available via Gmane (@url{http://gmane.org/}). The
3787 group is called @samp{gmane.emacs.muse.announce}.
3789 @item muse-el-discuss
3790 Discussion, bugfixes, suggestions, tips, and the like for Muse.
3791 This mailing list also includes the content of muse-el-announce.
3793 You can join this mailing list (@email{muse-el-discuss@@gna.org})
3794 using the subscription form at
3795 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
3796 list is also available via Gmane with the identifier
3797 @samp{gmane.emacs.muse.general}.
3800 Log messages for commits made to Muse.
3802 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
3803 the subscription form at
3804 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
3805 is also available via Gmane with the identifier
3806 @samp{gmane.emacs.muse.scm}.
3808 @item muse-el-commits
3809 Generated bug reports for Emacs Muse. If you use our bug-tracker at
3810 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
3811 sent to this list automatically.
3813 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
3814 the subscription form at
3815 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
3816 is also available via Gmane with the identifier
3817 @samp{gmane.emacs.muse.cvs}.
3819 @item muse-el-internationalization
3820 Discussion of translation of the Muse website and documentation into
3823 You can join this mailing list
3824 (@email{muse-el-internationalization@@gna.org}) using the subscription
3825 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
3826 mailing list is also available via Gmane with the identifier
3827 @samp{gmane.emacs.muse.internationalization}.
3832 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
3833 contributors are frequently around and willing to answer your
3834 questions. The @samp{#muse} channel is also available for
3835 Muse-specific help, and its current maintainer hangs out there.
3838 The maintainer of Emacs Muse, Michael Olson, may be contacted at
3839 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
3840 it is often better to use the muse-el-discuss mailing list.
3844 @node History, Contributors, Getting Help and Reporting Bugs, Top
3845 @comment node-name, next, previous, up
3846 @chapter History of This Document
3847 @cindex history, of Muse
3851 John Wiegley started Muse upon realizing that EmacsWiki had some serious
3852 limitations. Around February 2004, he started making "emacs-wiki version
3853 3.00 APLHA", which eventually became known as Muse.
3855 Most of those who frequent the emacs-wiki mailing list continued to use
3856 emacs-wiki, mainly because Planner hasn't been ported over to it.
3858 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
3859 John Wiegley's request.
3862 Michael Olson overhauled this document and added many new sections in
3863 preparation for the first release of Muse (3.01).
3867 @node Contributors, GNU Free Documentation License, History, Top
3868 @comment node-name, next, previous, up
3869 @chapter Contributors to This Documentation
3870 @cindex contributors
3872 The first draft of this document was taken from the emacs-wiki texinfo
3873 manual. Michael Olson adapted it for Muse and added most of its
3876 John Sullivan did a majority of the work on the emacs-wiki texinfo
3879 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
3880 emacs-wiki texinfo manual.
3883 @node GNU Free Documentation License, Concept Index, Contributors, Top
3884 @appendix GNU Free Documentation License
3885 @include doclicense.texi
3888 @node Concept Index, , GNU Free Documentation License, Top
3889 @comment node-name, next, previous, up