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 @item List upstream changes that are missing from your local copy.
306 Do this whenever you want to see whether new changes have been committed
307 to Muse. If you wish, you may skip this step and proceed directly to
311 # Change to the source directory you are interested in.
314 # Fetch new changes from the repository, but don't apply them yet
317 # Display log messages for the new changes
321 ``origin'' is git's name for the location where you originally got Muse
322 from. You can change this location at any time by editing the
323 @file{.git/config} file in the directory where the Muse source was
326 @cindex updating Muse with git
327 @item Update to the latest version by pulling in any missing changes.
334 git will show how many files changed, and will provide a visual display
335 for how many lines were changed in each file.
339 There are other ways to interact with the Muse repository.
342 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
343 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
344 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
347 The latest development snapshot can lag behind the git repo by as much
348 as 20 minutes, but never more than that.
350 @node Installation, Getting Started, Obtaining Muse, Top
351 @comment node-name, next, previous, up
352 @chapter Compiling and Installing Muse
354 Muse may be compiled and installed on your machine.
356 @subheading Compilation
357 @cindex compiling Muse
359 This is an optional step, since Emacs Lisp source code does not
360 necessarily have to be byte-compiled. Byte-compilation may yield a very
361 slight speed increase.
363 A working copy of Emacs or XEmacs is needed in order to compile Emacs
364 Muse. By default, the program that is installed with the name
365 @command{emacs} will be used.
367 If you want to use the @command{xemacs} binary to perform the
368 compilation, you copy @file{Makefile.defs.default} to
369 @file{Makefile.defs} in the top-level directory, and then edit
370 @file{Makefile.defs} as follows. You can put either a full path to an
371 Emacs or XEmacs binary or just the command name, as long as it is in the
372 @env{PATH}. Depending on your setup, changes to @option{PREFIX},
373 @option{ELISPDIR}, and @option{INFODIR} may also need to be made.
377 SITEFLAG = -no-site-file
378 # Edit the section as necessary
379 install_info = install-info --section "XEmacs 21.4" $(1).info \
383 Running @code{make} in the top-level directory should compile the Muse
384 source files in the @file{lisp} directory, and generate an autoloads
385 file in @file{lisp/muse-autoloads.el}.
387 @subheading Installation
388 @cindex installing Muse
390 Muse may be installed into your file hierarchy by doing the following.
392 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
393 top-level directory, if you haven't done so already. Then edit the
394 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
395 want the source and compiled Muse files to be installed and
396 @env{INFODIR} indicates where to put the Muse manual. As mentioned
397 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
398 in the Compilation section if you are using XEmacs.
400 If you are installing Muse on a Debian or Ubuntu system, you might want
401 to change the value of @env{INSTALLINFO} as specified in
402 @file{Makefile.defs}.
404 If you wish to install Muse to different locations than the defaults
405 specify, edit @file{Makefile.defs} accordingly.
407 Run @code{make} as a normal user, if you haven't done so already.
409 Run @code{make install} as the root user if you have chosen installation
410 locations that require root permissions.
413 @cindex ELPA package for Muse
415 For those used to installing software packages, there will be a
416 @code{muse} package available in the Emacs Lisp Package Archive
417 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
418 will be compiled and installed automatically in a user-specific
419 location. For more information on ELPA, see
420 @uref{http://tromey.com/elpa/}.
422 @node Getting Started, Projects, Installation, Top
423 @comment node-name, next, previous, up
424 @chapter Getting Started
428 * Loading Muse:: How to load Muse.
429 * Using Muse Mode:: How to edit files in Muse.
430 * Publishing Files Overview:: Publishing a single file or project.
431 * File Extensions:: Using a different file extension.
434 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
435 @comment node-name, next, previous, up
436 @section How to Load Muse
437 @cindex settings, init file
439 To use Muse, add the directory containing its files to your
440 @code{load-path} variable, in your @file{.emacs} file. Then, load in
441 the authoring mode, and the styles you wish to publish to. An example
445 (add-to-list 'load-path "<path to Muse>")
447 (require 'muse-mode) ; load authoring mode
449 (require 'muse-html) ; load publishing styles I use
450 (require 'muse-latex)
451 (require 'muse-texinfo)
452 (require 'muse-docbook)
454 (require 'muse-project) ; publish files in projects
457 An easy way of seeing which settings are available and changing settings
458 is to use the Muse customization interface. To do this, type
459 @kbd{M-x customize-group muse RET}. Each of the options has its own
460 documentation. Options are grouped logically according to what effect
463 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
464 @comment node-name, next, previous, up
465 @section How to Edit Files in Muse
466 @cindex editing Muse files
468 Muse Mode should automatically be activated when you visit a file with a
469 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
470 available in the @file{examples} directory of the Muse distribution.
471 You can tell that Muse Mose has been activated by checking for the text
472 ``Muse'' in your mode line. If Muse Mode has not been activated, you
473 may activate it by type @kbd{M-x muse-mode RET}.
475 You will notice that Muse files are highlighted very simply. Links are
476 colored blue, headings are large and bold text, and @verb{|<example>|}
477 tags are colored in grey.
479 There are several different ways to edit things like links, which hide
480 the underlying Muse markup. One way is to toggle font-locking off by
481 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
482 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
483 on. Another way is just to move into the text and edit it. Markup can
484 also be removed by normal deletion methods, though some side effects
485 might require a second deletion.
487 For the particular case of editing links, it is easiest to move to the
488 link and do @kbd{C-c C-e}, which is also @kbd{M-x
489 muse-edit-link-at-point}. This prompts you for the link and its
490 description, using the previous contents of the link as initial values.
491 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
492 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
493 followed by hitting @kbd{RET} on them.
495 If you want to add a new list item, this may by accomplished by hitting
496 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
497 dash is the Muse markup that indicates a list item. It is also possible
498 to created ``nested'' lists with this command, by adjusting the number
499 of spaces in front of the dashes. If you have lists with long lines,
500 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
503 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
504 @comment node-name, next, previous, up
505 @section Publishing a Single File or Project
506 @cindex editing Muse files
508 The command @kbd{M-x muse-project-publish-this-file} will publish the
509 current document to any available publishing style (a publishing style
510 is an output format, like HTML or Docbook), placing the output in the
511 current directory. If you are in Muse Mode, this command will be bound
512 to @kbd{C-c C-t}. If the file has been published recently, and its
513 contents have not changed, running @kbd{C-c C-t} again will not publish
514 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
516 If you have set up projects and are visiting a file that is part of a
517 project, then @kbd{C-c C-t} will restrict the output formats to those
518 which are used by the project, and will automatically publish to the
519 output directory defined by the project. If you want to publish to a
520 different directory or use a different format, then use @kbd{C-c M-C-t},
521 which is also @kbd{M-x muse-publish-this-file}.
523 If the currently opened file is part of a defined project in
524 @code{muse-project-alist}, it (and the rest of the changed files in a
525 project) may be published using @kbd{C-c C-p}.
527 @node File Extensions, , Publishing Files Overview, Getting Started
528 @comment node-name, next, previous, up
529 @section Using a Different File Extension
530 @cindex file extension, specifying
532 By default, Muse expects all project files to have the file extension
533 @file{.muse}. Files without this extension will not be associated with
534 Muse mode and will not be considered part of any project, even if they
535 are within a project directory.
537 If you don't want to use @file{.muse}, you can customize the extension
538 by setting the value of @code{muse-file-extension}.
540 If you don't want to use any extension at all, and want Muse to
541 autodetect project files based on their location, then add the following
542 to your Muse settings file.
545 (setq muse-file-extension nil
549 Note that if you chose to have @code{muse-file-extension} set to
550 @code{nil}, you may have trouble if your @file{.emacs} file or other
551 init scripts attempt to visit a Muse file. (A very common example of
552 this is if you use Planner with Muse and run @code{(plan)} from your
553 @file{.emacs}.) If you wish to visit Muse files from your
554 @file{.emacs}, be sure to also add the following additional code before
555 any such visits happen:
558 (add-hook 'find-file-hooks 'muse-mode-maybe)
562 @node Projects, Keystroke Summary, Getting Started, Top
563 @comment node-name, next, previous, up
564 @chapter Creating and Managing Muse Projects
567 Often you will want to publish all the files within a directory to a
568 particular set of output styles automatically. To support, Muse
569 allows for the creation of "projects".
572 * Single Project:: A single-project example.
573 * Multiple Projects:: A multiple-project example.
574 * Projects and Subdirectories:: Publishing subdirectories in projects.
575 * Options for Projects:: Listing of available options for projects.
578 @node Single Project, Multiple Projects, Projects, Projects
579 @comment node-name, next, previous, up
580 @section A Single-Project Example
581 @cindex projects, single
583 Here is a sample project, which may be defined in your @file{.emacs}
587 (setq muse-project-alist
588 '(("Website" ("~/Pages" :default "index")
589 (:base "html" :path "~/public_html")
590 (:base "pdf" :path "~/public_html/pdf"))))
593 The above defines a project named "website", whose files are located
594 in the directory @file{~/Pages}. The default page to visit is
595 @file{index}. When this project is published, each page will be
596 output as HTML to the directory @file{~/public_html}, and as PDF to
597 the directory @file{~/public_html/pdf}. Within any project page, you
598 may create a link to other pages using the syntax @samp{[[pagename]]}.
600 If you would like to include only some files from a directory in a Muse
601 project, you may use a regexp in place of @file{~/Pages} in the example.
603 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
604 @comment node-name, next, previous, up
605 @section A Multiple-Project Example
606 @cindex projects, multiple
608 It is possible to specify multiple projects. Here is an example of
609 three projects: a generic website, a projects area, and a day-planner
610 (the day-planner part requires Planner Mode---see
611 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
614 (setq muse-project-alist
615 '(("Website" ("~/Pages" :default "index")
616 (:base "html" :path "~/public_html"))
617 (("Projects" ("~/Projects" :default "index")
619 :path "~/public_html/projects"
620 :exclude "/TopSecret")
622 :path "~/public_html/projects/pdf"
623 :exclude "/TopSecret")))
626 :major-mode planner-mode
627 :visit-link planner-visit-link)
628 (:base "planner-xhtml"
629 :path "~/public_html/plans"))))
632 The @option{:major-mode} attribute specifies which major to use when
633 visiting files in this directory.
635 The @option{:visit-link} attribute specifies the function to call when
638 The @option{:exclude} attribute has a regexp that matches files to never
641 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
642 @comment node-name, next, previous, up
643 @section Publishing Subdirectories in Projects
644 @cindex projects, subdirectories
646 If you want to publish a directory and all of its subdirectories, Muse
647 provides two convenience functions that together generate the proper
648 rules for you. Note that we use the backtick to begin this
649 muse-project-alist definition, rather than a single quote.
652 (setq muse-project-alist
653 `(("Website" ("~/Pages" :default "index")
654 (:base "html" :path "~/public_html"))
655 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
657 ;; Publish this directory and its subdirectories. Arguments
658 ;; are as follows. The above `muse-project-alist-dirs' part
660 ;; 1. Source directory
661 ;; 2. Output directory
662 ;; 3. Publishing style
663 ;; remainder: Other things to put in every generated style
664 ,@@(muse-project-alist-styles "~/Blog"
669 The @code{muse-project-alist-dirs} function takes a directory and
670 returns it and all of its subdirectories in a list.
672 The @code{muse-project-alist-styles} function is explained by the
675 The ``blosxom'' text is the name of another publishing style, much like
676 ``html''. @xref{Blosxom}, for further information about it. You can
677 use any publishing style you like for the third argument to
678 @code{muse-project-alist-styles}.
680 @node Options for Projects, , Projects and Subdirectories, Projects
681 @comment node-name, next, previous, up
682 @section Listing of Available Options for Projects
683 @cindex projects, options
684 @cindex muse-project-alist, reference
686 This is a listing of all of the various options (or, more accurately:
687 attributes) that may be specified in @code{muse-project-alist}.
689 Each muse-project-alist entry looks like this:
692 (PROJECT-NAME (SOURCES)
696 We refer to these names below.
698 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
699 The first value is a keyword, like @option{:default}. The second part
700 is the value associated with that keyword, such as the text ``index''.
701 If you are familiar with Emacs Lisp property lists, the concept is
702 similar to that, except that in the SOURCES section, single directories
703 can be interspersed with two-value attributes.
705 @subheading Project Name
707 This is a string that indicates the name of the project. It is
708 primarily used for publishing interwiki links with the
709 @file{muse-wiki.el} module.
713 This part of a muse-project-alist entry consists of two-value
714 attributes, and also directory names. If you are publishing a book, the
715 order of directories and attributes is significant.
717 The minimal content for the sources section is a list of directories.
722 Indicates a new chapter of a book. The text of the title of the chapter
723 comes immediately after this keyword.
726 Indicates the end of a book. Directories listed after this one are
727 ignored when publishing a book. The value ``t'' (without quotes) should
728 come immediately after this keyword.
731 A function to call while publishing a book. This is useful for doing
732 something just after a particular chapter.
735 Indicates the beginning of a new part of the book. The text of the
736 title should come immediately after this keyword.
739 Indicate a particular publishing style to use for this part of the book.
740 If this is specified, it should come just after a @option{:part}
744 The default page to visit when browsing a project. Also, if you are
745 using the @file{muse-wiki.el} module, publishing a link to just a
746 project's name will cause it to link to this default file.
749 This specifies a list of pages which should be published every time a
750 project is published (by using @kbd{C-c C-p}, for example), regardless
751 of whether their contents have changed. This is useful for updating
752 Index pages, pages that use the @verb{|<include>|} tag, and other pages
753 that have dynamically-generated content.
756 This specifies the major mode to use when visiting files in this
757 project. The default is @code{muse-mode}.
760 This indicates that while publishing a book, do not automatically create
761 chapters. Values which may follow this are nil (the default, which
762 means that we automatically create chapters), or non-nil, which means
763 that we manually specify chapters with the @option{:book-chapter}
766 @item :publish-project
767 Indicates which function we should call when publishing a project.
770 This specifies a list of variables and values to set when publishing a
771 project. The list should be a property list, which is in the form:
774 (VAR1 VALUE1 VAR2 VALUE2 ...)
778 Specifies the function to call when visiting a link. The default is
779 @code{muse-visit-link-default}. The arguments for that function should
780 be (1) the link and (2) whether to visit the link in a new window.
786 This part of a muse-project-alist entry is composed of lists of
787 attributes. Each list is called an ``output style''.
789 The minimal content for an output style is a @option{:base} attribute
790 and a @option{:path} attribute.
795 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
798 An external URL which can be used to access published files. This is
799 mainly used by the @file{muse-wiki} module when publishing links between
800 two separate projects, if the projects are served on different domains.
802 It is also used by the @file{muse-journal} module to create the RSS or
806 Exclude items matching a regexp from being published. The regexp should
807 usually begin with "/".
810 Only include items matching a regexp when publishing. The regexp should
811 usually begin with "/".
814 The directory in which to store published files.
817 A file containing the timestamps (that is, time of creation) for files
818 in this project. It might eventually used by the @file{muse-blosxom}
819 module, but this option is not currently in use by any Muse code.
824 @node Keystroke Summary, Markup Rules, Projects, Top
825 @comment node-name, next, previous, up
826 @chapter Keys Used in Muse Mode
829 This is a summary of keystrokes available in every Muse buffer.
833 @item C-c C-a (`muse-index')
834 Display an index of all known Muse pages.
836 @item C-c C-b (`muse-find-backlinks')
837 Find all pages that link to this page.
839 @item C-c C-e (`muse-edit-link-at-point')
842 @item C-c C-f (`muse-project-find-file')
843 Open another Muse page. Prompt for the name.
845 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
846 Insert a link to a file interactively.
848 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
849 Insert a tag interactively.
851 @item C-c C-i u, C-c TAB u (`muse-insert-url')
852 Insert a URL interactively.
854 @item C-c C-l (`font-lock-mode')
855 Toggle font lock / highlighting for the current buffer.
857 @item C-c C-p (`muse-project-publish')
858 Publish any Muse pages that have changed.
860 @item C-c C-s (`muse-search')
861 Find text in all files of the current project.
863 @item C-c C-t (`muse-project-publish-this-file')
864 Publish the currently-visited file. Prompt for the style if the current
865 file can be published using more than one style.
867 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
868 Publish the currently-visited file. Prompt for both the style and
871 @item C-c C-v (`muse-browse-result')
872 Show the published result of this page.
874 @item C-c = (`muse-what-changed')
875 Diff this page against the last backup version.
878 Move to the next Wiki reference.
881 Move to the previous Wiki reference.
884 Complete the name of a page from the current project at point.
887 Insert a new list item at point, indenting properly.
890 Decrease the indentation of the list item at point.
893 Increase the indentation of the list item at point.
895 @item M-x muse-colors-toggle-inline-images RET
896 Toggle display of inlined images on/off.
901 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
902 @comment node-name, next, previous, up
903 @chapter Rules for Using Markup
906 A Muse document uses special, contextual markup rules to determine how
907 to format the output result. For example, if a paragraph is indented,
908 Muse assumes it should be quoted.
910 There are not too many markup rules, and all of them strive to be as
911 simple as possible so that you can focus on document creation, rather
915 * Paragraphs:: Paragraphs: centering and quoting.
916 * Headings:: Levels of headings.
917 * Directives:: Directives at the beginning of a
919 * Emphasizing Text:: Bold, italicized, and underlined text.
920 * Footnotes:: Making notes to be shown at the end.
921 * Verse:: Indicating poetic stanzas.
922 * Lists:: Lists of items.
923 * Tables:: Generation of data tables.
924 * Explicit Links:: Hyperlinks and email addresses with
926 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
928 * Images:: Publishing and displaying images.
929 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
930 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
932 * Comments:: Lines to omit from published output.
933 * Tag Summary:: Tags that Muse recognizes.
936 @node Paragraphs, Headings, Markup Rules, Markup Rules
937 @comment node-name, next, previous, up
938 @section Paragraphs: centering and quoting
941 Paragraphs in Muse must be separated by a blank line.
943 @cindex paragraphs, centered
944 @subheading Centered paragraphs and quotations
946 A line that begins with six or more columns of whitespace (either tabs
947 or spaces) indicates a centered paragraph. Alternatively, you can use
948 the @verb{|<center>|} tag to surround regions that are to be published as
951 @cindex paragraphs, quoted
953 But if a line begins with whitespace, though less than six columns, it
954 indicates a quoted paragraph. Alternatively, you can use the
955 @verb{|<quote>|} tag to surround regions that are to be published as
959 @cindex monospace, rendering blocks
960 @cindex HTML, rendering blocks in monospace
961 @subheading Literal paragraphs
963 The @verb{|<example>|} tag is used for examples, where whitespace should
964 be preserved, the text rendered in monospace, and any characters special
965 to the output style escaped.
968 @cindex HTML, inserting a raw block
969 There is also the @verb{|<literal>|} tag, which causes a marked block to
970 be entirely left alone. This can be used for inserting a hand-coded
971 HTML blocks into HTML output, for example.
973 If you want some text to only be inserted when publishing to a
974 particular publishing style, use the @option{style} attribute for the
975 @verb{|<literal>|} tag. An example follows.
978 <literal style="latex">
979 A LaTeX-based style was used in the publishing of this document.
983 This will leave the region alone if the current publishing style is
984 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
985 otherwise. It is also possible to leave the text alone only for one
986 particular style, rather than its derivations, by adding
987 @code{exact="t"} to the tag.
989 @node Headings, Directives, Paragraphs, Markup Rules
990 @comment node-name, next, previous, up
991 @section Levels of headings
994 A heading becomes a chapter or section in printed output -- depending on
995 the style. To indicate a heading, start a new paragraph with one or
996 more asterices, followed by a space and the heading title. Then begin
997 another paragraph to enter the text for that section.
999 All levels of headings will be published. Most publishing styles only
1000 distinguish the between the first 4 levels, however.
1012 @node Directives, Emphasizing Text, Headings, Markup Rules
1013 @comment node-name, next, previous, up
1014 @section Directives at the beginning of a document
1017 Directives are lines beginning with the @samp{#} character that come
1018 before any paragraphs or sections in the document. Directives are of
1019 the form ``#directive content of directive''. You can use any
1020 combination of uppercase and lowercase letters for directives, even if
1021 the directive is not in the list below.
1023 The @code{muse-publishing-directive} function may be used in header and
1024 footer text to access directives. For example, to access the
1025 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
1027 The following is a list of directives that Muse uses.
1032 The author of this document.
1034 If this is not specified, Muse will attempt to figure it out from the
1035 @code{user-full-name} variable.
1039 The date that the document was last modified.
1041 This is used by publishing styles that are able to embed the date
1046 A short description of this document.
1048 This is used by the @code{journal} publishing style to embed information
1049 inside of an RSS/RDF feed.
1053 The title of this document.
1055 If this is not specified, the name of the file is used.
1059 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1060 @comment node-name, next, previous, up
1061 @section Bold, italicized, and underlined text
1062 @cindex emphasizing text
1063 @cindex underlining text
1064 @cindex italicizing text
1065 @cindex verbatim text
1066 @cindex monospace, rendering words
1068 To emphasize text, surround it with certain specially recognized
1074 ***very strong emphasis***
1076 =verbatim and monospace=
1080 While editing a Muse document in Muse mode, these forms of emphasis will
1081 be highlighted in a WYSIWYG manner. Each of these forms may span
1084 Verbatim text will be colored as gray by default. To change this,
1085 customize @code{muse-verbatim-face}.
1087 You can also use the @verb{|<code>|} tag to indicate verbatim and
1088 monospace text. This is handy for regions that have an ``='' in them.
1090 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1091 @comment node-name, next, previous, up
1092 @section Making notes to be shown at the end
1095 A footnote reference is simply a number in square brackets. To define
1096 the footnote, place this definition at the bottom of your file.
1097 @samp{footnote-mode} can be used to greatly facilitate the creation of
1098 these kinds of footnotes.
1100 Footnotes are defined by the same number in brackets occurring at the
1101 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1102 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1103 the point of insertion.
1105 @node Verse, Lists, Footnotes, Markup Rules
1106 @comment node-name, next, previous, up
1107 @section Indicating poetic stanzas
1111 Poetry requires that whitespace be preserved, but without resorting to
1112 monospace. To indicate this, use the following markup, reminiscent of
1116 > A line of Emacs verse;
1117 > forgive its being so terse.
1120 You can also use the @verb{|<verse>|} tag, if you prefer.
1124 A line of Emacs verse;
1125 forgive its being so terse.
1129 @cindex verses, multiple stanzas
1130 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1135 A line of Emacs verse;
1136 forgive its being so terse.
1138 In terms of terse verse,
1143 @node Lists, Tables, Verse, Markup Rules
1144 @comment node-name, next, previous, up
1145 @section Lists of items
1148 Lists are given using special characters at the beginning of a line.
1149 Whitespace must occur before bullets or numbered items, to distinguish
1150 from the possibility of those characters occurring in a real sentence.
1152 @cindex lists, bullets
1153 These are rendered as a bullet list.
1162 @cindex lists, enumerated
1163 An enumerated list follows.
1172 @cindex lists, definitions
1173 Here is a definition list.
1177 This is a first definition
1178 And it has two lines;
1179 no, make that three.
1181 Term2 :: This is a second definition
1184 @subheading Nested lists
1186 @cindex lists, nested
1187 It is possible to nest lists of the same or different kinds. The
1188 ``level'' of the list is determined by the amount of initial whitespace.
1193 - Level 1, bullet item one
1194 1. Level 2, enum item one
1195 2. Level 2, enum item two
1196 - Level 1, bullet item two
1197 1. Level 2, enum item three
1198 2. Level 2, enum item four
1202 @subheading Breaking list items
1204 @cindex lists, breaking lines
1205 If you want to break up a line within any list type, just put one blank
1206 line between the end of the previous line and the beginning of the next
1207 line, using the same amount of initial indentation.
1210 - bullet item 1, line 1
1212 bullet item 1, line 2
1218 - bullet item 2, line 1
1220 bullet item 2, line 2
1223 @node Tables, Explicit Links, Lists, Markup Rules
1224 @comment node-name, next, previous, up
1225 @section Generation of data tables
1228 @cindex tables, simple
1229 Only very simple tables are supported. The syntax is as follows.
1232 Double bars || Separate header fields
1234 Single bars | Separate body fields
1235 Here are more | body fields
1237 Triple bars ||| Separate footer fields
1240 Some publishing styles require header fields to come first, then footer
1241 fields, and then the body fields. You can use any order for these
1242 sections that you like, and Muse will re-order them for you at
1245 If you wish to disable table generation for one Muse file, add the
1246 directive @samp{#disable-tables t} to the top of the file.
1248 @subheading Other table formats
1250 @cindex tables, orgtbl-mode style
1251 It is possible to publish very basic Orgtbl-mode style tables.
1254 | org | style | table |
1255 |------+-------+-------|
1259 |------+-------+-------|
1263 If you are used to the way that Org Mode publishes these tables, then
1264 customize `muse-html-table-attributes' to the following, in order to get
1265 a similar kind of output.
1268 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1271 @cindex tables, table.el style
1272 @file{table.el} style tables are also supported, as long as
1273 @file{table.el} itself supports outputting tables for a particular
1274 publishing style. At the time of this writing, the ``html'', ``latex'',
1275 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1276 from these styles will also work.
1288 @node Explicit Links, Implicit Links, Tables, Markup Rules
1289 @comment node-name, next, previous, up
1290 @section Hyperlinks and email addresses with descriptions
1291 @cindex links, explicit
1293 A hyperlink can reference a URL, or another page within a Muse
1294 project. In addition, descriptive text can be specified, which should
1295 be displayed rather than the link text in output styles that supports
1296 link descriptions. The syntax is as follows.
1299 [[link target][link description]]
1300 [[link target without description]]
1303 Thus, the current maintainer's homepage for Muse can be found
1304 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1305 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1307 @node Implicit Links, Images, Explicit Links, Markup Rules
1308 @comment node-name, next, previous, up
1309 @section Bare URLs, WikiNames, and InterWiki links
1310 @cindex links, implicit
1314 @cindex Email addresses
1316 A URL or email address encountered in the input text is published as a
1317 hyperlink. These kind of links are called @dfn{implicit links} because
1318 they are not separated from the rest of the Muse document in any way.
1320 Some characters in URLs will prevent Muse from recognizing them as
1321 implicit links. If you want to link to a URL containing spaces or any of
1322 the characters ``][,"'`()<>^'', you will have to make the link
1323 explicit. The punctuation characters ``.,;:'' are also not recognized as
1324 part of a URL when they appear at its end. For information on how to
1325 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1326 addresses with descriptions}.
1329 If the @command{muse-wiki} module is loaded, another form of implicit
1330 link will be made available. WikiNames, which are typed in CamelCase,
1331 are highlighted and published as links, provided that the file they
1334 Customization of WikiName recognition may be accomplished by editing the
1335 @code{muse-wiki-wikiword-regexp} option and subsequently running
1336 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1337 If you use the Customize interface, the latter will be done
1340 @cindex InterWiki links
1341 @cindex inter-project links
1342 The @command{muse-wiki} module also allows for InterWiki links. These
1343 are similar to WikiWords, but they specify both the project and page of
1344 a file. The names of your project entries in @code{muse-project-alist}
1345 will be used as InterWiki names by default. Several examples follow.
1348 Blog::DocumentingMuse
1353 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1354 the project name, and @samp{DocumentingMuse} is the page name. In the
1355 second example, @samp{#} is the interwiki delimiter. If the name of a
1356 project occurs by itself in text, like the third case, it will be
1357 colorized and published as a link to the default page of the given
1360 Customization of interwiki links may be accomplished by editing the
1361 @code{muse-wiki-interwiki-alist} option.
1363 It is also possible to link to an anchor in an interwiki document. This
1364 is called a ``three-part link''. Examples of this follow.
1367 Blog::DocumentingMuse#anchor1
1368 Projects#EmacsMuse#anchor2
1371 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1372 @comment node-name, next, previous, up
1373 @section Publishing and displaying images
1375 @cindex links, with images
1376 @subheading Image links
1378 Links to images may be used in either the target or the description, or
1379 both. Thus, the following code will publish as a clickable image that
1380 points to @url{http://mwolson.org/}.
1383 [[http://mwolson.org/][/static/logos/site-logo.png]]
1386 Normally, images in the link part will be inlined.
1388 If you want these images to be published as links instead, place the
1389 text ``URL:'' immediately in front of the link text. An example
1393 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1396 @cindex images, displaying
1397 @cindex images, local
1398 @subheading Displaying images in Muse mode
1399 If a link to a locally-available image is encountered in the link
1400 description, Muse mode will attempt to display it if your version of
1403 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1404 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1406 The method for finding images may be altered by customizing the
1407 @code{muse-colors-inline-image-method} option. One useful value for
1408 this option is @code{muse-colors-use-publishing-directory}, which tells
1409 Muse mode to look in the directory where the current file will be
1410 published. The default is to look in the current directory. Relative
1411 paths like @samp{../pics/} should work for either setting.
1413 Eventually, it is hoped that Muse will be able to copy images from the a
1414 ``source'' directory to a publishing directory by customizing
1415 @code{muse-project-alist}, but this has not been implemented yet.
1417 @cindex images, without descriptions
1418 @cindex images, inlined
1419 @subheading Publishing simple images
1420 The following example will display correctly and publish correctly if a
1421 @acronym{PNG} file called @file{TestLogo.png} exists in the
1422 @file{../pics/} directory. If text is on the same line as the picture,
1423 it will remain so in the output.
1429 @cindex images, captions
1430 @subheading Publishing images with captions
1431 If you want to add a caption to an image, use the following syntax.
1432 This will center the image (if the output format supports it) and add a
1433 centered caption below the picture. Formats that do not support
1434 centering the image will instead leave it against the left margin.
1437 [[../pics/mycat.png][My cat Dexter]]
1440 Images with captions may only occur in their own paragraphs, with no
1441 text on the same line. Otherwise, the published output will not be
1442 syntactically correct.
1444 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1445 @comment node-name, next, previous, up
1446 @section Inserting a horizontal line or anchor
1448 @cindex horizontal rules
1450 @subheading Horizontal Rules
1452 Four or more dashes indicate a horizontal rule. Be sure to put blank
1453 lines around it, or it will be considered part of the proceeding or
1454 following paragraph!
1457 @cindex links, with target on same page
1460 If you begin a line with "#anchor" -- where "anchor" can be any word
1461 that doesn't contain whitespace -- it defines an anchor at that point
1462 into the document. This point can be referenced using "page#anchor" as
1463 the target in a Muse link.
1465 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
1466 @comment node-name, next, previous, up
1467 @section Evaluating Emacs Lisp code in documents for extensibility
1468 @cindex lisp, embedded
1470 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1471 which is the only Muse tag supported in a style's header and footer
1472 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1473 text you wish. The inserted output will get marked up, if the
1474 @verb{|<lisp>|} tag appears within the main text of the document.
1477 <lisp>(concat "This form gets " "inserted")</lisp>
1480 @cindex lisp, and insert command
1481 Note that you should not use the @code{insert} command within a set of
1482 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1483 tags will be automatically inserted into the document.
1485 It is also possible to treat the output as if it were surrounded by the
1486 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1487 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1488 attribute of the @verb{|<lisp>|} tag.
1491 <lisp markup="example">
1492 (concat "Insert" " me")
1496 Other languages also have tags that cause source code to be evaluated.
1497 @xref{Tag Summary}, for details.
1499 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
1500 @comment node-name, next, previous, up
1501 @section Lines to omit from published output
1503 @cindex publishing, omitting lines
1505 Use the following syntax to indicate a comment. Comments will not be
1509 ; Comment text goes here.
1512 That is, only a semi-colon at the beginning of a line, followed by a
1513 literal space, will cause that line to be treated as a comment.
1515 You can alternatively surround the region with the @verb{|<comment>|}
1518 If you wish the comment to be published, but just commented out using
1519 the comment syntax of the output format, then set
1520 @option{muse-publish-comments-p} to non-nil.
1522 @node Tag Summary, , Comments, Markup Rules
1523 @comment node-name, next, previous, up
1524 @section Tags that Muse recognizes
1526 @cindex inserting files at publish time
1527 @cindex publishing, including markup in headers and footers
1528 @cindex publishing, inserting files
1530 Muse has several built-in tags that may prove useful during publishing.
1531 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1532 Muse uses, as well as make your own tags.
1536 If a tag takes arguments, it will look like this, where ``tagname'' is
1537 the name of the tag.
1540 <tagname arg1="string1" arg2="string2">
1543 If you want the tag to look like it came straight from an XHTML
1544 document, you can alternatively do the following.
1547 <tagname arg1="string1" arg2="string2" />
1550 If a tag surrounds some text, it will look like this.
1553 <tagname>Some text</tagname>
1556 If a tag surrounds a large region, it will look like this.
1565 @subheading Tag listing
1567 This is the complete list of tags that Muse accepts, including those
1568 that were mentioned in previous sections.
1573 If publishing to HTML, surround the given text with a @verb{|<span>|}
1574 tag. It takes one argument called ``name'' that specifies the class
1575 attribute of the @verb{|<span>|} tag.
1577 If publishing to a different format, do nothing extra to the text.
1580 Treat the text surrounded by the tag as if they were enclosed in equal
1581 signs, that is, make it monospace.
1584 Run a command on the region, replacing the region with the result of the
1585 command. The command is specified with the ``interp'' argument. If no
1586 value for ``interp'' is given, pass the entire region to the shell.
1588 The ``markup'' argument controls how this section is marked up.
1590 If it is omitted, publish the region with the normal Muse rules.
1592 If "nil", do not mark up the region at all, but prevent Muse from
1593 further interpreting it.
1595 If "example", treat the region as if it was surrounded by the
1596 @verb{|<example>|} tag.
1598 If "src", treat the included text as if it was surrounded by the
1599 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1602 If "verse", treat the region as if it was surrounded by the
1603 @verb{|<verse>|} tag, to preserve newlines.
1605 Otherwise, it should be the name of a function to call, with the buffer
1606 narrowed to the region.
1609 Treat the entire region as a comment. If the option
1610 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1611 publish it using the comment syntax of the current publishing style.
1614 Publish a Table of Contents. This will either be inserted in-place or
1615 at the beginning of the document, depending on your publishing style.
1616 It does not have a delimiting tag.
1618 By default, only 2 levels of headings will be included in the generated
1619 Table of Contents. To change this globally, customize the
1620 @var{muse-publish-contents-depth} option. To change this only for the
1621 current tag, use the ``depth'' argument.
1624 Publish the region in monospace, preserving the newlines in the region.
1625 This is useful for snippets of code.
1628 Insert the given file at the current location during publishing. The
1629 basic use of this tag is as follows, replacing ``included_file'' with
1630 the name of the file that you want to include.
1633 <include file="included_file">
1636 The ``markup'' argument controls how this section is marked up.
1638 If it is omitted, publish the included text with the normal Muse
1641 If "nil", do not mark up the included text at all.
1643 If "example", treat the included text as if it was surrounded by the
1644 @verb{|<example>|} tag.
1646 If "src", treat the included text as if it was surrounded by the
1647 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1650 If "verse", treat the included text as if it was surrounded by the
1651 @verb{|<verse>|} tag, to preserve newlines.
1653 Otherwise, it should be the name of a function to call after inserting
1654 the file with the buffer narrowed to the section inserted.
1657 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1658 The result is then inserted into the document, so you do not need to
1659 explicitly call @code{insert}. All text properties are removed from the
1662 This tag takes the ``markup'' argument. See the description of
1663 @verb{|<command>|} for details.
1666 Make sure that the text enclosed by this tag is published without
1667 escaping it in any way. This is useful for inserting markup directly
1668 into the published document, when Muse does not provide the desired
1672 Mark up the text between the initial and ending tags. The markup
1673 command to use may be specified by the ``function'' argument. The
1674 standard Muse markup routines are used by default if no ``function''
1675 argument is provided.
1677 This is useful for marking up regions in headers and footers. One
1678 example that comes to mind is generating a published index of all of the
1679 files in the current project by doing the following.
1682 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1686 Run the @command{perl} language interpreter on the region, replacing the
1687 region with the result of the command.
1689 This tag takes the ``markup'' argument. See the description of
1690 @verb{|<command>|} for details.
1693 Run the @command{python} language interpreter on the region, replacing
1694 the region with the result of the command.
1696 This tag takes the ``markup'' argument. See the description of
1697 @verb{|<command>|} for details.
1700 Publish the region as a blockquote. This will either be inserted
1701 in-place or at the beginning of the document, depending on your
1702 publishing style. It does not have a delimiting tag.
1705 Run the @command{ruby} language interpreter on the region, replacing the
1706 region with the result of the command.
1708 This tag takes the ``markup'' argument. See the description of
1709 @verb{|<command>|} for details.
1712 Publish the region using htmlize.
1713 The language to use may be specified by the ``lang'' attribute.
1715 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1716 the value of the ``lang'' attribute.
1718 This tag requires htmlize 1.34 or later in order to work. If this is
1719 not satisfied, or the current publishing style is not HTML-based, Muse
1720 will publish the region like an @verb{|<example>|} tag.
1723 This is used when you want to prevent Muse from trying to interpret some
1724 markup. Surround the markup in @verb{|<verbatim>|} and
1725 @verb{|</verbatim>|}, and it will not be interpreted.
1727 This tag was used often in previous versions of Muse because they did
1728 not support whole-document escaping of specials. Now, it will only be
1729 needed for other tags, and perhaps footnotes as well.
1732 Preserve the newlines in the region. In formats like HTML, newlines are
1733 removed by default, hence the need for this tag. In other publishing
1734 styles, this tag may cause the text to be indented slightly in a way
1735 that looks nice for poetry and prose.
1739 @node Publishing Styles, Extending Muse, Markup Rules, Top
1740 @comment node-name, next, previous, up
1741 @chapter Publishing Various Types of Documents
1742 @cindex publishing styles
1744 One of the principle features of Muse is the ability to publish a simple
1745 input text to a variety of different output styles. Muse also makes it
1746 easy to create new styles, or derive from an existing style.
1749 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1750 * Book:: Publishing entries into a compilation.
1751 * ConTeXt:: Publishing ConTeXt documents.
1752 * DocBook:: Publishing in DocBook XML form.
1753 * HTML:: Publishing in HTML or XHTML form.
1754 * Journal:: Keeping a journal or blog.
1755 * LaTeX:: Publishing LaTeX documents.
1756 * Poem:: Publish a poem to LaTex or PDF.
1757 * Texinfo:: Publish entries to Texinfo format or PDF.
1758 * XML:: Publish entries to XML.
1761 @node Blosxom, Book, Publishing Styles, Publishing Styles
1762 @comment node-name, next, previous, up
1763 @section Integrating Muse and pyblosxom.cgi
1764 @cindex blog, one-file-per-entry style
1766 The Blosxom publishing style publishes a tree of categorised files to a
1767 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1768 In other words, each blog entry corresponds with one file.
1771 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1772 * Blosxom Entries:: Format of a Blosxom entry and automation.
1773 * Blosxom Options:: Blosxom styles and options provided.
1776 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1777 @comment node-name, next, previous, up
1778 @subsection Other tools needed for the Blosxom style
1780 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1781 installed on a machine that you have upload access to.
1783 The following additional components are required in order to make the
1784 date of blog entries display as something sensible.
1788 A script to gather date directives from the entire blog tree into a
1789 single file. The file must associate a blog entry with a date.
1792 A plugin for (py)blosxom that reads this file.
1795 These 2 things are provided for @command{pyblosxom.cgi} in the
1796 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1797 former service, while @file{hardcodedates.py} provides the latter
1798 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1799 script will be found/written.
1801 Here is a sample listing from my @file{timestamps} file, which maps
1802 each file to a date. This can really be in any format, as long as your
1803 date-gathering script and your plugin can both understand it.
1806 2005-04-01-14-16 personal/paper_cranes
1807 2005-03-21 personal/spring_break_over
1808 2004-10-24 personal/finished_free_culture
1811 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1812 @file{getstamps.py}. Note that you will need to set the current
1813 directory to where your Muse files are, execute @file{getstamps.py}, and
1814 then move the generated timestamps file to your publishing directory.
1816 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1817 @comment node-name, next, previous, up
1818 @subsection Format of a Blosxom entry and automation
1820 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1821 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1822 plus whatever normal content is desired.
1824 The date directive is not used directly by @command{pyblosxom.cgi} or
1825 this program. You need to have the two additional items from the former
1826 section to make use of this feature.
1828 There is a function called @code{muse-blosxom-new-entry} that will
1829 automate the process of making a new blog entry. To make use of it, do
1834 Customize @code{muse-blosxom-base-directory} to the location that your
1835 blog entries are stored.
1838 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1839 use the following code to assign this function to @kbd{C-c p l'}.
1842 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1846 You should create your directory structure ahead of time under your base
1847 directory. These directories, which correspond with category names, may
1851 When you enter this key sequence, you will be prompted for the category
1852 of your entry and its title. Upon entering this information, a new file
1853 will be created that corresponds with the title, but in lowercase
1854 letters and having special characters converted to underscores. The
1855 title and date directives will be inserted automatically.
1858 @node Blosxom Options, , Blosxom Entries, Blosxom
1859 @comment node-name, next, previous, up
1860 @subsection Blosxom styles and options provided
1862 The following styles and options are available in the Blosxom publishing
1865 @subheading Styles provided
1869 @cindex publishing styles, blosxom-html
1871 Publish Blosxom entries in HTML form.
1873 @cindex publishing styles, blosxom-xhtml
1875 Publish Blosxom entries in XHTML form.
1879 @subheading Options provided
1883 @item muse-blosxom-extension
1884 Default file extension for publishing Blosxom files.
1886 @item muse-blosxom-header
1887 Header used for publishing Blosxom files.
1889 This may be text or a filename.
1891 @item muse-blosxom-footer
1892 Footer used for publishing Blosxom files.
1894 This may be text or a filename.
1896 @item muse-blosxom-base-directory
1897 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1899 This is the top-level directory where your blog entries may be found
1904 @node Book, ConTeXt, Blosxom, Publishing Styles
1905 @comment node-name, next, previous, up
1906 @section Publishing entries into a compilation
1908 This publishing style is used to output ``books'' in LaTeX or PDF
1911 Each page will become a separate chapter in the book, unless the style
1912 keyword @option{:nochapters} is used, in which case they are all run
1913 together as if one giant chapter.
1915 One way of publishing a book is to make a project for it, add the
1916 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1917 with a very specific @option{:include} value to specify some page whose
1918 contents will be checked for the values of @code{#title} and
1919 @code{#date}, and whose name will be used in the output file. Then to
1920 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1921 @kbd{C-c C-p} to trigger the publishing process. An example
1922 @code{muse-project-alist} for this method follows.
1925 (setq muse-project-alist
1926 '(("MyNotes" (:nochapters t ; do automatically add chapters
1927 :book-chapter "Computer Science"
1929 :book-chapter "Mathematics"
1931 :book-chapter "Emacs"
1933 :book-end t ; the rest will not be placed in the book
1934 "~/Notes" ; so we can find the notes-anthology page
1936 :force-publish ("index")
1939 :include "/notes-anthology[^/]*$"
1940 :path "~/public_html/notes")
1941 ;; other publishing styles for each directory go here,
1946 In this example, there would be a file called
1947 @file{~/Notes/notes-anthology.muse}, which would contain just the
1948 following. The resulting book would be published to
1949 @file{~/public_html/notes/notes-anthology.pdf}.
1952 #title My Technology Ramblings
1955 Another way is to call the @code{muse-book-publish-project} function
1956 manually, with a custom project entry. An example of this may be found
1957 in John Wiegley's configuration file at
1958 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
1961 @subheading Styles provided
1965 @cindex publishing styles, book-latex
1967 Publish a book in LaTeX form. The header and footer are different than
1968 the normal LaTeX publishing mode.
1970 @cindex publishing styles, book-pdf
1972 Publish a book in PDF form. The header and footer are different than
1973 the normal PDF publishing mode.
1977 @subheading Options provided
1981 @item muse-book-before-publish-hook
1982 A hook run in the book buffer before it is marked up.
1984 @item muse-book-after-publish-hook
1985 A hook run in the book buffer after it is marked up.
1987 @item muse-book-latex-header
1988 Header used for publishing books to LaTeX.
1990 This may be text or a filename.
1992 @item muse-book-latex-footer
1993 Footer used for publishing books to LaTeX.
1995 This may be text or a filename.
1998 @node ConTeXt, DocBook, Book, Publishing Styles
1999 @comment node-name, next, previous, up
2000 @section Publishing ConTeXt documents
2002 This publishing style is capable of producing ConTeXt or PDF documents.
2004 If you wish to publish PDF documents based on ConTeXt, you will need to
2005 have it installed. For Debian and Ubuntu, this can be accomplished by
2006 installing the ``texlive'' package.
2008 @subheading Styles provided
2012 @cindex publishing styles, context
2014 Publish a ConTeXt document.
2016 @cindex publishing styles, context-pdf
2018 Publish a PDF document, using an external ConTeXt document conversion
2021 @cindex publishing styles, context-slides
2022 @item context-slides
2023 Produce slides from a ConTeXt document.
2025 Here is an example of a slide.
2030 [[Some-sort-of-cute-image.png]]
2035 - Another bullet point.
2042 @cindex publishing styles, context-slides-pdf
2043 @item context-slides-pdf
2044 Publish a PDF document of ConTeXt slides.
2048 @subheading Options provided
2052 @item muse-context-extension
2053 Default file extension for publishing ConTeXt files.
2055 @item muse-context-pdf-extension
2056 Default file extension for publishing ConTeXt files to PDF.
2058 @item muse-context-pdf-program
2059 The program that is called to generate PDF content from ConTeXt content.
2061 @item muse-context-pdf-cruft
2062 Extensions of files to remove after generating PDF output successfully.
2064 @item muse-context-header
2065 Header used for publishing ConTeXt files.
2067 This may be text or a filename.
2069 @item muse-context-footer
2070 Footer used for publishing ConTeXt files.
2072 This may be text or a filename.
2074 @item muse-context-markup-regexps
2075 List of markup regexps for identifying regions in a Muse page.
2077 For more on the structure of this list,
2078 @xref{muse-publish-markup-regexps}.
2080 @item muse-context-markup-functions
2081 An alist of style types to custom functions for that kind of text.
2083 For more on the structure of this list,
2084 @xref{muse-publish-markup-functions}.
2086 @item muse-context-markup-strings
2087 Strings used for marking up text.
2089 These cover the most basic kinds of markup, the handling of which
2090 differs little between the various styles.
2092 @item muse-context-slides-header
2093 Header for publishing a presentation (slides) using ConTeXt.
2095 You can use any of the predefined modules, which are available in the
2096 tex/context/base of your distribution, provided it has TitlePage and
2097 Topic defined. Alternatively, you can use your own style (mystyle) by
2098 replacing ``\\usemodule[]'' with ``\\input mystyle''.
2100 This may be text or a filename.
2102 @item muse-context-slides-markup-strings
2103 Strings used for marking up text in ConTeXt slides.
2105 @item muse-context-markup-specials-document
2106 A table of characters which must be represented specially.
2107 These are applied to the entire document, sans already-escaped
2110 @item muse-context-markup-specials-example
2111 A table of characters which must be represented specially.
2112 These are applied to @verb{|example>|} regions.
2114 With the default interpretation of @verb{|<example>|} regions, no
2115 specials need to be escaped.
2117 @item muse-context-markup-specials-literal
2118 A table of characters which must be represented specially.
2119 This applies to =monospaced text= and @verb{|<code>|} regions.
2121 @item muse-context-markup-specials-url
2122 A table of characters which must be represented specially.
2123 These are applied to URLs.
2125 @item muse-context-markup-specials-image
2126 A table of characters which must be represented specially.
2127 These are applied to image filenames.
2129 @item muse-context-permit-contents-tag
2130 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2133 Most of the time, it is best to have a table of contents on the
2134 first page, with a new page immediately following. To make this
2135 work with documents published in both HTML and ConTeXt, we need to
2136 ignore the @verb{|<contents>|} tag.
2138 If you don't agree with this, then set this option to non-nil,
2139 and it will do what you expect.
2143 @node DocBook, HTML, ConTeXt, Publishing Styles
2144 @comment node-name, next, previous, up
2145 @section Publishing in DocBook XML form
2147 This publishing style is used to generate DocBook XML files.
2149 @subheading Styles provided
2153 @cindex publishing styles, docbook
2155 Publish a file in Docbook form.
2159 @subheading Options provided
2161 This publishing style uses the same options for markup up special
2162 characters as the ``xml'' publishing style. @xref{XML}, for details.
2166 @item muse-docbook-extension
2167 Default file extension for publishing DocBook XML files.
2169 @item muse-docbook-header
2170 Header used for publishing DocBook XML files.
2172 This may be text or a filename.
2174 @item muse-docbook-footer
2175 Footer used for publishing DocBook XML files.
2177 This may be text or a filename.
2179 @item muse-docbook-markup-regexps
2180 List of markup rules for publishing a Muse page to DocBook XML.
2182 @item muse-docbook-markup-functions
2183 An alist of style types to custom functions for that kind of text.
2185 @item muse-docbook-markup-strings
2186 Strings used for marking up text.
2188 These cover the most basic kinds of markup, the handling of which
2189 differs little between the various styles.
2191 @item muse-docbook-encoding-default
2192 The default Emacs buffer encoding to use in published files.
2193 This will be used if no special characters are found.
2195 @item muse-docbook-charset-default
2196 The default DocBook XML charset to use if no translation is
2197 found in @code{muse-xml-encoding-map}.
2201 @node HTML, Journal, DocBook, Publishing Styles
2202 @comment node-name, next, previous, up
2203 @section Publishing in HTML or XHTML form
2205 This publishing style is capable of producing HTML or XHTML documents.
2207 @subheading Styles provided
2211 @cindex publishing styles, html
2213 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2216 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2220 @subheading Options provided
2222 If an HTML option does not have a corresponding XHTML option, it will
2223 be used for both of these publishing styles.
2225 These publishing styles use the same options for markup up special
2226 characters as the ``xml'' publishing style. @xref{XML}, for details.
2230 @item muse-html-extension
2231 Default file extension for publishing HTML files.
2233 @item muse-xhtml-extension
2234 Default file extension for publishing XHTML files.
2236 @item muse-html-style-sheet
2237 Store your stylesheet definitions here.
2239 This is used in @code{muse-html-header}. You can put raw CSS in here or
2240 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2241 @verb{|<lisp>|} markup tags.
2243 If you are publishing to XHTML, then customize the
2244 @code{muse-xhtml-style-sheet} option instead.
2246 @item muse-xhtml-style-sheet
2247 Store your stylesheet definitions here.
2249 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2250 or a @verb{|<link>|} tag to an external stylesheet. This text may
2251 contain @verb{|<lisp>|} markup tags.
2253 @item muse-html-header
2254 Header used for publishing HTML files.
2256 This may be text or a filename.
2258 @item muse-html-footer
2259 Footer used for publishing HTML files.
2261 This may be text or a filename.
2263 @item muse-xhtml-header
2264 Header used for publishing XHTML files.
2266 This may be text or a filename.
2268 @item muse-xhtml-footer
2269 Footer used for publishing XHTML files.
2271 This may be text or a filename.
2273 @item muse-html-anchor-on-word
2274 When true, anchors surround the closest word.
2276 This allows you to select them in a browser (i.e. for pasting), but has
2277 the side-effect of marking up headers in multiple colors if your header
2278 style is different from your link style.
2280 @item muse-html-table-attributes
2281 The attribute to be used with HTML @verb{|<table>|} tags.
2283 If you want to make more-complicated tables in HTML, surround the HTML
2284 with the @verb{|literal|} tag, so that it does not get escaped.
2286 @item muse-html-markup-regexps
2287 List of markup rules for publishing a Muse page to HTML.
2289 @item muse-html-markup-functions
2290 An alist of style types to custom functions for that kind of text.
2292 @item muse-html-markup-strings
2293 Strings used for marking up text as HTML.
2295 These cover the most basic kinds of markup, the handling of which
2296 differs little between the various styles.
2298 @item muse-xhtml-markup-strings
2299 Strings used for marking up text as XHTML.
2301 These cover the most basic kinds of markup, the handling of which
2302 differs little between the various styles.
2304 @item muse-html-markup-tags
2305 A list of tag specifications, for specially marking up HTML.
2306 @xref{muse-publish-markup-tags}, for more information.
2308 @item muse-html-meta-http-equiv
2309 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2311 @item muse-html-meta-content-type
2312 The content type used for the HTML @verb{|<meta>|} tag.
2314 If you are striving for XHTML 1.1 compliance, you may want to change
2315 this to ``application/xhtml+xml''.
2317 @item muse-html-meta-content-encoding
2318 The charset to append to the HTML @verb{|<meta>|} tag.
2320 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2321 and determine the HTML charset from emacs's coding. If set to a string,
2322 this string will be used to force a particular charset.
2324 @item muse-html-charset-default
2325 The default HTML meta charset to use if no translation is found in
2326 @code{muse-xml-encoding-map}.
2328 @item muse-html-encoding-default
2329 The default Emacs buffer encoding to use in published files.
2330 This will be used if no special characters are found.
2334 @node Journal, LaTeX, HTML, Publishing Styles
2335 @comment node-name, next, previous, up
2336 @section Keeping a journal or blog
2338 @cindex blog, journal style
2340 The module facilitates the keeping and publication of a journal. When
2341 publishing to HTML, it assumes the form of a web log, or blog.
2343 The input format for each entry is as follows.
2346 * 20040317: Title of entry
2351 "You know who you are. It comes down to a simple gut check: You
2352 either love what you do or you don't. Period." -- P. Bronson
2356 The "qotd", or Quote of the Day, is entirely optional. When generated
2357 to HTML, this entry is rendered as the following.
2361 <div class="entry-qotd">
2362 <h3>Quote of the Day:</h3>
2363 <p>"You know who you are. It comes down to a simple gut
2364 check: You either love what you do or you don't. Period."
2367 <div class="entry-body">
2368 <div class="entry-head">
2369 <div class="entry-date">
2370 <span class="date">March 17, 2004</span>
2372 <div class="entry-title">
2373 <h2>Title of entry</h2>
2376 <div class="entry-text">
2377 <p>Text for the entry.</p>
2383 The plurality of "div" tags makes it possible to display the entries in
2384 any form you wish, using a CSS style.
2386 Also, an .RDF file can be generated from your journal by publishing it
2387 with the "rdf" style. It uses the first two sentences of the first
2388 paragraph of each entry as its "description", and auto-generates tags
2389 for linking to the various entries.
2391 @subheading muse-project-alist considerations
2393 If you wish to publish an RDF or RSS feed, it is important to include
2394 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2395 for your Journal projects. An example follows.
2398 (setq muse-project-alist
2399 '(("Journal" ("~/Journal/"
2401 (:base "journal-rss"
2402 :base-url "http://example.org/journal/"
2403 :path "~/public_html/journal"))))
2406 @subheading Styles provided
2410 @cindex publishing styles, journal-html
2412 Publish journal entries as an HTML document.
2414 @cindex publishing styles, journal-xhtml
2416 Publish journal entries as an XHTML document.
2418 @cindex publishing styles, journal-latex
2420 Publish journal entries as a LaTeX document.
2422 @cindex publishing styles, journal-pdf
2424 Publish journal entries as a PDF document.
2426 @cindex publishing styles, journal-book-latex
2427 @item journal-book-latex
2428 Publish journal entries as a LaTeX book.
2430 @cindex publishing styles, journal-book-pdf
2431 @item journal-book-pdf
2432 Publish journal entries as a PDF book.
2434 @cindex publishing styles, journal-rdf
2435 @cindex publishing styles, RSS 1.0
2437 Publish journal entries as an RDF file (RSS 1.0).
2439 @cindex publishing styles, journal-rss
2440 @cindex publishing styles, RSS 2.0
2442 Publish journal entries as an RSS file (RSS 2.0).
2444 @cindex publishing styles, journal-rss-entry
2445 @item journal-rss-entry
2446 Used internally by @code{journal-rss} and @code{journal-rdf} for
2447 publishing individual entries.
2451 @subheading Options provided
2455 @item muse-journal-heading-regexp
2456 A regexp that matches a journal heading.
2458 Paren group 1 is the ISO date, group 2 is the optional category, and
2459 group 3 is the optional heading for the entry.
2461 @item muse-journal-date-format
2462 Date format to use for journal entries.
2464 @item muse-journal-html-heading-regexp
2465 A regexp that matches a journal heading from an HTML document.
2467 Paren group 1 is the ISO date, group 2 is the optional category, and
2468 group 3 is the optional heading for the entry.
2470 @item muse-journal-html-entry-template
2471 Template used to publish individual journal entries as HTML.
2473 This may be text or a filename.
2475 @item muse-journal-latex-section
2476 Template used to publish a LaTeX section.
2478 @item muse-journal-latex-subsection
2479 Template used to publish a LaTeX subsection.
2481 @item muse-journal-markup-tags
2482 A list of tag specifications, for specially marking up Journal entries.
2484 @xref{muse-publish-markup-tags}, for more information.
2486 This is used by @code{journal-latex} and its related styles, as well as
2487 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2488 @code{journal-rss} use.
2490 @item muse-journal-rdf-extension
2491 Default file extension for publishing RDF (RSS 1.0) files.
2493 @item muse-journal-rdf-base-url
2494 The base URL of the website referenced by the RDF file.
2496 @item muse-journal-rdf-header
2497 Header used for publishing RDF (RSS 1.0) files.
2499 This may be text or a filename.
2501 @item muse-journal-rdf-footer
2502 Footer used for publishing RDF (RSS 1.0) files.
2504 This may be text or a filename.
2506 @item muse-journal-rdf-date-format
2507 Date format to use for RDF entries.
2509 @item muse-journal-rdf-entry-template
2510 Template used to publish individual journal entries as RDF.
2512 This may be text or a filename.
2514 @item muse-journal-rdf-summarize-entries
2515 If non-nil, include only summaries in the RDF file, not the full data.
2517 The default is nil, because this annoys some subscribers.
2519 @item muse-journal-rss-heading-regexp
2520 A regexp that matches a journal heading from an HTML document.
2522 Paren group 1 is the ISO date, group 2 is the optional category,
2523 and group 3 is the optional heading for the entry.
2525 @item muse-journal-rss-extension
2526 Default file extension for publishing RSS 2.0 files.
2528 @item muse-journal-rss-base-url
2529 The base URL of the website referenced by the RSS file.
2531 @item muse-journal-rss-header
2532 Header used for publishing RSS 2.0 files.
2534 This may be text or a filename.
2536 @item muse-journal-rss-footer
2537 Footer used for publishing RSS 2.0 files.
2539 This may be text or a filename.
2541 @item muse-journal-rss-date-format
2542 Date format to use for RSS 2.0 entries.
2544 @item muse-journal-rss-entry-template
2545 Template used to publish individual journal entries as RSS 2.0.
2547 This may be text or a filename.
2549 @item muse-journal-rss-enclosure-types-alist
2550 File types that are accepted as RSS enclosures.
2552 This is an alist that maps file extension to content type.
2554 Useful for podcasting.
2556 @item muse-journal-rss-summarize-entries
2557 If non-nil, include only summaries in the RSS file, not the full data.
2559 The default is nil, because this annoys some subscribers.
2561 @item muse-journal-rss-markup-regexps
2562 List of markup rules for publishing a Muse journal page to RSS.
2564 For more information on the structure of this list,
2565 @xref{muse-publish-markup-regexps}.
2567 @item muse-journal-rss-markup-functions
2568 An alist of style types to custom functions for that kind of text.
2570 For more on the structure of this list,
2571 @xref{muse-publish-markup-functions}.
2575 @node LaTeX, Poem, Journal, Publishing Styles
2576 @comment node-name, next, previous, up
2577 @section Publishing LaTeX documents
2579 This publishing style is capable of producing LaTeX or PDF documents.
2581 If you wish to publish PDF documents, you will need to have a good TeX
2582 installation. For Debian and Ubuntu, this can be accomplished by
2583 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2586 @subheading Styles provided
2590 @cindex publishing styles, latex
2592 Publish a LaTeX document.
2594 @cindex publishing styles, pdf
2596 Publish a PDF document, using an external LaTeX document conversion
2599 @cindex publishing styles, latexcjk
2601 Publish a LaTeX document with CJK (Chinese) encodings.
2603 @cindex publishing styles, pdfcjk
2605 Publish a PDF document with CJK (Chinese) encodings, using an external
2606 LaTeX document conversion tool.
2608 @cindex publishing styles, slides
2610 Publish a LaTeX document that uses the Beamer extension. This is
2611 suitable for producing slides.
2613 Here is an example of a slide.
2616 <slide title="First Slide">
2617 Everything between the slide tags composes this slide.
2619 [[Some-sort-of-cute-image.png]]
2622 - Another bullet point.
2626 @cindex publishing styles, slides-pdf
2628 Publish a PDF document of slides, using the Beamer extension.
2630 @cindex publishing styles, lecture-notes
2632 Publish a LaTeX document that uses the Beamer extension. This is
2633 suitable for producing lecture notes.
2635 This can also use the @verb{|<slide>|} tag.
2637 @cindex publishing styles, lecture-notes-pdf
2638 @item lecture-notes-pdf
2639 Publish a PDF document of lecture notes, using the Beamer extension.
2643 @subheading Options provided
2647 @item muse-latex-extension
2648 Default file extension for publishing LaTeX files.
2650 @item muse-latex-pdf-extension
2651 Default file extension for publishing LaTeX files to PDF.
2653 @item muse-latex-pdf-program
2654 The program that is called to generate PDF content from LaTeX content.
2656 @item muse-latex-pdf-cruft
2657 Extensions of files to remove after generating PDF output successfully.
2659 @item muse-latex-header
2660 Header used for publishing LaTeX files.
2662 This may be text or a filename.
2664 @item muse-latex-footer
2665 Footer used for publishing LaTeX files.
2667 This may be text or a filename.
2669 @item muse-latexcjk-header
2670 Header used for publishing LaTeX files (CJK).
2672 This may be text or a filename.
2674 @item muse-latexcjk-footer
2675 Footer used for publishing LaTeX files (CJK).
2677 This may be text or a filename.
2679 @item muse-latex-slides-header
2680 Header for publishing of slides using LaTeX.
2682 This may be text or a filename.
2684 You must have the Beamer extension for LaTeX installed for this to work.
2686 @item muse-latex-lecture-notes-header
2687 Header publishing of lecture notes using LaTeX.
2689 This may be text or a filename.
2691 You must have the Beamer extension for LaTeX installed for this to work.
2693 @item muse-latex-markup-regexps
2694 List of markup regexps for identifying regions in a Muse page.
2696 For more on the structure of this list,
2697 @xref{muse-publish-markup-regexps}.
2699 @item muse-latex-markup-functions
2700 An alist of style types to custom functions for that kind of text.
2702 For more on the structure of this list,
2703 @xref{muse-publish-markup-functions}.
2705 @item muse-latex-markup-strings
2706 Strings used for marking up text.
2708 These cover the most basic kinds of markup, the handling of which
2709 differs little between the various styles.
2711 @item muse-latex-slides-markup-tags
2712 A list of tag specifications, for specially marking up LaTeX slides.
2714 @item muse-latexcjk-encoding-map
2715 An alist mapping emacs coding systems to appropriate CJK codings.
2716 Use the base name of the coding system (ie, without the -unix).
2718 @item muse-latexcjk-encoding-default
2719 The default Emacs buffer encoding to use in published files.
2721 This will be used if no special characters are found.
2723 @item muse-latex-markup-specials-document
2724 A table of characters which must be represented specially.
2725 These are applied to the entire document, sans already-escaped
2728 @item muse-latex-markup-specials-example
2729 A table of characters which must be represented specially.
2730 These are applied to @verb{|example>|} regions.
2732 With the default interpretation of @verb{|<example>|} regions, no
2733 specials need to be escaped.
2735 @item muse-latex-markup-specials-literal
2736 A table of characters which must be represented specially.
2737 This applies to =monospaced text= and @verb{|<code>|} regions.
2739 @item muse-latex-markup-specials-url
2740 A table of characters which must be represented specially.
2741 These are applied to URLs.
2743 @item muse-latex-markup-specials-image
2744 A table of characters which must be represented specially.
2745 These are applied to image filenames.
2747 @item muse-latex-permit-contents-tag
2748 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2751 Most of the time, it is best to have a table of contents on the
2752 first page, with a new page immediately following. To make this
2753 work with documents published in both HTML and LaTeX, we need to
2754 ignore the @verb{|<contents>|} tag.
2756 If you don't agree with this, then set this option to non-nil,
2757 and it will do what you expect.
2761 @node Poem, Texinfo, LaTeX, Publishing Styles
2762 @comment node-name, next, previous, up
2763 @section Publish a poem to LaTex or PDF
2765 The @code{muse-poem} module makes it easy to attractively publish and
2766 reference poems in the following format, using the "memoir" module for
2767 LaTeX publishing. It will also markup poems for every other output
2768 style, though none are nearly as pretty.
2777 Annotations, history, notes, etc.
2780 Once a poem is written in this format, just publish it to PDF using the
2781 @code{poem-pdf} style. To make an inlined reference to a poem that
2782 you've written -- for example, from a blog page -- there is a "poem" tag
2783 defined by this module.
2786 <poem title="name.of.poem.page">
2789 Let's assume the template above was called @file{name.of.poem.page};
2790 then the above tag would result in this inclusion.
2798 John Wiegley uses this module for publishing all of the poems on his
2799 website, which are at
2800 @uref{http://www.newartisans.com/johnw/poems.html}.
2802 @subheading Styles provided
2806 @cindex publishing styles, poem-latex
2808 Publish a poem in LaTeX form.
2810 @cindex publishing styles, poem-pdf
2812 Publish a poem to a PDF document.
2814 @cindex publishing styles, chapbook-latex
2815 @item chapbook-latex
2816 Publish a book of poems in LaTeX form.
2818 @cindex publishing styles, chapbook-pdf
2820 Publish a book of poems to a PDF document.
2824 @subheading Options provided
2828 @item muse-poem-latex-header
2829 Header used for publishing LaTeX poems.
2831 This may be text or a filename.
2833 @item muse-poem-latex-footer
2834 Footer used for publishing LaTeX files.
2836 This may be text or a filename.
2838 @item muse-poem-markup-strings
2839 Strings used for marking up poems.
2841 These cover the most basic kinds of markup, the handling of which
2842 differs little between the various styles.
2844 @item muse-chapbook-latex-header
2845 Header used for publishing a book of poems in LaTeX form.
2847 This may be text or a filename.
2849 @item muse-chapbook-latex-footer
2850 Footer used for publishing a book of poems in LaTeX form.
2852 This may be text or a filename.
2854 @item muse-poem-chapbook-strings
2855 Strings used for marking up books of poems.
2857 These cover the most basic kinds of markup, the handling of which
2858 differs little between the various styles.
2862 @node Texinfo, XML, Poem, Publishing Styles
2863 @comment node-name, next, previous, up
2864 @section Publish entries to Texinfo format or PDF
2866 Rules for publishing a Muse file as a Texinfo article.
2868 @subheading Styles provided
2872 @cindex publishing styles, texi
2874 Publish a file in Texinfo form.
2876 @cindex publishing styles, texi
2878 Generate an Info file from a Muse file.
2880 @cindex publishing styles, info-pdf
2882 Publish a file in PDF form.
2886 @subheading Options provided
2890 @item muse-texinfo-process-natively
2891 If non-nil, use the Emacs `texinfmt' module to make Info files.
2893 @item muse-texinfo-extension
2894 Default file extension for publishing Texinfo files.
2896 @item muse-texinfo-info-extension
2897 Default file extension for publishing Info files.
2899 @item muse-texinfo-pdf-extension
2900 Default file extension for publishing PDF files.
2902 @item muse-texinfo-header
2903 Text to prepend to a Muse page being published as Texinfo.
2905 This may be text or a filename.
2906 It may contain @verb{|<lisp>|} markup tags.
2908 @item muse-texinfo-footer
2909 Text to append to a Muse page being published as Texinfo.
2911 This may be text or a filename.
2912 It may contain @verb{|<lisp>|} markup tags.
2914 @item muse-texinfo-markup-regexps
2915 List of markup rules for publishing a Muse page to Texinfo.
2917 For more on the structure of this list,
2918 @xref{muse-publish-markup-regexps}.
2920 @item muse-texinfo-markup-functions
2921 An alist of style types to custom functions for that kind of text.
2923 For more on the structure of this list,
2924 @xref{muse-publish-markup-functions}.
2926 @item muse-texinfo-markup-strings
2927 Strings used for marking up text.
2929 These cover the most basic kinds of markup, the handling of which
2930 differs little between the various styles.
2932 @item muse-texinfo-markup-specials
2933 A table of characters which must be represented specially.
2935 @item muse-texinfo-markup-specials
2936 A table of characters which must be represented specially.
2937 These are applied to URLs.
2941 @node XML, , Texinfo, Publishing Styles
2942 @comment node-name, next, previous, up
2943 @section Publish entries to XML
2945 Muse is capable of publishing XML documents, with the help of the
2946 @file{muse-xml.el} module.
2948 A RelaxNG schema is available as part of the Muse distribution in the
2949 @file{etc/muse.rnc} file.
2951 @subheading Styles provided
2955 @cindex publishing styles, xml
2957 Publish a file in XML form.
2961 @subheading Options provided
2965 @cindex muse-xml-encoding-map
2966 @item muse-xml-encoding-map
2967 An alist mapping Emacs coding systems to appropriate XML charsets.
2968 Use the base name of the coding system (i.e. without the -unix).
2970 @item muse-xml-markup-specials
2971 A table of characters which must be represented specially in all
2972 XML-like markup formats.
2974 @item muse-xml-markup-specials-url-extra
2975 A table of characters which must be represented specially in all
2976 XML-like markup formats.
2978 These are extra characters that are escaped within URLs.
2980 @item muse-xml-extension
2981 Default file extension used for publishing XML files.
2983 @item muse-xml-header
2984 Header used for publishing XML files.
2986 This may be text or a filename.
2988 @item muse-xml-footer
2989 Footer used for publishing XML files.
2991 This may be text or a filename.
2993 @item muse-xml-markup-regexps
2994 List of markup rules for publishing a Muse page to XML.
2996 For more on the structure of this list,
2997 @xref{muse-publish-markup-regexps}.
2999 @item muse-xml-markup-functions
3000 An alist of style types to custom functions for that kind of text.
3002 For more on the structure of this list,
3003 @xref{muse-publish-markup-functions}.
3005 @item muse-xml-markup-strings
3006 Strings used for marking up text.
3008 These cover the most basic kinds of markup, the handling of which
3009 differs little between the various styles.
3011 @item muse-xml-encoding-default
3012 The default Emacs buffer encoding to use in published files.
3014 This will be used if no special characters are found.
3016 @item muse-xml-charset-default
3017 The default XML charset to use if no translation is found in
3018 @code{muse-xml-encoding-map}.
3023 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
3024 @comment node-name, next, previous, up
3025 @chapter Making your own publishing styles
3028 * Common Elements:: Common functionality shared by styles.
3029 * Deriving Styles:: Deriving a new style from an existing
3033 @node Common Elements, Deriving Styles, , Extending Muse
3034 @comment node-name, next, previous, up
3035 @section Common functionality shared by styles
3036 @cindex publishing styles, common
3039 * Markup Functions:: Specifying functions to mark up text.
3040 * Markup Regexps:: Markup rules for publishing.
3041 * Markup Strings:: Strings specific to a publishing style.
3042 * Markup Tags:: Tag specifications for special markup.
3043 * Style Elements:: Parameters used for defining styles.
3046 @node Markup Functions, Markup Regexps, , Common Elements
3047 @comment node-name, next, previous, up
3048 @subsection Specifying functions to mark up text
3049 @cindex publishing, markup functions
3051 @anchor{muse-publish-markup-functions}
3052 @code{muse-publish-markup-functions}
3054 An alist of style types to custom functions for that kind of text.
3056 This is used by publishing styles to attempt to minimize the amount of
3057 custom regexps that each has to define. @file{muse-publish} provides
3058 rules for the most common types of markup.
3060 Each member of the list is of the following form.
3068 Describes the type of text to associate with this rule.
3069 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3072 Function to use to mark up this kind of rule if no suitable function is
3073 found through the @option{:functions} tag of the current style.
3076 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3077 @comment node-name, next, previous, up
3078 @subsection Markup rules for publishing
3079 @cindex publishing, markup regexps
3080 @cindex publishing, rules
3082 @anchor{muse-publish-markup-regexps}
3083 @code{muse-publish-markup-regexps}
3085 List of markup rules for publishing a page with Muse.
3087 The rules given in this variable are invoked first, followed by whatever
3088 rules are specified by the current style.
3090 Each member of the list is either a function, or a list of the following
3094 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3099 A regular expression, or symbol whose value is a regular expression,
3100 which is searched for using `re-search-forward'.
3102 @item TEXT-BEGIN-GROUP
3103 The matching group within that regexp which denotes the beginning of the
3104 actual text to be marked up.
3106 @item REPLACEMENT-TEXT
3107 A string that will be passed to `replace-match'.
3109 If it is not a string, but a function, it will be called to determine
3110 what the replacement text should be (it must return a string). If it is
3111 a symbol, the value of that symbol should be a string.
3114 The replacements are done in order, one rule at a time. Writing
3115 the regular expressions can be a tricky business. Note that case
3116 is never ignored. `case-fold-search' is always bound to nil
3117 while processing the markup rules.
3119 @subheading Publishing order
3121 This is the order that the publishing rules are consulted, by default.
3122 This may be changed by customizing @code{muse-publish-markup-regexps}.
3126 @item trailing and leading whitespace
3127 Remove trailing and leading whitespace from a file.
3132 This is only recognized at the beginning of a file.
3135 @samp{; a commented line}
3143 @item explicit links
3144 Prevent emphasis characters in explicit links from being marked up.
3146 Don't actually publish them here, just add a special no-emphasis text
3150 Whitespace-delimited word, possibly with emphasis characters
3152 This function is responsible for marking up emphasis and escaping some
3158 Outline-mode style headings.
3163 These are ellipses with a dot at end.
3173 Horizontal rule or section separator.
3175 @item no-break-space
3178 Prevent lines from being split before or after these characters.
3183 beginning of footnotes section
3188 Footnote definition or reference. If at beginning of line, it is a
3203 Numbered list, item list, or term definition list.
3207 @file{table.el} style tables
3210 @samp{table | cells}
3212 Muse tables or orgtbl-mode style tables.
3215 spaces before beginning of text
3231 @samp{[[explicit][links]]}
3234 @samp{http://example.com/}
3237 @samp{bare-email@@example.com}
3241 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3242 @comment node-name, next, previous, up
3243 @subsection Strings specific to a publishing style
3244 @cindex publishing, markup strings
3246 @dfn{Markup strings} are strings used for marking up text for a
3249 These cover the most basic kinds of markup, the handling of which
3250 differs little between the various styles.
3252 @subheading Available markup strings
3256 @item image-with-desc
3257 An image and a description.
3259 Argument 1: image without extension. Argument 2: image extension.
3260 Argument 3: description.
3265 Argument 1: image without extension. Argument 2: image extension.
3268 An image with a link around it.
3270 Argument 1: link. Argument 2: image without extension.
3271 Argument 3: image extension.
3274 A reference to an anchor on the current page.
3276 Argument 1: anchor name. Argument 2: description if one exists, or the
3277 original link otherwise.
3280 A URL without a description.
3285 A link to a Muse page with a description.
3287 Argument 1: link. Argument 2: description if one exists, or the
3288 original link otherwise.
3290 @item link-and-anchor
3291 A link to a Muse page with an anchor, and a description.
3293 Argument 1: link. Argument 2: anchor name.
3294 Argument 3: description if one exists, or the original link otherwise.
3295 Argument 4: link without an extension.
3298 A link to an email address.
3300 Argument 1: email address. Argument 2: email address.
3305 Argument 1: name of anchor.
3310 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3313 Beginning of a comment.
3319 A horizontal line or space.
3321 @item no-break-space
3322 A space that separates two words which are not to be separated.
3325 Beginning of footnote.
3331 Mark a reference for the current footnote.
3333 Argument 1: number of this footnote.
3335 @item footnotemark-end
3336 End of a reference for the current footnote.
3339 Indicate the text of the current footnote.
3341 Argument 1: number of this footnote.
3343 @item footnotetext-end
3344 End of a footnote text line.
3347 Text used to replace ``Footnotes:'' line.
3356 Beginning of a part indicator line. This is used by book publishing.
3359 End of a part indicator line. This is used by book publishing.
3362 Beginning of a chapter indicator line. This is used by book publishing.
3365 End of a chapter indicator line. This is used by book publishing.
3368 Beginning of level 1 section indicator line.
3370 Argument 1: level of section; always 1.
3373 End of level 1 section indicator line.
3375 Argument 1: level of section; always 1.
3378 Beginning of level 2 section indicator line.
3380 Argument 1: level of section; always 2.
3382 @item subsection-end
3383 End of level 2 section indicator line.
3385 Argument 1: level of section; always 2.
3388 Beginning of level 3 section indicator line.
3390 Argument 1: level of section; always 3.
3392 @item subsubsection-end
3393 End of level 3 section indicator line.
3395 Argument 1: level of section; always 3.
3398 Beginning of section indicator line, where level is greater than 3.
3400 Argument 1: level of section.
3402 @item section-other-end
3403 End of section indicator line, where level is greater than 3.
3405 Argument 1: level of section.
3407 @item begin-underline
3408 Beginning of underlined text.
3411 End of underlined text.
3414 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3418 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3422 Beginning of the first level of emphasized text.
3425 End of the first level of emphasized text.
3427 @item begin-more-emph
3428 Beginning of the second level of emphasized text.
3431 End of the second level of emphasized text.
3433 @item begin-most-emph
3434 Beginning of the third (and final) level of emphasized text.
3437 End of the third (and final) level of emphasized text.
3440 Beginning of verse text.
3443 String used to each space that is further indented than the beginning of
3446 @item begin-verse-line
3447 Beginning of a line of verse.
3449 @item empty-verse-line
3450 End of a line of verse.
3452 @item begin-last-stanza-line
3453 Beginning of the last line of a verse stanza.
3455 @item end-last-stanza-line
3456 End of the last line of a verse stanza.
3462 Beginning of an example region. To make use of this, an
3463 @samp{<example>} tag is needed.
3466 End of an example region. To make use of this, an @samp{</example>} tag
3470 Begin a centered line.
3473 End a centered line.
3476 Begin a quoted region.
3479 End a quoted region.
3481 @item begin-quote-item
3482 Begin a quote paragraph.
3484 @item end-quote-item
3485 End a quote paragraph.
3488 Begin an unordered list.
3491 End an unordered list.
3493 @item begin-uli-item
3494 Begin an unordered list item.
3497 End an unordered list item.
3500 Begin an ordered list.
3503 End an ordered list.
3505 @item begin-oli-item
3506 Begin an ordered list item.
3509 End an ordered list item.
3512 Begin a definition list.
3515 End a definition list.
3518 Begin a definition list item.
3521 End a definition list item.
3524 Begin a definition list term.
3527 End a definition list term.
3530 Begin a definition list entry.
3533 End a definition list entry.
3541 @item begin-table-group
3542 Begin a table grouping.
3544 @item end-table-group
3545 End a table grouping.
3547 @item begin-table-row
3553 @item begin-table-entry
3554 Begin a table entry.
3556 @item end-table-entry
3561 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3562 @comment node-name, next, previous, up
3563 @subsection Tag specifications for special markup
3564 @cindex publishing, markup tags
3566 @anchor{muse-publish-markup-tags}
3567 @code{muse-publish-markup-tags}
3569 A list of tag specifications, for specially marking up text.
3571 XML-style tags are the best way to add custom markup to Muse. This is
3572 easily accomplished by customizing this list of markup tags.
3574 For each entry, the name of the tag is given, whether it expects a
3575 closing tag and/or an optional set of attributes, whether it is
3576 nestable, and a function that performs whatever action is desired within
3577 the delimited region.
3579 The tags themselves are deleted during publishing, before the function
3580 is called. The function is called with three arguments, the beginning
3581 and end of the region surrounded by the tags. If properties are
3582 allowed, they are passed as a third argument in the form of an alist.
3583 The `end' argument to the function is always a marker.
3585 Point is always at the beginning of the region within the tags, when the
3586 function is called. Wherever point is when the function finishes is
3587 where tag markup will resume.
3589 These tag rules are processed once at the beginning of markup, and once
3590 at the end, to catch any tags which may have been inserted in-between.
3592 @node Style Elements, , Markup Tags, Common Elements
3593 @comment node-name, next, previous, up
3594 @subsection Parameters used for defining styles
3595 @cindex publishing, style elements
3597 Style elements are tags that define a style. Use
3598 @code{muse-define-style} to create a new style.
3601 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3604 @subheading Usable elements
3609 File extension to use for publishing files with this style.
3612 File extension to use for publishing links to Muse files with this
3616 File extension to use for publishing second-stage files with this style.
3618 For example, PDF publishing generates a LaTeX file first, then a PDF
3619 from that LaTeX file.
3622 List of markup rules for publishing a page with Muse.
3623 @xref{muse-publish-markup-regexps}.
3626 An alist of style types to custom functions for that kind of text.
3627 @xref{muse-publish-markup-functions}.
3630 Strings used for marking up text with this style.
3632 These cover the most basic kinds of markup, the handling of which
3633 differs little between the various styles.
3636 A list of tag specifications, used for handling extra tags.
3637 @xref{muse-publish-markup-tags}.
3640 A table of characters which must be represented specially.
3643 A function that is to be executed on the newly-created publishing buffer
3644 (or the current region) before any publishing occurs.
3646 This is used to set extra parameters that direct the publishing process.
3649 A function that is to be executed on the publishing buffer (or the
3650 current region) immediately after applying all of the markup regexps.
3652 This is used to fix the order of table elements (header, footer, body)
3656 A function that is to be executed on the publishing buffer after
3657 :before-end, and immediately after inserting the header and footer.
3659 This is used for generating the table of contents as well as setting the
3663 A function that is to be executed after saving the published file, but
3664 while still in its buffer.
3666 This is used for generating second-stage documents like PDF files from
3667 just-published LaTeX files.
3670 Header used for publishing files of this style.
3672 This may be a variable, text, or a filename. It is inserted at the
3673 beginning of a file, after evaluating the publishing markup.
3676 Footer used for publishing files of this style.
3678 This may be a variable, text, or a filename. It is inserted at the end
3679 of a file, after evaluating the publishing markup.
3682 Style sheet used for publishing files of this style.
3684 This may be a variable or text. It is used in the header of HTML and
3685 XHTML based publishing styles.
3688 The function used to browse the published result of files of this style.
3692 @node Deriving Styles, , Common Elements, Extending Muse
3693 @comment node-name, next, previous, up
3694 @section Deriving a new style from an existing one
3695 @cindex publishing styles, deriving
3697 To create a new style from an existing one, use @code{muse-derive-style}
3698 as follows. This is a good way to fix something you don't like about a
3699 particular publishing style, or to personalize it.
3702 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3705 The derived name is a string defining the new style, such as "my-html".
3706 The base name must identify an existing style, such as "html" -- if you
3707 have loaded @file{muse-html}. The style parameters are the same as
3708 those used to create a style, except that they override whatever
3709 definitions exist in the base style. However, some definitions only
3710 partially override. The following parameters support partial
3713 @xref{Style Elements}, for a complete list of all parameters.
3718 If a markup function is not found in the derived style's function list,
3719 the base style's function list will be queried.
3722 All regexps in the current style and the base style(s) will be used.
3725 If a markup string is not found in the derived style's string list, the
3726 base style's string list will be queried.
3731 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
3732 @comment node-name, next, previous, up
3733 @chapter Getting Help and Reporting Bugs
3734 @cindex help, getting
3735 @cindex bugs, reporting
3737 After you have read this guide, if you still have questions about
3738 Muse, or if you have bugs to report, there are several places you can
3744 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
3745 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
3749 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
3750 that Michael Olson (the current maintainer) made for Muse.
3753 Muse has several different mailing lists.
3757 @item muse-el-announce
3758 Low-traffic list for Muse-related announcements.
3760 You can join this mailing list (@email{muse-el-announce@@gna.org})
3761 using the subscription form at
3762 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
3763 mailing list is also available via Gmane (@url{http://gmane.org/}). The
3764 group is called @samp{gmane.emacs.muse.announce}.
3766 @item muse-el-discuss
3767 Discussion, bugfixes, suggestions, tips, and the like for Muse.
3768 This mailing list also includes the content of muse-el-announce.
3770 You can join this mailing list (@email{muse-el-discuss@@gna.org})
3771 using the subscription form at
3772 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
3773 list is also available via Gmane with the identifier
3774 @samp{gmane.emacs.muse.general}.
3777 Log messages for commits made to Muse.
3779 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
3780 the subscription form at
3781 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
3782 is also available via Gmane with the identifier
3783 @samp{gmane.emacs.muse.scm}.
3785 @item muse-el-commits
3786 Generated bug reports for Emacs Muse. If you use our bug-tracker at
3787 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
3788 sent to this list automatically.
3790 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
3791 the subscription form at
3792 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
3793 is also available via Gmane with the identifier
3794 @samp{gmane.emacs.muse.cvs}.
3796 @item muse-el-internationalization
3797 Discussion of translation of the Muse website and documentation into
3800 You can join this mailing list
3801 (@email{muse-el-internationalization@@gna.org}) using the subscription
3802 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
3803 mailing list is also available via Gmane with the identifier
3804 @samp{gmane.emacs.muse.internationalization}.
3809 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
3810 contributors are frequently around and willing to answer your
3811 questions. The @samp{#muse} channel is also available for
3812 Muse-specific help, and its current maintainer hangs out there.
3815 The maintainer of Emacs Muse, Michael Olson, may be contacted at
3816 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
3817 it is often better to use the muse-el-discuss mailing list.
3821 @node History, Contributors, Getting Help and Reporting Bugs, Top
3822 @comment node-name, next, previous, up
3823 @chapter History of This Document
3824 @cindex history, of Muse
3828 John Wiegley started Muse upon realizing that EmacsWiki had some serious
3829 limitations. Around February 2004, he started making "emacs-wiki version
3830 3.00 APLHA", which eventually became known as Muse.
3832 Most of those who frequent the emacs-wiki mailing list continued to use
3833 emacs-wiki, mainly because Planner hasn't been ported over to it.
3835 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
3836 John Wiegley's request.
3839 Michael Olson overhauled this document and added many new sections in
3840 preparation for the first release of Muse (3.01).
3844 @node Contributors, GNU Free Documentation License, History, Top
3845 @comment node-name, next, previous, up
3846 @chapter Contributors to This Documentation
3847 @cindex contributors
3849 The first draft of this document was taken from the emacs-wiki texinfo
3850 manual. Michael Olson adapted it for Muse and added most of its
3853 John Sullivan did a majority of the work on the emacs-wiki texinfo
3856 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
3857 emacs-wiki texinfo manual.
3860 @node GNU Free Documentation License, Concept Index, Contributors, Top
3861 @appendix GNU Free Documentation License
3862 @include doclicense.texi
3865 @node Concept Index, , GNU Free Documentation License, Top
3866 @comment node-name, next, previous, up