1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.11.
17 Copyright @copyright{} 2004, 2005, 2006,
18 2007 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU
25 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
26 license is included in the section entitled ``GNU Free Documentation
27 License'' in this manual.
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software. Copies published by the Free
31 Software Foundation raise funds for GNU development.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License. If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
38 All Emacs Lisp code contained in this document may be used, distributed,
39 and modified without restriction.
45 @subtitle an authoring and publishing environment
46 @subtitle for GNU Emacs and XEmacs
48 @c The following two commands
49 @c start the copyright page.
51 @vskip 0pt plus 1filll
55 @c So the toc is printed at the start
59 @node Top, Preface, (dir), (dir)
60 @comment node-name, next, previous, up
67 * Preface:: About the documentation.
68 * Introduction:: What is Muse?
69 * Obtaining Muse:: How to get Muse releases and development
71 * Installation:: Compiling and installing Muse.
72 * Getting Started:: Setting up Muse and editing files.
73 * Projects:: Creating and managing Muse projects.
74 * Keystroke Summary:: Keys used in Muse mode.
75 * Markup Rules:: Rules for using markup.
76 * Publishing Styles:: Publishing various types of documents.
77 * Extending Muse:: Making your own publishing styles.
78 * 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 * Common Elements:: Common functionality shared by styles.
152 * Deriving Styles:: Deriving a new style from an existing
155 Common functionality shared by styles
157 * Markup Functions:: Specifying functions to mark up text.
158 * Markup Regexps:: Markup rules for publishing.
159 * Markup Strings:: Strings specific to a publishing style.
160 * Markup Tags:: Tag specifications for special markup.
161 * Style Elements:: Parameters used for defining styles.
163 Miscellaneous add-ons, like a minor mode
165 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
170 @node Preface, Introduction, Top, Top
171 @comment node-name, next, previous, up
172 @chapter About the documentation
174 This document describes Muse, which was written by John Wiegley and is
175 now maintained by Michael Olson. Several versions of this manual are
179 @item PDF: http://mwolson.org/static/doc/muse.pdf
180 @item HTML (single file): http://mwolson.org/static/doc/muse.html
181 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
184 @node Introduction, Obtaining Muse, Preface, Top
185 @comment node-name, next, previous, up
186 @chapter What is Muse?
188 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
189 and publishing environment for Emacs. It simplifies the process of
190 writing documents and publishing them to various output formats.
192 Muse consists of two main parts: an enhanced text-mode for authoring
193 documents and navigating within Muse projects, and a set of publishing
194 styles for generating different kinds of output.
196 What makes Muse distinct from other text-publishing systems is a modular
197 environment, with a rather simple core, in which "styles" are derived
198 from to create new styles. Much of Muse's overall functionality is
199 optional. For example, you can use the publisher without the
200 major-mode, or the mode without doing any publishing; or if you don't
201 load the Texinfo or LaTeX modules, those styles won't be available.
203 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
204 code has been restructured and rewritten, especially its publishing
205 functions. The focus in this revision is on the authoring and
206 publishing aspects, and the "wikiness" has been removed as a default
207 behavior (available in the optional @file{muse-wiki} module). CamelCase
208 words are no longer special by default.
210 One of the principal aims in the development of Muse is to make it very
211 easy to produce good-looking, standards-compliant documents.
213 @node Obtaining Muse, Installation, Introduction, Top
214 @comment node-name, next, previous, up
215 @chapter How to Get Muse Releases and Development Changes
218 * Releases:: Released versions of Muse.
219 * Development:: Latest unreleased development changes.
222 @node Releases, Development, Obtaining Muse, Obtaining Muse
223 @comment node-name, next, previous, up
224 @section Released versions of Muse
226 Choose to install a release if you want to minimize risk.
228 Errors are corrected in development first. User-visible changes will be
229 announced on the @email{muse-el-discuss@@gna.org} mailing list.
230 @xref{Getting Help and Reporting Bugs}.
232 @cindex releases, Debian package
233 @cindex Debian package for Muse
234 Debian users can get Muse via apt-get. The @file{muse-el} package is
235 available both at Michael Olson's APT repository and the official Debian
236 repository. To make use of the former, add the following line to your
237 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
240 deb http://mwolson.org/debian/ ./
243 @cindex releases, Ubuntu package
244 @cindex Ubuntu package for Muse
245 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
246 is available both at Michael Olson's APT repository and the official
247 Ubuntu repository. To make use of the former, add the following line to
248 your @file{/etc/apt/sources.list} file and run @code{apt-get install
252 deb http://mwolson.org/ubuntu/ ./
255 The reason for making separate Debian and Ubuntu packages is that this
256 manual is under the GFDL, and Debian will not allow it to be distributed
257 in its main repository. Ubuntu, on the other hand, permits this manual
258 to be included with the @file{muse-el} package.
260 @cindex releases, from source
261 Alternatively, you can download the latest release from
262 @uref{http://download.gna.org/muse-el/} .
264 @node Development, , Releases, Obtaining Muse
265 @comment node-name, next, previous, up
266 @section Latest unreleased development changes
269 Choose the development version if you want to live on the bleeding edge
270 of Muse development or try out new features before release.
272 @cindex git version control system, using
273 The git version control system allows you to keep up-to-date with the
274 latest changes to the development version of Muse. It also allows you
275 to contribute changes (via commits, if you are have developer access to
276 the repository, or via patches, otherwise). If you would like to
277 contribute to Muse development, it is highly recommended that you use
280 If you are new to git, you might find this tutorial helpful:
281 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
283 Downloading the Muse module with git and staying up-to-date involves
290 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
291 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
292 @item Other operating systems: download, compile, and install the source
293 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
294 package for your operating system.
297 @item Download the Muse development branch.
299 If you have developer access to Muse, do:
302 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
308 git clone git://repo.or.cz/muse-el.git muse
311 If you are behind a restrictive firewall, and do not have developer
312 access, then do the following instead:
315 git clone http://repo.or.cz/r/muse-el.git muse
318 @item List upstream changes that are missing from your local copy.
319 Do this whenever you want to see whether new changes have been committed
320 to Muse. If you wish, you may skip this step and proceed directly to
324 # Change to the source directory you are interested in.
327 # Fetch new changes from the repository, but don't apply them yet
330 # Display log messages for the new changes
334 ``origin'' is git's name for the location where you originally got Muse
335 from. You can change this location at any time by editing the
336 @file{.git/config} file in the directory where the Muse source was
339 @cindex updating Muse with git
340 @item Update to the latest version by pulling in any missing changes.
347 git will show how many files changed, and will provide a visual display
348 for how many lines were changed in each file.
352 There are other ways to interact with the Muse repository.
355 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
356 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
357 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
360 The latest development snapshot can lag behind the git repo by as much
361 as 20 minutes, but never more than that.
363 @subheading Becoming a Muse developer
364 @cindex developer, becoming
366 If you want commit access to the shared Muse repository, then register
367 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
368 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
369 best to send some patches to the @email{muse-el-discuss@@gna.org}
370 mailing list first, so that he knows that you know what you are doing.
371 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
374 You must also be willing to sign a copyright assignment for your changes
375 to Muse, since Muse is a GNU project. The current maintainer will
376 assist you in this process if you contact him.
378 For information on committing changes to Muse and performing
379 development, please consult
380 @uref{http://emacswiki.org/cgi-bin/wiki/MuseDevelopment}.
382 @node Installation, Getting Started, Obtaining Muse, Top
383 @comment node-name, next, previous, up
384 @chapter Compiling and Installing Muse
386 Muse may be compiled and installed on your machine.
388 @subheading Compilation
389 @cindex compiling Muse
391 This is an optional step, since Emacs Lisp source code does not
392 necessarily have to be byte-compiled. Byte-compilation may yield a very
393 slight speed increase.
395 A working copy of Emacs or XEmacs is needed in order to compile Emacs
396 Muse. By default, the program that is installed with the name
397 @command{emacs} will be used.
399 If you want to use the @command{xemacs} binary to perform the
400 compilation, you must copy @file{Makefile.defs.default} to
401 @file{Makefile.defs} in the top-level directory, and then edit
402 @file{Makefile.defs} as follows. You can put either a full path to an
403 Emacs or XEmacs binary or just the command name, as long as it is in the
404 @env{PATH}. Depending on your setup, changes to the @option{PREFIX},
405 @option{ELISPDIR}, and/or @option{INFODIR} variables may also need to be
410 SITEFLAG = -no-site-file
411 # Edit the section as necessary
412 install_info = install-info --section "XEmacs 21.4" $(1).info \
416 Running @code{make} in the top-level directory should compile the Muse
417 source files in the @file{lisp} directory, and generate an autoloads
418 file in @file{lisp/muse-autoloads.el}.
420 @subheading Installation
421 @cindex installing Muse
423 Muse may be installed into your file hierarchy by doing the following.
425 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
426 top-level directory, if you haven't done so already. Then edit the
427 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
428 want the source and compiled Muse files to be installed and
429 @env{INFODIR} indicates where to put the Muse manual. As mentioned
430 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
431 in the Compilation section if you are using XEmacs.
433 If you are installing Muse on a Debian or Ubuntu system, you might want
434 to change the value of @env{INSTALLINFO} as specified in
435 @file{Makefile.defs}.
437 If you wish to install Muse to different locations than the defaults
438 specify, edit @file{Makefile.defs} accordingly.
440 Run @code{make} as a normal user, if you haven't done so already.
442 Run @code{make install} as the root user if you have chosen installation
443 locations that require root permissions.
446 @cindex ELPA package for Muse
448 For those used to installing software packages, there will be a
449 @code{muse} package available in the Emacs Lisp Package Archive
450 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
451 will be compiled and installed automatically in a user-specific
452 location. For more information on ELPA, see
453 @uref{http://tromey.com/elpa/}.
455 @node Getting Started, Projects, Installation, Top
456 @comment node-name, next, previous, up
457 @chapter Getting Started
461 * Loading Muse:: How to load Muse.
462 * Using Muse Mode:: How to edit files in Muse.
463 * Publishing Files Overview:: Publishing a single file or project.
464 * File Extensions:: Using a different file extension.
467 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
468 @comment node-name, next, previous, up
469 @section How to Load Muse
470 @cindex settings, init file
472 To use Muse, add the directory containing its files to your
473 @code{load-path} variable, in your @file{.emacs} file. Then, load in
474 the authoring mode, and the styles you wish to publish to. An example
478 (add-to-list 'load-path "<path to Muse>")
480 (require 'muse-mode) ; load authoring mode
482 (require 'muse-html) ; load publishing styles I use
483 (require 'muse-latex)
484 (require 'muse-texinfo)
485 (require 'muse-docbook)
487 (require 'muse-project) ; publish files in projects
490 An easy way of seeing which settings are available and changing settings
491 is to use the Muse customization interface. To do this, type
492 @kbd{M-x customize-group muse RET}. Each of the options has its own
493 documentation. Options are grouped logically according to what effect
496 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
497 @comment node-name, next, previous, up
498 @section How to Edit Files in Muse
499 @cindex editing Muse files
501 Muse Mode should automatically be activated when you visit a file with a
502 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
503 available in the @file{examples} directory of the Muse distribution.
504 You can tell that Muse Mose has been activated by checking for the text
505 ``Muse'' in your mode line. If Muse Mode has not been activated, you
506 may activate it by type @kbd{M-x muse-mode RET}.
508 You will notice that Muse files are highlighted very simply. Links are
509 colored blue, headings are large and bold text, and @verb{|<example>|}
510 tags are colored in grey.
512 There are several different ways to edit things like links, which hide
513 the underlying Muse markup. One way is to toggle font-locking off by
514 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
515 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
516 on. Another way is just to move into the text and edit it. Markup can
517 also be removed by normal deletion methods, though some side effects
518 might require a second deletion.
520 For the particular case of editing links, it is easiest to move to the
521 link and do @kbd{C-c C-e}, which is also @kbd{M-x
522 muse-edit-link-at-point}. This prompts you for the link and its
523 description, using the previous contents of the link as initial values.
524 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
525 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
526 followed by hitting @kbd{RET} on them.
528 If you want to add a new list item, this may by accomplished by hitting
529 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
530 dash is the Muse markup that indicates a list item. It is also possible
531 to created ``nested'' lists with this command, by adjusting the number
532 of spaces in front of the dashes. If you have lists with long lines,
533 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
536 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
537 @comment node-name, next, previous, up
538 @section Publishing a Single File or Project
539 @cindex editing Muse files
541 The command @kbd{M-x muse-project-publish-this-file} will publish the
542 current document to any available publishing style (a publishing style
543 is an output format, like HTML or Docbook), placing the output in the
544 current directory. If you are in Muse Mode, this command will be bound
545 to @kbd{C-c C-t}. If the file has been published recently, and its
546 contents have not changed, running @kbd{C-c C-t} again will not publish
547 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
549 If you have set up projects and are visiting a file that is part of a
550 project, then @kbd{C-c C-t} will restrict the output formats to those
551 which are used by the project, and will automatically publish to the
552 output directory defined by the project. If you want to publish to a
553 different directory or use a different format, then use @kbd{C-c M-C-t},
554 which is also @kbd{M-x muse-publish-this-file}.
556 If the currently opened file is part of a defined project in
557 @code{muse-project-alist}, it (and the rest of the changed files in a
558 project) may be published using @kbd{C-c C-p}.
560 @node File Extensions, , Publishing Files Overview, Getting Started
561 @comment node-name, next, previous, up
562 @section Using a Different File Extension
563 @cindex file extension, specifying
565 By default, Muse expects all project files to have the file extension
566 @file{.muse}. Files without this extension will not be associated with
567 Muse mode and will not be considered part of any project, even if they
568 are within a project directory.
570 If you don't want to use @file{.muse}, you can customize the extension
571 by setting the value of @code{muse-file-extension}.
573 If you don't want to use any extension at all, and want Muse to
574 autodetect project files based on their location, then add the following
575 to your Muse settings file.
578 (setq muse-file-extension nil
582 Note that if you chose to have @code{muse-file-extension} set to
583 @code{nil}, you may have trouble if your @file{.emacs} file or other
584 init scripts attempt to visit a Muse file. (A very common example of
585 this is if you use Planner with Muse and run @code{(plan)} from your
586 @file{.emacs}.) If you wish to visit Muse files from your
587 @file{.emacs}, be sure to also add the following additional code before
588 any such visits happen:
591 (add-hook 'find-file-hooks 'muse-mode-maybe)
595 @node Projects, Keystroke Summary, Getting Started, Top
596 @comment node-name, next, previous, up
597 @chapter Creating and Managing Muse Projects
600 Often you will want to publish all the files within a directory to a
601 particular set of output styles automatically. To support, Muse
602 allows for the creation of "projects".
605 * Single Project:: A single-project example.
606 * Multiple Projects:: A multiple-project example.
607 * Projects and Subdirectories:: Publishing subdirectories in projects.
608 * Options for Projects:: Listing of available options for projects.
611 @node Single Project, Multiple Projects, Projects, Projects
612 @comment node-name, next, previous, up
613 @section A Single-Project Example
614 @cindex projects, single
616 Here is a sample project, which may be defined in your @file{.emacs}
620 (setq muse-project-alist
621 '(("Website" ("~/Pages" :default "index")
622 (:base "html" :path "~/public_html")
623 (:base "pdf" :path "~/public_html/pdf"))))
626 The above defines a project named "website", whose files are located
627 in the directory @file{~/Pages}. The default page to visit is
628 @file{index}. When this project is published, each page will be
629 output as HTML to the directory @file{~/public_html}, and as PDF to
630 the directory @file{~/public_html/pdf}. Within any project page, you
631 may create a link to other pages using the syntax @samp{[[pagename]]}.
633 If you would like to include only some files from a directory in a Muse
634 project, you may use a regexp in place of @file{~/Pages} in the example.
636 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
637 @comment node-name, next, previous, up
638 @section A Multiple-Project Example
639 @cindex projects, multiple
641 It is possible to specify multiple projects. Here is an example of
642 three projects: a generic website, a projects area, and a day-planner
643 (the day-planner part requires Planner Mode---see
644 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
647 (setq muse-project-alist
648 '(("Website" ("~/Pages" :default "index")
649 (:base "html" :path "~/public_html"))
650 (("Projects" ("~/Projects" :default "index")
652 :path "~/public_html/projects"
653 :exclude "/TopSecret")
655 :path "~/public_html/projects/pdf"
656 :exclude "/TopSecret")))
659 :major-mode planner-mode
660 :visit-link planner-visit-link)
661 (:base "planner-xhtml"
662 :path "~/public_html/plans"))))
665 The @option{:major-mode} attribute specifies which major to use when
666 visiting files in this directory.
668 The @option{:visit-link} attribute specifies the function to call when
671 The @option{:exclude} attribute has a regexp that matches files to never
674 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
675 @comment node-name, next, previous, up
676 @section Publishing Subdirectories in Projects
677 @cindex projects, subdirectories
679 If you want to publish a directory and all of its subdirectories, Muse
680 provides two convenience functions that together generate the proper
681 rules for you. Note that we use the backtick to begin this
682 muse-project-alist definition, rather than a single quote.
685 (setq muse-project-alist
686 `(("Website" ("~/Pages" :default "index")
687 (:base "html" :path "~/public_html"))
688 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
690 ;; Publish this directory and its subdirectories. Arguments
691 ;; are as follows. The above `muse-project-alist-dirs' part
693 ;; 1. Source directory
694 ;; 2. Output directory
695 ;; 3. Publishing style
696 ;; remainder: Other things to put in every generated style
697 ,@@(muse-project-alist-styles "~/Blog"
702 The @code{muse-project-alist-dirs} function takes a directory and
703 returns it and all of its subdirectories in a list.
705 The @code{muse-project-alist-styles} function is explained by the
708 The ``blosxom'' text is the name of another publishing style, much like
709 ``html''. @xref{Blosxom}, for further information about it. You can
710 use any publishing style you like for the third argument to
711 @code{muse-project-alist-styles}.
713 @node Options for Projects, , Projects and Subdirectories, Projects
714 @comment node-name, next, previous, up
715 @section Listing of Available Options for Projects
716 @cindex projects, options
717 @cindex muse-project-alist, reference
719 This is a listing of all of the various options (or, more accurately:
720 attributes) that may be specified in @code{muse-project-alist}.
722 Each muse-project-alist entry looks like this:
725 (PROJECT-NAME (SOURCES)
729 We refer to these names below.
731 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
732 The first value is a keyword, like @option{:default}. The second part
733 is the value associated with that keyword, such as the text ``index''.
734 If you are familiar with Emacs Lisp property lists, the concept is
735 similar to that, except that in the SOURCES section, single directories
736 can be interspersed with two-value attributes.
738 @subheading Project Name
740 This is a string that indicates the name of the project. It is
741 primarily used for publishing interwiki links with the
742 @file{muse-wiki.el} module.
746 This part of a muse-project-alist entry consists of two-value
747 attributes, and also directory names. If you are publishing a book, the
748 order of directories and attributes is significant.
750 The minimal content for the sources section is a list of directories.
755 Indicates a new chapter of a book. The text of the title of the chapter
756 comes immediately after this keyword.
759 Indicates the end of a book. Directories listed after this one are
760 ignored when publishing a book. The value ``t'' (without quotes) should
761 come immediately after this keyword.
764 A function to call while publishing a book. This is useful for doing
765 something just after a particular chapter.
768 Indicates the beginning of a new part of the book. The text of the
769 title should come immediately after this keyword.
772 Indicate a particular publishing style to use for this part of the book.
773 If this is specified, it should come just after a @option{:part}
777 The default page to visit when browsing a project. Also, if you are
778 using the @file{muse-wiki.el} module, publishing a link to just a
779 project's name will cause it to link to this default file.
782 This specifies a list of pages which should be published every time a
783 project is published (by using @kbd{C-c C-p}, for example), regardless
784 of whether their contents have changed. This is useful for updating
785 Index pages, pages that use the @verb{|<include>|} tag, and other pages
786 that have dynamically-generated content.
789 This specifies the major mode to use when visiting files in this
790 project. The default is @code{muse-mode}.
793 This indicates that while publishing a book, do not automatically create
794 chapters. Values which may follow this are nil (the default, which
795 means that we automatically create chapters), or non-nil, which means
796 that we manually specify chapters with the @option{:book-chapter}
799 @item :publish-project
800 Indicates which function we should call when publishing a project.
803 This specifies a list of variables and values to set when publishing a
804 project. The list should be a property list, which is in the form:
807 (VAR1 VALUE1 VAR2 VALUE2 ...)
811 Specifies the function to call when visiting a link. The default is
812 @code{muse-visit-link-default}. The arguments for that function should
813 be (1) the link and (2) whether to visit the link in a new window.
819 This part of a muse-project-alist entry is composed of lists of
820 attributes. Each list is called an ``output style''.
822 The minimal content for an output style is a @option{:base} attribute
823 and a @option{:path} attribute.
828 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
831 An external URL which can be used to access published files. This is
832 mainly used by the @file{muse-wiki} module when publishing links between
833 two separate projects, if the projects are served on different domains.
835 It is also used by the @file{muse-journal} module to create the RSS or
839 Exclude items matching a regexp from being published. The regexp should
840 usually begin with "/".
843 Only include items matching a regexp when publishing. The regexp should
844 usually begin with "/".
847 The directory in which to store published files.
850 A file containing the timestamps (that is, time of creation) for files
851 in this project. It might eventually used by the @file{muse-blosxom}
852 module, but this option is not currently in use by any Muse code.
857 @node Keystroke Summary, Markup Rules, Projects, Top
858 @comment node-name, next, previous, up
859 @chapter Keys Used in Muse Mode
862 This is a summary of keystrokes available in every Muse buffer.
866 @item C-c C-a (`muse-index')
867 Display an index of all known Muse pages.
869 @item C-c C-b (`muse-find-backlinks')
870 Find all pages that link to this page.
872 @item C-c C-e (`muse-edit-link-at-point')
875 @item C-c C-f (`muse-project-find-file')
876 Open another Muse page. Prompt for the name.
878 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
879 Insert a link to a file interactively.
881 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
882 Insert a tag interactively.
884 @item C-c C-i u, C-c TAB u (`muse-insert-url')
885 Insert a URL interactively.
887 @item C-c C-l (`font-lock-mode')
888 Toggle font lock / highlighting for the current buffer.
890 @item C-c C-p (`muse-project-publish')
891 Publish any Muse pages that have changed.
893 @item C-c C-s (`muse-search')
894 Find text in all files of the current project.
896 @item C-c C-t (`muse-project-publish-this-file')
897 Publish the currently-visited file. Prompt for the style if the current
898 file can be published using more than one style.
900 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
901 Publish the currently-visited file. Prompt for both the style and
904 @item C-c C-v (`muse-browse-result')
905 Show the published result of this page.
907 @item C-c = (`muse-what-changed')
908 Diff this page against the last backup version.
911 Move to the next Wiki reference.
914 Move to the previous Wiki reference.
917 Complete the name of a page from the current project at point.
920 Insert a new list item at point, indenting properly.
923 Decrease the indentation of the list item at point.
926 Increase the indentation of the list item at point.
928 @item M-x muse-colors-toggle-inline-images RET
929 Toggle display of inlined images on/off.
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 as
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.
1023 @node Headings, Directives, Paragraphs, Markup Rules
1024 @comment node-name, next, previous, up
1025 @section Levels of headings
1028 A heading becomes a chapter or section in printed output -- depending on
1029 the style. To indicate a heading, start a new paragraph with one or
1030 more asterices, followed by a space and the heading title. Then begin
1031 another paragraph to enter the text for that section.
1033 All levels of headings will be published. Most publishing styles only
1034 distinguish the between the first 4 levels, however.
1046 @node Directives, Emphasizing Text, Headings, Markup Rules
1047 @comment node-name, next, previous, up
1048 @section Directives at the beginning of a document
1051 Directives are lines beginning with the @samp{#} character that come
1052 before any paragraphs or sections in the document. Directives are of
1053 the form ``#directive content of directive''. You can use any
1054 combination of uppercase and lowercase letters for directives, even if
1055 the directive is not in the list below.
1057 The @code{muse-publishing-directive} function may be used in header and
1058 footer text to access directives. For example, to access the
1059 @code{#title} directive, use @code{(muse-publishing-directive "title")}.
1061 The following is a list of directives that Muse uses.
1066 The author of this document.
1068 If this is not specified, Muse will attempt to figure it out from the
1069 @code{user-full-name} variable.
1073 The date that the document was last modified.
1075 This is used by publishing styles that are able to embed the date
1080 A short description of this document.
1082 This is used by the @code{journal} publishing style to embed information
1083 inside of an RSS/RDF feed.
1087 The title of this document.
1089 If this is not specified, the name of the file is used.
1093 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1094 @comment node-name, next, previous, up
1095 @section Bold, italicized, and underlined text
1096 @cindex emphasizing text
1097 @cindex underlining text
1098 @cindex italicizing text
1099 @cindex verbatim text
1100 @cindex monospace, rendering words
1102 To emphasize text, surround it with certain specially recognized
1108 ***very strong emphasis***
1110 =verbatim and monospace=
1114 While editing a Muse document in Muse mode, these forms of emphasis will
1115 be highlighted in a WYSIWYG manner. Each of these forms may span
1118 Verbatim text will be colored as gray by default. To change this,
1119 customize @code{muse-verbatim-face}.
1121 You can also use the @verb{|<code>|} tag to indicate verbatim and
1122 monospace text. This is handy for regions that have an ``='' in them.
1124 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1125 @comment node-name, next, previous, up
1126 @section Making notes to be shown at the end
1129 A footnote reference is simply a number in square brackets. To define
1130 the footnote, place this definition at the bottom of your file.
1131 @samp{footnote-mode} can be used to greatly facilitate the creation of
1132 these kinds of footnotes.
1134 Footnotes are defined by the same number in brackets occurring at the
1135 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1136 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1137 the point of insertion.
1139 @node Verse, Lists, Footnotes, Markup Rules
1140 @comment node-name, next, previous, up
1141 @section Indicating poetic stanzas
1145 Poetry requires that whitespace be preserved, but without resorting to
1146 monospace. To indicate this, use the following markup, reminiscent of
1150 > A line of Emacs verse;
1151 > forgive its being so terse.
1154 You can also use the @verb{|<verse>|} tag, if you prefer.
1158 A line of Emacs verse;
1159 forgive its being so terse.
1163 @cindex verses, multiple stanzas
1164 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1169 A line of Emacs verse;
1170 forgive its being so terse.
1172 In terms of terse verse,
1177 @node Lists, Tables, Verse, Markup Rules
1178 @comment node-name, next, previous, up
1179 @section Lists of items
1182 Lists are given using special characters at the beginning of a line.
1183 Whitespace must occur before bullets or numbered items, to distinguish
1184 from the possibility of those characters occurring in a real sentence.
1186 @cindex lists, bullets
1187 These are rendered as a bullet list.
1196 @cindex lists, enumerated
1197 An enumerated list follows.
1206 @cindex lists, definitions
1207 Here is a definition list.
1211 This is a first definition
1212 And it has two lines;
1213 no, make that three.
1215 Term2 :: This is a second definition
1218 @subheading Nested lists
1220 @cindex lists, nested
1221 It is possible to nest lists of the same or different kinds. The
1222 ``level'' of the list is determined by the amount of initial whitespace.
1227 - Level 1, bullet item one
1228 1. Level 2, enum item one
1229 2. Level 2, enum item two
1230 - Level 1, bullet item two
1231 1. Level 2, enum item three
1232 2. Level 2, enum item four
1236 @subheading Breaking list items
1238 @cindex lists, breaking lines
1239 If you want to break up a line within any list type, just put one blank
1240 line between the end of the previous line and the beginning of the next
1241 line, using the same amount of initial indentation.
1244 - bullet item 1, line 1
1246 bullet item 1, line 2
1252 - bullet item 2, line 1
1254 bullet item 2, line 2
1257 @node Tables, Explicit Links, Lists, Markup Rules
1258 @comment node-name, next, previous, up
1259 @section Generation of data tables
1262 @cindex tables, simple
1263 Only very simple tables are supported. The syntax is as follows.
1266 Double bars || Separate header fields
1268 Single bars | Separate body fields
1269 Here are more | body fields
1271 Triple bars ||| Separate footer fields
1274 Some publishing styles require header fields to come first, then footer
1275 fields, and then the body fields. You can use any order for these
1276 sections that you like, and Muse will re-order them for you at
1279 If you wish to disable table generation for one Muse file, add the
1280 directive @samp{#disable-tables t} to the top of the file.
1282 @subheading Other table formats
1284 @cindex tables, orgtbl-mode style
1285 It is possible to publish very basic Orgtbl-mode style tables.
1288 | org | style | table |
1289 |------+-------+-------|
1293 |------+-------+-------|
1297 If you are used to the way that Org Mode publishes these tables, then
1298 customize `muse-html-table-attributes' to the following, in order to get
1299 a similar kind of output.
1302 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1305 @cindex tables, table.el style
1306 @file{table.el} style tables are also supported, as long as
1307 @file{table.el} itself supports outputting tables for a particular
1308 publishing style. At the time of this writing, the ``html'', ``latex'',
1309 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1310 from these styles will also work.
1322 @node Explicit Links, Implicit Links, Tables, Markup Rules
1323 @comment node-name, next, previous, up
1324 @section Hyperlinks and email addresses with descriptions
1325 @cindex links, explicit
1327 A hyperlink can reference a URL, or another page within a Muse
1328 project. In addition, descriptive text can be specified, which should
1329 be displayed rather than the link text in output styles that supports
1330 link descriptions. The syntax is as follows.
1333 [[link target][link description]]
1334 [[link target without description]]
1337 Thus, the current maintainer's homepage for Muse can be found
1338 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1339 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1341 @node Implicit Links, Images, Explicit Links, Markup Rules
1342 @comment node-name, next, previous, up
1343 @section Bare URLs, WikiNames, and InterWiki links
1344 @cindex links, implicit
1348 @cindex Email addresses
1350 A URL or email address encountered in the input text is published as a
1351 hyperlink. These kind of links are called @dfn{implicit links} because
1352 they are not separated from the rest of the Muse document in any way.
1354 Some characters in URLs will prevent Muse from recognizing them as
1355 implicit links. If you want to link to a URL containing spaces or any of
1356 the characters ``][,"'`()<>^'', you will have to make the link
1357 explicit. The punctuation characters ``.,;:'' are also not recognized as
1358 part of a URL when they appear at its end. For information on how to
1359 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1360 addresses with descriptions}.
1363 If the @command{muse-wiki} module is loaded, another form of implicit
1364 link will be made available. WikiNames, which are typed in CamelCase,
1365 are highlighted and published as links, provided that the file they
1368 Customization of WikiName recognition may be accomplished by editing the
1369 @code{muse-wiki-wikiword-regexp} option and subsequently running
1370 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1371 If you use the Customize interface, the latter will be done
1374 @cindex InterWiki links
1375 @cindex inter-project links
1376 The @command{muse-wiki} module also allows for InterWiki links. These
1377 are similar to WikiWords, but they specify both the project and page of
1378 a file. The names of your project entries in @code{muse-project-alist}
1379 will be used as InterWiki names by default. Several examples follow.
1382 Blog::DocumentingMuse
1387 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1388 the project name, and @samp{DocumentingMuse} is the page name. In the
1389 second example, @samp{#} is the interwiki delimiter. If the name of a
1390 project occurs by itself in text, like the third case, it will be
1391 colorized and published as a link to the default page of the given
1394 Customization of interwiki links may be accomplished by editing the
1395 @code{muse-wiki-interwiki-alist} option.
1397 It is also possible to link to an anchor in an interwiki document. This
1398 is called a ``three-part link''. Examples of this follow.
1401 Blog::DocumentingMuse#anchor1
1402 Projects#EmacsMuse#anchor2
1405 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1406 @comment node-name, next, previous, up
1407 @section Publishing and displaying images
1409 @cindex links, with images
1410 @subheading Image links
1412 Links to images may be used in either the target or the description, or
1413 both. Thus, the following code will publish as a clickable image that
1414 points to @url{http://mwolson.org/}.
1417 [[http://mwolson.org/][/static/logos/site-logo.png]]
1420 Normally, images in the link part will be inlined.
1422 If you want these images to be published as links instead, place the
1423 text ``URL:'' immediately in front of the link text. An example
1427 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1430 @cindex images, displaying
1431 @cindex images, local
1432 @subheading Displaying images in Muse mode
1433 If a link to a locally-available image is encountered in the link
1434 description, Muse mode will attempt to display it if your version of
1437 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1438 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1440 The method for finding images may be altered by customizing the
1441 @code{muse-colors-inline-image-method} option. One useful value for
1442 this option is @code{muse-colors-use-publishing-directory}, which tells
1443 Muse mode to look in the directory where the current file will be
1444 published. The default is to look in the current directory. Relative
1445 paths like @samp{../pics/} should work for either setting.
1447 Eventually, it is hoped that Muse will be able to copy images from the a
1448 ``source'' directory to a publishing directory by customizing
1449 @code{muse-project-alist}, but this has not been implemented yet.
1451 @cindex images, without descriptions
1452 @cindex images, inlined
1453 @subheading Publishing simple images
1454 The following example will display correctly and publish correctly if a
1455 @acronym{PNG} file called @file{TestLogo.png} exists in the
1456 @file{../pics/} directory. If text is on the same line as the picture,
1457 it will remain so in the output.
1463 @cindex images, captions
1464 @subheading Publishing images with captions
1465 If you want to add a caption to an image, use the following syntax.
1466 This will center the image (if the output format supports it) and add a
1467 centered caption below the picture. Formats that do not support
1468 centering the image will instead leave it against the left margin.
1471 [[../pics/mycat.png][My cat Dexter]]
1474 Images with captions may only occur in their own paragraphs, with no
1475 text on the same line. Otherwise, the published output will not be
1476 syntactically correct.
1478 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1479 @comment node-name, next, previous, up
1480 @section Inserting a horizontal line or anchor
1482 @cindex horizontal rules
1484 @subheading Horizontal Rules
1486 Four or more dashes indicate a horizontal rule. Be sure to put blank
1487 lines around it, or it will be considered part of the proceeding or
1488 following paragraph!
1491 @cindex links, with target on same page
1494 If you begin a line with "#anchor" -- where "anchor" can be any word
1495 that doesn't contain whitespace -- it defines an anchor at that point
1496 into the document. This point can be referenced using "page#anchor" as
1497 the target in a Muse link.
1499 @node Embedded Lisp, Citations, Horizontal Rules and Anchors, Markup Rules
1500 @comment node-name, next, previous, up
1501 @section Evaluating Emacs Lisp code in documents for extensibility
1502 @cindex lisp, embedded
1504 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1505 which is the only Muse tag supported in a style's header and footer
1506 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1507 text you wish. The inserted output will get marked up, if the
1508 @verb{|<lisp>|} tag appears within the main text of the document.
1511 <lisp>(concat "This form gets " "inserted")</lisp>
1514 @cindex lisp, and insert command
1515 Note that you should not use the @code{insert} command within a set of
1516 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1517 tags will be automatically inserted into the document.
1519 It is also possible to treat the output as if it were surrounded by the
1520 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1521 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1522 attribute of the @verb{|<lisp>|} tag.
1525 <lisp markup="example">
1526 (concat "Insert" " me")
1530 Other languages also have tags that cause source code to be evaluated.
1531 @xref{Tag Summary}, for details.
1533 @node Citations, Comments, Embedded Lisp, Markup Rules
1534 @comment node-name, next, previous, up
1535 @section Support for citing other resources
1537 @cindex tags, <cite>
1541 Here is an example of what citations look like in a Muse document.
1549 Some text before <cite>Miller1999</cite> and after the citation.
1551 This is an author-only citation <cite type="author">Miller1999</cite>.
1553 And this is a year-only citation <cite type="year">Miller1999</cite>.
1555 Finally, this is a multi-head citation
1556 <cite>Miller1999,Andrews2005</cite>.
1559 @subheading Overview
1561 The @code{#bibsource} directive defines the source of the
1562 bibliographies. The following sources are possible.
1565 @item DocBook + RefDB:
1568 @item LaTeX + bibtex:
1569 the name of an appropriate bibtex file
1571 @item LaTeX + RefDB:
1572 if the input file is called "foo.muse", then set this to "foo.bib"
1575 Citations are encoded as @verb{|<cite>|} elements which enclose the
1576 citation keys as they are defined in the bibliography file or database.
1577 In multi-head citations, the citation keys have to be separated by
1578 colons or semicolons. The @code{latex} and @code{docbook} styles
1579 translate these to the proper separator automatically.
1581 The @verb{|<cite>|} elements take an optional ``type'' attribute that
1582 defines how the citation is rendered. If the attribute is missing,
1583 you'll get a regular citation according to the bibliography style,
1584 e.g.'' (Miller et al., 1999)''. If the attribute is set to "author",
1585 only the name of the author(s) will be rendered. Accordingly, "year"
1586 will cause the year to be printed. This is useful to create citations
1590 Miller et al. had already shown in a previous publication (1999) that
1591 this is not going to work.
1594 Remember that refdb-mode (the Emacs interface to RefDB) can retrieve
1595 references by simply marking the citation key and running the
1596 @code{refdb-getref-by-field-on-region} command. Later versions of
1597 @code{refdb-mode} will also allow to insert references as Muse citations
1598 (which is already implemented for DocBook, TEI, and LaTeX documents).
1600 You may have noticed that there is no element to indicate the position
1601 of the bibliography. The latter is always created at a valid position
1602 close to the end of the document. The functions
1603 @code{muse-docbook-bibliography} and @code{muse-latex-bibliography} are
1604 called in the header or footer to generate this content, so it is
1605 possible to change the exact position.
1607 @node Comments, Tag Summary, Citations, Markup Rules
1608 @comment node-name, next, previous, up
1609 @section Lines to omit from published output
1611 @cindex publishing, omitting lines
1613 Use the following syntax to indicate a comment. Comments will not be
1617 ; Comment text goes here.
1620 That is, only a semi-colon at the beginning of a line, followed by a
1621 literal space, will cause that line to be treated as a comment.
1623 You can alternatively surround the region with the @verb{|<comment>|}
1626 If you wish the comment to be published, but just commented out using
1627 the comment syntax of the output format, then set
1628 @option{muse-publish-comments-p} to non-nil.
1630 @node Tag Summary, , Comments, Markup Rules
1631 @comment node-name, next, previous, up
1632 @section Tags that Muse recognizes
1634 @cindex inserting files at publish time
1635 @cindex publishing, including markup in headers and footers
1636 @cindex publishing, inserting files
1638 Muse has several built-in tags that may prove useful during publishing.
1639 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1640 Muse uses, as well as make your own tags.
1644 If a tag takes arguments, it will look like this, where ``tagname'' is
1645 the name of the tag.
1648 <tagname arg1="string1" arg2="string2">
1651 If you want the tag to look like it came straight from an XHTML
1652 document, you can alternatively do the following.
1655 <tagname arg1="string1" arg2="string2" />
1658 If a tag surrounds some text, it will look like this.
1661 <tagname>Some text</tagname>
1664 If a tag surrounds a large region, it will look like this.
1673 @subheading Tag listing
1675 This is the complete list of tags that Muse accepts, including those
1676 that were mentioned in previous sections.
1681 Insert a citation to another source.
1683 This takes the argument @option{type}, which indicates the type of
1684 citation. The valid types are "author" and "year". If this argument is
1685 omitted, include both author and year in the citation.
1687 The bibliography to use for the citation may be specified by the
1688 @option{#bibsource} directive.
1690 @xref{Citations}, for additional information.
1693 If publishing to HTML, surround the given text with a @verb{|<span>|}
1694 tag. It takes one argument called ``name'' that specifies the ``class''
1695 attribute of the @verb{|<span>|} tag.
1697 If publishing to a different format, do nothing extra to the text.
1700 Treat the text surrounded by the tag as if they were enclosed in equal
1701 signs, that is, make it monospace.
1704 Run a command on the region, replacing the region with the result of the
1705 command. The command is specified with the ``interp'' argument. If no
1706 value for ``interp'' is given, pass the entire region to the shell.
1708 The ``markup'' argument controls how this section is marked up.
1710 If it is omitted, publish the region with the normal Muse rules.
1712 If "nil", do not mark up the region at all, but prevent Muse from
1713 further interpreting it.
1715 If "example", treat the region as if it was surrounded by the
1716 @verb{|<example>|} tag.
1718 If "src", treat the included text as if it was surrounded by the
1719 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1722 If "verse", treat the region as if it was surrounded by the
1723 @verb{|<verse>|} tag, to preserve newlines.
1725 Otherwise, it should be the name of a function to call, with the buffer
1726 narrowed to the region.
1729 Treat the entire region as a comment. If the option
1730 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1731 publish it using the comment syntax of the current publishing style.
1734 Publish a Table of Contents. This will either be inserted in-place or
1735 at the beginning of the document, depending on your publishing style.
1736 It does not have a delimiting tag.
1738 By default, only 2 levels of headings will be included in the generated
1739 Table of Contents. To change this globally, customize the
1740 @var{muse-publish-contents-depth} option. To change this only for the
1741 current tag, use the ``depth'' argument.
1744 Publish the region in monospace, preserving the newlines in the region.
1745 This is useful for snippets of code.
1748 Insert the given file at the current location during publishing. The
1749 basic use of this tag is as follows, replacing ``included_file'' with
1750 the name of the file that you want to include.
1753 <include file="included_file">
1756 The ``markup'' argument controls how this section is marked up.
1758 If it is omitted, publish the included text with the normal Muse
1761 If "nil", do not mark up the included text at all.
1763 If "example", treat the included text as if it was surrounded by the
1764 @verb{|<example>|} tag.
1766 If "src", treat the included text as if it was surrounded by the
1767 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1770 If "verse", treat the included text as if it was surrounded by the
1771 @verb{|<verse>|} tag, to preserve newlines.
1773 Otherwise, it should be the name of a function to call after inserting
1774 the file with the buffer narrowed to the section inserted.
1777 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1778 The result is then inserted into the document, so you do not need to
1779 explicitly call @code{insert}. All text properties are removed from the
1782 This tag takes the ``markup'' argument. See the description of
1783 @verb{|<command>|} for details.
1786 Make sure that the text enclosed by this tag is published without
1787 escaping it in any way. This is useful for inserting markup directly
1788 into the published document, when Muse does not provide the desired
1792 Mark up the text between the initial and ending tags. The markup
1793 command to use may be specified by the ``function'' argument. The
1794 standard Muse markup routines are used by default if no ``function''
1795 argument is provided.
1797 This is useful for marking up regions in headers and footers. One
1798 example that comes to mind is generating a published index of all of the
1799 files in the current project by doing the following.
1802 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1806 Run the @command{perl} language interpreter on the region, replacing the
1807 region with the result of the command.
1809 This tag takes the ``markup'' argument. See the description of
1810 @verb{|<command>|} for details.
1813 Run the @command{python} language interpreter on the region, replacing
1814 the region with the result of the command.
1816 This tag takes the ``markup'' argument. See the description of
1817 @verb{|<command>|} for details.
1820 Publish the region as a blockquote. This will either be inserted
1821 in-place or at the beginning of the document, depending on your
1822 publishing style. It does not have a delimiting tag.
1825 Run the @command{ruby} language interpreter on the region, replacing the
1826 region with the result of the command.
1828 This tag takes the ``markup'' argument. See the description of
1829 @verb{|<command>|} for details.
1832 Publish the region using htmlize.
1833 The language to use may be specified by the ``lang'' attribute.
1835 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1836 the value of the ``lang'' attribute.
1838 This tag requires htmlize 1.34 or later in order to work. If this is
1839 not satisfied, or the current publishing style is not HTML-based, Muse
1840 will publish the region like an @verb{|<example>|} tag.
1843 This is used when you want to prevent Muse from trying to interpret some
1844 markup. Surround the markup in @verb{|<verbatim>|} and
1845 @verb{|</verbatim>|}, and it will not be interpreted.
1847 This tag was used often in previous versions of Muse because they did
1848 not support whole-document escaping of specials. Now, it will only be
1849 needed for other tags, and perhaps footnotes as well.
1852 Preserve the newlines in the region. In formats like HTML, newlines are
1853 removed by default, hence the need for this tag. In other publishing
1854 styles, this tag may cause the text to be indented slightly in a way
1855 that looks nice for poetry and prose.
1859 @node Publishing Styles, Extending Muse, Markup Rules, Top
1860 @comment node-name, next, previous, up
1861 @chapter Publishing Various Types of Documents
1862 @cindex publishing styles
1864 One of the principle features of Muse is the ability to publish a simple
1865 input text to a variety of different output styles. Muse also makes it
1866 easy to create new styles, or derive from an existing style.
1869 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1870 * Book:: Publishing entries into a compilation.
1871 * ConTeXt:: Publishing ConTeXt documents.
1872 * DocBook:: Publishing in DocBook XML form.
1873 * HTML:: Publishing in HTML or XHTML form.
1874 * Journal:: Keeping a journal or blog.
1875 * LaTeX:: Publishing LaTeX documents.
1876 * Poem:: Publish a poem to LaTex or PDF.
1877 * Texinfo:: Publish entries to Texinfo format or PDF.
1878 * XML:: Publish entries to XML.
1881 @node Blosxom, Book, Publishing Styles, Publishing Styles
1882 @comment node-name, next, previous, up
1883 @section Integrating Muse and pyblosxom.cgi
1884 @cindex blog, one-file-per-entry style
1886 The Blosxom publishing style publishes a tree of categorised files to a
1887 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1888 In other words, each blog entry corresponds with one file.
1891 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1892 * Blosxom Entries:: Format of a Blosxom entry and automation.
1893 * Blosxom Options:: Blosxom styles and options provided.
1896 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1897 @comment node-name, next, previous, up
1898 @subsection Other tools needed for the Blosxom style
1900 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1901 installed on a machine that you have upload access to.
1903 The major difficulty in both of these programs is specifying the date of
1904 the entries. Both programs rely on the file modification time rather
1905 than any data contained in the entries themselves. A plugin is needed
1906 in order for these programs to be able to get the correct date.
1908 @subheading PyBlosxom
1910 There are two different ways of accomplishing this in pyblosxom. The
1911 first way involves gathering the timestamps (as specified by the
1912 @code{#date} directive) into one file and then sending that file along
1913 with published entries to the webserver.
1915 The second will read each file at render time and parse the
1916 @code{#postdate} directive. Muse will translate the @code{#date}
1917 directive into @code{#postdate} at publish time, so you don't have to do
1920 @subsubheading Placing timestamps in one file
1922 The following additional components are required in order to make the
1923 date of blog entries display as something sensible.
1927 A script to gather date directives from the entire blog tree into a
1928 single file. The file must associate a blog entry with a date.
1931 A plugin for (py)blosxom that reads this file.
1934 These 2 things are provided for @command{pyblosxom.cgi} in the
1935 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1936 former service, while @file{hardcodedates.py} provides the latter
1939 Here is a sample listing from my @file{timestamps} file, which maps
1940 each file to a date. This can really be in any format, as long as your
1941 date-gathering script and your plugin can both understand it.
1944 2005-04-01-14-16 personal/paper_cranes
1945 2005-03-21 personal/spring_break_over
1946 2004-10-24 personal/finished_free_culture
1949 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1950 @file{getstamps.py}. Note that you will need to set the current
1951 directory to where your Muse files are, execute @file{getstamps.py}, and
1952 then move the generated timestamps file to your publishing directory.
1954 @subsubheading Getting timestamp from entry while rendering
1956 Alternately, the pyblosxom metadate plugin may be used. On the plus
1957 side, there is no need to run a script to gather the date. On the
1958 downside, each entry is read twice rather than once when the page is
1959 rendered. Set the value of @code{muse-blosxom-use-metadate} to non-nil
1960 to enable adding a @code{#postdate} directive to all published files.
1964 M-x customize-variable RET muse-blosxom-use-metadate RET
1967 With the metadate plugin installed in pyblosxom, the date set in this
1968 directive will be used instead of the file's modification time. The
1969 plugin is included with Muse at @file{contrib/pyblosxom/metadate.py}.
1973 It is also possible to use Blosxom, which is written in Perl, to serve
1974 blog entries that were published with Muse. The steps are as follows.
1978 Download and install blosxom from @url{http://blosxom.sourceforge.net/}.
1981 Install the metadate plugin. It is available in
1982 @file{contrib/blosxom/metadate_0_0_3}.
1985 Every time you make a new blog entry, change to the blosxom data
1986 directory and execute the @file{contrib/blosxom/getstamps.pl} script.
1987 This script has only recently been made, and may still have some bugs,
1988 so use with caution.
1992 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1993 @comment node-name, next, previous, up
1994 @subsection Format of a Blosxom entry and automation
1996 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1997 longer `#date yyyy-mm-dd-hh-mm', a title (using the @code{#title}
1998 directive), plus whatever normal content is desired.
2000 The date directive is not used directly by @command{pyblosxom.cgi} or
2001 this program. You need to have the two additional items from the former
2002 section to make use of this feature.
2004 There is a function called @code{muse-blosxom-new-entry} that will
2005 automate the process of making a new blog entry. To make use of it, do
2010 Customize @code{muse-blosxom-base-directory} to the location that your
2011 blog entries are stored.
2014 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
2015 use the following code to assign this function to @kbd{C-c p l'}.
2018 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
2022 You should create your directory structure ahead of time under your base
2023 directory. These directories, which correspond with category names, may
2027 When you enter this key sequence, you will be prompted for the category
2028 of your entry and its title. Upon entering this information, a new file
2029 will be created that corresponds with the title, but in lowercase
2030 letters and having special characters converted to underscores. The
2031 title and date directives will be inserted automatically.
2034 @node Blosxom Options, , Blosxom Entries, Blosxom
2035 @comment node-name, next, previous, up
2036 @subsection Blosxom styles and options provided
2038 The following styles and options are available in the Blosxom publishing
2041 @subheading Styles provided
2045 @cindex publishing styles, blosxom-html
2047 Publish Blosxom entries in HTML form.
2049 @cindex publishing styles, blosxom-xhtml
2051 Publish Blosxom entries in XHTML form.
2055 @subheading Options provided
2059 @item muse-blosxom-extension
2060 Default file extension for publishing Blosxom files.
2062 @item muse-blosxom-header
2063 Header used for publishing Blosxom files.
2065 This may be text or a filename.
2067 @item muse-blosxom-footer
2068 Footer used for publishing Blosxom files.
2070 This may be text or a filename.
2072 @item muse-blosxom-base-directory
2073 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
2075 This is the top-level directory where your blog entries may be found
2080 @node Book, ConTeXt, Blosxom, Publishing Styles
2081 @comment node-name, next, previous, up
2082 @section Publishing entries into a compilation
2084 This publishing style is used to output ``books'' in LaTeX or PDF
2087 Each page will become a separate chapter in the book, unless the style
2088 keyword @option{:nochapters} is used, in which case they are all run
2089 together as if one giant chapter.
2091 One way of publishing a book is to make a project for it, add the
2092 project to @code{muse-project-alist}, and use the @code{book-pdf} style
2093 with a very specific @option{:include} value to specify some page whose
2094 contents will be checked for the values of @code{#title} and
2095 @code{#date}, and whose name will be used in the output file. Then to
2096 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
2097 @kbd{C-c C-p} to trigger the publishing process. An example
2098 @code{muse-project-alist} for this method follows.
2101 (setq muse-project-alist
2102 '(("MyNotes" (:nochapters t ; do automatically add chapters
2103 :book-chapter "Computer Science"
2105 :book-chapter "Mathematics"
2107 :book-chapter "Emacs"
2109 :book-end t ; the rest will not be placed in the book
2110 "~/Notes" ; so we can find the notes-anthology page
2112 :force-publish ("index")
2115 :include "/notes-anthology[^/]*$"
2116 :path "~/public_html/notes")
2117 ;; other publishing styles for each directory go here,
2122 In this example, there would be a file called
2123 @file{~/Notes/notes-anthology.muse}, which would contain just the
2124 following. The resulting book would be published to
2125 @file{~/public_html/notes/notes-anthology.pdf}.
2128 #title My Technology Ramblings
2131 Another way is to call the @code{muse-book-publish-project} function
2132 manually, with a custom project entry. An example of this may be found
2133 in John Wiegley's configuration file at
2134 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
2137 @subheading Styles provided
2141 @cindex publishing styles, book-latex
2143 Publish a book in LaTeX form. The header and footer are different than
2144 the normal LaTeX publishing mode.
2146 @cindex publishing styles, book-pdf
2148 Publish a book in PDF form. The header and footer are different than
2149 the normal PDF publishing mode.
2153 @subheading Options provided
2157 @item muse-book-before-publish-hook
2158 A hook run in the book buffer before it is marked up.
2160 @item muse-book-after-publish-hook
2161 A hook run in the book buffer after it is marked up.
2163 @item muse-book-latex-header
2164 Header used for publishing books to LaTeX.
2166 This may be text or a filename.
2168 @item muse-book-latex-footer
2169 Footer used for publishing books to LaTeX.
2171 This may be text or a filename.
2174 @node ConTeXt, DocBook, Book, Publishing Styles
2175 @comment node-name, next, previous, up
2176 @section Publishing ConTeXt documents
2178 This publishing style is capable of producing ConTeXt or PDF documents.
2180 If you wish to publish PDF documents based on ConTeXt, you will need to
2181 have it installed. For Debian and Ubuntu, this can be accomplished by
2182 installing the ``texlive'' package.
2184 @subheading Styles provided
2188 @cindex publishing styles, context
2190 Publish a ConTeXt document.
2192 @cindex publishing styles, context-pdf
2194 Publish a PDF document, using an external ConTeXt document conversion
2197 @cindex publishing styles, context-slides
2198 @item context-slides
2199 Produce slides from a ConTeXt document.
2201 Here is an example of a slide.
2206 [[Some-sort-of-cute-image.png]]
2211 - Another bullet point.
2218 @cindex publishing styles, context-slides-pdf
2219 @item context-slides-pdf
2220 Publish a PDF document of ConTeXt slides.
2224 @subheading Options provided
2228 @item muse-context-extension
2229 Default file extension for publishing ConTeXt files.
2231 @item muse-context-pdf-extension
2232 Default file extension for publishing ConTeXt files to PDF.
2234 @item muse-context-pdf-program
2235 The program that is called to generate PDF content from ConTeXt content.
2237 @item muse-context-pdf-cruft
2238 Extensions of files to remove after generating PDF output successfully.
2240 @item muse-context-header
2241 Header used for publishing ConTeXt files.
2243 This may be text or a filename.
2245 @item muse-context-footer
2246 Footer used for publishing ConTeXt files.
2248 This may be text or a filename.
2250 @item muse-context-markup-regexps
2251 List of markup regexps for identifying regions in a Muse page.
2253 For more on the structure of this list,
2254 @xref{muse-publish-markup-regexps}.
2256 @item muse-context-markup-functions
2257 An alist of style types to custom functions for that kind of text.
2259 For more on the structure of this list,
2260 @xref{muse-publish-markup-functions}.
2262 @item muse-context-markup-strings
2263 Strings used for marking up text.
2265 These cover the most basic kinds of markup, the handling of which
2266 differs little between the various styles.
2268 @item muse-context-slides-header
2269 Header for publishing a presentation (slides) using ConTeXt.
2271 Any of the predefined modules, which are available in the
2272 tex/context/base directory, can be used by writing a "module" directive
2273 at the top of the Muse file; if no such directive is provided, module
2274 pre-01 is used. Alternatively, you can use your own style ("mystyle",
2275 in this example) by replacing "\usemodule[]" with "\input mystyle".
2277 This may be text or a filename.
2279 @item muse-context-slides-markup-strings
2280 Strings used for marking up text in ConTeXt slides.
2282 @item muse-context-markup-specials-document
2283 A table of characters which must be represented specially.
2284 These are applied to the entire document, sans already-escaped
2287 @item muse-context-markup-specials-example
2288 A table of characters which must be represented specially.
2289 These are applied to @verb{|example>|} regions.
2291 With the default interpretation of @verb{|<example>|} regions, no
2292 specials need to be escaped.
2294 @item muse-context-markup-specials-literal
2295 A table of characters which must be represented specially.
2296 This applies to =monospaced text= and @verb{|<code>|} regions.
2298 @item muse-context-markup-specials-url
2299 A table of characters which must be represented specially.
2300 These are applied to URLs.
2302 @item muse-context-markup-specials-image
2303 A table of characters which must be represented specially.
2304 These are applied to image filenames.
2306 @item muse-context-permit-contents-tag
2307 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2310 Most of the time, it is best to have a table of contents on the
2311 first page, with a new page immediately following. To make this
2312 work with documents published in both HTML and ConTeXt, we need to
2313 ignore the @verb{|<contents>|} tag.
2315 If you don't agree with this, then set this option to non-nil,
2316 and it will do what you expect.
2320 @node DocBook, HTML, ConTeXt, Publishing Styles
2321 @comment node-name, next, previous, up
2322 @section Publishing in DocBook XML form
2324 This publishing style is used to generate DocBook XML files.
2326 @subheading Styles provided
2330 @cindex publishing styles, docbook
2332 Publish a file in Docbook form.
2336 @subheading Options provided
2338 This publishing style uses the same options for markup up special
2339 characters as the ``xml'' publishing style. @xref{XML}, for details.
2343 @item muse-docbook-extension
2344 Default file extension for publishing DocBook XML files.
2346 @item muse-docbook-header
2347 Header used for publishing DocBook XML files.
2349 This may be text or a filename.
2351 @item muse-docbook-footer
2352 Footer used for publishing DocBook XML files.
2354 This may be text or a filename.
2356 @item muse-docbook-markup-regexps
2357 List of markup rules for publishing a Muse page to DocBook XML.
2359 @item muse-docbook-markup-functions
2360 An alist of style types to custom functions for that kind of text.
2362 @item muse-docbook-markup-strings
2363 Strings used for marking up text.
2365 These cover the most basic kinds of markup, the handling of which
2366 differs little between the various styles.
2368 @item muse-docbook-encoding-default
2369 The default Emacs buffer encoding to use in published files.
2370 This will be used if no special characters are found.
2372 @item muse-docbook-charset-default
2373 The default DocBook XML charset to use if no translation is
2374 found in @code{muse-xml-encoding-map}.
2378 @node HTML, Journal, DocBook, Publishing Styles
2379 @comment node-name, next, previous, up
2380 @section Publishing in HTML or XHTML form
2382 This publishing style is capable of producing HTML or XHTML documents.
2384 @subheading Styles provided
2388 @cindex publishing styles, html
2390 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2393 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2397 @subheading Options provided
2399 If an HTML option does not have a corresponding XHTML option, it will
2400 be used for both of these publishing styles.
2402 These publishing styles use the same options for markup up special
2403 characters as the ``xml'' publishing style. @xref{XML}, for details.
2407 @item muse-html-extension
2408 Default file extension for publishing HTML files.
2410 @item muse-xhtml-extension
2411 Default file extension for publishing XHTML files.
2413 @item muse-html-style-sheet
2414 Store your stylesheet definitions here.
2416 This is used in @code{muse-html-header}. You can put raw CSS in here or
2417 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2418 @verb{|<lisp>|} markup tags.
2420 If you are publishing to XHTML, then customize the
2421 @code{muse-xhtml-style-sheet} option instead.
2423 @item muse-xhtml-style-sheet
2424 Store your stylesheet definitions here.
2426 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2427 or a @verb{|<link>|} tag to an external stylesheet. This text may
2428 contain @verb{|<lisp>|} markup tags.
2430 @item muse-html-header
2431 Header used for publishing HTML files.
2433 This may be text or a filename.
2435 @item muse-html-footer
2436 Footer used for publishing HTML files.
2438 This may be text or a filename.
2440 @item muse-xhtml-header
2441 Header used for publishing XHTML files.
2443 This may be text or a filename.
2445 @item muse-xhtml-footer
2446 Footer used for publishing XHTML files.
2448 This may be text or a filename.
2450 @item muse-html-anchor-on-word
2451 When true, anchors surround the closest word.
2453 This allows you to select them in a browser (i.e. for pasting), but has
2454 the side-effect of marking up headers in multiple colors if your header
2455 style is different from your link style.
2457 @item muse-html-table-attributes
2458 The attribute to be used with HTML @verb{|<table>|} tags.
2460 If you want to make more-complicated tables in HTML, surround the HTML
2461 with the @verb{|literal|} tag, so that it does not get escaped.
2463 @item muse-html-markup-regexps
2464 List of markup rules for publishing a Muse page to HTML.
2466 @item muse-html-markup-functions
2467 An alist of style types to custom functions for that kind of text.
2469 @item muse-html-markup-strings
2470 Strings used for marking up text as HTML.
2472 These cover the most basic kinds of markup, the handling of which
2473 differs little between the various styles.
2475 @item muse-xhtml-markup-strings
2476 Strings used for marking up text as XHTML.
2478 These cover the most basic kinds of markup, the handling of which
2479 differs little between the various styles.
2481 @item muse-html-markup-tags
2482 A list of tag specifications, for specially marking up HTML.
2483 @xref{muse-publish-markup-tags}, for more information.
2485 @item muse-html-meta-http-equiv
2486 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2488 @item muse-html-meta-content-type
2489 The content type used for the HTML @verb{|<meta>|} tag.
2491 If you are striving for XHTML 1.1 compliance, you may want to change
2492 this to ``application/xhtml+xml''.
2494 @item muse-html-meta-content-encoding
2495 The charset to append to the HTML @verb{|<meta>|} tag.
2497 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2498 and determine the HTML charset from emacs's coding. If set to a string,
2499 this string will be used to force a particular charset.
2501 @item muse-html-charset-default
2502 The default HTML meta charset to use if no translation is found in
2503 @code{muse-xml-encoding-map}.
2505 @item muse-html-encoding-default
2506 The default Emacs buffer encoding to use in published files.
2507 This will be used if no special characters are found.
2511 @node Journal, LaTeX, HTML, Publishing Styles
2512 @comment node-name, next, previous, up
2513 @section Keeping a journal or blog
2515 @cindex blog, journal style
2517 The module facilitates the keeping and publication of a journal. When
2518 publishing to HTML, it assumes the form of a web log, or blog.
2520 The input format for each entry is as follows.
2523 * 20040317: Title of entry
2528 "You know who you are. It comes down to a simple gut check: You
2529 either love what you do or you don't. Period." -- P. Bronson
2533 The "qotd", or Quote of the Day, is entirely optional. When generated
2534 to HTML, this entry is rendered as the following.
2538 <div class="entry-qotd">
2539 <h3>Quote of the Day:</h3>
2540 <p>"You know who you are. It comes down to a simple gut
2541 check: You either love what you do or you don't. Period."
2544 <div class="entry-body">
2545 <div class="entry-head">
2546 <div class="entry-date">
2547 <span class="date">March 17, 2004</span>
2549 <div class="entry-title">
2550 <h2>Title of entry</h2>
2553 <div class="entry-text">
2554 <p>Text for the entry.</p>
2560 The plurality of "div" tags makes it possible to display the entries in
2561 any form you wish, using a CSS style.
2563 Also, an .RDF file can be generated from your journal by publishing it
2564 with the "rdf" style. It uses the first two sentences of the first
2565 paragraph of each entry as its "description", and auto-generates tags
2566 for linking to the various entries.
2568 @subheading muse-project-alist considerations
2570 If you wish to publish an RDF or RSS feed, it is important to include
2571 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2572 for your Journal projects. An example follows.
2575 (setq muse-project-alist
2576 '(("Journal" ("~/Journal/"
2578 (:base "journal-rss"
2579 :base-url "http://example.org/journal/"
2580 :path "~/public_html/journal"))))
2583 @subheading Styles provided
2587 @cindex publishing styles, journal-html
2589 Publish journal entries as an HTML document.
2591 @cindex publishing styles, journal-xhtml
2593 Publish journal entries as an XHTML document.
2595 @cindex publishing styles, journal-latex
2597 Publish journal entries as a LaTeX document.
2599 @cindex publishing styles, journal-pdf
2601 Publish journal entries as a PDF document.
2603 @cindex publishing styles, journal-book-latex
2604 @item journal-book-latex
2605 Publish journal entries as a LaTeX book.
2607 @cindex publishing styles, journal-book-pdf
2608 @item journal-book-pdf
2609 Publish journal entries as a PDF book.
2611 @cindex publishing styles, journal-rdf
2612 @cindex publishing styles, RSS 1.0
2614 Publish journal entries as an RDF file (RSS 1.0).
2616 @cindex publishing styles, journal-rss
2617 @cindex publishing styles, RSS 2.0
2619 Publish journal entries as an RSS file (RSS 2.0).
2621 @cindex publishing styles, journal-rss-entry
2622 @item journal-rss-entry
2623 Used internally by @code{journal-rss} and @code{journal-rdf} for
2624 publishing individual entries.
2628 @subheading Options provided
2632 @item muse-journal-heading-regexp
2633 A regexp that matches a journal heading.
2635 Paren group 1 is the ISO date, group 2 is the optional category, and
2636 group 3 is the optional heading for the entry.
2638 @item muse-journal-date-format
2639 Date format to use for journal entries.
2641 @item muse-journal-html-heading-regexp
2642 A regexp that matches a journal heading from an HTML document.
2644 Paren group 1 is the ISO date, group 2 is the optional category, and
2645 group 3 is the optional heading for the entry.
2647 @item muse-journal-html-entry-template
2648 Template used to publish individual journal entries as HTML.
2650 This may be text or a filename.
2652 @item muse-journal-latex-section
2653 Template used to publish a LaTeX section.
2655 @item muse-journal-latex-subsection
2656 Template used to publish a LaTeX subsection.
2658 @item muse-journal-markup-tags
2659 A list of tag specifications, for specially marking up Journal entries.
2661 @xref{muse-publish-markup-tags}, for more information.
2663 This is used by @code{journal-latex} and its related styles, as well as
2664 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2665 @code{journal-rss} use.
2667 @item muse-journal-rdf-extension
2668 Default file extension for publishing RDF (RSS 1.0) files.
2670 @item muse-journal-rdf-base-url
2671 The base URL of the website referenced by the RDF file.
2673 @item muse-journal-rdf-header
2674 Header used for publishing RDF (RSS 1.0) files.
2676 This may be text or a filename.
2678 @item muse-journal-rdf-footer
2679 Footer used for publishing RDF (RSS 1.0) files.
2681 This may be text or a filename.
2683 @item muse-journal-rdf-date-format
2684 Date format to use for RDF entries.
2686 @item muse-journal-rdf-entry-template
2687 Template used to publish individual journal entries as RDF.
2689 This may be text or a filename.
2691 @item muse-journal-rdf-summarize-entries
2692 If non-nil, include only summaries in the RDF file, not the full data.
2694 The default is nil, because this annoys some subscribers.
2696 @item muse-journal-rss-heading-regexp
2697 A regexp that matches a journal heading from an HTML document.
2699 Paren group 1 is the ISO date, group 2 is the optional category,
2700 and group 3 is the optional heading for the entry.
2702 @item muse-journal-rss-extension
2703 Default file extension for publishing RSS 2.0 files.
2705 @item muse-journal-rss-base-url
2706 The base URL of the website referenced by the RSS file.
2708 @item muse-journal-rss-header
2709 Header used for publishing RSS 2.0 files.
2711 This may be text or a filename.
2713 @item muse-journal-rss-footer
2714 Footer used for publishing RSS 2.0 files.
2716 This may be text or a filename.
2718 @item muse-journal-rss-date-format
2719 Date format to use for RSS 2.0 entries.
2721 @item muse-journal-rss-entry-template
2722 Template used to publish individual journal entries as RSS 2.0.
2724 This may be text or a filename.
2726 @item muse-journal-rss-enclosure-types-alist
2727 File types that are accepted as RSS enclosures.
2729 This is an alist that maps file extension to content type.
2731 Useful for podcasting.
2733 @item muse-journal-rss-summarize-entries
2734 If non-nil, include only summaries in the RSS file, not the full data.
2736 The default is nil, because this annoys some subscribers.
2738 @item muse-journal-rss-markup-regexps
2739 List of markup rules for publishing a Muse journal page to RSS.
2741 For more information on the structure of this list,
2742 @xref{muse-publish-markup-regexps}.
2744 @item muse-journal-rss-markup-functions
2745 An alist of style types to custom functions for that kind of text.
2747 For more on the structure of this list,
2748 @xref{muse-publish-markup-functions}.
2752 @node LaTeX, Poem, Journal, Publishing Styles
2753 @comment node-name, next, previous, up
2754 @section Publishing LaTeX documents
2756 This publishing style is capable of producing LaTeX or PDF documents.
2758 If you wish to publish PDF documents, you will need to have a good TeX
2759 installation. For Debian and Ubuntu, this can be accomplished by
2760 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2763 @subheading Styles provided
2767 @cindex publishing styles, latex
2769 Publish a LaTeX document.
2771 @cindex publishing styles, pdf
2773 Publish a PDF document, using an external LaTeX document conversion
2776 @cindex publishing styles, latexcjk
2778 Publish a LaTeX document with CJK (Chinese) encodings.
2780 @cindex publishing styles, pdfcjk
2782 Publish a PDF document with CJK (Chinese) encodings, using an external
2783 LaTeX document conversion tool.
2785 @cindex publishing styles, slides
2787 Publish a LaTeX document that uses the Beamer extension. This is
2788 suitable for producing slides.
2790 Here is an example of a slide.
2793 <slide title="First Slide">
2794 Everything between the slide tags composes this slide.
2796 [[Some-sort-of-cute-image.png]]
2799 - Another bullet point.
2803 @cindex publishing styles, slides-pdf
2805 Publish a PDF document of slides, using the Beamer extension.
2807 @cindex publishing styles, lecture-notes
2809 Publish a LaTeX document that uses the Beamer extension. This is
2810 suitable for producing lecture notes.
2812 This can also use the @verb{|<slide>|} tag.
2814 @cindex publishing styles, lecture-notes-pdf
2815 @item lecture-notes-pdf
2816 Publish a PDF document of lecture notes, using the Beamer extension.
2820 @subheading Options provided
2824 @item muse-latex-extension
2825 Default file extension for publishing LaTeX files.
2827 @item muse-latex-pdf-extension
2828 Default file extension for publishing LaTeX files to PDF.
2830 @item muse-latex-pdf-program
2831 The program that is called to generate PDF content from LaTeX content.
2833 @item muse-latex-pdf-cruft
2834 Extensions of files to remove after generating PDF output successfully.
2836 @item muse-latex-header
2837 Header used for publishing LaTeX files.
2839 This may be text or a filename.
2841 @item muse-latex-footer
2842 Footer used for publishing LaTeX files.
2844 This may be text or a filename.
2846 @item muse-latexcjk-header
2847 Header used for publishing LaTeX files (CJK).
2849 This may be text or a filename.
2851 @item muse-latexcjk-footer
2852 Footer used for publishing LaTeX files (CJK).
2854 This may be text or a filename.
2856 @item muse-latex-slides-header
2857 Header for publishing of slides using LaTeX.
2859 This may be text or a filename.
2861 You must have the Beamer extension for LaTeX installed for this to work.
2863 @item muse-latex-lecture-notes-header
2864 Header publishing of lecture notes using LaTeX.
2866 This may be text or a filename.
2868 You must have the Beamer extension for LaTeX installed for this to work.
2870 @item muse-latex-markup-regexps
2871 List of markup regexps for identifying regions in a Muse page.
2873 For more on the structure of this list,
2874 @xref{muse-publish-markup-regexps}.
2876 @item muse-latex-markup-functions
2877 An alist of style types to custom functions for that kind of text.
2879 For more on the structure of this list,
2880 @xref{muse-publish-markup-functions}.
2882 @item muse-latex-markup-strings
2883 Strings used for marking up text.
2885 These cover the most basic kinds of markup, the handling of which
2886 differs little between the various styles.
2888 @item muse-latex-slides-markup-tags
2889 A list of tag specifications, for specially marking up LaTeX slides.
2891 @item muse-latexcjk-encoding-map
2892 An alist mapping emacs coding systems to appropriate CJK codings.
2893 Use the base name of the coding system (ie, without the -unix).
2895 @item muse-latexcjk-encoding-default
2896 The default Emacs buffer encoding to use in published files.
2898 This will be used if no special characters are found.
2900 @item muse-latex-markup-specials-document
2901 A table of characters which must be represented specially.
2902 These are applied to the entire document, sans already-escaped
2905 @item muse-latex-markup-specials-example
2906 A table of characters which must be represented specially.
2907 These are applied to @verb{|example>|} regions.
2909 With the default interpretation of @verb{|<example>|} regions, no
2910 specials need to be escaped.
2912 @item muse-latex-markup-specials-literal
2913 A table of characters which must be represented specially.
2914 This applies to =monospaced text= and @verb{|<code>|} regions.
2916 @item muse-latex-markup-specials-url
2917 A table of characters which must be represented specially.
2918 These are applied to URLs.
2920 @item muse-latex-markup-specials-image
2921 A table of characters which must be represented specially.
2922 These are applied to image filenames.
2924 @item muse-latex-permit-contents-tag
2925 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2928 Most of the time, it is best to have a table of contents on the
2929 first page, with a new page immediately following. To make this
2930 work with documents published in both HTML and LaTeX, we need to
2931 ignore the @verb{|<contents>|} tag.
2933 If you don't agree with this, then set this option to non-nil,
2934 and it will do what you expect.
2938 @node Poem, Texinfo, LaTeX, Publishing Styles
2939 @comment node-name, next, previous, up
2940 @section Publish a poem to LaTex or PDF
2942 The @code{muse-poem} module makes it easy to attractively publish and
2943 reference poems in the following format, using the "memoir" module for
2944 LaTeX publishing. It will also markup poems for every other output
2945 style, though none are nearly as pretty.
2954 Annotations, history, notes, etc.
2957 Once a poem is written in this format, just publish it to PDF using the
2958 @code{poem-pdf} style. To make an inlined reference to a poem that
2959 you've written -- for example, from a blog page -- there is a "poem" tag
2960 defined by this module.
2963 <poem title="name.of.poem.page">
2966 Let's assume the template above was called @file{name.of.poem.page};
2967 then the above tag would result in this inclusion.
2975 John Wiegley uses this module for publishing all of the poems on his
2976 website, which are at
2977 @uref{http://www.newartisans.com/johnw/poems.html}.
2979 @subheading Styles provided
2983 @cindex publishing styles, poem-latex
2985 Publish a poem in LaTeX form.
2987 @cindex publishing styles, poem-pdf
2989 Publish a poem to a PDF document.
2991 @cindex publishing styles, chapbook-latex
2992 @item chapbook-latex
2993 Publish a book of poems in LaTeX form.
2995 @cindex publishing styles, chapbook-pdf
2997 Publish a book of poems to a PDF document.
3001 @subheading Options provided
3005 @item muse-poem-latex-header
3006 Header used for publishing LaTeX poems.
3008 This may be text or a filename.
3010 @item muse-poem-latex-footer
3011 Footer used for publishing LaTeX files.
3013 This may be text or a filename.
3015 @item muse-poem-markup-strings
3016 Strings used for marking up poems.
3018 These cover the most basic kinds of markup, the handling of which
3019 differs little between the various styles.
3021 @item muse-chapbook-latex-header
3022 Header used for publishing a book of poems in LaTeX form.
3024 This may be text or a filename.
3026 @item muse-chapbook-latex-footer
3027 Footer used for publishing a book of poems in LaTeX form.
3029 This may be text or a filename.
3031 @item muse-poem-chapbook-strings
3032 Strings used for marking up books of poems.
3034 These cover the most basic kinds of markup, the handling of which
3035 differs little between the various styles.
3039 @node Texinfo, XML, Poem, Publishing Styles
3040 @comment node-name, next, previous, up
3041 @section Publish entries to Texinfo format or PDF
3043 Rules for publishing a Muse file as a Texinfo article.
3045 @subheading Styles provided
3049 @cindex publishing styles, texi
3051 Publish a file in Texinfo form.
3053 @cindex publishing styles, texi
3055 Generate an Info file from a Muse file.
3057 @cindex publishing styles, info-pdf
3059 Publish a file in PDF form.
3063 @subheading Options provided
3067 @item muse-texinfo-process-natively
3068 If non-nil, use the Emacs `texinfmt' module to make Info files.
3070 @item muse-texinfo-extension
3071 Default file extension for publishing Texinfo files.
3073 @item muse-texinfo-info-extension
3074 Default file extension for publishing Info files.
3076 @item muse-texinfo-pdf-extension
3077 Default file extension for publishing PDF files.
3079 @item muse-texinfo-header
3080 Text to prepend to a Muse page being published as Texinfo.
3082 This may be text or a filename.
3083 It may contain @verb{|<lisp>|} markup tags.
3085 @item muse-texinfo-footer
3086 Text to append to a Muse page being published as Texinfo.
3088 This may be text or a filename.
3089 It may contain @verb{|<lisp>|} markup tags.
3091 @item muse-texinfo-markup-regexps
3092 List of markup rules for publishing a Muse page to Texinfo.
3094 For more on the structure of this list,
3095 @xref{muse-publish-markup-regexps}.
3097 @item muse-texinfo-markup-functions
3098 An alist of style types to custom functions for that kind of text.
3100 For more on the structure of this list,
3101 @xref{muse-publish-markup-functions}.
3103 @item muse-texinfo-markup-strings
3104 Strings used for marking up text.
3106 These cover the most basic kinds of markup, the handling of which
3107 differs little between the various styles.
3109 @item muse-texinfo-markup-specials
3110 A table of characters which must be represented specially.
3112 @item muse-texinfo-markup-specials
3113 A table of characters which must be represented specially.
3114 These are applied to URLs.
3118 @node XML, , Texinfo, Publishing Styles
3119 @comment node-name, next, previous, up
3120 @section Publish entries to XML
3122 Muse is capable of publishing XML documents, with the help of the
3123 @file{muse-xml.el} module.
3125 A RelaxNG schema is available as part of the Muse distribution in the
3126 @file{etc/muse.rnc} file.
3128 @subheading Styles provided
3132 @cindex publishing styles, xml
3134 Publish a file in XML form.
3138 @subheading Options provided
3142 @cindex muse-xml-encoding-map
3143 @item muse-xml-encoding-map
3144 An alist mapping Emacs coding systems to appropriate XML charsets.
3145 Use the base name of the coding system (i.e. without the -unix).
3147 @item muse-xml-markup-specials
3148 A table of characters which must be represented specially in all
3149 XML-like markup formats.
3151 @item muse-xml-markup-specials-url-extra
3152 A table of characters which must be represented specially in all
3153 XML-like markup formats.
3155 These are extra characters that are escaped within URLs.
3157 @item muse-xml-extension
3158 Default file extension used for publishing XML files.
3160 @item muse-xml-header
3161 Header used for publishing XML files.
3163 This may be text or a filename.
3165 @item muse-xml-footer
3166 Footer used for publishing XML files.
3168 This may be text or a filename.
3170 @item muse-xml-markup-regexps
3171 List of markup rules for publishing a Muse page to XML.
3173 For more on the structure of this list,
3174 @xref{muse-publish-markup-regexps}.
3176 @item muse-xml-markup-functions
3177 An alist of style types to custom functions for that kind of text.
3179 For more on the structure of this list,
3180 @xref{muse-publish-markup-functions}.
3182 @item muse-xml-markup-strings
3183 Strings used for marking up text.
3185 These cover the most basic kinds of markup, the handling of which
3186 differs little between the various styles.
3188 @item muse-xml-encoding-default
3189 The default Emacs buffer encoding to use in published files.
3191 This will be used if no special characters are found.
3193 @item muse-xml-charset-default
3194 The default XML charset to use if no translation is found in
3195 @code{muse-xml-encoding-map}.
3200 @node Extending Muse, Miscellaneous, Publishing Styles, Top
3201 @comment node-name, next, previous, up
3202 @chapter Making your own publishing styles
3205 * Common Elements:: Common functionality shared by styles.
3206 * Deriving Styles:: Deriving a new style from an existing
3210 @node Common Elements, Deriving Styles, , Extending Muse
3211 @comment node-name, next, previous, up
3212 @section Common functionality shared by styles
3213 @cindex publishing styles, common
3216 * Markup Functions:: Specifying functions to mark up text.
3217 * Markup Regexps:: Markup rules for publishing.
3218 * Markup Strings:: Strings specific to a publishing style.
3219 * Markup Tags:: Tag specifications for special markup.
3220 * Style Elements:: Parameters used for defining styles.
3223 @node Markup Functions, Markup Regexps, , Common Elements
3224 @comment node-name, next, previous, up
3225 @subsection Specifying functions to mark up text
3226 @cindex publishing, markup functions
3228 @anchor{muse-publish-markup-functions}
3229 @code{muse-publish-markup-functions}
3231 An alist of style types to custom functions for that kind of text.
3233 This is used by publishing styles to attempt to minimize the amount of
3234 custom regexps that each has to define. @file{muse-publish} provides
3235 rules for the most common types of markup.
3237 Each member of the list is of the following form.
3245 Describes the type of text to associate with this rule.
3246 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3249 Function to use to mark up this kind of rule if no suitable function is
3250 found through the @option{:functions} tag of the current style.
3253 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3254 @comment node-name, next, previous, up
3255 @subsection Markup rules for publishing
3256 @cindex publishing, markup regexps
3257 @cindex publishing, rules
3259 @anchor{muse-publish-markup-regexps}
3260 @code{muse-publish-markup-regexps}
3262 List of markup rules for publishing a page with Muse.
3264 The rules given in this variable are invoked first, followed by whatever
3265 rules are specified by the current style.
3267 Each member of the list is either a function, or a list of the following
3271 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3276 A regular expression, or symbol whose value is a regular expression,
3277 which is searched for using `re-search-forward'.
3279 @item TEXT-BEGIN-GROUP
3280 The matching group within that regexp which denotes the beginning of the
3281 actual text to be marked up.
3283 @item REPLACEMENT-TEXT
3284 A string that will be passed to `replace-match'.
3286 If it is not a string, but a function, it will be called to determine
3287 what the replacement text should be (it must return a string). If it is
3288 a symbol, the value of that symbol should be a string.
3291 The replacements are done in order, one rule at a time. Writing
3292 the regular expressions can be a tricky business. Note that case
3293 is never ignored. `case-fold-search' is always bound to nil
3294 while processing the markup rules.
3296 @subheading Publishing order
3298 This is the order that the publishing rules are consulted, by default.
3299 This may be changed by customizing @code{muse-publish-markup-regexps}.
3303 @item trailing and leading whitespace
3304 Remove trailing and leading whitespace from a file.
3309 This is only recognized at the beginning of a file.
3312 @samp{; a commented line}
3320 @item explicit links
3321 Prevent emphasis characters in explicit links from being marked up.
3323 Don't actually publish them here, just add a special no-emphasis text
3327 Whitespace-delimited word, possibly with emphasis characters
3329 This function is responsible for marking up emphasis and escaping some
3335 Outline-mode style headings.
3340 These are ellipses with a dot at end.
3350 Horizontal rule or section separator.
3352 @item no-break-space
3355 Prevent lines from being split before or after these characters.
3360 beginning of footnotes section
3365 Footnote definition or reference. If at beginning of line, it is a
3380 Numbered list, item list, or term definition list.
3384 @file{table.el} style tables
3387 @samp{table | cells}
3389 Muse tables or orgtbl-mode style tables.
3392 spaces before beginning of text
3408 @samp{[[explicit][links]]}
3411 @samp{http://example.com/}
3414 @samp{bare-email@@example.com}
3418 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3419 @comment node-name, next, previous, up
3420 @subsection Strings specific to a publishing style
3421 @cindex publishing, markup strings
3423 @dfn{Markup strings} are strings used for marking up text for a
3426 These cover the most basic kinds of markup, the handling of which
3427 differs little between the various styles.
3429 @subheading Available markup strings
3433 @item image-with-desc
3434 An image and a description.
3436 Argument 1: image without extension. Argument 2: image extension.
3437 Argument 3: description.
3442 Argument 1: image without extension. Argument 2: image extension.
3445 An image with a link around it.
3447 Argument 1: link. Argument 2: image without extension.
3448 Argument 3: image extension.
3451 A reference to an anchor on the current page.
3453 Argument 1: anchor name. Argument 2: description if one exists, or the
3454 original link otherwise.
3457 A URL without a description.
3462 A link to a Muse page with a description.
3464 Argument 1: link. Argument 2: description if one exists, or the
3465 original link otherwise.
3467 @item link-and-anchor
3468 A link to a Muse page with an anchor, and a description.
3470 Argument 1: link. Argument 2: anchor name.
3471 Argument 3: description if one exists, or the original link otherwise.
3472 Argument 4: link without an extension.
3475 A link to an email address.
3477 Argument 1: email address. Argument 2: email address.
3482 Argument 1: name of anchor.
3487 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3490 Beginning of a comment.
3496 A horizontal line or space.
3498 @item no-break-space
3499 A space that separates two words which are not to be separated.
3502 Beginning of footnote.
3508 Mark a reference for the current footnote.
3510 Argument 1: number of this footnote.
3512 @item footnotemark-end
3513 End of a reference for the current footnote.
3516 Indicate the text of the current footnote.
3518 Argument 1: number of this footnote.
3520 @item footnotetext-end
3521 End of a footnote text line.
3524 Text used to replace ``Footnotes:'' line.
3533 Beginning of a part indicator line. This is used by book publishing.
3536 End of a part indicator line. This is used by book publishing.
3539 Beginning of a chapter indicator line. This is used by book publishing.
3542 End of a chapter indicator line. This is used by book publishing.
3545 Beginning of level 1 section indicator line.
3547 Argument 1: level of section; always 1.
3550 End of level 1 section indicator line.
3552 Argument 1: level of section; always 1.
3555 Beginning of level 2 section indicator line.
3557 Argument 1: level of section; always 2.
3559 @item subsection-end
3560 End of level 2 section indicator line.
3562 Argument 1: level of section; always 2.
3565 Beginning of level 3 section indicator line.
3567 Argument 1: level of section; always 3.
3569 @item subsubsection-end
3570 End of level 3 section indicator line.
3572 Argument 1: level of section; always 3.
3575 Beginning of section indicator line, where level is greater than 3.
3577 Argument 1: level of section.
3579 @item section-other-end
3580 End of section indicator line, where level is greater than 3.
3582 Argument 1: level of section.
3584 @item begin-underline
3585 Beginning of underlined text.
3588 End of underlined text.
3591 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3595 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3599 Beginning of the first level of emphasized text.
3602 End of the first level of emphasized text.
3604 @item begin-more-emph
3605 Beginning of the second level of emphasized text.
3608 End of the second level of emphasized text.
3610 @item begin-most-emph
3611 Beginning of the third (and final) level of emphasized text.
3614 End of the third (and final) level of emphasized text.
3617 Beginning of verse text.
3620 String used to each space that is further indented than the beginning of
3623 @item begin-verse-line
3624 Beginning of a line of verse.
3626 @item empty-verse-line
3627 End of a line of verse.
3629 @item begin-last-stanza-line
3630 Beginning of the last line of a verse stanza.
3632 @item end-last-stanza-line
3633 End of the last line of a verse stanza.
3639 Beginning of an example region. To make use of this, an
3640 @samp{<example>} tag is needed.
3643 End of an example region. To make use of this, an @samp{</example>} tag
3647 Begin a centered line.
3650 End a centered line.
3653 Begin a quoted region.
3656 End a quoted region.
3658 @item begin-quote-item
3659 Begin a quote paragraph.
3661 @item end-quote-item
3662 End a quote paragraph.
3665 Begin an unordered list.
3668 End an unordered list.
3670 @item begin-uli-item
3671 Begin an unordered list item.
3674 End an unordered list item.
3677 Begin an ordered list.
3680 End an ordered list.
3682 @item begin-oli-item
3683 Begin an ordered list item.
3686 End an ordered list item.
3689 Begin a definition list.
3692 End a definition list.
3695 Begin a definition list item.
3698 End a definition list item.
3701 Begin a definition list term.
3704 End a definition list term.
3707 Begin a definition list entry.
3710 End a definition list entry.
3718 @item begin-table-group
3719 Begin a table grouping.
3721 @item end-table-group
3722 End a table grouping.
3724 @item begin-table-row
3730 @item begin-table-entry
3731 Begin a table entry.
3733 @item end-table-entry
3738 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3739 @comment node-name, next, previous, up
3740 @subsection Tag specifications for special markup
3741 @cindex publishing, markup tags
3743 @anchor{muse-publish-markup-tags}
3744 @code{muse-publish-markup-tags}
3746 A list of tag specifications, for specially marking up text.
3748 XML-style tags are the best way to add custom markup to Muse. This is
3749 easily accomplished by customizing this list of markup tags.
3751 For each entry, the name of the tag is given, whether it expects a
3752 closing tag and/or an optional set of attributes, whether it is
3753 nestable, and a function that performs whatever action is desired within
3754 the delimited region.
3756 The tags themselves are deleted during publishing, before the function
3757 is called. The function is called with three arguments, the beginning
3758 and end of the region surrounded by the tags. If properties are
3759 allowed, they are passed as a third argument in the form of an alist.
3760 The `end' argument to the function is always a marker.
3762 Point is always at the beginning of the region within the tags, when the
3763 function is called. Wherever point is when the function finishes is
3764 where tag markup will resume.
3766 These tag rules are processed once at the beginning of markup, and once
3767 at the end, to catch any tags which may have been inserted in-between.
3769 @node Style Elements, , Markup Tags, Common Elements
3770 @comment node-name, next, previous, up
3771 @subsection Parameters used for defining styles
3772 @cindex publishing, style elements
3774 Style elements are tags that define a style. Use
3775 @code{muse-define-style} to create a new style.
3778 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3781 @subheading Usable elements
3786 File extension to use for publishing files with this style.
3789 File extension to use for publishing links to Muse files with this
3793 File extension to use for publishing second-stage files with this style.
3795 For example, PDF publishing generates a LaTeX file first, then a PDF
3796 from that LaTeX file.
3799 List of markup rules for publishing a page with Muse.
3800 @xref{muse-publish-markup-regexps}.
3803 An alist of style types to custom functions for that kind of text.
3804 @xref{muse-publish-markup-functions}.
3807 Strings used for marking up text with this style.
3809 These cover the most basic kinds of markup, the handling of which
3810 differs little between the various styles.
3813 A list of tag specifications, used for handling extra tags.
3814 @xref{muse-publish-markup-tags}.
3817 A table of characters which must be represented specially.
3820 A function that is to be executed on the newly-created publishing buffer
3821 (or the current region) before any publishing occurs.
3823 This is used to set extra parameters that direct the publishing process.
3826 A function that is to be executed on the publishing buffer (or the
3827 current region) immediately after applying all of the markup regexps.
3829 This is used to fix the order of table elements (header, footer, body)
3833 A function that is to be executed on the publishing buffer after
3834 :before-end, and immediately after inserting the header and footer.
3836 This is used for generating the table of contents as well as setting the
3840 A function that is to be executed after saving the published file, but
3841 while still in its buffer.
3843 This is used for generating second-stage documents like PDF files from
3844 just-published LaTeX files.
3847 Header used for publishing files of this style.
3849 This may be a variable, text, or a filename. It is inserted at the
3850 beginning of a file, after evaluating the publishing markup.
3853 Footer used for publishing files of this style.
3855 This may be a variable, text, or a filename. It is inserted at the end
3856 of a file, after evaluating the publishing markup.
3859 Style sheet used for publishing files of this style.
3861 This may be a variable or text. It is used in the header of HTML and
3862 XHTML based publishing styles.
3865 The function used to browse the published result of files of this style.
3869 @node Deriving Styles, , Common Elements, Extending Muse
3870 @comment node-name, next, previous, up
3871 @section Deriving a new style from an existing one
3872 @cindex publishing styles, deriving
3874 To create a new style from an existing one, use @code{muse-derive-style}
3875 as follows. This is a good way to fix something you don't like about a
3876 particular publishing style, or to personalize it.
3879 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3882 The derived name is a string defining the new style, such as "my-html".
3883 The base name must identify an existing style, such as "html" -- if you
3884 have loaded @file{muse-html}. The style parameters are the same as
3885 those used to create a style, except that they override whatever
3886 definitions exist in the base style. However, some definitions only
3887 partially override. The following parameters support partial
3890 @xref{Style Elements}, for a complete list of all parameters.
3895 If a markup function is not found in the derived style's function list,
3896 the base style's function list will be queried.
3899 All regexps in the current style and the base style(s) will be used.
3902 If a markup string is not found in the derived style's string list, the
3903 base style's string list will be queried.
3907 @node Miscellaneous, Getting Help and Reporting Bugs, Extending Muse, Top
3908 @comment node-name, next, previous, up
3909 @chapter Miscellaneous add-ons, like a minor mode
3912 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
3915 @node Muse List Edit Minor Mode, , , Miscellaneous
3916 @comment node-name, next, previous, up
3917 @section Edit lists easily in other major modes
3918 @cindex muse-list-edit-minor-mode
3920 @code{muse-list-edit-minor-mode} is meant to be used with other major
3921 modes, such as Message (for composing email) and debian-changelog-mode
3922 (for editing debian/changelog files).
3924 It implements practically perfect support for editing and filling lists.
3925 It can even handle nested lists. In addition to Muse-specific list
3926 items ("-", numbers, definition lists, footnotes), it can also handle
3927 items that begin with "*" or "+". Filling list items behaves in the
3928 same way that it does in Muse, regardless of whether filladapt is also
3929 enabled, which is the primary reason to use this tool.
3931 @subheading Installation
3933 To use it, add ``(require 'muse-mode)'' to your Emacs customization file
3934 and add the function @code{turn-on-muse-list-edit-minor-mode} to any
3935 mode hooks where you wish to enable this minor mode.
3937 @subheading Keybindings
3939 @code{muse-list-edit-minor-mode} uses the following keybindings.
3943 @item M-RET (`muse-l-e-m-m-insert-list-item')
3944 Insert a new list item at point, using the indentation level of the
3947 @item C-< (`muse-l-e-m-m-decrease-list-item-indent')
3948 Decrease indentation of the current list item.
3950 @item C-> (`muse-l-e-m-m-increase-list-item-indent')
3951 Increase indentation of the current list item.
3955 @subheading Functions
3957 @defun muse-list-edit-minor-mode
3958 This is a global minor mode for editing files with lists.
3959 It is meant to be used with other major modes, and not with Muse mode.
3961 Interactively, with no prefix argument, toggle the mode.
3962 With universal prefix @var{arg} turn mode on.
3963 With zero or negative @var{arg} turn mode off.
3965 This minor mode provides the Muse keybindings for editing lists,
3966 and support for filling lists properly.
3968 It recognizes not only Muse-style lists, which use the "-"
3969 character or numbers, but also lists that use asterisks or plus
3970 signs. This should make the minor mode generally useful.
3972 Definition lists and footnotes are also recognized.
3974 Note that list items may omit leading spaces, for compatibility
3975 with modes that set @code{left-margin}, such as
3976 @code{debian-changelog-mode}.
3979 @defun turn-on-muse-list-edit-minor-mode
3980 Unconditionally turn on Muse list edit minor mode.
3983 @defun turn-off-muse-list-edit-minor-mode
3984 Unconditionally turn off Muse list edit minor mode.
3987 @node Getting Help and Reporting Bugs, History, Miscellaneous, Top
3988 @comment node-name, next, previous, up
3989 @chapter Getting Help and Reporting Bugs
3990 @cindex help, getting
3991 @cindex bugs, reporting
3993 After you have read this guide, if you still have questions about
3994 Muse, or if you have bugs to report, there are several places you can
4000 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
4001 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
4005 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
4006 that Michael Olson (the current maintainer) made for Muse.
4009 Muse has several different mailing lists.
4013 @item muse-el-announce
4014 Low-traffic list for Muse-related announcements.
4016 You can join this mailing list (@email{muse-el-announce@@gna.org})
4017 using the subscription form at
4018 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
4019 mailing list is also available via Gmane (@url{http://gmane.org/}). The
4020 group is called @samp{gmane.emacs.muse.announce}.
4022 @item muse-el-discuss
4023 Discussion, bugfixes, suggestions, tips, and the like for Muse.
4024 This mailing list also includes the content of muse-el-announce.
4026 You can join this mailing list (@email{muse-el-discuss@@gna.org})
4027 using the subscription form at
4028 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
4029 list is also available via Gmane with the identifier
4030 @samp{gmane.emacs.muse.general}.
4033 Log messages for commits made to Muse.
4035 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
4036 the subscription form at
4037 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
4038 is also available via Gmane with the identifier
4039 @samp{gmane.emacs.muse.scm}.
4041 @item muse-el-commits
4042 Generated bug reports for Emacs Muse. If you use our bug-tracker at
4043 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
4044 sent to this list automatically.
4046 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
4047 the subscription form at
4048 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
4049 is also available via Gmane with the identifier
4050 @samp{gmane.emacs.muse.cvs}.
4052 @item muse-el-internationalization
4053 Discussion of translation of the Muse website and documentation into
4056 You can join this mailing list
4057 (@email{muse-el-internationalization@@gna.org}) using the subscription
4058 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
4059 mailing list is also available via Gmane with the identifier
4060 @samp{gmane.emacs.muse.internationalization}.
4065 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
4066 contributors are frequently around and willing to answer your
4067 questions. The @samp{#muse} channel is also available for
4068 Muse-specific help, and its current maintainer hangs out there.
4071 The maintainer of Emacs Muse, Michael Olson, may be contacted at
4072 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
4073 it is often better to use the muse-el-discuss mailing list.
4077 @node History, Contributors, Getting Help and Reporting Bugs, Top
4078 @comment node-name, next, previous, up
4079 @chapter History of This Document
4080 @cindex history, of Muse
4084 John Wiegley started Muse upon realizing that EmacsWiki had some serious
4085 limitations. Around February 2004, he started making "emacs-wiki version
4086 3.00 APLHA", which eventually became known as Muse.
4088 Most of those who frequent the emacs-wiki mailing list continued to use
4089 emacs-wiki, mainly because Planner hasn't been ported over to it.
4091 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
4092 John Wiegley's request.
4095 Michael Olson overhauled this document and added many new sections in
4096 preparation for the first release of Muse (3.01).
4100 @node Contributors, GNU Free Documentation License, History, Top
4101 @comment node-name, next, previous, up
4102 @chapter Contributors to This Documentation
4103 @cindex contributors
4105 The first draft of this document was taken from the emacs-wiki texinfo
4106 manual. Michael Olson adapted it for Muse and added most of its
4109 John Sullivan did a majority of the work on the emacs-wiki texinfo
4112 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
4113 emacs-wiki texinfo manual.
4116 @node GNU Free Documentation License, Concept Index, Contributors, Top
4117 @appendix GNU Free Documentation License
4118 @include doclicense.texi
4121 @node Concept Index, , GNU Free Documentation License, Top
4122 @comment node-name, next, previous, up