1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.12.
17 Copyright @copyright{} 2004, 2005, 2006, 2007,
18 2008 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 * Miscellaneous:: Miscellaneous add-ons, like a minor mode.
79 * Getting Help and Reporting Bugs::
80 * History:: History of this document.
81 * Contributors:: Contributors to this documentation.
82 * GNU Free Documentation License:: The license for this documentation.
83 * Concept Index:: Search for terms.
86 --- The Detailed Node Listing ---
88 How to Get Muse Releases and Development Changes
90 * Releases:: Released versions of Muse.
91 * Development:: Latest unreleased development changes.
95 * Loading Muse:: How to load Muse.
96 * Using Muse Mode:: How to edit files in Muse.
97 * Publishing Files Overview:: Publishing a single file or project.
98 * File Extensions:: Using a different file extension.
100 Creating and Managing Muse Projects
102 * Single Project:: A single-project example.
103 * Multiple Projects:: A multiple-project example.
104 * Projects and Subdirectories:: Publishing subdirectories in projects.
105 * Options for Projects:: Listing of available options for projects.
107 Rules for Using Markup
109 * Paragraphs:: Paragraphs: centering and quoting.
110 * Headings:: Levels of headings.
111 * Directives:: Directives at the beginning of a
113 * Emphasizing Text:: Bold, italicized, and underlined text.
114 * Footnotes:: Making notes to be shown at the end.
115 * Verse:: Indicating poetic stanzas.
116 * Lists:: Lists of items.
117 * Tables:: Generation of data tables.
118 * Explicit Links:: Hyperlinks and email addresses with
120 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
122 * Images:: Publishing and displaying images.
123 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
124 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
126 * Citations:: Support for citing other resources.
127 * Comments:: Lines to omit from published output.
128 * Tag Summary:: Tags that Muse recognizes.
130 Publishing Various Types of Documents
132 * Blosxom:: Integrating Muse and pyblosxom.cgi.
133 * Book:: Publishing entries into a compilation.
134 * ConTeXt:: Publishing ConTeXt documents.
135 * DocBook:: Publishing in DocBook XML form.
136 * HTML:: Publishing in HTML or XHTML form.
137 * Journal:: Keeping a journal or blog.
138 * LaTeX:: Publishing LaTeX documents.
139 * Poem:: Publish a poem to LaTeX or PDF.
140 * Texinfo:: Publish entries to Texinfo format or PDF.
141 * XML:: Publish entries to XML.
143 Integrating Muse and pyblosxom.cgi
145 * Blosxom Requirements:: Other tools needed for the Blosxom style.
146 * Blosxom Entries:: Format of a Blosxom entry and automation.
147 * Blosxom Options:: Blosxom styles and options provided.
149 Making your own publishing styles
151 * Markup Functions:: Specifying functions to mark up text.
152 * Markup Regexps:: Markup rules for publishing.
153 * Markup Strings:: Strings specific to a publishing style.
154 * Markup Tags:: Tag specifications for special markup.
155 * Style Elements:: Parameters used for defining styles.
156 * Deriving Styles:: Deriving a new style from an existing
159 Miscellaneous add-ons, like a minor mode
161 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
166 @node Preface, Introduction, Top, Top
167 @comment node-name, next, previous, up
168 @chapter About the documentation
170 This document describes Muse, which was written by John Wiegley and is
171 now maintained by Michael Olson. Several versions of this manual are
175 @item PDF: http://mwolson.org/static/doc/muse.pdf
176 @item HTML (single file): http://mwolson.org/static/doc/muse.html
177 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
180 @node Introduction, Obtaining Muse, Preface, Top
181 @comment node-name, next, previous, up
182 @chapter What is Muse?
184 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
185 and publishing environment for Emacs. It simplifies the process of
186 writing documents and publishing them to various output formats.
188 Muse consists of two main parts: an enhanced text-mode for authoring
189 documents and navigating within Muse projects, and a set of publishing
190 styles for generating different kinds of output.
192 What makes Muse distinct from other text-publishing systems is a modular
193 environment, with a rather simple core, in which "styles" are derived
194 from to create new styles. Much of Muse's overall functionality is
195 optional. For example, you can use the publisher without the
196 major-mode, or the mode without doing any publishing; or if you don't
197 load the Texinfo or LaTeX modules, those styles won't be available.
199 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
200 code has been restructured and rewritten, especially its publishing
201 functions. The focus in this revision is on the authoring and
202 publishing aspects, and the "wikiness" has been removed as a default
203 behavior (available in the optional @file{muse-wiki} module). CamelCase
204 words are no longer special by default.
206 One of the principal aims in the development of Muse is to make it very
207 easy to produce good-looking, standards-compliant documents.
209 @node Obtaining Muse, Installation, Introduction, Top
210 @comment node-name, next, previous, up
211 @chapter How to Get Muse Releases and Development Changes
214 * Releases:: Released versions of Muse.
215 * Development:: Latest unreleased development changes.
218 @node Releases, Development, Obtaining Muse, Obtaining Muse
219 @comment node-name, next, previous, up
220 @section Released versions of Muse
222 Choose to install a release if you want to minimize risk.
224 Errors are corrected in development first. User-visible changes will be
225 announced on the @email{muse-el-discuss@@gna.org} mailing list.
226 @xref{Getting Help and Reporting Bugs}.
228 @cindex releases, Debian package
229 @cindex Debian package for Muse
230 Debian users can get Muse via apt-get. The @file{muse-el} package is
231 available both at Michael Olson's APT repository and the official Debian
232 repository. To make use of the former, add the following line to your
233 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
236 deb http://mwolson.org/debian/ ./
239 @cindex releases, Ubuntu package
240 @cindex Ubuntu package for Muse
241 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
242 is available both at Michael Olson's APT repository and the official
243 Ubuntu repository. To make use of the former, add the following line to
244 your @file{/etc/apt/sources.list} file and run @code{apt-get install
248 deb http://mwolson.org/ubuntu/ ./
251 The reason for making separate Debian and Ubuntu packages is that this
252 manual is under the GFDL, and Debian will not allow it to be distributed
253 in its main repository. Ubuntu, on the other hand, permits this manual
254 to be included with the @file{muse-el} package.
256 @cindex releases, from source
257 Alternatively, you can download the latest release from
258 @uref{http://download.gna.org/muse-el/} .
260 @node Development, , Releases, Obtaining Muse
261 @comment node-name, next, previous, up
262 @section Latest unreleased development changes
265 Choose the development version if you want to live on the bleeding edge
266 of Muse development or try out new features before release.
268 @cindex git version control system, using
269 The git version control system allows you to keep up-to-date with the
270 latest changes to the development version of Muse. It also allows you
271 to contribute changes (via commits, if you are have developer access to
272 the repository, or via patches, otherwise). If you would like to
273 contribute to Muse development, it is highly recommended that you use
276 If you are new to git, you might find this tutorial helpful:
277 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
279 Downloading the Muse module with git and staying up-to-date involves
286 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
287 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
288 @item Other operating systems: download, compile, and install the source
289 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
290 package for your operating system.
293 @item Download the Muse development branch.
295 If you have developer access to Muse, do:
298 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
304 git clone git://repo.or.cz/muse-el.git muse
307 If you are behind a restrictive firewall, and do not have developer
308 access, then do the following instead:
311 git clone http://repo.or.cz/r/muse-el.git muse
314 @item List upstream changes that are missing from your local copy.
315 Do this whenever you want to see whether new changes have been committed
316 to Muse. If you wish, you may skip this step and proceed directly to
320 # Change to the source directory you are interested in.
323 # Fetch new changes from the repository, but don't apply them yet
326 # Display log messages for the new changes
330 ``origin'' is git's name for the location where you originally got Muse
331 from. You can change this location at any time by editing the
332 @file{.git/config} file in the directory where the Muse source was
335 @cindex updating Muse with git
336 @item Update to the latest version by pulling in any missing changes.
343 git will show how many files changed, and will provide a visual display
344 for how many lines were changed in each file.
348 There are other ways to interact with the Muse repository.
351 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
352 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
353 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
356 The latest development snapshot can lag behind the git repo by as much
357 as 20 minutes, but never more than that.
359 @subheading Becoming a Muse developer
360 @cindex developer, becoming
362 If you want commit access to the shared Muse repository, then register
363 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
364 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
365 best to send some patches to the @email{muse-el-discuss@@gna.org}
366 mailing list first, so that he knows that you know what you are doing.
367 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
370 You must also be willing to sign a copyright assignment for your changes
371 to Muse, since Muse is a GNU project. The current maintainer will
372 assist you in this process if you contact him.
374 For information on committing changes to Muse and performing
375 development, please consult
376 @uref{http://emacswiki.org/cgi-bin/wiki/MuseDevelopment}.
378 @node Installation, Getting Started, Obtaining Muse, Top
379 @comment node-name, next, previous, up
380 @chapter Compiling and Installing Muse
382 Muse may be compiled and installed on your machine.
384 @subheading Compilation
385 @cindex compiling Muse
387 This is an optional step, since Emacs Lisp source code does not
388 necessarily have to be byte-compiled. Byte-compilation may yield a very
389 slight speed increase.
391 A working copy of Emacs or XEmacs is needed in order to compile Emacs
392 Muse. By default, the program that is installed with the name
393 @command{emacs} will be used.
395 If you want to use the @command{xemacs} binary to perform the
396 compilation, you must copy @file{Makefile.defs.default} to
397 @file{Makefile.defs} in the top-level directory, and then edit
398 @file{Makefile.defs} as follows. You can put either a full path to an
399 Emacs or XEmacs binary or just the command name, as long as it is in the
404 SITEFLAG = -no-site-file
405 # Edit the section as necessary
406 install_info = install-info --section "XEmacs 21.4" $(1).info \
410 Running @code{make} in the top-level directory should compile the Muse
411 source files in the @file{lisp} directory, and generate an autoloads
412 file in @file{lisp/muse-autoloads.el}.
414 @subheading Installation
415 @cindex installing Muse
417 Muse may be installed into your file hierarchy by doing the following.
419 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
420 top-level directory, if you haven't done so already. Then edit the
421 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
422 want the source and compiled Muse files to be installed and
423 @env{INFODIR} indicates where to put the Muse manual. You may use a
424 combination of @env{DESTDIR} and @env{PREFIX} to further determine where
425 the installed files should be placed. As mentioned earlier, you will
426 want to edit @env{EMACS} and @env{SITEFLAG} as shown in the Compilation
427 section if you are using XEmacs.
429 If you are installing Muse on a Debian or Ubuntu system, you might want
430 to change the value of @env{INSTALLINFO} as specified in
431 @file{Makefile.defs}.
433 If you wish to install Muse to different locations than the defaults
434 specify, edit @file{Makefile.defs} accordingly.
436 Run @code{make} as a normal user, if you haven't done so already.
438 Run @code{make install} as the root user if you have chosen installation
439 locations that require root permissions.
442 @cindex ELPA package for Muse
444 For those used to installing software packages, there will be a
445 @code{muse} package available in the Emacs Lisp Package Archive
446 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
447 will be compiled and installed automatically in a user-specific
448 location. For more information on ELPA, see
449 @uref{http://tromey.com/elpa/}.
451 @node Getting Started, Projects, Installation, Top
452 @comment node-name, next, previous, up
453 @chapter Getting Started
457 * Loading Muse:: How to load Muse.
458 * Using Muse Mode:: How to edit files in Muse.
459 * Publishing Files Overview:: Publishing a single file or project.
460 * File Extensions:: Using a different file extension.
463 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
464 @comment node-name, next, previous, up
465 @section How to Load Muse
466 @cindex settings, init file
468 To use Muse, add the directory containing its files to your
469 @code{load-path} variable, in your @file{.emacs} file. Then, load in
470 the authoring mode, and the styles you wish to publish to. An example
474 (add-to-list 'load-path "<path to Muse>")
476 (require 'muse-mode) ; load authoring mode
478 (require 'muse-html) ; load publishing styles I use
479 (require 'muse-latex)
480 (require 'muse-texinfo)
481 (require 'muse-docbook)
483 (require 'muse-project) ; publish files in projects
486 An easy way of seeing which settings are available and changing settings
487 is to use the Muse customization interface. To do this, type
488 @kbd{M-x customize-group muse RET}. Each of the options has its own
489 documentation. Options are grouped logically according to what effect
492 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
493 @comment node-name, next, previous, up
494 @section How to Edit Files in Muse
495 @cindex editing Muse files
497 Muse Mode should automatically be activated when you visit a file with a
498 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
499 available in the @file{examples} directory of the Muse distribution.
500 You can tell that Muse Mose has been activated by checking for the text
501 ``Muse'' in your mode line. If Muse Mode has not been activated, you
502 may activate it by type @kbd{M-x muse-mode RET}.
504 You will notice that Muse files are highlighted very simply. Links are
505 colored blue, headings are large and bold text, and @verb{|<example>|}
506 tags are colored in grey.
508 There are several different ways to edit things like links, which hide
509 the underlying Muse markup. One way is to toggle font-locking off by
510 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
511 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
512 on. Another way is just to move into the text and edit it. Markup can
513 also be removed by normal deletion methods, though some side effects
514 might require a second deletion.
516 For the particular case of editing links, it is easiest to move to the
517 link and do @kbd{C-c C-e}, which is also @kbd{M-x
518 muse-edit-link-at-point}. This prompts you for the link and its
519 description, using the previous contents of the link as initial values.
520 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
521 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
522 followed by hitting @kbd{RET} on them.
524 If you want to add a new list item, this may by accomplished by hitting
525 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
526 dash is the Muse markup that indicates a list item. It is also possible
527 to created ``nested'' lists with this command, by adjusting the number
528 of spaces in front of the dashes. If you have lists with long lines,
529 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
532 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
533 @comment node-name, next, previous, up
534 @section Publishing a Single File or Project
535 @cindex editing Muse files
537 The command @kbd{M-x muse-project-publish-this-file} will publish the
538 current document to any available publishing style (a publishing style
539 is an output format, like HTML or Docbook), placing the output in the
540 current directory. If you are in Muse Mode, this command will be bound
541 to @kbd{C-c C-t}. If the file has been published recently, and its
542 contents have not changed, running @kbd{C-c C-t} again will not publish
543 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
545 If you have set up projects and are visiting a file that is part of a
546 project, then @kbd{C-c C-t} will restrict the output formats to those
547 which are used by the project, and will automatically publish to the
548 output directory defined by the project. If you want to publish to a
549 different directory or use a different format, then use @kbd{C-c M-C-t},
550 which is also @kbd{M-x muse-publish-this-file}.
552 If the currently opened file is part of a defined project in
553 @code{muse-project-alist}, it (and the rest of the changed files in a
554 project) may be published using @kbd{C-c C-p}.
556 @node File Extensions, , Publishing Files Overview, Getting Started
557 @comment node-name, next, previous, up
558 @section Using a Different File Extension
559 @cindex file extension, specifying
561 By default, Muse expects all project files to have the file extension
562 @file{.muse}. Files without this extension will not be associated with
563 Muse mode and will not be considered part of any project, even if they
564 are within a project directory.
566 If you don't want to use @file{.muse}, you can customize the extension
567 by setting the value of @code{muse-file-extension}.
569 If you don't want to use any extension at all, and want Muse to
570 autodetect project files based on their location, then add the following
571 to your Muse settings file.
574 (setq muse-file-extension nil
578 Note that if you chose to have @code{muse-file-extension} set to
579 @code{nil}, you may have trouble if your @file{.emacs} file or other
580 init scripts attempt to visit a Muse file. (A very common example of
581 this is if you use Planner with Muse and run @code{(plan)} from your
582 @file{.emacs}.) If you wish to visit Muse files from your
583 @file{.emacs}, be sure to also add the following additional code before
584 any such visits happen:
587 (add-hook 'find-file-hooks 'muse-mode-maybe)
591 @node Projects, Keystroke Summary, Getting Started, Top
592 @comment node-name, next, previous, up
593 @chapter Creating and Managing Muse Projects
596 Often you will want to publish all the files within a directory to a
597 particular set of output styles automatically. To support, Muse
598 allows for the creation of "projects".
601 * Single Project:: A single-project example.
602 * Multiple Projects:: A multiple-project example.
603 * Projects and Subdirectories:: Publishing subdirectories in projects.
604 * Options for Projects:: Listing of available options for projects.
607 @node Single Project, Multiple Projects, Projects, Projects
608 @comment node-name, next, previous, up
609 @section A Single-Project Example
610 @cindex projects, single
612 Here is a sample project, which may be defined in your @file{.emacs}
616 (setq muse-project-alist
617 '(("Website" ("~/Pages" :default "index")
618 (:base "html" :path "~/public_html")
619 (:base "pdf" :path "~/public_html/pdf"))))
622 The above defines a project named "website", whose files are located
623 in the directory @file{~/Pages}. The default page to visit is
624 @file{index}. When this project is published, each page will be
625 output as HTML to the directory @file{~/public_html}, and as PDF to
626 the directory @file{~/public_html/pdf}. Within any project page, you
627 may create a link to other pages using the syntax @samp{[[pagename]]}.
629 If you would like to include only some files from a directory in a Muse
630 project, you may use a regexp in place of @file{~/Pages} in the example.
632 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
633 @comment node-name, next, previous, up
634 @section A Multiple-Project Example
635 @cindex projects, multiple
637 It is possible to specify multiple projects. Here is an example of
638 three projects: a generic website, a projects area, and a day-planner
639 (the day-planner part requires Planner Mode---see
640 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
643 (setq muse-project-alist
644 '(("Website" ("~/Pages" :default "index")
645 (:base "html" :path "~/public_html"))
646 (("Projects" ("~/Projects" :default "index")
648 :path "~/public_html/projects"
649 :exclude "/TopSecret")
651 :path "~/public_html/projects/pdf"
652 :exclude "/TopSecret")))
655 :major-mode planner-mode
656 :visit-link planner-visit-link)
657 (:base "planner-xhtml"
658 :path "~/public_html/plans"))))
661 The @option{:major-mode} attribute specifies which major to use when
662 visiting files in this directory.
664 The @option{:visit-link} attribute specifies the function to call when
667 The @option{:exclude} attribute has a regexp that matches files to never
670 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
671 @comment node-name, next, previous, up
672 @section Publishing Subdirectories in Projects
673 @cindex projects, subdirectories
675 If you want to publish a directory and all of its subdirectories, Muse
676 provides two convenience functions that together generate the proper
677 rules for you. Note that we use the backtick to begin this
678 muse-project-alist definition, rather than a single quote.
681 (setq muse-project-alist
682 `(("Website" ("~/Pages" :default "index")
683 (:base "html" :path "~/public_html"))
684 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
686 ;; Publish this directory and its subdirectories. Arguments
687 ;; are as follows. The above `muse-project-alist-dirs' part
689 ;; 1. Source directory
690 ;; 2. Output directory
691 ;; 3. Publishing style
692 ;; remainder: Other things to put in every generated style
693 ,@@(muse-project-alist-styles "~/Blog"
698 The @code{muse-project-alist-dirs} function takes a directory and
699 returns it and all of its subdirectories in a list.
701 The @code{muse-project-alist-styles} function is explained by the
704 The ``blosxom'' text is the name of another publishing style, much like
705 ``html''. @xref{Blosxom}, for further information about it. You can
706 use any publishing style you like for the third argument to
707 @code{muse-project-alist-styles}.
709 @node Options for Projects, , Projects and Subdirectories, Projects
710 @comment node-name, next, previous, up
711 @section Listing of Available Options for Projects
712 @cindex projects, options
713 @cindex muse-project-alist, reference
715 This is a listing of all of the various options (or, more accurately:
716 attributes) that may be specified in @code{muse-project-alist}.
718 Each muse-project-alist entry looks like this:
721 (PROJECT-NAME (SOURCES)
725 We refer to these names below.
727 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
728 The first value is a keyword, like @option{:default}. The second part
729 is the value associated with that keyword, such as the text ``index''.
730 If you are familiar with Emacs Lisp property lists, the concept is
731 similar to that, except that in the SOURCES section, single directories
732 can be interspersed with two-value attributes.
734 @subheading Project Name
736 This is a string that indicates the name of the project. It is
737 primarily used for publishing interwiki links with the
738 @file{muse-wiki.el} module.
742 This part of a muse-project-alist entry consists of two-value
743 attributes, and also directory names. If you are publishing a book, the
744 order of directories and attributes is significant.
746 The minimal content for the sources section is a list of directories.
751 Indicates a new chapter of a book. The text of the title of the chapter
752 comes immediately after this keyword.
755 Indicates the end of a book. Directories listed after this one are
756 ignored when publishing a book. The value ``t'' (without quotes) should
757 come immediately after this keyword.
760 A function to call while publishing a book. This is useful for doing
761 something just after a particular chapter.
764 Indicates the beginning of a new part of the book. The text of the
765 title should come immediately after this keyword.
768 Indicate a particular publishing style to use for this part of the book.
769 If this is specified, it should come just after a @option{:part}
773 The default page to visit when browsing a project. Also, if you are
774 using the @file{muse-wiki.el} module, publishing a link to just a
775 project's name will cause it to link to this default file.
778 This specifies a list of pages which should be published every time a
779 project is published (by using @kbd{C-c C-p}, for example), regardless
780 of whether their contents have changed. This is useful for updating
781 Index pages, pages that use the @verb{|<include>|} tag, and other pages
782 that have dynamically-generated content.
785 This specifies the major mode to use when visiting files in this
786 project. The default is @code{muse-mode}.
789 This indicates that while publishing a book, do not automatically create
790 chapters. Values which may follow this are nil (the default, which
791 means that we automatically create chapters), or non-nil, which means
792 that we manually specify chapters with the @option{:book-chapter}
795 @item :publish-project
796 Indicates which function we should call when publishing a project.
799 This specifies a list of variables and values to set when publishing a
800 project. The list should be a property list, which is in the form:
803 (VAR1 VALUE1 VAR2 VALUE2 ...)
807 Specifies the function to call when visiting a link. The default is
808 @code{muse-visit-link-default}. The arguments for that function should
809 be (1) the link and (2) whether to visit the link in a new window.
815 This part of a muse-project-alist entry is composed of lists of
816 attributes. Each list is called an ``output style''.
818 The minimal content for an output style is a @option{:base} attribute
819 and a @option{:path} attribute.
824 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
827 An external URL which can be used to access published files. This is
828 mainly used by the @file{muse-wiki} module when publishing links between
829 two separate projects, if the projects are served on different domains.
831 It is also used by the @file{muse-journal} module to create the RSS or
835 Exclude items matching a regexp from being published. The regexp should
836 usually begin with "/".
839 Only include items matching a regexp when publishing. The regexp should
840 usually begin with "/".
843 The directory in which to store published files.
846 A file containing the timestamps (that is, time of creation) for files
847 in this project. It might eventually used by the @file{muse-blosxom}
848 module, but this option is not currently in use by any Muse code.
853 @node Keystroke Summary, Markup Rules, Projects, Top
854 @comment node-name, next, previous, up
855 @chapter Keys Used in Muse Mode
858 This is a summary of keystrokes available in every Muse buffer.
862 @item C-c C-a (`muse-index')
863 Display an index of all known Muse pages.
865 @item C-c C-b (`muse-find-backlinks')
866 Find all pages that link to this page.
868 @item C-c C-e (`muse-edit-link-at-point')
871 @item C-c C-f (`muse-project-find-file')
872 Open another Muse page. Prompt for the name.
874 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
875 Insert a link to a file interactively.
877 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
878 Insert a tag interactively.
880 @item C-c C-i u, C-c TAB u (`muse-insert-url')
881 Insert a URL interactively.
883 @item C-c C-l (`font-lock-mode')
884 Toggle font lock / highlighting for the current buffer.
886 @item C-c C-p (`muse-project-publish')
887 Publish any Muse pages that have changed.
889 @item C-c C-s (`muse-search')
890 Find text in all files of the current project.
892 @item C-c C-t (`muse-project-publish-this-file')
893 Publish the currently-visited file. Prompt for the style if the current
894 file can be published using more than one style.
896 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
897 Publish the currently-visited file. Prompt for both the style and
900 @item C-c C-v (`muse-browse-result')
901 Show the published result of this page.
903 @item C-c = (`muse-what-changed')
904 Diff this page against the last backup version.
907 Move to the next Wiki reference.
910 Move to the previous Wiki reference.
913 Complete the name of a page from the current project at point.
916 Insert a new list item at point, indenting properly.
919 Decrease the indentation of the list item at point.
922 Increase the indentation of the list item at point.
924 @item M-x muse-colors-toggle-inline-images RET
925 Toggle display of inlined images on/off.
927 @item M-x muse-update-values RET
928 Update various values that are automatically generated.
930 Call this after changing @code{muse-project-alist}.
934 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
935 @comment node-name, next, previous, up
936 @chapter Rules for Using Markup
939 A Muse document uses special, contextual markup rules to determine how
940 to format the output result. For example, if a paragraph is indented,
941 Muse assumes it should be quoted.
943 There are not too many markup rules, and all of them strive to be as
944 simple as possible so that you can focus on document creation, rather
948 * Paragraphs:: Paragraphs: centering and quoting.
949 * Headings:: Levels of headings.
950 * Directives:: Directives at the beginning of a
952 * Emphasizing Text:: Bold, italicized, and underlined text.
953 * Footnotes:: Making notes to be shown at the end.
954 * Verse:: Indicating poetic stanzas.
955 * Lists:: Lists of items.
956 * Tables:: Generation of data tables.
957 * Explicit Links:: Hyperlinks and email addresses with
959 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
961 * Images:: Publishing and displaying images.
962 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
963 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
965 * Citations:: Support for citing other resources.
966 * Comments:: Lines to omit from published output.
967 * Tag Summary:: Tags that Muse recognizes.
970 @node Paragraphs, Headings, Markup Rules, Markup Rules
971 @comment node-name, next, previous, up
972 @section Paragraphs: centering and quoting
975 Paragraphs in Muse must be separated by a blank line.
977 @cindex paragraphs, centered
978 @subheading Centered paragraphs and quotations
980 A line that begins with six or more columns of whitespace (either tabs
981 or spaces) indicates a centered paragraph. Alternatively, you can use
982 the @verb{|<center>|} tag to surround regions that are to be published
983 as centered paragraphs.
985 @cindex paragraphs, quoted
987 But if a line begins with whitespace, though less than six columns, it
988 indicates a quoted paragraph. Alternatively, you can use the
989 @verb{|<quote>|} tag to surround regions that are to be published as
993 @cindex monospace, rendering blocks
994 @cindex HTML, rendering blocks in monospace
995 @subheading Literal paragraphs
997 The @verb{|<example>|} tag is used for examples, where whitespace should
998 be preserved, the text rendered in monospace, and any characters special
999 to the output style escaped.
1001 @cindex literal text
1002 @cindex HTML, inserting a raw block
1003 There is also the @verb{|<literal>|} tag, which causes a marked block to
1004 be entirely left alone. This can be used for inserting a hand-coded
1005 HTML blocks into HTML output, for example.
1007 If you want some text to only be inserted when publishing to a
1008 particular publishing style, use the @option{style} attribute for the
1009 @verb{|<literal>|} tag. An example follows.
1012 <literal style="latex">
1013 A LaTeX-based style was used in the publishing of this document.
1017 This will leave the region alone if the current publishing style is
1018 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
1019 otherwise. It is also possible to leave the text alone only for one
1020 particular style, rather than its derivations, by adding
1021 @code{exact="t"} to the tag.
1024 @subheading Line breaks
1026 If you need a line break, then use the @samp{<br>} tag. Most of the
1027 time this tag is unnecessary, because Muse will automatically detect
1028 paragraphs by means of blank lines. If you want to preserve newlines in
1029 several lines of text, then use verse markup instead (@pxref{Verse}).
1031 @node Headings, Directives, Paragraphs, Markup Rules
1032 @comment node-name, next, previous, up
1033 @section Levels of headings
1036 A heading becomes a chapter or section in printed output -- depending on
1037 the style. To indicate a heading, start a new paragraph with one or
1038 more asterices, followed by a space and the heading title. Then begin
1039 another paragraph to enter the text for that section.
1041 All levels of headings will be published. Most publishing styles only
1042 distinguish the between the first 4 levels, however.
1054 @node Directives, Emphasizing Text, Headings, Markup Rules
1055 @comment node-name, next, previous, up
1056 @section Directives at the beginning of a document
1059 Directives are lines beginning with the @samp{#} character that come
1060 before any paragraphs or sections in the document. Directives are of
1061 the form ``#directive content of directive''. You can use any
1062 combination of uppercase and lowercase letters for directives, even if
1063 the directive is not in the list below.
1065 The @code{muse-publishing-directive} function may be used in header and
1066 footer text to access directives. For example, to access the
1067 @code{#title} directive, use @code{(muse-publishing-directive "title")}.
1069 The following is a list of directives that Muse uses.
1074 The author of this document.
1076 If this is not specified, Muse will attempt to figure it out from the
1077 @code{user-full-name} variable.
1081 The date that the document was last modified.
1083 This is used by publishing styles that are able to embed the date
1088 A short description of this document.
1090 This is used by the @code{journal} publishing style to embed information
1091 inside of an RSS/RDF feed.
1095 The title of this document.
1097 If this is not specified, the name of the file is used.
1101 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1102 @comment node-name, next, previous, up
1103 @section Bold, italicized, and underlined text
1104 @cindex emphasizing text
1105 @cindex underlining text
1106 @cindex italicizing text
1107 @cindex verbatim text
1108 @cindex monospace, rendering words
1110 To emphasize text, surround it with certain specially recognized
1116 ***very strong emphasis***
1118 =verbatim and monospace=
1122 While editing a Muse document in Muse mode, these forms of emphasis will
1123 be highlighted in a WYSIWYG manner. Each of these forms may span
1126 Verbatim text will be colored as gray by default. To change this,
1127 customize @code{muse-verbatim-face}.
1129 You can also use the @verb{|<code>|} tag to indicate verbatim and
1130 monospace text. This is handy for regions that have an ``='' in them.
1132 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1133 @comment node-name, next, previous, up
1134 @section Making notes to be shown at the end
1137 A footnote reference is simply a number in square brackets. To define
1138 the footnote, place this definition at the bottom of your file.
1139 @samp{footnote-mode} can be used to greatly facilitate the creation of
1140 these kinds of footnotes.
1142 Footnotes are defined by the same number in brackets occurring at the
1143 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1144 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1145 the point of insertion.
1147 @node Verse, Lists, Footnotes, Markup Rules
1148 @comment node-name, next, previous, up
1149 @section Indicating poetic stanzas
1153 Poetry requires that whitespace be preserved, but without resorting to
1154 monospace. To indicate this, use the following markup, reminiscent of
1158 > A line of Emacs verse;
1159 > forgive its being so terse.
1162 You can also use the @verb{|<verse>|} tag, if you prefer.
1166 A line of Emacs verse;
1167 forgive its being so terse.
1171 @cindex verses, multiple stanzas
1172 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1177 A line of Emacs verse;
1178 forgive its being so terse.
1180 In terms of terse verse,
1185 @node Lists, Tables, Verse, Markup Rules
1186 @comment node-name, next, previous, up
1187 @section Lists of items
1190 Lists are given using special characters at the beginning of a line.
1191 Whitespace must occur before bullets or numbered items, to distinguish
1192 from the possibility of those characters occurring in a real sentence.
1194 @cindex lists, bullets
1195 These are rendered as a bullet list.
1204 @cindex lists, enumerated
1205 An enumerated list follows.
1214 @cindex lists, definitions
1215 Here is a definition list.
1219 This is a first definition
1220 And it has two lines;
1221 no, make that three.
1223 Term2 :: This is a second definition
1226 @subheading Nested lists
1228 @cindex lists, nested
1229 It is possible to nest lists of the same or different kinds. The
1230 ``level'' of the list is determined by the amount of initial whitespace.
1235 - Level 1, bullet item one
1236 1. Level 2, enum item one
1237 2. Level 2, enum item two
1238 - Level 1, bullet item two
1239 1. Level 2, enum item three
1240 2. Level 2, enum item four
1244 @subheading Breaking list items
1246 @cindex lists, breaking lines
1247 If you want to break up a line within any list type, just put one blank
1248 line between the end of the previous line and the beginning of the next
1249 line, using the same amount of initial indentation.
1252 - bullet item 1, line 1
1254 bullet item 1, line 2
1260 - bullet item 2, line 1
1262 bullet item 2, line 2
1265 @node Tables, Explicit Links, Lists, Markup Rules
1266 @comment node-name, next, previous, up
1267 @section Generation of data tables
1270 @cindex tables, simple
1271 Only very simple tables are supported. The syntax is as follows.
1274 Double bars || Separate header fields
1276 Single bars | Separate body fields
1277 Here are more | body fields
1279 Triple bars ||| Separate footer fields
1282 Some publishing styles require header fields to come first, then footer
1283 fields, and then the body fields. You can use any order for these
1284 sections that you like, and Muse will re-order them for you at
1287 If you wish to disable table generation for one Muse file, add the
1288 directive @samp{#disable-tables t} to the top of the file.
1290 @subheading Other table formats
1292 @cindex tables, orgtbl-mode style
1293 It is possible to publish very basic Orgtbl-mode style tables.
1296 | org | style | table |
1297 |------+-------+-------|
1301 |------+-------+-------|
1305 If you are used to the way that Org Mode publishes these tables, then
1306 customize `muse-html-table-attributes' to the following, in order to get
1307 a similar kind of output.
1310 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1313 @cindex tables, table.el style
1314 @file{table.el} style tables are also supported, as long as
1315 @file{table.el} itself supports outputting tables for a particular
1316 publishing style. At the time of this writing, the ``html'', ``latex'',
1317 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1318 from these styles will also work.
1330 @node Explicit Links, Implicit Links, Tables, Markup Rules
1331 @comment node-name, next, previous, up
1332 @section Hyperlinks and email addresses with descriptions
1333 @cindex links, explicit
1335 A hyperlink can reference a URL, or another page within a Muse
1336 project. In addition, descriptive text can be specified, which should
1337 be displayed rather than the link text in output styles that supports
1338 link descriptions. The syntax is as follows.
1341 [[link target][link description]]
1342 [[link target without description]]
1345 Thus, the current maintainer's homepage for Muse can be found
1346 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1347 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1349 @node Implicit Links, Images, Explicit Links, Markup Rules
1350 @comment node-name, next, previous, up
1351 @section Bare URLs, WikiNames, and InterWiki links
1352 @cindex links, implicit
1356 @cindex Email addresses
1358 A URL or email address encountered in the input text is published as a
1359 hyperlink. These kind of links are called @dfn{implicit links} because
1360 they are not separated from the rest of the Muse document in any way.
1362 Some characters in URLs will prevent Muse from recognizing them as
1363 implicit links. If you want to link to a URL containing spaces or any of
1364 the characters ``][,"'`()<>^'', you will have to make the link
1365 explicit. The punctuation characters ``.,;:'' are also not recognized as
1366 part of a URL when they appear at its end. For information on how to
1367 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1368 addresses with descriptions}.
1371 If the @command{muse-wiki} module is loaded, another form of implicit
1372 link will be made available. WikiNames, which are typed in CamelCase,
1373 are highlighted and published as links, provided that the file they
1376 Customization of WikiName recognition may be accomplished by editing the
1377 @code{muse-wiki-wikiword-regexp} option and subsequently running
1378 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1379 If you use the Customize interface, the latter will be done
1382 @cindex InterWiki links
1383 @cindex inter-project links
1384 The @command{muse-wiki} module also allows for InterWiki links. These
1385 are similar to WikiWords, but they specify both the project and page of
1386 a file. The names of your project entries in @code{muse-project-alist}
1387 will be used as InterWiki names by default. Several examples follow.
1390 Blog::DocumentingMuse
1395 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1396 the project name, and @samp{DocumentingMuse} is the page name. In the
1397 second example, @samp{#} is the interwiki delimiter. If the name of a
1398 project occurs by itself in text, like the third case, it will be
1399 colorized and published as a link to the default page of the given
1402 Customization of interwiki links may be accomplished by editing the
1403 @code{muse-wiki-interwiki-alist} option.
1405 It is also possible to link to an anchor in an interwiki document. This
1406 is called a ``three-part link''. Examples of this follow.
1409 Blog::DocumentingMuse#anchor1
1410 Projects#EmacsMuse#anchor2
1413 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1414 @comment node-name, next, previous, up
1415 @section Publishing and displaying images
1417 @cindex links, with images
1418 @subheading Image links
1420 Links to images may be used in either the target or the description, or
1421 both. Thus, the following code will publish as a clickable image that
1422 points to @url{http://mwolson.org/}.
1425 [[http://mwolson.org/][/static/logos/site-logo.png]]
1428 Normally, images in the link part will be inlined.
1430 If you want these images to be published as links instead, place the
1431 text ``URL:'' immediately in front of the link text. An example
1435 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1438 @cindex images, displaying
1439 @cindex images, local
1440 @subheading Displaying images in Muse mode
1441 If a link to a locally-available image is encountered in the link
1442 description, Muse mode will attempt to display it if your version of
1445 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1446 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1448 The method for finding images may be altered by customizing the
1449 @code{muse-colors-inline-image-method} option. One useful value for
1450 this option is @code{muse-colors-use-publishing-directory}, which tells
1451 Muse mode to look in the directory where the current file will be
1452 published. The default is to look in the current directory. Relative
1453 paths like @samp{../pics/} should work for either setting.
1455 Eventually, it is hoped that Muse will be able to copy images from the a
1456 ``source'' directory to a publishing directory by customizing
1457 @code{muse-project-alist}, but this has not been implemented yet.
1459 @cindex images, without descriptions
1460 @cindex images, inlined
1461 @subheading Publishing simple images
1462 The following example will display correctly and publish correctly if a
1463 @acronym{PNG} file called @file{TestLogo.png} exists in the
1464 @file{../pics/} directory. If text is on the same line as the picture,
1465 it will remain so in the output.
1471 @cindex images, captions
1472 @subheading Publishing images with captions
1473 If you want to add a caption to an image, use the following syntax.
1474 This will center the image (if the output format supports it) and add a
1475 centered caption below the picture. Formats that do not support
1476 centering the image will instead leave it against the left margin.
1479 [[../pics/mycat.png][My cat Dexter]]
1482 Images with captions may only occur in their own paragraphs, with no
1483 text on the same line. Otherwise, the published output will not be
1484 syntactically correct.
1486 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1487 @comment node-name, next, previous, up
1488 @section Inserting a horizontal line or anchor
1490 @cindex horizontal rules
1492 @subheading Horizontal Rules
1494 Four or more dashes indicate a horizontal rule. Be sure to put blank
1495 lines around it, or it will be considered part of the proceeding or
1496 following paragraph!
1499 @cindex links, with target on same page
1502 If you begin a line with "#anchor" -- where "anchor" can be any word
1503 that doesn't contain whitespace -- it defines an anchor at that point
1504 into the document. This point can be referenced using "page#anchor" as
1505 the target in a Muse link.
1507 @node Embedded Lisp, Citations, Horizontal Rules and Anchors, Markup Rules
1508 @comment node-name, next, previous, up
1509 @section Evaluating Emacs Lisp code in documents for extensibility
1510 @cindex lisp, embedded
1512 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag.
1513 With the @verb{|<lisp>|} tag, you may generate whatever output text you
1514 wish. The inserted output will get marked up if the @verb{|<lisp>|}
1515 tag appears within the main text of the document.
1518 <lisp>(concat "This form gets " "inserted")</lisp>
1521 @cindex lisp, and insert command
1522 Note that you should not use the @code{insert} command within a set of
1523 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1524 tags will be automatically inserted into the document.
1526 It is also possible to treat the output as if it were surrounded by the
1527 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1528 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1529 attribute of the @verb{|<lisp>|} tag.
1532 <lisp markup="example">
1533 (concat "Insert" " me")
1537 Other languages also have tags that cause source code to be evaluated.
1538 @xref{Tag Summary}, for details.
1540 @node Citations, Comments, Embedded Lisp, Markup Rules
1541 @comment node-name, next, previous, up
1542 @section Support for citing other resources
1544 @cindex tags, <cite>
1548 Here is an example of what citations look like in a Muse document.
1556 Some text before <cite>Miller1999</cite> and after the citation.
1558 This is an author-only citation <cite type="author">Miller1999</cite>.
1560 And this is a year-only citation <cite type="year">Miller1999</cite>.
1562 Finally, this is a multi-head citation
1563 <cite>Miller1999,Andrews2005</cite>.
1566 @subheading Overview
1568 The @code{#bibsource} directive defines the source of the
1569 bibliographies. The following sources are possible.
1572 @item DocBook + RefDB:
1575 @item LaTeX + bibtex:
1576 the name of an appropriate bibtex file
1578 @item LaTeX + RefDB:
1579 if the input file is called "foo.muse", then set this to "foo.bib"
1582 Citations are encoded as @verb{|<cite>|} elements which enclose the
1583 citation keys as they are defined in the bibliography file or database.
1584 In multi-head citations, the citation keys have to be separated by
1585 colons or semicolons. The @code{latex} and @code{docbook} styles
1586 translate these to the proper separator automatically.
1588 The @verb{|<cite>|} elements take an optional ``type'' attribute that
1589 defines how the citation is rendered. If the attribute is missing,
1590 you'll get a regular citation according to the bibliography style,
1591 e.g.'' (Miller et al., 1999)''. If the attribute is set to "author",
1592 only the name of the author(s) will be rendered. Accordingly, "year"
1593 will cause the year to be printed. This is useful to create citations
1597 Miller et al. had already shown in a previous publication (1999) that
1598 this is not going to work.
1601 Remember that refdb-mode (the Emacs interface to RefDB) can retrieve
1602 references by simply marking the citation key and running the
1603 @code{refdb-getref-by-field-on-region} command. Later versions of
1604 @code{refdb-mode} will also allow to insert references as Muse citations
1605 (which is already implemented for DocBook, TEI, and LaTeX documents).
1607 You may have noticed that there is no element to indicate the position
1608 of the bibliography. The latter is always created at a valid position
1609 close to the end of the document. The functions
1610 @code{muse-docbook-bibliography} and @code{muse-latex-bibliography} are
1611 called in the header or footer to generate this content, so it is
1612 possible to change the exact position.
1614 @node Comments, Tag Summary, Citations, Markup Rules
1615 @comment node-name, next, previous, up
1616 @section Lines to omit from published output
1618 @cindex publishing, omitting lines
1620 Use the following syntax to indicate a comment. Comments will not be
1624 ; Comment text goes here.
1627 That is, only a semi-colon at the beginning of a line, followed by a
1628 literal space, will cause that line to be treated as a comment.
1630 You can alternatively surround the region with the @verb{|<comment>|}
1633 If you wish the comment to be published, but just commented out using
1634 the comment syntax of the output format, then set
1635 @option{muse-publish-comments-p} to non-nil.
1637 @node Tag Summary, , Comments, Markup Rules
1638 @comment node-name, next, previous, up
1639 @section Tags that Muse recognizes
1641 @cindex inserting files at publish time
1642 @cindex publishing, including markup in headers and footers
1643 @cindex publishing, inserting files
1645 Muse has several built-in tags that may prove useful during publishing.
1646 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1647 Muse uses, as well as make your own tags.
1649 Only a small subset of these tags are available in header and footer
1650 text. The @code{muse-publish-markup-header-footer-tags} option lists
1651 the tags that are allowed in headers and footers.
1655 If a tag takes arguments, it will look like this, where ``tagname'' is
1656 the name of the tag.
1659 <tagname arg1="string1" arg2="string2">
1662 If you want the tag to look like it came straight from an XHTML
1663 document, you can alternatively do the following.
1666 <tagname arg1="string1" arg2="string2" />
1669 If a tag surrounds some text, it will look like this.
1672 <tagname>Some text</tagname>
1675 If a tag surrounds a large region, it will look like this.
1684 @subheading Tag listing
1686 This is the complete list of tags that Muse accepts, including those
1687 that were mentioned in previous sections.
1692 Insert a line break.
1694 Muse will automatically detect paragraphs when publishing by means of
1695 blank lines, so this tag is usually unnecessary.
1698 Insert a citation to another source.
1700 This takes the argument @option{type}, which indicates the type of
1701 citation. The valid types are "author" and "year". If this argument is
1702 omitted, include both author and year in the citation.
1704 The bibliography to use for the citation may be specified by the
1705 @option{#bibsource} directive.
1707 @xref{Citations}, for additional information.
1710 If publishing to HTML, surround the given text with a @verb{|<span>|}
1711 tag. It takes one argument called ``name'' that specifies the ``class''
1712 attribute of the @verb{|<span>|} tag.
1714 If publishing to a different format, do nothing extra to the text.
1717 Treat the text surrounded by the tag as if they were enclosed in equal
1718 signs, that is, make it monospace.
1721 Run a command on the region, replacing the region with the result of the
1722 command. The command is specified with the ``interp'' argument. If no
1723 value for ``interp'' is given, pass the entire region to the shell.
1725 The ``markup'' argument controls how this section is marked up.
1727 If it is omitted, publish the region with the normal Muse rules.
1729 If "nil", do not mark up the region at all, but prevent Muse from
1730 further interpreting it.
1732 If "example", treat the region as if it was surrounded by the
1733 @verb{|<example>|} tag.
1735 If "src", treat the included text as if it was surrounded by the
1736 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1739 If "verse", treat the region as if it was surrounded by the
1740 @verb{|<verse>|} tag, to preserve newlines.
1742 Otherwise, it should be the name of a function to call, with the buffer
1743 narrowed to the region.
1746 Treat the entire region as a comment. If the option
1747 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1748 publish it using the comment syntax of the current publishing style.
1751 Publish a Table of Contents. This will either be inserted in-place or
1752 at the beginning of the document, depending on your publishing style.
1753 It does not have a delimiting tag.
1755 By default, only 2 levels of headings will be included in the generated
1756 Table of Contents. To change this globally, customize the
1757 @var{muse-publish-contents-depth} option. To change this only for the
1758 current tag, use the ``depth'' argument.
1761 Publish the region in monospace, preserving the newlines in the region.
1762 This is useful for snippets of code.
1765 Insert the given file at the current location during publishing. The
1766 basic use of this tag is as follows, replacing ``included_file'' with
1767 the name of the file that you want to include.
1770 <include file="included_file">
1773 The ``markup'' argument controls how this section is marked up.
1775 If it is omitted, publish the included text with the normal Muse
1778 If "nil", do not mark up the included text at all.
1780 If "example", treat the included text as if it was surrounded by the
1781 @verb{|<example>|} tag.
1783 If "src", treat the included text as if it was surrounded by the
1784 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1787 If "verse", treat the included text as if it was surrounded by the
1788 @verb{|<verse>|} tag, to preserve newlines.
1790 Otherwise, it should be the name of a function to call after inserting
1791 the file with the buffer narrowed to the section inserted.
1794 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1795 The result is then inserted into the document, so you do not need to
1796 explicitly call @code{insert}. All text properties are removed from the
1799 This tag takes the ``markup'' argument. See the description of
1800 @verb{|<command>|} for details.
1803 Make sure that the text enclosed by this tag is published without
1804 escaping it in any way. This is useful for inserting markup directly
1805 into the published document, when Muse does not provide the desired
1809 Mark up the text between the initial and ending tags. The markup
1810 command to use may be specified by the ``function'' argument. The
1811 standard Muse markup routines are used by default if no ``function''
1812 argument is provided.
1814 This is useful for marking up regions in headers and footers. One
1815 example that comes to mind is generating a published index of all of the
1816 files in the current project by doing the following.
1819 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1823 Run the @command{perl} language interpreter on the region, replacing the
1824 region with the result of the command.
1826 This tag takes the ``markup'' argument. See the description of
1827 @verb{|<command>|} for details.
1830 Run the @command{python} language interpreter on the region, replacing
1831 the region with the result of the command.
1833 This tag takes the ``markup'' argument. See the description of
1834 @verb{|<command>|} for details.
1837 Publish the region as a blockquote. This will either be inserted
1838 in-place or at the beginning of the document, depending on your
1839 publishing style. It does not have a delimiting tag.
1842 Run the @command{ruby} language interpreter on the region, replacing the
1843 region with the result of the command.
1845 This tag takes the ``markup'' argument. See the description of
1846 @verb{|<command>|} for details.
1849 Publish the region using htmlize.
1850 The language to use may be specified by the ``lang'' attribute.
1852 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1853 the value of the ``lang'' attribute.
1855 This tag requires htmlize 1.34 or later in order to work. If this is
1856 not satisfied, or the current publishing style is not HTML-based, Muse
1857 will publish the region like an @verb{|<example>|} tag.
1860 This is used when you want to prevent Muse from trying to interpret some
1861 markup. Surround the markup in @verb{|<verbatim>|} and
1862 @verb{|</verbatim>|}, and it will not be interpreted.
1864 This tag was used often in previous versions of Muse because they did
1865 not support whole-document escaping of specials. Now, it will only be
1866 needed for other tags, and perhaps footnotes as well.
1869 Preserve the newlines in the region. In formats like HTML, newlines are
1870 removed by default, hence the need for this tag. In other publishing
1871 styles, this tag may cause the text to be indented slightly in a way
1872 that looks nice for poetry and prose.
1876 @node Publishing Styles, Extending Muse, Markup Rules, Top
1877 @comment node-name, next, previous, up
1878 @chapter Publishing Various Types of Documents
1879 @cindex publishing styles
1881 One of the principle features of Muse is the ability to publish a simple
1882 input text to a variety of different output styles. Muse also makes it
1883 easy to create new styles, or derive from an existing style.
1886 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1887 * Book:: Publishing entries into a compilation.
1888 * ConTeXt:: Publishing ConTeXt documents.
1889 * DocBook:: Publishing in DocBook XML form.
1890 * HTML:: Publishing in HTML or XHTML form.
1891 * Journal:: Keeping a journal or blog.
1892 * LaTeX:: Publishing LaTeX documents.
1893 * Poem:: Publish a poem to LaTeX or PDF.
1894 * Texinfo:: Publish entries to Texinfo format or PDF.
1895 * XML:: Publish entries to XML.
1898 @node Blosxom, Book, Publishing Styles, Publishing Styles
1899 @comment node-name, next, previous, up
1900 @section Integrating Muse and pyblosxom.cgi
1901 @cindex blog, one-file-per-entry style
1903 The Blosxom publishing style publishes a tree of categorised files to a
1904 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1905 In other words, each blog entry corresponds with one file.
1908 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1909 * Blosxom Entries:: Format of a Blosxom entry and automation.
1910 * Blosxom Options:: Blosxom styles and options provided.
1913 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1914 @comment node-name, next, previous, up
1915 @subsection Other tools needed for the Blosxom style
1917 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1918 installed on a machine that you have upload access to.
1920 The major difficulty in both of these programs is specifying the date of
1921 the entries. Both programs rely on the file modification time rather
1922 than any data contained in the entries themselves. A plugin is needed
1923 in order for these programs to be able to get the correct date.
1925 @subheading PyBlosxom
1927 There are two different ways of accomplishing this in pyblosxom. The
1928 first way involves gathering the timestamps (as specified by the
1929 @code{#date} directive) into one file and then sending that file along
1930 with published entries to the webserver.
1932 The second will read each file at render time and parse the
1933 @code{#postdate} directive. Muse will translate the @code{#date}
1934 directive into @code{#postdate} at publish time, so you don't have to do
1937 @subsubheading Placing timestamps in one file
1939 The following additional components are required in order to make the
1940 date of blog entries display as something sensible.
1944 A script to gather date directives from the entire blog tree into a
1945 single file. The file must associate a blog entry with a date.
1948 A plugin for (py)blosxom that reads this file.
1951 These 2 things are provided for @command{pyblosxom.cgi} in the
1952 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1953 former service, while @file{hardcodedates.py} provides the latter
1956 Here is a sample listing from my @file{timestamps} file, which maps
1957 each file to a date. This can really be in any format, as long as your
1958 date-gathering script and your plugin can both understand it.
1961 2005-04-01-14-16 personal/paper_cranes
1962 2005-03-21 personal/spring_break_over
1963 2004-10-24 personal/finished_free_culture
1966 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1967 @file{getstamps.py}. Note that you will need to set the current
1968 directory to where your Muse files are, execute @file{getstamps.py}, and
1969 then move the generated timestamps file to your publishing directory.
1971 @subsubheading Getting timestamp from entry while rendering
1973 Alternately, the pyblosxom metadate plugin may be used. On the plus
1974 side, there is no need to run a script to gather the date. On the
1975 downside, each entry is read twice rather than once when the page is
1976 rendered. Set the value of @code{muse-blosxom-use-metadate} to non-nil
1977 to enable adding a @code{#postdate} directive to all published files.
1981 M-x customize-variable RET muse-blosxom-use-metadate RET
1984 With the metadate plugin installed in pyblosxom, the date set in this
1985 directive will be used instead of the file's modification time. The
1986 plugin is included with Muse at @file{contrib/pyblosxom/metadate.py}.
1990 It is also possible to use Blosxom, which is written in Perl, to serve
1991 blog entries that were published with Muse. The steps are as follows.
1995 Download and install blosxom from @url{http://blosxom.sourceforge.net/}.
1998 Install the metadate plugin. It is available in
1999 @file{contrib/blosxom/metadate_0_0_3}.
2002 Every time you make a new blog entry, change to the blosxom data
2003 directory and execute the @file{contrib/blosxom/getstamps.pl} script.
2004 This script has only recently been made, and may still have some bugs,
2005 so use with caution.
2009 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
2010 @comment node-name, next, previous, up
2011 @subsection Format of a Blosxom entry and automation
2013 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
2014 longer `#date yyyy-mm-dd-hh-mm', a title (using the @code{#title}
2015 directive), plus whatever normal content is desired.
2017 The date directive is not used directly by @command{pyblosxom.cgi} or
2018 this program. You need to have the two additional items from the former
2019 section to make use of this feature.
2021 There is a function called @code{muse-blosxom-new-entry} that will
2022 automate the process of making a new blog entry. To make use of it, do
2027 Customize @code{muse-blosxom-base-directory} to the location that your
2028 blog entries are stored.
2031 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
2032 use the following code to assign this function to @kbd{C-c p l'}.
2035 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
2039 You should create your directory structure ahead of time under your base
2040 directory. These directories, which correspond with category names, may
2044 When you enter this key sequence, you will be prompted for the category
2045 of your entry and its title. Upon entering this information, a new file
2046 will be created that corresponds with the title, but in lowercase
2047 letters and having special characters converted to underscores. The
2048 title and date directives will be inserted automatically.
2051 @node Blosxom Options, , Blosxom Entries, Blosxom
2052 @comment node-name, next, previous, up
2053 @subsection Blosxom styles and options provided
2055 The following styles and options are available in the Blosxom publishing
2058 @subheading Styles provided
2062 @cindex publishing styles, blosxom-html
2064 Publish Blosxom entries in HTML form.
2066 @cindex publishing styles, blosxom-xhtml
2068 Publish Blosxom entries in XHTML form.
2072 @subheading Options provided
2076 @item muse-blosxom-extension
2077 Default file extension for publishing Blosxom files.
2079 @item muse-blosxom-header
2080 Header used for publishing Blosxom files.
2082 This may be text or a filename.
2084 @item muse-blosxom-footer
2085 Footer used for publishing Blosxom files.
2087 This may be text or a filename.
2089 @item muse-blosxom-base-directory
2090 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
2092 This is the top-level directory where your blog entries may be found
2097 @node Book, ConTeXt, Blosxom, Publishing Styles
2098 @comment node-name, next, previous, up
2099 @section Publishing entries into a compilation
2101 This publishing style is used to output ``books'' in LaTeX or PDF
2104 Each page will become a separate chapter in the book, unless the style
2105 keyword @option{:nochapters} is used, in which case they are all run
2106 together as if one giant chapter.
2108 One way of publishing a book is to make a project for it, add the
2109 project to @code{muse-project-alist}, and use the @code{book-pdf} style
2110 with a very specific @option{:include} value to specify some page whose
2111 contents will be checked for the values of @code{#title} and
2112 @code{#date}, and whose name will be used in the output file. Then to
2113 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
2114 @kbd{C-c C-p} to trigger the publishing process. An example
2115 @code{muse-project-alist} for this method follows.
2118 (setq muse-project-alist
2119 '(("MyNotes" (:nochapters t ; do automatically add chapters
2120 :book-chapter "Computer Science"
2122 :book-chapter "Mathematics"
2124 :book-chapter "Emacs"
2126 :book-end t ; the rest will not be placed in the book
2127 "~/Notes" ; so we can find the notes-anthology page
2129 :force-publish ("index")
2132 :include "/notes-anthology[^/]*$"
2133 :path "~/public_html/notes")
2134 ;; other publishing styles for each directory go here,
2139 In this example, there would be a file called
2140 @file{~/Notes/notes-anthology.muse}, which would contain just the
2141 following. The resulting book would be published to
2142 @file{~/public_html/notes/notes-anthology.pdf}.
2145 #title My Technology Ramblings
2148 Another way is to call the @code{muse-book-publish-project} function
2149 manually, with a custom project entry. An example of this may be found
2150 in John Wiegley's configuration file at
2151 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
2154 @subheading Styles provided
2158 @cindex publishing styles, book-latex
2160 Publish a book in LaTeX form. The header and footer are different than
2161 the normal LaTeX publishing mode.
2163 @cindex publishing styles, book-pdf
2165 Publish a book in PDF form. The header and footer are different than
2166 the normal PDF publishing mode.
2170 @subheading Options provided
2174 @item muse-book-before-publish-hook
2175 A hook run in the book buffer before it is marked up.
2177 @item muse-book-after-publish-hook
2178 A hook run in the book buffer after it is marked up.
2180 @item muse-book-latex-header
2181 Header used for publishing books to LaTeX.
2183 This may be text or a filename.
2185 @item muse-book-latex-footer
2186 Footer used for publishing books to LaTeX.
2188 This may be text or a filename.
2191 @node ConTeXt, DocBook, Book, Publishing Styles
2192 @comment node-name, next, previous, up
2193 @section Publishing ConTeXt documents
2195 This publishing style is capable of producing ConTeXt or PDF documents.
2197 If you wish to publish PDF documents based on ConTeXt, you will need to
2198 have it installed. For Debian and Ubuntu, this can be accomplished by
2199 installing the ``texlive'' package.
2201 @subheading Styles provided
2205 @cindex publishing styles, context
2207 Publish a ConTeXt document.
2209 @cindex publishing styles, context-pdf
2211 Publish a PDF document, using an external ConTeXt document conversion
2214 @cindex publishing styles, context-slides
2215 @item context-slides
2216 Produce slides from a ConTeXt document.
2218 Here is an example of a slide.
2223 [[Some-sort-of-cute-image.png]]
2228 - Another bullet point.
2235 @cindex publishing styles, context-slides-pdf
2236 @item context-slides-pdf
2237 Publish a PDF document of ConTeXt slides.
2241 @subheading Options provided
2245 @item muse-context-extension
2246 Default file extension for publishing ConTeXt files.
2248 @item muse-context-pdf-extension
2249 Default file extension for publishing ConTeXt files to PDF.
2251 @item muse-context-pdf-program
2252 The program that is called to generate PDF content from ConTeXt content.
2254 @item muse-context-pdf-cruft
2255 Extensions of files to remove after generating PDF output successfully.
2257 @item muse-context-header
2258 Header used for publishing ConTeXt files.
2260 This may be text or a filename.
2262 @item muse-context-footer
2263 Footer used for publishing ConTeXt files.
2265 This may be text or a filename.
2267 @item muse-context-markup-regexps
2268 List of markup regexps for identifying regions in a Muse page.
2270 For more on the structure of this list,
2271 @xref{muse-publish-markup-regexps}.
2273 @item muse-context-markup-functions
2274 An alist of style types to custom functions for that kind of text.
2276 For more on the structure of this list,
2277 @xref{muse-publish-markup-functions}.
2279 @item muse-context-markup-strings
2280 Strings used for marking up text.
2282 These cover the most basic kinds of markup, the handling of which
2283 differs little between the various styles.
2285 @item muse-context-slides-header
2286 Header for publishing a presentation (slides) using ConTeXt.
2288 Any of the predefined modules, which are available in the
2289 tex/context/base directory, can be used by writing a "module" directive
2290 at the top of the Muse file; if no such directive is provided, module
2291 pre-01 is used. Alternatively, you can use your own style ("mystyle",
2292 in this example) by replacing "\usemodule[]" with "\input mystyle".
2294 This may be text or a filename.
2296 @item muse-context-slides-markup-strings
2297 Strings used for marking up text in ConTeXt slides.
2299 @item muse-context-markup-specials-document
2300 A table of characters which must be represented specially.
2301 These are applied to the entire document, sans already-escaped
2304 @item muse-context-markup-specials-example
2305 A table of characters which must be represented specially.
2306 These are applied to @verb{|example>|} regions.
2308 With the default interpretation of @verb{|<example>|} regions, no
2309 specials need to be escaped.
2311 @item muse-context-markup-specials-literal
2312 A table of characters which must be represented specially.
2313 This applies to =monospaced text= and @verb{|<code>|} regions.
2315 @item muse-context-markup-specials-url
2316 A table of characters which must be represented specially.
2317 These are applied to URLs.
2319 @item muse-context-markup-specials-image
2320 A table of characters which must be represented specially.
2321 These are applied to image filenames.
2323 @item muse-context-permit-contents-tag
2324 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2327 Most of the time, it is best to have a table of contents on the
2328 first page, with a new page immediately following. To make this
2329 work with documents published in both HTML and ConTeXt, we need to
2330 ignore the @verb{|<contents>|} tag.
2332 If you don't agree with this, then set this option to non-nil,
2333 and it will do what you expect.
2337 @node DocBook, HTML, ConTeXt, Publishing Styles
2338 @comment node-name, next, previous, up
2339 @section Publishing in DocBook XML form
2341 This publishing style is used to generate DocBook XML files.
2343 @subheading Styles provided
2347 @cindex publishing styles, docbook
2349 Publish a file in Docbook form.
2353 @subheading Options provided
2355 This publishing style uses the same options for markup up special
2356 characters as the ``xml'' publishing style. @xref{XML}, for details.
2360 @item muse-docbook-extension
2361 Default file extension for publishing DocBook XML files.
2363 @item muse-docbook-header
2364 Header used for publishing DocBook XML files.
2366 This may be text or a filename.
2368 @item muse-docbook-footer
2369 Footer used for publishing DocBook XML files.
2371 This may be text or a filename.
2373 @item muse-docbook-markup-regexps
2374 List of markup rules for publishing a Muse page to DocBook XML.
2376 @item muse-docbook-markup-functions
2377 An alist of style types to custom functions for that kind of text.
2379 @item muse-docbook-markup-strings
2380 Strings used for marking up text.
2382 These cover the most basic kinds of markup, the handling of which
2383 differs little between the various styles.
2385 @item muse-docbook-encoding-default
2386 The default Emacs buffer encoding to use in published files.
2387 This will be used if no special characters are found.
2389 @item muse-docbook-charset-default
2390 The default DocBook XML charset to use if no translation is
2391 found in @code{muse-xml-encoding-map}.
2395 @node HTML, Journal, DocBook, Publishing Styles
2396 @comment node-name, next, previous, up
2397 @section Publishing in HTML or XHTML form
2399 This publishing style is capable of producing HTML or XHTML documents.
2401 @subheading Styles provided
2405 @cindex publishing styles, html
2407 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2410 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2414 @subheading Options provided
2416 If an HTML option does not have a corresponding XHTML option, it will
2417 be used for both of these publishing styles.
2419 These publishing styles use the same options for markup up special
2420 characters as the ``xml'' publishing style. @xref{XML}, for details.
2424 @item muse-html-extension
2425 Default file extension for publishing HTML files.
2427 @item muse-xhtml-extension
2428 Default file extension for publishing XHTML files.
2430 @item muse-html-style-sheet
2431 Store your stylesheet definitions here.
2433 This is used in @code{muse-html-header}. You can put raw CSS in here or
2434 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2435 @verb{|<lisp>|} markup tags.
2437 If you are publishing to XHTML, then customize the
2438 @code{muse-xhtml-style-sheet} option instead.
2440 @item muse-xhtml-style-sheet
2441 Store your stylesheet definitions here.
2443 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2444 or a @verb{|<link>|} tag to an external stylesheet. This text may
2445 contain @verb{|<lisp>|} markup tags.
2447 @item muse-html-header
2448 Header used for publishing HTML files.
2450 This may be text or a filename.
2452 @item muse-html-footer
2453 Footer used for publishing HTML files.
2455 This may be text or a filename.
2457 @item muse-xhtml-header
2458 Header used for publishing XHTML files.
2460 This may be text or a filename.
2462 @item muse-xhtml-footer
2463 Footer used for publishing XHTML files.
2465 This may be text or a filename.
2467 @item muse-html-anchor-on-word
2468 When true, anchors surround the closest word.
2470 This allows you to select them in a browser (i.e. for pasting), but has
2471 the side-effect of marking up headers in multiple colors if your header
2472 style is different from your link style.
2474 @item muse-html-table-attributes
2475 The attribute to be used with HTML @verb{|<table>|} tags.
2477 If you want to make more-complicated tables in HTML, surround the HTML
2478 with the @verb{|literal|} tag, so that it does not get escaped.
2480 @item muse-html-markup-regexps
2481 List of markup rules for publishing a Muse page to HTML.
2483 @item muse-html-markup-functions
2484 An alist of style types to custom functions for that kind of text.
2486 @item muse-html-markup-strings
2487 Strings used for marking up text as HTML.
2489 These cover the most basic kinds of markup, the handling of which
2490 differs little between the various styles.
2492 @item muse-xhtml-markup-strings
2493 Strings used for marking up text as XHTML.
2495 These cover the most basic kinds of markup, the handling of which
2496 differs little between the various styles.
2498 @item muse-html-markup-tags
2499 A list of tag specifications, for specially marking up HTML.
2500 @xref{muse-publish-markup-tags}, for more information.
2502 @item muse-html-meta-http-equiv
2503 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2505 @item muse-html-meta-content-type
2506 The content type used for the HTML @verb{|<meta>|} tag.
2508 If you are striving for XHTML 1.1 compliance, you may want to change
2509 this to ``application/xhtml+xml''.
2511 @item muse-html-meta-content-encoding
2512 The charset to append to the HTML @verb{|<meta>|} tag.
2514 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2515 and determine the HTML charset from emacs's coding. If set to a string,
2516 this string will be used to force a particular charset.
2518 @item muse-html-charset-default
2519 The default HTML meta charset to use if no translation is found in
2520 @code{muse-xml-encoding-map}.
2522 @item muse-html-encoding-default
2523 The default Emacs buffer encoding to use in published files.
2524 This will be used if no special characters are found.
2528 @node Journal, LaTeX, HTML, Publishing Styles
2529 @comment node-name, next, previous, up
2530 @section Keeping a journal or blog
2532 @cindex blog, journal style
2534 The module facilitates the keeping and publication of a journal. When
2535 publishing to HTML, it assumes the form of a web log, or blog.
2537 The input format for each entry is as follows.
2540 * 20040317: Title of entry
2545 "You know who you are. It comes down to a simple gut check: You
2546 either love what you do or you don't. Period." -- P. Bronson
2550 The "qotd", or Quote of the Day, is entirely optional. When generated
2551 to HTML, this entry is rendered as the following.
2555 <div class="entry-qotd">
2556 <h3>Quote of the Day:</h3>
2557 <p>"You know who you are. It comes down to a simple gut
2558 check: You either love what you do or you don't. Period."
2561 <div class="entry-body">
2562 <div class="entry-head">
2563 <div class="entry-date">
2564 <span class="date">March 17, 2004</span>
2566 <div class="entry-title">
2567 <h2>Title of entry</h2>
2570 <div class="entry-text">
2571 <p>Text for the entry.</p>
2577 The plurality of "div" tags makes it possible to display the entries in
2578 any form you wish, using a CSS style.
2580 Also, an .RDF file can be generated from your journal by publishing it
2581 with the "rdf" style. It uses the first two sentences of the first
2582 paragraph of each entry as its "description", and auto-generates tags
2583 for linking to the various entries.
2585 @subheading muse-project-alist considerations
2587 If you wish to publish an RDF or RSS feed, it is important to include
2588 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2589 for your Journal projects. An example follows.
2592 (setq muse-project-alist
2593 '(("Journal" ("~/Journal/"
2595 (:base "journal-rss"
2596 :base-url "http://example.org/journal/"
2597 :path "~/public_html/journal"))))
2600 @subheading Styles provided
2604 @cindex publishing styles, journal-html
2606 Publish journal entries as an HTML document.
2608 @cindex publishing styles, journal-xhtml
2610 Publish journal entries as an XHTML document.
2612 @cindex publishing styles, journal-latex
2614 Publish journal entries as a LaTeX document.
2616 @cindex publishing styles, journal-pdf
2618 Publish journal entries as a PDF document.
2620 @cindex publishing styles, journal-book-latex
2621 @item journal-book-latex
2622 Publish journal entries as a LaTeX book.
2624 @cindex publishing styles, journal-book-pdf
2625 @item journal-book-pdf
2626 Publish journal entries as a PDF book.
2628 @cindex publishing styles, journal-rdf
2629 @cindex publishing styles, RSS 1.0
2631 Publish journal entries as an RDF file (RSS 1.0).
2633 @cindex publishing styles, journal-rss
2634 @cindex publishing styles, RSS 2.0
2636 Publish journal entries as an RSS file (RSS 2.0).
2638 @cindex publishing styles, journal-rss-entry
2639 @item journal-rss-entry
2640 Used internally by @code{journal-rss} and @code{journal-rdf} for
2641 publishing individual entries.
2645 @subheading Options provided
2649 @item muse-journal-heading-regexp
2650 A regexp that matches a journal heading.
2652 Paren group 1 is the ISO date, group 2 is the optional category, and
2653 group 3 is the optional heading for the entry.
2655 @item muse-journal-date-format
2656 Date format to use for journal entries.
2658 @item muse-journal-html-heading-regexp
2659 A regexp that matches a journal heading from an HTML document.
2661 Paren group 1 is the ISO date, group 2 is the optional category, and
2662 group 3 is the optional heading for the entry.
2664 @item muse-journal-html-entry-template
2665 Template used to publish individual journal entries as HTML.
2667 This may be text or a filename.
2669 @item muse-journal-latex-section
2670 Template used to publish a LaTeX section.
2672 @item muse-journal-latex-subsection
2673 Template used to publish a LaTeX subsection.
2675 @item muse-journal-markup-tags
2676 A list of tag specifications, for specially marking up Journal entries.
2678 @xref{muse-publish-markup-tags}, for more information.
2680 This is used by @code{journal-latex} and its related styles, as well as
2681 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2682 @code{journal-rss} use.
2684 @item muse-journal-rdf-extension
2685 Default file extension for publishing RDF (RSS 1.0) files.
2687 @item muse-journal-rdf-base-url
2688 The base URL of the website referenced by the RDF file.
2690 @item muse-journal-rdf-header
2691 Header used for publishing RDF (RSS 1.0) files.
2693 This may be text or a filename.
2695 @item muse-journal-rdf-footer
2696 Footer used for publishing RDF (RSS 1.0) files.
2698 This may be text or a filename.
2700 @item muse-journal-rdf-date-format
2701 Date format to use for RDF entries.
2703 @item muse-journal-rdf-entry-template
2704 Template used to publish individual journal entries as RDF.
2706 This may be text or a filename.
2708 @item muse-journal-rdf-summarize-entries
2709 If non-nil, include only summaries in the RDF file, not the full data.
2711 The default is nil, because this annoys some subscribers.
2713 @item muse-journal-rss-heading-regexp
2714 A regexp that matches a journal heading from an HTML document.
2716 Paren group 1 is the ISO date, group 2 is the optional category,
2717 and group 3 is the optional heading for the entry.
2719 @item muse-journal-rss-extension
2720 Default file extension for publishing RSS 2.0 files.
2722 @item muse-journal-rss-base-url
2723 The base URL of the website referenced by the RSS file.
2725 @item muse-journal-rss-header
2726 Header used for publishing RSS 2.0 files.
2728 This may be text or a filename.
2730 @item muse-journal-rss-footer
2731 Footer used for publishing RSS 2.0 files.
2733 This may be text or a filename.
2735 @item muse-journal-rss-date-format
2736 Date format to use for RSS 2.0 entries.
2738 @item muse-journal-rss-entry-template
2739 Template used to publish individual journal entries as RSS 2.0.
2741 This may be text or a filename.
2743 @item muse-journal-rss-enclosure-types-alist
2744 File types that are accepted as RSS enclosures.
2746 This is an alist that maps file extension to content type.
2748 Useful for podcasting.
2750 @item muse-journal-rss-summarize-entries
2751 If non-nil, include only summaries in the RSS file, not the full data.
2753 The default is nil, because this annoys some subscribers.
2755 @item muse-journal-rss-markup-regexps
2756 List of markup rules for publishing a Muse journal page to RSS.
2758 For more information on the structure of this list,
2759 @xref{muse-publish-markup-regexps}.
2761 @item muse-journal-rss-markup-functions
2762 An alist of style types to custom functions for that kind of text.
2764 For more on the structure of this list,
2765 @xref{muse-publish-markup-functions}.
2769 @node LaTeX, Poem, Journal, Publishing Styles
2770 @comment node-name, next, previous, up
2771 @section Publishing LaTeX documents
2773 This publishing style is capable of producing LaTeX or PDF documents.
2775 If you wish to publish PDF documents, you will need to have a good LaTeX
2776 installation. For Debian and Ubuntu, this can be accomplished by
2777 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2780 If your LaTeX installation has the file @file{grffile.sty}, which may be
2781 found in the @file{texlive-latex-recommended} package for Debian and
2782 Ubuntu, then consider using it by adding the following to your header
2783 file. This allows spaces in filenames to work.
2786 \usepackage@{grffile@}
2789 @subheading Styles provided
2793 @cindex publishing styles, latex
2795 Publish a LaTeX document.
2797 @cindex publishing styles, pdf
2799 Publish a PDF document, using an external LaTeX document conversion
2802 @cindex publishing styles, latexcjk
2804 Publish a LaTeX document with CJK (Chinese) encodings.
2806 @cindex publishing styles, pdfcjk
2808 Publish a PDF document with CJK (Chinese) encodings, using an external
2809 LaTeX document conversion tool.
2811 @cindex publishing styles, slides
2813 Publish a LaTeX document that uses the Beamer extension. This is
2814 suitable for producing slides.
2816 Here is an example of a slide.
2819 <slide title="First Slide">
2820 Everything between the slide tags composes this slide.
2822 [[Some-sort-of-cute-image.png]]
2825 - Another bullet point.
2829 @cindex publishing styles, slides-pdf
2831 Publish a PDF document of slides, using the Beamer extension.
2833 @cindex publishing styles, lecture-notes
2835 Publish a LaTeX document that uses the Beamer extension. This is
2836 suitable for producing lecture notes.
2838 This can also use the @verb{|<slide>|} tag.
2840 @cindex publishing styles, lecture-notes-pdf
2841 @item lecture-notes-pdf
2842 Publish a PDF document of lecture notes, using the Beamer extension.
2846 @subheading Options provided
2850 @item muse-latex-extension
2851 Default file extension for publishing LaTeX files.
2853 @item muse-latex-pdf-extension
2854 Default file extension for publishing LaTeX files to PDF.
2856 @item muse-latex-pdf-program
2857 The program that is called to generate PDF content from LaTeX content.
2859 @item muse-latex-pdf-cruft
2860 Extensions of files to remove after generating PDF output successfully.
2862 @item muse-latex-header
2863 Header used for publishing LaTeX files.
2865 This may be text or a filename.
2867 @item muse-latex-footer
2868 Footer used for publishing LaTeX files.
2870 This may be text or a filename.
2872 @item muse-latexcjk-header
2873 Header used for publishing LaTeX files (CJK).
2875 This may be text or a filename.
2877 @item muse-latexcjk-footer
2878 Footer used for publishing LaTeX files (CJK).
2880 This may be text or a filename.
2882 @item muse-latex-slides-header
2883 Header for publishing of slides using LaTeX.
2885 This may be text or a filename.
2887 You must have the Beamer extension for LaTeX installed for this to work.
2889 @item muse-latex-lecture-notes-header
2890 Header publishing of lecture notes using LaTeX.
2892 This may be text or a filename.
2894 You must have the Beamer extension for LaTeX installed for this to work.
2896 @item muse-latex-markup-regexps
2897 List of markup regexps for identifying regions in a Muse page.
2899 For more on the structure of this list,
2900 @xref{muse-publish-markup-regexps}.
2902 @item muse-latex-markup-functions
2903 An alist of style types to custom functions for that kind of text.
2905 For more on the structure of this list,
2906 @xref{muse-publish-markup-functions}.
2908 @item muse-latex-markup-strings
2909 Strings used for marking up text.
2911 These cover the most basic kinds of markup, the handling of which
2912 differs little between the various styles.
2914 @item muse-latex-slides-markup-tags
2915 A list of tag specifications, for specially marking up LaTeX slides.
2917 @item muse-latexcjk-encoding-map
2918 An alist mapping emacs coding systems to appropriate CJK codings.
2919 Use the base name of the coding system (ie, without the -unix).
2921 @item muse-latexcjk-encoding-default
2922 The default Emacs buffer encoding to use in published files.
2924 This will be used if no special characters are found.
2926 @item muse-latex-markup-specials-document
2927 A table of characters which must be represented specially.
2928 These are applied to the entire document, sans already-escaped
2931 @item muse-latex-markup-specials-example
2932 A table of characters which must be represented specially.
2933 These are applied to @verb{|example>|} regions.
2935 With the default interpretation of @verb{|<example>|} regions, no
2936 specials need to be escaped.
2938 @item muse-latex-markup-specials-literal
2939 A table of characters which must be represented specially.
2940 This applies to =monospaced text= and @verb{|<code>|} regions.
2942 @item muse-latex-markup-specials-url
2943 A table of characters which must be represented specially.
2944 These are applied to URLs.
2946 @item muse-latex-markup-specials-image
2947 A table of characters which must be represented specially.
2948 These are applied to image filenames.
2950 @item muse-latex-permit-contents-tag
2951 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2954 Most of the time, it is best to have a table of contents on the
2955 first page, with a new page immediately following. To make this
2956 work with documents published in both HTML and LaTeX, we need to
2957 ignore the @verb{|<contents>|} tag.
2959 If you don't agree with this, then set this option to non-nil,
2960 and it will do what you expect.
2964 @node Poem, Texinfo, LaTeX, Publishing Styles
2965 @comment node-name, next, previous, up
2966 @section Publish a poem to LaTeX or PDF
2968 The @code{muse-poem} module makes it easy to attractively publish and
2969 reference poems in the following format, using the "memoir" module for
2970 LaTeX publishing. It will also markup poems for every other output
2971 style, though none are nearly as pretty.
2980 Annotations, history, notes, etc.
2983 Once a poem is written in this format, just publish it to PDF using the
2984 @code{poem-pdf} style. To make an inlined reference to a poem that
2985 you've written -- for example, from a blog page -- there is a "poem" tag
2986 defined by this module.
2989 <poem title="name.of.poem.page">
2992 Let's assume the template above was called @file{name.of.poem.page};
2993 then the above tag would result in this inclusion.
3001 John Wiegley uses this module for publishing all of the poems on his
3002 website, which are at
3003 @uref{http://www.newartisans.com/johnw/poems.html}.
3005 @subheading Styles provided
3009 @cindex publishing styles, poem-latex
3011 Publish a poem in LaTeX form.
3013 @cindex publishing styles, poem-pdf
3015 Publish a poem to a PDF document.
3017 @cindex publishing styles, chapbook-latex
3018 @item chapbook-latex
3019 Publish a book of poems in LaTeX form.
3021 @cindex publishing styles, chapbook-pdf
3023 Publish a book of poems to a PDF document.
3027 @subheading Options provided
3031 @item muse-poem-latex-header
3032 Header used for publishing LaTeX poems.
3034 This may be text or a filename.
3036 @item muse-poem-latex-footer
3037 Footer used for publishing LaTeX files.
3039 This may be text or a filename.
3041 @item muse-poem-markup-strings
3042 Strings used for marking up poems.
3044 These cover the most basic kinds of markup, the handling of which
3045 differs little between the various styles.
3047 @item muse-chapbook-latex-header
3048 Header used for publishing a book of poems in LaTeX form.
3050 This may be text or a filename.
3052 @item muse-chapbook-latex-footer
3053 Footer used for publishing a book of poems in LaTeX form.
3055 This may be text or a filename.
3057 @item muse-poem-chapbook-strings
3058 Strings used for marking up books of poems.
3060 These cover the most basic kinds of markup, the handling of which
3061 differs little between the various styles.
3065 @node Texinfo, XML, Poem, Publishing Styles
3066 @comment node-name, next, previous, up
3067 @section Publish entries to Texinfo format or PDF
3069 Rules for publishing a Muse file as a Texinfo article.
3071 @subheading Styles provided
3075 @cindex publishing styles, texi
3077 Publish a file in Texinfo form.
3079 @cindex publishing styles, texi
3081 Generate an Info file from a Muse file.
3083 @cindex publishing styles, info-pdf
3085 Publish a file in PDF form.
3089 @subheading Options provided
3093 @item muse-texinfo-process-natively
3094 If non-nil, use the Emacs `texinfmt' module to make Info files.
3096 @item muse-texinfo-extension
3097 Default file extension for publishing Texinfo files.
3099 @item muse-texinfo-info-extension
3100 Default file extension for publishing Info files.
3102 @item muse-texinfo-pdf-extension
3103 Default file extension for publishing PDF files.
3105 @item muse-texinfo-header
3106 Text to prepend to a Muse page being published as Texinfo.
3108 This may be text or a filename.
3109 It may contain @verb{|<lisp>|} markup tags.
3111 @item muse-texinfo-footer
3112 Text to append to a Muse page being published as Texinfo.
3114 This may be text or a filename.
3115 It may contain @verb{|<lisp>|} markup tags.
3117 @item muse-texinfo-markup-regexps
3118 List of markup rules for publishing a Muse page to Texinfo.
3120 For more on the structure of this list,
3121 @xref{muse-publish-markup-regexps}.
3123 @item muse-texinfo-markup-functions
3124 An alist of style types to custom functions for that kind of text.
3126 For more on the structure of this list,
3127 @xref{muse-publish-markup-functions}.
3129 @item muse-texinfo-markup-strings
3130 Strings used for marking up text.
3132 These cover the most basic kinds of markup, the handling of which
3133 differs little between the various styles.
3135 @item muse-texinfo-markup-specials
3136 A table of characters which must be represented specially.
3138 @item muse-texinfo-markup-specials
3139 A table of characters which must be represented specially.
3140 These are applied to URLs.
3144 @node XML, , Texinfo, Publishing Styles
3145 @comment node-name, next, previous, up
3146 @section Publish entries to XML
3148 Muse is capable of publishing XML documents, with the help of the
3149 @file{muse-xml.el} module.
3151 A RelaxNG schema is available as part of the Muse distribution in the
3152 @file{etc/muse.rnc} file.
3154 @subheading Styles provided
3158 @cindex publishing styles, xml
3160 Publish a file in XML form.
3164 @subheading Options provided
3168 @cindex muse-xml-encoding-map
3169 @item muse-xml-encoding-map
3170 An alist mapping Emacs coding systems to appropriate XML charsets.
3171 Use the base name of the coding system (i.e. without the -unix).
3173 @item muse-xml-markup-specials
3174 A table of characters which must be represented specially in all
3175 XML-like markup formats.
3177 @item muse-xml-markup-specials-url-extra
3178 A table of characters which must be represented specially in all
3179 XML-like markup formats.
3181 These are extra characters that are escaped within URLs.
3183 @item muse-xml-extension
3184 Default file extension used for publishing XML files.
3186 @item muse-xml-header
3187 Header used for publishing XML files.
3189 This may be text or a filename.
3191 @item muse-xml-footer
3192 Footer used for publishing XML files.
3194 This may be text or a filename.
3196 @item muse-xml-markup-regexps
3197 List of markup rules for publishing a Muse page to XML.
3199 For more on the structure of this list,
3200 @xref{muse-publish-markup-regexps}.
3202 @item muse-xml-markup-functions
3203 An alist of style types to custom functions for that kind of text.
3205 For more on the structure of this list,
3206 @xref{muse-publish-markup-functions}.
3208 @item muse-xml-markup-strings
3209 Strings used for marking up text.
3211 These cover the most basic kinds of markup, the handling of which
3212 differs little between the various styles.
3214 @item muse-xml-encoding-default
3215 The default Emacs buffer encoding to use in published files.
3217 This will be used if no special characters are found.
3219 @item muse-xml-charset-default
3220 The default XML charset to use if no translation is found in
3221 @code{muse-xml-encoding-map}.
3226 @node Extending Muse, Miscellaneous, Publishing Styles, Top
3227 @comment node-name, next, previous, up
3228 @chapter Making your own publishing styles
3231 * Markup Functions:: Specifying functions to mark up text.
3232 * Markup Regexps:: Markup rules for publishing.
3233 * Markup Strings:: Strings specific to a publishing style.
3234 * Markup Tags:: Tag specifications for special markup.
3235 * Style Elements:: Parameters used for defining styles.
3236 * Deriving Styles:: Deriving a new style from an existing
3240 @node Markup Functions, Markup Regexps, , Extending Muse
3241 @comment node-name, next, previous, up
3242 @section Specifying functions to mark up text
3243 @cindex publishing, markup functions
3245 @anchor{muse-publish-markup-functions}
3246 @code{muse-publish-markup-functions}
3248 An alist of style types to custom functions for that kind of text.
3250 This is used by publishing styles to attempt to minimize the amount of
3251 custom regexps that each has to define. @file{muse-publish} provides
3252 rules for the most common types of markup.
3254 Each member of the list is of the following form.
3262 Describes the type of text to associate with this rule.
3263 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3266 Function to use to mark up this kind of rule if no suitable function is
3267 found through the @option{:functions} tag of the current style.
3270 @node Markup Regexps, Markup Strings, Markup Functions, Extending Muse
3271 @comment node-name, next, previous, up
3272 @section Markup rules for publishing
3273 @cindex publishing, markup regexps
3274 @cindex publishing, rules
3276 @anchor{muse-publish-markup-regexps}
3277 @code{muse-publish-markup-regexps}
3279 List of markup rules for publishing a page with Muse.
3281 The rules given in this variable are invoked first, followed by whatever
3282 rules are specified by the current style.
3284 Each member of the list is either a function, or a list of the following
3288 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3293 A regular expression, or symbol whose value is a regular expression,
3294 which is searched for using `re-search-forward'.
3296 @item TEXT-BEGIN-GROUP
3297 The matching group within that regexp which denotes the beginning of the
3298 actual text to be marked up.
3300 @item REPLACEMENT-TEXT
3301 A string that will be passed to `replace-match'.
3303 If it is not a string, but a function, it will be called to determine
3304 what the replacement text should be (it must return a string). If it is
3305 a symbol, the value of that symbol should be a string.
3308 The replacements are done in order, one rule at a time. Writing
3309 the regular expressions can be a tricky business. Note that case
3310 is never ignored. `case-fold-search' is always bound to nil
3311 while processing the markup rules.
3313 @subheading Publishing order
3315 This is the order that the publishing rules are consulted, by default.
3316 This may be changed by customizing @code{muse-publish-markup-regexps}.
3320 @item trailing and leading whitespace
3321 Remove trailing and leading whitespace from a file.
3326 This is only recognized at the beginning of a file.
3329 @samp{; a commented line}
3337 @item explicit links
3338 Prevent emphasis characters in explicit links from being marked up.
3340 Don't actually publish them here, just add a special no-emphasis text
3344 Whitespace-delimited word, possibly with emphasis characters
3346 This function is responsible for marking up emphasis and escaping some
3352 Outline-mode style headings.
3357 These are ellipses with a dot at end.
3367 Horizontal rule or section separator.
3369 @item no-break-space
3372 Prevent lines from being split before or after these characters.
3377 Break a line at point.
3382 Beginning of footnotes section.
3387 Footnote definition or reference. If at beginning of line, it is a
3402 Numbered list, item list, or term definition list.
3406 @file{table.el} style tables
3409 @samp{table | cells}
3411 Muse tables or orgtbl-mode style tables.
3414 spaces before beginning of text
3430 @samp{[[explicit][links]]}
3433 @samp{http://example.com/}
3436 @samp{bare-email@@example.com}
3440 @node Markup Strings, Markup Tags, Markup Regexps, Extending Muse
3441 @comment node-name, next, previous, up
3442 @section Strings specific to a publishing style
3443 @cindex publishing, markup strings
3445 @dfn{Markup strings} are strings used for marking up text for a
3448 These cover the most basic kinds of markup, the handling of which
3449 differs little between the various styles.
3451 @subheading Available markup strings
3455 @item image-with-desc
3456 An image and a description.
3458 Argument 1: image without extension. Argument 2: image extension.
3459 Argument 3: description.
3464 Argument 1: image without extension. Argument 2: image extension.
3467 An image with a link around it.
3469 Argument 1: link. Argument 2: image without extension.
3470 Argument 3: image extension.
3473 A reference to an anchor on the current page.
3475 Argument 1: anchor name. Argument 2: description if one exists, or the
3476 original link otherwise.
3479 A URL without a description.
3484 A link to a Muse page with a description.
3486 Argument 1: link. Argument 2: description if one exists, or the
3487 original link otherwise.
3489 @item link-and-anchor
3490 A link to a Muse page with an anchor, and a description.
3492 Argument 1: link. Argument 2: anchor name.
3493 Argument 3: description if one exists, or the original link otherwise.
3494 Argument 4: link without an extension.
3497 A link to an email address.
3499 Argument 1: email address. Argument 2: email address.
3504 Argument 1: name of anchor.
3509 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3512 Beginning of a comment.
3518 A horizontal line or space.
3520 @item no-break-space
3521 A space that separates two words which are not to be separated.
3524 Beginning of footnote.
3530 Mark a reference for the current footnote.
3532 Argument 1: number of this footnote.
3534 @item footnotemark-end
3535 End of a reference for the current footnote.
3538 Indicate the text of the current footnote.
3540 Argument 1: number of this footnote.
3542 @item footnotetext-end
3543 End of a footnote text line.
3546 Text used to replace ``Footnotes:'' line.
3555 Beginning of a part indicator line. This is used by book publishing.
3558 End of a part indicator line. This is used by book publishing.
3561 Beginning of a chapter indicator line. This is used by book publishing.
3564 End of a chapter indicator line. This is used by book publishing.
3567 Beginning of level 1 section indicator line.
3569 Argument 1: level of section; always 1.
3572 End of level 1 section indicator line.
3574 Argument 1: level of section; always 1.
3577 Beginning of level 2 section indicator line.
3579 Argument 1: level of section; always 2.
3581 @item subsection-end
3582 End of level 2 section indicator line.
3584 Argument 1: level of section; always 2.
3587 Beginning of level 3 section indicator line.
3589 Argument 1: level of section; always 3.
3591 @item subsubsection-end
3592 End of level 3 section indicator line.
3594 Argument 1: level of section; always 3.
3597 Beginning of section indicator line, where level is greater than 3.
3599 Argument 1: level of section.
3601 @item section-other-end
3602 End of section indicator line, where level is greater than 3.
3604 Argument 1: level of section.
3606 @item begin-underline
3607 Beginning of underlined text.
3610 End of underlined text.
3613 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3617 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3621 Beginning of the first level of emphasized text.
3624 End of the first level of emphasized text.
3626 @item begin-more-emph
3627 Beginning of the second level of emphasized text.
3630 End of the second level of emphasized text.
3632 @item begin-most-emph
3633 Beginning of the third (and final) level of emphasized text.
3636 End of the third (and final) level of emphasized text.
3639 Beginning of verse text.
3642 String used to each space that is further indented than the beginning of
3645 @item begin-verse-line
3646 Beginning of a line of verse.
3648 @item empty-verse-line
3649 End of a line of verse.
3651 @item begin-last-stanza-line
3652 Beginning of the last line of a verse stanza.
3654 @item end-last-stanza-line
3655 End of the last line of a verse stanza.
3661 Beginning of an example region. To make use of this, an
3662 @samp{<example>} tag is needed.
3665 End of an example region. To make use of this, an @samp{</example>} tag
3669 Begin a centered line.
3672 End a centered line.
3675 Begin a quoted region.
3678 End a quoted region.
3680 @item begin-quote-item
3681 Begin a quote paragraph.
3683 @item end-quote-item
3684 End a quote paragraph.
3687 Begin an unordered list.
3690 End an unordered list.
3692 @item begin-uli-item
3693 Begin an unordered list item.
3696 End an unordered list item.
3699 Begin an ordered list.
3702 End an ordered list.
3704 @item begin-oli-item
3705 Begin an ordered list item.
3708 End an ordered list item.
3711 Begin a definition list.
3714 End a definition list.
3717 Begin a definition list item.
3720 End a definition list item.
3723 Begin a definition list term.
3726 End a definition list term.
3729 Begin a definition list entry.
3732 End a definition list entry.
3740 @item begin-table-group
3741 Begin a table grouping.
3743 @item end-table-group
3744 End a table grouping.
3746 @item begin-table-row
3752 @item begin-table-entry
3753 Begin a table entry.
3755 @item end-table-entry
3760 @node Markup Tags, Style Elements, Markup Strings, Extending Muse
3761 @comment node-name, next, previous, up
3762 @section Tag specifications for special markup
3763 @cindex publishing, markup tags
3765 @anchor{muse-publish-markup-tags}
3766 @code{muse-publish-markup-tags}
3768 A list of tag specifications, for specially marking up text.
3770 XML-style tags are the best way to add custom markup to Muse. This is
3771 easily accomplished by customizing this list of markup tags.
3773 For each entry, the name of the tag is given, whether it expects a
3774 closing tag and/or an optional set of attributes, whether it is
3775 nestable, and a function that performs whatever action is desired within
3776 the delimited region.
3778 The tags themselves are deleted during publishing, before the function
3779 is called. The function is called with three arguments, the beginning
3780 and end of the region surrounded by the tags. If properties are
3781 allowed, they are passed as a third argument in the form of an alist.
3782 The `end' argument to the function is always a marker.
3784 Point is always at the beginning of the region within the tags, when the
3785 function is called. Wherever point is when the function finishes is
3786 where tag markup will resume.
3788 These tag rules are processed once at the beginning of markup, and once
3789 at the end, to catch any tags which may have been inserted in-between.
3791 @node Style Elements, Deriving Styles, Markup Tags, Extending Muse
3792 @comment node-name, next, previous, up
3793 @section Parameters used for defining styles
3794 @cindex publishing, style elements
3796 Style elements are tags that define a style. Use either
3797 @code{muse-define-style} or @code{muse-derive-style}
3798 (@pxref{Deriving Styles}) to create a new style.
3800 @defun muse-define-style name &rest elements
3803 @subheading Usable elements
3808 File extension to use for publishing files with this style.
3811 File extension to use for publishing links to Muse files with this
3815 File extension to use for publishing second-stage files with this style.
3817 For example, PDF publishing generates a LaTeX file first, then a PDF
3818 from that LaTeX file.
3821 List of markup rules for publishing a page with Muse.
3822 @xref{muse-publish-markup-regexps}.
3825 An alist of style types to custom functions for that kind of text.
3826 @xref{muse-publish-markup-functions}.
3829 Strings used for marking up text with this style.
3831 These cover the most basic kinds of markup, the handling of which
3832 differs little between the various styles.
3835 A list of tag specifications, used for handling extra tags.
3836 @xref{muse-publish-markup-tags}.
3839 A table of characters which must be represented specially.
3842 A function that is to be executed on the newly-created publishing buffer
3843 (or the current region) before any publishing occurs.
3845 This is used to set extra parameters that direct the publishing process.
3848 A function that is to be executed on the publishing buffer (or the
3849 current region) immediately after applying all of the markup regexps.
3851 This is used to fix the order of table elements (header, footer, body)
3855 A function that is to be executed on the publishing buffer after
3856 :before-end, and immediately after inserting the header and footer.
3858 This is used for generating the table of contents as well as setting the
3862 A function that is to be executed after saving the published file, but
3863 while still in its buffer.
3865 This is used for generating second-stage documents like PDF files from
3866 just-published LaTeX files.
3868 The function must accept three arguments: the name of the muse source
3869 file, the name of the just-published file, and the name of the
3870 second-stage target file. The name of the second-stage target file is
3871 the same as that of the just-published file if no second-stage
3872 publishing is required.
3875 Header used for publishing files of this style.
3877 This may be a variable, text, or a filename. It is inserted at the
3878 beginning of a file, after evaluating the publishing markup.
3881 Footer used for publishing files of this style.
3883 This may be a variable, text, or a filename. It is inserted at the end
3884 of a file, after evaluating the publishing markup.
3887 Style sheet used for publishing files of this style.
3889 This may be a variable or text. It is used in the header of HTML and
3890 XHTML based publishing styles.
3893 The function used to browse the published result of files of this style.
3897 @node Deriving Styles, , Style Elements, Extending Muse
3898 @comment node-name, next, previous, up
3899 @section Deriving a new style from an existing one
3900 @cindex publishing styles, deriving
3902 To create a new style from an existing one, use @code{muse-derive-style}
3903 as follows. This is a good way to fix something you don't like about a
3904 particular publishing style, or to personalize it.
3906 @defun muse-derive-style new-name base-name &rest elements
3909 The derived name is a string defining the new style, such as "my-html".
3910 The base name must identify an existing style, such as "html" -- if you
3911 have loaded @file{muse-html}. The style parameters are the same as
3912 those used to create a style, except that they override whatever
3913 definitions exist in the base style. However, some definitions only
3914 partially override. The following parameters support partial
3917 @xref{Style Elements}, for a complete list of all parameters.
3922 If a markup function is not found in the derived style's function list,
3923 the base style's function list will be queried.
3926 All regexps in the current style and the base style(s) will be used.
3929 If a markup string is not found in the derived style's string list, the
3930 base style's string list will be queried.
3934 @node Miscellaneous, Getting Help and Reporting Bugs, Extending Muse, Top
3935 @comment node-name, next, previous, up
3936 @chapter Miscellaneous add-ons, like a minor mode
3939 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
3942 @node Muse List Edit Minor Mode, , , Miscellaneous
3943 @comment node-name, next, previous, up
3944 @section Edit lists easily in other major modes
3945 @cindex muse-list-edit-minor-mode
3947 @code{muse-list-edit-minor-mode} is meant to be used with other major
3948 modes, such as Message (for composing email) and debian-changelog-mode
3949 (for editing debian/changelog files).
3951 It implements practically perfect support for editing and filling lists.
3952 It can even handle nested lists. In addition to Muse-specific list
3953 items ("-", numbers, definition lists, footnotes), it can also handle
3954 items that begin with "*" or "+". Filling list items behaves in the
3955 same way that it does in Muse, regardless of whether filladapt is also
3956 enabled, which is the primary reason to use this tool.
3958 @subheading Installation
3960 To use it, add ``(require 'muse-mode)'' to your Emacs customization file
3961 and add the function @code{turn-on-muse-list-edit-minor-mode} to any
3962 mode hooks where you wish to enable this minor mode.
3964 @subheading Keybindings
3966 @code{muse-list-edit-minor-mode} uses the following keybindings.
3970 @item M-RET (`muse-l-e-m-m-insert-list-item')
3971 Insert a new list item at point, using the indentation level of the
3974 @item C-< (`muse-l-e-m-m-decrease-list-item-indent')
3975 Decrease indentation of the current list item.
3977 @item C-> (`muse-l-e-m-m-increase-list-item-indent')
3978 Increase indentation of the current list item.
3982 @subheading Functions
3984 @defun muse-list-edit-minor-mode
3985 This is a global minor mode for editing files with lists.
3986 It is meant to be used with other major modes, and not with Muse mode.
3988 Interactively, with no prefix argument, toggle the mode.
3989 With universal prefix @var{arg} turn mode on.
3990 With zero or negative @var{arg} turn mode off.
3992 This minor mode provides the Muse keybindings for editing lists,
3993 and support for filling lists properly.
3995 It recognizes not only Muse-style lists, which use the "-"
3996 character or numbers, but also lists that use asterisks or plus
3997 signs. This should make the minor mode generally useful.
3999 Definition lists and footnotes are also recognized.
4001 Note that list items may omit leading spaces, for compatibility
4002 with modes that set @code{left-margin}, such as
4003 @code{debian-changelog-mode}.
4006 @defun turn-on-muse-list-edit-minor-mode
4007 Unconditionally turn on Muse list edit minor mode.
4010 @defun turn-off-muse-list-edit-minor-mode
4011 Unconditionally turn off Muse list edit minor mode.
4014 @node Getting Help and Reporting Bugs, History, Miscellaneous, Top
4015 @comment node-name, next, previous, up
4016 @chapter Getting Help and Reporting Bugs
4017 @cindex help, getting
4018 @cindex bugs, reporting
4020 After you have read this guide, if you still have questions about
4021 Muse, or if you have bugs to report, there are several places you can
4027 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
4028 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
4032 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
4033 that Michael Olson (the current maintainer) made for Muse.
4036 Muse has several different mailing lists.
4040 @item muse-el-announce
4041 Low-traffic list for Muse-related announcements.
4043 You can join this mailing list (@email{muse-el-announce@@gna.org})
4044 using the subscription form at
4045 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
4046 mailing list is also available via Gmane (@url{http://gmane.org/}). The
4047 group is called @samp{gmane.emacs.muse.announce}.
4049 @item muse-el-discuss
4050 Discussion, bugfixes, suggestions, tips, and the like for Muse.
4051 This mailing list also includes the content of muse-el-announce.
4053 You can join this mailing list (@email{muse-el-discuss@@gna.org})
4054 using the subscription form at
4055 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
4056 list is also available via Gmane with the identifier
4057 @samp{gmane.emacs.muse.general}.
4060 Log messages for commits made to Muse.
4062 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
4063 the subscription form at
4064 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
4065 is also available via Gmane with the identifier
4066 @samp{gmane.emacs.muse.scm}.
4068 @item muse-el-commits
4069 Generated bug reports for Emacs Muse. If you use our bug-tracker at
4070 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
4071 sent to this list automatically.
4073 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
4074 the subscription form at
4075 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
4076 is also available via Gmane with the identifier
4077 @samp{gmane.emacs.muse.cvs}.
4079 @item muse-el-internationalization
4080 Discussion of translation of the Muse website and documentation into
4083 You can join this mailing list
4084 (@email{muse-el-internationalization@@gna.org}) using the subscription
4085 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
4086 mailing list is also available via Gmane with the identifier
4087 @samp{gmane.emacs.muse.internationalization}.
4092 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
4093 contributors are frequently around and willing to answer your
4094 questions. The @samp{#muse} channel is also available for
4095 Muse-specific help, and its current maintainer hangs out there.
4098 The maintainer of Emacs Muse, Michael Olson, may be contacted at
4099 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
4100 it is often better to use the muse-el-discuss mailing list.
4104 @node History, Contributors, Getting Help and Reporting Bugs, Top
4105 @comment node-name, next, previous, up
4106 @chapter History of This Document
4107 @cindex history, of Muse
4111 John Wiegley started Muse upon realizing that EmacsWiki had some serious
4112 limitations. Around February 2004, he started making "emacs-wiki version
4113 3.00 APLHA", which eventually became known as Muse.
4115 Most of those who frequent the emacs-wiki mailing list continued to use
4116 emacs-wiki, mainly because Planner hasn't been ported over to it.
4118 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
4119 John Wiegley's request.
4122 Michael Olson overhauled this document and added many new sections in
4123 preparation for the first release of Muse (3.01).
4127 @node Contributors, GNU Free Documentation License, History, Top
4128 @comment node-name, next, previous, up
4129 @chapter Contributors to This Documentation
4130 @cindex contributors
4132 The first draft of this document was taken from the emacs-wiki texinfo
4133 manual. Michael Olson adapted it for Muse and added most of its
4136 John Sullivan did a majority of the work on the emacs-wiki texinfo
4139 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
4140 emacs-wiki texinfo manual.
4143 @node GNU Free Documentation License, Concept Index, Contributors, Top
4144 @appendix GNU Free Documentation License
4145 @include doclicense.texi
4148 @node Concept Index, , GNU Free Documentation License, Top
4149 @comment node-name, next, previous, up