1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.03.
17 Copyright @copyright{} 2004, 2005, 2006,
18 2007 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU
25 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
26 license is included in the section entitled ``GNU Free Documentation
27 License'' in this manual.
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software. Copies published by the Free
31 Software Foundation raise funds for GNU development.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License. If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
38 All Emacs Lisp code contained in this document may be used, distributed,
39 and modified without restriction.
45 @subtitle an authoring and publishing environment
46 @subtitle for GNU Emacs and XEmacs
48 @c The following two commands
49 @c start the copyright page.
51 @vskip 0pt plus 1filll
55 @c So the toc is printed at the start
59 @node Top, Preface, (dir), (dir)
60 @comment node-name, next, previous, up
67 * Preface:: About the documentation.
68 * Introduction:: What is Muse?
69 * Obtaining Muse:: How to get Muse releases and development
71 * Installation:: Compiling and installing Muse.
72 * Getting Started:: Setting up Muse and editing files.
73 * Projects:: Creating and managing Muse projects.
74 * Keystroke Summary:: Keys used in Muse mode.
75 * Markup Rules:: Rules for using markup.
76 * Publishing Styles:: Publishing various types of documents.
77 * Extending Muse:: Making your own publishing styles.
78 * Getting Help and Reporting Bugs::
79 * History:: History of this document.
80 * Contributors:: Contributors to this documentation.
81 * GNU Free Documentation License:: The license for this documentation.
82 * Concept Index:: Search for terms.
85 --- The Detailed Node Listing ---
87 How to Get Muse Releases and Development Changes
89 * Releases:: Released versions of Muse.
90 * Development:: Latest unreleased development changes.
94 * Loading Muse:: How to load Muse.
95 * Using Muse Mode:: How to edit files in Muse.
96 * Publishing Files Overview:: Publishing a single file or project.
97 * File Extensions:: Using a different file extension.
99 Creating and Managing Muse Projects
101 * Single Project:: A single-project example.
102 * Multiple Projects:: A multiple-project example.
103 * Projects and Subdirectories:: Publishing subdirectories in projects.
104 * Options for Projects:: Listing of available options for projects.
106 Rules for Using Markup
108 * Paragraphs:: Paragraphs: centering and quoting.
109 * Headings:: Levels of headings.
110 * Directives:: Directives at the beginning of a
112 * Emphasizing Text:: Bold, italicized, and underlined text.
113 * Footnotes:: Making notes to be shown at the end.
114 * Verse:: Indicating poetic stanzas.
115 * Lists:: Lists of items.
116 * Tables:: Generation of data tables.
117 * Explicit Links:: Hyperlinks and email addresses with
119 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
121 * Images:: Publishing and displaying images.
122 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
123 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
125 * Comments:: Lines to omit from published output.
126 * Tag Summary:: Tags that Muse recognizes.
128 Publishing Various Types of Documents
130 * Blosxom:: Integrating Muse and pyblosxom.cgi.
131 * Book:: Publishing entries into a compilation.
132 * ConTeXt:: Publishing ConTeXt documents.
133 * DocBook:: Publishing in DocBook XML form.
134 * HTML:: Publishing in HTML or XHTML form.
135 * Journal:: Keeping a journal or blog.
136 * LaTeX:: Publishing LaTeX documents.
137 * Poem:: Publish a poem to LaTex or PDF.
138 * Texinfo:: Publish entries to Texinfo format or PDF.
139 * XML:: Publish entries to XML.
141 Integrating Muse and pyblosxom.cgi
143 * Blosxom Requirements:: Other tools needed for the Blosxom style.
144 * Blosxom Entries:: Format of a Blosxom entry and automation.
145 * Blosxom Options:: Blosxom styles and options provided.
147 Making your own publishing styles
149 * Common Elements:: Common functionality shared by styles.
150 * Deriving Styles:: Deriving a new style from an existing
153 Common functionality shared by styles
155 * Markup Functions:: Specifying functions to mark up text.
156 * Markup Regexps:: Markup rules for publishing.
157 * Markup Strings:: Strings specific to a publishing style.
158 * Markup Tags:: Tag specifications for special markup.
159 * Style Elements:: Parameters used for defining styles.
164 @node Preface, Introduction, Top, Top
165 @comment node-name, next, previous, up
166 @chapter About the documentation
168 This document describes Muse, which was written by John Wiegley and is
169 now maintained by Michael Olson. Several versions of this manual are
173 @item PDF: http://mwolson.org/static/doc/muse.pdf
174 @item HTML (single file): http://mwolson.org/static/doc/muse.html
175 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
178 @node Introduction, Obtaining Muse, Preface, Top
179 @comment node-name, next, previous, up
180 @chapter What is Muse?
182 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
183 and publishing environment for Emacs. It simplifies the process of
184 writing documents and publishing them to various output formats.
186 Muse consists of two main parts: an enhanced text-mode for authoring
187 documents and navigating within Muse projects, and a set of publishing
188 styles for generating different kinds of output.
190 What makes Muse distinct from other text-publishing systems is a modular
191 environment, with a rather simple core, in which "styles" are derived
192 from to create new styles. Much of Muse's overall functionality is
193 optional. For example, you can use the publisher without the
194 major-mode, or the mode without doing any publishing; or if you don't
195 load the Texinfo or LaTeX modules, those styles won't be available.
197 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
198 code has been restructured and rewritten, especially its publishing
199 functions. The focus in this revision is on the authoring and
200 publishing aspects, and the "wikiness" has been removed as a default
201 behavior (available in the optional @file{muse-wiki} module). CamelCase
202 words are no longer special by default.
204 One of the principal aims in the development of Muse is to make it very
205 easy to produce good-looking, standards-compliant documents.
207 @node Obtaining Muse, Installation, Introduction, Top
208 @comment node-name, next, previous, up
209 @chapter How to Get Muse Releases and Development Changes
212 * Releases:: Released versions of Muse.
213 * Development:: Latest unreleased development changes.
216 @node Releases, Development, Obtaining Muse, Obtaining Muse
217 @comment node-name, next, previous, up
218 @section Released versions of Muse
220 Choose to install a release if you want to minimize risk.
222 Errors are corrected in development first. User-visible changes will be
223 announced on the @email{muse-el-discuss@@gna.org} mailing list.
224 @xref{Getting Help and Reporting Bugs}.
226 @cindex releases, Debian package
227 @cindex Debian package for Muse
228 Debian users can get Muse via apt-get. The @file{muse-el} package is
229 available both at Michael Olson's APT repository and the official Debian
230 repository. To make use of the former, add the following line to your
231 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
234 deb http://mwolson.org/debian/ ./
237 @cindex releases, Ubuntu package
238 @cindex Ubuntu package for Muse
239 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
240 is available both at Michael Olson's APT repository and the official
241 Ubuntu repository. To make use of the former, add the following line to
242 your @file{/etc/apt/sources.list} file and run @code{apt-get install
246 deb http://mwolson.org/ubuntu/ ./
249 The reason for making separate Debian and Ubuntu packages is that this
250 manual is under the GFDL, and Debian will not allow it to be distributed
251 in its main repository. Ubuntu, on the other hand, permits this manual
252 to be included with the @file{muse-el} package.
254 @cindex releases, from source
255 Alternatively, you can download the latest release from
256 @uref{http://download.gna.org/muse-el/} .
258 @node Development, , Releases, Obtaining Muse
259 @comment node-name, next, previous, up
260 @section Latest unreleased development changes
263 Choose the development version if you want to live on the bleeding edge
264 of Muse development or try out new features before release.
266 @cindex git version control system, using
267 The git version control system allows you to keep up-to-date with the
268 latest changes to the development version of Muse. It also allows you
269 to contribute changes (via commits, if you are have developer access to
270 the repository, or via patches, otherwise). If you would like to
271 contribute to Muse development, it is highly recommended that you use
274 If you are new to git, you might find this tutorial helpful:
275 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
277 Downloading the Muse module with git and staying up-to-date involves
284 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
285 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
286 @item Other operating systems: download, compile, and install the source
287 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
288 package for your operating system.
291 @item Download the Muse development branch.
293 If you have developer access to Muse, do:
296 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
302 git clone git://repo.or.cz/muse-el.git muse
305 @item List upstream changes that are missing from your local copy.
306 Do this whenever you want to see whether new changes have been committed
307 to Muse. If you wish, you may skip this step and proceed directly to
311 # Change to the source directory you are interested in.
314 # Fetch new changes from the repository, but don't apply them yet
317 # Display log messages for the new changes
321 ``origin'' is git's name for the location where you originally got Muse
322 from. You can change this location at any time by editing the
323 @file{.git/config} file in the directory where the Muse source was
326 @cindex updating Muse with git
327 @item Update to the latest version by pulling in any missing changes.
334 git will show how many files changed, and will provide a visual display
335 for how many lines were changed in each file.
339 There are other ways to interact with the Muse repository.
342 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
343 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
344 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
347 The latest development snapshot can lag behind the git repo by as much
348 as 20 minutes, but never more than that.
350 @subheading Becoming a Muse developer
351 @cindex developer, becoming
353 If you want commit access to the shared Muse repository, then register
354 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
355 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
356 best to send some patches to the @email{muse-el-discuss@@gna.org}
357 mailing list first, so that he knows that you know what you are doing.
358 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
361 You must also be willing to sign a copyright assignment for your changes
362 to Muse, since Muse is a GNU project. The current maintainer will
363 assist you in this process if you contact him.
365 @node Installation, Getting Started, Obtaining Muse, Top
366 @comment node-name, next, previous, up
367 @chapter Compiling and Installing Muse
369 Muse may be compiled and installed on your machine.
371 @subheading Compilation
372 @cindex compiling Muse
374 This is an optional step, since Emacs Lisp source code does not
375 necessarily have to be byte-compiled. Byte-compilation may yield a very
376 slight speed increase.
378 A working copy of Emacs or XEmacs is needed in order to compile Emacs
379 Muse. By default, the program that is installed with the name
380 @command{emacs} will be used.
382 If you want to use the @command{xemacs} binary to perform the
383 compilation, you must copy @file{Makefile.defs.default} to
384 @file{Makefile.defs} in the top-level directory, and then edit
385 @file{Makefile.defs} as follows. You can put either a full path to an
386 Emacs or XEmacs binary or just the command name, as long as it is in the
387 @env{PATH}. Depending on your setup, changes to the @option{PREFIX},
388 @option{ELISPDIR}, and/or @option{INFODIR} variables may also need to be
393 SITEFLAG = -no-site-file
394 # Edit the section as necessary
395 install_info = install-info --section "XEmacs 21.4" $(1).info \
399 Running @code{make} in the top-level directory should compile the Muse
400 source files in the @file{lisp} directory, and generate an autoloads
401 file in @file{lisp/muse-autoloads.el}.
403 @subheading Installation
404 @cindex installing Muse
406 Muse may be installed into your file hierarchy by doing the following.
408 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
409 top-level directory, if you haven't done so already. Then edit the
410 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
411 want the source and compiled Muse files to be installed and
412 @env{INFODIR} indicates where to put the Muse manual. As mentioned
413 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
414 in the Compilation section if you are using XEmacs.
416 If you are installing Muse on a Debian or Ubuntu system, you might want
417 to change the value of @env{INSTALLINFO} as specified in
418 @file{Makefile.defs}.
420 If you wish to install Muse to different locations than the defaults
421 specify, edit @file{Makefile.defs} accordingly.
423 Run @code{make} as a normal user, if you haven't done so already.
425 Run @code{make install} as the root user if you have chosen installation
426 locations that require root permissions.
429 @cindex ELPA package for Muse
431 For those used to installing software packages, there will be a
432 @code{muse} package available in the Emacs Lisp Package Archive
433 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
434 will be compiled and installed automatically in a user-specific
435 location. For more information on ELPA, see
436 @uref{http://tromey.com/elpa/}.
438 @node Getting Started, Projects, Installation, Top
439 @comment node-name, next, previous, up
440 @chapter Getting Started
444 * Loading Muse:: How to load Muse.
445 * Using Muse Mode:: How to edit files in Muse.
446 * Publishing Files Overview:: Publishing a single file or project.
447 * File Extensions:: Using a different file extension.
450 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
451 @comment node-name, next, previous, up
452 @section How to Load Muse
453 @cindex settings, init file
455 To use Muse, add the directory containing its files to your
456 @code{load-path} variable, in your @file{.emacs} file. Then, load in
457 the authoring mode, and the styles you wish to publish to. An example
461 (add-to-list 'load-path "<path to Muse>")
463 (require 'muse-mode) ; load authoring mode
465 (require 'muse-html) ; load publishing styles I use
466 (require 'muse-latex)
467 (require 'muse-texinfo)
468 (require 'muse-docbook)
470 (require 'muse-project) ; publish files in projects
473 An easy way of seeing which settings are available and changing settings
474 is to use the Muse customization interface. To do this, type
475 @kbd{M-x customize-group muse RET}. Each of the options has its own
476 documentation. Options are grouped logically according to what effect
479 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
480 @comment node-name, next, previous, up
481 @section How to Edit Files in Muse
482 @cindex editing Muse files
484 Muse Mode should automatically be activated when you visit a file with a
485 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
486 available in the @file{examples} directory of the Muse distribution.
487 You can tell that Muse Mose has been activated by checking for the text
488 ``Muse'' in your mode line. If Muse Mode has not been activated, you
489 may activate it by type @kbd{M-x muse-mode RET}.
491 You will notice that Muse files are highlighted very simply. Links are
492 colored blue, headings are large and bold text, and @verb{|<example>|}
493 tags are colored in grey.
495 There are several different ways to edit things like links, which hide
496 the underlying Muse markup. One way is to toggle font-locking off by
497 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
498 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
499 on. Another way is just to move into the text and edit it. Markup can
500 also be removed by normal deletion methods, though some side effects
501 might require a second deletion.
503 For the particular case of editing links, it is easiest to move to the
504 link and do @kbd{C-c C-e}, which is also @kbd{M-x
505 muse-edit-link-at-point}. This prompts you for the link and its
506 description, using the previous contents of the link as initial values.
507 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
508 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
509 followed by hitting @kbd{RET} on them.
511 If you want to add a new list item, this may by accomplished by hitting
512 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
513 dash is the Muse markup that indicates a list item. It is also possible
514 to created ``nested'' lists with this command, by adjusting the number
515 of spaces in front of the dashes. If you have lists with long lines,
516 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
519 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
520 @comment node-name, next, previous, up
521 @section Publishing a Single File or Project
522 @cindex editing Muse files
524 The command @kbd{M-x muse-project-publish-this-file} will publish the
525 current document to any available publishing style (a publishing style
526 is an output format, like HTML or Docbook), placing the output in the
527 current directory. If you are in Muse Mode, this command will be bound
528 to @kbd{C-c C-t}. If the file has been published recently, and its
529 contents have not changed, running @kbd{C-c C-t} again will not publish
530 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
532 If you have set up projects and are visiting a file that is part of a
533 project, then @kbd{C-c C-t} will restrict the output formats to those
534 which are used by the project, and will automatically publish to the
535 output directory defined by the project. If you want to publish to a
536 different directory or use a different format, then use @kbd{C-c M-C-t},
537 which is also @kbd{M-x muse-publish-this-file}.
539 If the currently opened file is part of a defined project in
540 @code{muse-project-alist}, it (and the rest of the changed files in a
541 project) may be published using @kbd{C-c C-p}.
543 @node File Extensions, , Publishing Files Overview, Getting Started
544 @comment node-name, next, previous, up
545 @section Using a Different File Extension
546 @cindex file extension, specifying
548 By default, Muse expects all project files to have the file extension
549 @file{.muse}. Files without this extension will not be associated with
550 Muse mode and will not be considered part of any project, even if they
551 are within a project directory.
553 If you don't want to use @file{.muse}, you can customize the extension
554 by setting the value of @code{muse-file-extension}.
556 If you don't want to use any extension at all, and want Muse to
557 autodetect project files based on their location, then add the following
558 to your Muse settings file.
561 (setq muse-file-extension nil
565 Note that if you chose to have @code{muse-file-extension} set to
566 @code{nil}, you may have trouble if your @file{.emacs} file or other
567 init scripts attempt to visit a Muse file. (A very common example of
568 this is if you use Planner with Muse and run @code{(plan)} from your
569 @file{.emacs}.) If you wish to visit Muse files from your
570 @file{.emacs}, be sure to also add the following additional code before
571 any such visits happen:
574 (add-hook 'find-file-hooks 'muse-mode-maybe)
578 @node Projects, Keystroke Summary, Getting Started, Top
579 @comment node-name, next, previous, up
580 @chapter Creating and Managing Muse Projects
583 Often you will want to publish all the files within a directory to a
584 particular set of output styles automatically. To support, Muse
585 allows for the creation of "projects".
588 * Single Project:: A single-project example.
589 * Multiple Projects:: A multiple-project example.
590 * Projects and Subdirectories:: Publishing subdirectories in projects.
591 * Options for Projects:: Listing of available options for projects.
594 @node Single Project, Multiple Projects, Projects, Projects
595 @comment node-name, next, previous, up
596 @section A Single-Project Example
597 @cindex projects, single
599 Here is a sample project, which may be defined in your @file{.emacs}
603 (setq muse-project-alist
604 '(("Website" ("~/Pages" :default "index")
605 (:base "html" :path "~/public_html")
606 (:base "pdf" :path "~/public_html/pdf"))))
609 The above defines a project named "website", whose files are located
610 in the directory @file{~/Pages}. The default page to visit is
611 @file{index}. When this project is published, each page will be
612 output as HTML to the directory @file{~/public_html}, and as PDF to
613 the directory @file{~/public_html/pdf}. Within any project page, you
614 may create a link to other pages using the syntax @samp{[[pagename]]}.
616 If you would like to include only some files from a directory in a Muse
617 project, you may use a regexp in place of @file{~/Pages} in the example.
619 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
620 @comment node-name, next, previous, up
621 @section A Multiple-Project Example
622 @cindex projects, multiple
624 It is possible to specify multiple projects. Here is an example of
625 three projects: a generic website, a projects area, and a day-planner
626 (the day-planner part requires Planner Mode---see
627 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
630 (setq muse-project-alist
631 '(("Website" ("~/Pages" :default "index")
632 (:base "html" :path "~/public_html"))
633 (("Projects" ("~/Projects" :default "index")
635 :path "~/public_html/projects"
636 :exclude "/TopSecret")
638 :path "~/public_html/projects/pdf"
639 :exclude "/TopSecret")))
642 :major-mode planner-mode
643 :visit-link planner-visit-link)
644 (:base "planner-xhtml"
645 :path "~/public_html/plans"))))
648 The @option{:major-mode} attribute specifies which major to use when
649 visiting files in this directory.
651 The @option{:visit-link} attribute specifies the function to call when
654 The @option{:exclude} attribute has a regexp that matches files to never
657 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
658 @comment node-name, next, previous, up
659 @section Publishing Subdirectories in Projects
660 @cindex projects, subdirectories
662 If you want to publish a directory and all of its subdirectories, Muse
663 provides two convenience functions that together generate the proper
664 rules for you. Note that we use the backtick to begin this
665 muse-project-alist definition, rather than a single quote.
668 (setq muse-project-alist
669 `(("Website" ("~/Pages" :default "index")
670 (:base "html" :path "~/public_html"))
671 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
673 ;; Publish this directory and its subdirectories. Arguments
674 ;; are as follows. The above `muse-project-alist-dirs' part
676 ;; 1. Source directory
677 ;; 2. Output directory
678 ;; 3. Publishing style
679 ;; remainder: Other things to put in every generated style
680 ,@@(muse-project-alist-styles "~/Blog"
685 The @code{muse-project-alist-dirs} function takes a directory and
686 returns it and all of its subdirectories in a list.
688 The @code{muse-project-alist-styles} function is explained by the
691 The ``blosxom'' text is the name of another publishing style, much like
692 ``html''. @xref{Blosxom}, for further information about it. You can
693 use any publishing style you like for the third argument to
694 @code{muse-project-alist-styles}.
696 @node Options for Projects, , Projects and Subdirectories, Projects
697 @comment node-name, next, previous, up
698 @section Listing of Available Options for Projects
699 @cindex projects, options
700 @cindex muse-project-alist, reference
702 This is a listing of all of the various options (or, more accurately:
703 attributes) that may be specified in @code{muse-project-alist}.
705 Each muse-project-alist entry looks like this:
708 (PROJECT-NAME (SOURCES)
712 We refer to these names below.
714 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
715 The first value is a keyword, like @option{:default}. The second part
716 is the value associated with that keyword, such as the text ``index''.
717 If you are familiar with Emacs Lisp property lists, the concept is
718 similar to that, except that in the SOURCES section, single directories
719 can be interspersed with two-value attributes.
721 @subheading Project Name
723 This is a string that indicates the name of the project. It is
724 primarily used for publishing interwiki links with the
725 @file{muse-wiki.el} module.
729 This part of a muse-project-alist entry consists of two-value
730 attributes, and also directory names. If you are publishing a book, the
731 order of directories and attributes is significant.
733 The minimal content for the sources section is a list of directories.
738 Indicates a new chapter of a book. The text of the title of the chapter
739 comes immediately after this keyword.
742 Indicates the end of a book. Directories listed after this one are
743 ignored when publishing a book. The value ``t'' (without quotes) should
744 come immediately after this keyword.
747 A function to call while publishing a book. This is useful for doing
748 something just after a particular chapter.
751 Indicates the beginning of a new part of the book. The text of the
752 title should come immediately after this keyword.
755 Indicate a particular publishing style to use for this part of the book.
756 If this is specified, it should come just after a @option{:part}
760 The default page to visit when browsing a project. Also, if you are
761 using the @file{muse-wiki.el} module, publishing a link to just a
762 project's name will cause it to link to this default file.
765 This specifies a list of pages which should be published every time a
766 project is published (by using @kbd{C-c C-p}, for example), regardless
767 of whether their contents have changed. This is useful for updating
768 Index pages, pages that use the @verb{|<include>|} tag, and other pages
769 that have dynamically-generated content.
772 This specifies the major mode to use when visiting files in this
773 project. The default is @code{muse-mode}.
776 This indicates that while publishing a book, do not automatically create
777 chapters. Values which may follow this are nil (the default, which
778 means that we automatically create chapters), or non-nil, which means
779 that we manually specify chapters with the @option{:book-chapter}
782 @item :publish-project
783 Indicates which function we should call when publishing a project.
786 This specifies a list of variables and values to set when publishing a
787 project. The list should be a property list, which is in the form:
790 (VAR1 VALUE1 VAR2 VALUE2 ...)
794 Specifies the function to call when visiting a link. The default is
795 @code{muse-visit-link-default}. The arguments for that function should
796 be (1) the link and (2) whether to visit the link in a new window.
802 This part of a muse-project-alist entry is composed of lists of
803 attributes. Each list is called an ``output style''.
805 The minimal content for an output style is a @option{:base} attribute
806 and a @option{:path} attribute.
811 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
814 An external URL which can be used to access published files. This is
815 mainly used by the @file{muse-wiki} module when publishing links between
816 two separate projects, if the projects are served on different domains.
818 It is also used by the @file{muse-journal} module to create the RSS or
822 Exclude items matching a regexp from being published. The regexp should
823 usually begin with "/".
826 Only include items matching a regexp when publishing. The regexp should
827 usually begin with "/".
830 The directory in which to store published files.
833 A file containing the timestamps (that is, time of creation) for files
834 in this project. It might eventually used by the @file{muse-blosxom}
835 module, but this option is not currently in use by any Muse code.
840 @node Keystroke Summary, Markup Rules, Projects, Top
841 @comment node-name, next, previous, up
842 @chapter Keys Used in Muse Mode
845 This is a summary of keystrokes available in every Muse buffer.
849 @item C-c C-a (`muse-index')
850 Display an index of all known Muse pages.
852 @item C-c C-b (`muse-find-backlinks')
853 Find all pages that link to this page.
855 @item C-c C-e (`muse-edit-link-at-point')
858 @item C-c C-f (`muse-project-find-file')
859 Open another Muse page. Prompt for the name.
861 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
862 Insert a link to a file interactively.
864 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
865 Insert a tag interactively.
867 @item C-c C-i u, C-c TAB u (`muse-insert-url')
868 Insert a URL interactively.
870 @item C-c C-l (`font-lock-mode')
871 Toggle font lock / highlighting for the current buffer.
873 @item C-c C-p (`muse-project-publish')
874 Publish any Muse pages that have changed.
876 @item C-c C-s (`muse-search')
877 Find text in all files of the current project.
879 @item C-c C-t (`muse-project-publish-this-file')
880 Publish the currently-visited file. Prompt for the style if the current
881 file can be published using more than one style.
883 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
884 Publish the currently-visited file. Prompt for both the style and
887 @item C-c C-v (`muse-browse-result')
888 Show the published result of this page.
890 @item C-c = (`muse-what-changed')
891 Diff this page against the last backup version.
894 Move to the next Wiki reference.
897 Move to the previous Wiki reference.
900 Complete the name of a page from the current project at point.
903 Insert a new list item at point, indenting properly.
906 Decrease the indentation of the list item at point.
909 Increase the indentation of the list item at point.
911 @item M-x muse-colors-toggle-inline-images RET
912 Toggle display of inlined images on/off.
917 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
918 @comment node-name, next, previous, up
919 @chapter Rules for Using Markup
922 A Muse document uses special, contextual markup rules to determine how
923 to format the output result. For example, if a paragraph is indented,
924 Muse assumes it should be quoted.
926 There are not too many markup rules, and all of them strive to be as
927 simple as possible so that you can focus on document creation, rather
931 * Paragraphs:: Paragraphs: centering and quoting.
932 * Headings:: Levels of headings.
933 * Directives:: Directives at the beginning of a
935 * Emphasizing Text:: Bold, italicized, and underlined text.
936 * Footnotes:: Making notes to be shown at the end.
937 * Verse:: Indicating poetic stanzas.
938 * Lists:: Lists of items.
939 * Tables:: Generation of data tables.
940 * Explicit Links:: Hyperlinks and email addresses with
942 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
944 * Images:: Publishing and displaying images.
945 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
946 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
948 * Comments:: Lines to omit from published output.
949 * Tag Summary:: Tags that Muse recognizes.
952 @node Paragraphs, Headings, Markup Rules, Markup Rules
953 @comment node-name, next, previous, up
954 @section Paragraphs: centering and quoting
957 Paragraphs in Muse must be separated by a blank line.
959 @cindex paragraphs, centered
960 @subheading Centered paragraphs and quotations
962 A line that begins with six or more columns of whitespace (either tabs
963 or spaces) indicates a centered paragraph. Alternatively, you can use
964 the @verb{|<center>|} tag to surround regions that are to be published as
967 @cindex paragraphs, quoted
969 But if a line begins with whitespace, though less than six columns, it
970 indicates a quoted paragraph. Alternatively, you can use the
971 @verb{|<quote>|} tag to surround regions that are to be published as
975 @cindex monospace, rendering blocks
976 @cindex HTML, rendering blocks in monospace
977 @subheading Literal paragraphs
979 The @verb{|<example>|} tag is used for examples, where whitespace should
980 be preserved, the text rendered in monospace, and any characters special
981 to the output style escaped.
984 @cindex HTML, inserting a raw block
985 There is also the @verb{|<literal>|} tag, which causes a marked block to
986 be entirely left alone. This can be used for inserting a hand-coded
987 HTML blocks into HTML output, for example.
989 If you want some text to only be inserted when publishing to a
990 particular publishing style, use the @option{style} attribute for the
991 @verb{|<literal>|} tag. An example follows.
994 <literal style="latex">
995 A LaTeX-based style was used in the publishing of this document.
999 This will leave the region alone if the current publishing style is
1000 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
1001 otherwise. It is also possible to leave the text alone only for one
1002 particular style, rather than its derivations, by adding
1003 @code{exact="t"} to the tag.
1005 @node Headings, Directives, Paragraphs, Markup Rules
1006 @comment node-name, next, previous, up
1007 @section Levels of headings
1010 A heading becomes a chapter or section in printed output -- depending on
1011 the style. To indicate a heading, start a new paragraph with one or
1012 more asterices, followed by a space and the heading title. Then begin
1013 another paragraph to enter the text for that section.
1015 All levels of headings will be published. Most publishing styles only
1016 distinguish the between the first 4 levels, however.
1028 @node Directives, Emphasizing Text, Headings, Markup Rules
1029 @comment node-name, next, previous, up
1030 @section Directives at the beginning of a document
1033 Directives are lines beginning with the @samp{#} character that come
1034 before any paragraphs or sections in the document. Directives are of
1035 the form ``#directive content of directive''. You can use any
1036 combination of uppercase and lowercase letters for directives, even if
1037 the directive is not in the list below.
1039 The @code{muse-publishing-directive} function may be used in header and
1040 footer text to access directives. For example, to access the
1041 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
1043 The following is a list of directives that Muse uses.
1048 The author of this document.
1050 If this is not specified, Muse will attempt to figure it out from the
1051 @code{user-full-name} variable.
1055 The date that the document was last modified.
1057 This is used by publishing styles that are able to embed the date
1062 A short description of this document.
1064 This is used by the @code{journal} publishing style to embed information
1065 inside of an RSS/RDF feed.
1069 The title of this document.
1071 If this is not specified, the name of the file is used.
1075 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1076 @comment node-name, next, previous, up
1077 @section Bold, italicized, and underlined text
1078 @cindex emphasizing text
1079 @cindex underlining text
1080 @cindex italicizing text
1081 @cindex verbatim text
1082 @cindex monospace, rendering words
1084 To emphasize text, surround it with certain specially recognized
1090 ***very strong emphasis***
1092 =verbatim and monospace=
1096 While editing a Muse document in Muse mode, these forms of emphasis will
1097 be highlighted in a WYSIWYG manner. Each of these forms may span
1100 Verbatim text will be colored as gray by default. To change this,
1101 customize @code{muse-verbatim-face}.
1103 You can also use the @verb{|<code>|} tag to indicate verbatim and
1104 monospace text. This is handy for regions that have an ``='' in them.
1106 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1107 @comment node-name, next, previous, up
1108 @section Making notes to be shown at the end
1111 A footnote reference is simply a number in square brackets. To define
1112 the footnote, place this definition at the bottom of your file.
1113 @samp{footnote-mode} can be used to greatly facilitate the creation of
1114 these kinds of footnotes.
1116 Footnotes are defined by the same number in brackets occurring at the
1117 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1118 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1119 the point of insertion.
1121 @node Verse, Lists, Footnotes, Markup Rules
1122 @comment node-name, next, previous, up
1123 @section Indicating poetic stanzas
1127 Poetry requires that whitespace be preserved, but without resorting to
1128 monospace. To indicate this, use the following markup, reminiscent of
1132 > A line of Emacs verse;
1133 > forgive its being so terse.
1136 You can also use the @verb{|<verse>|} tag, if you prefer.
1140 A line of Emacs verse;
1141 forgive its being so terse.
1145 @cindex verses, multiple stanzas
1146 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1151 A line of Emacs verse;
1152 forgive its being so terse.
1154 In terms of terse verse,
1159 @node Lists, Tables, Verse, Markup Rules
1160 @comment node-name, next, previous, up
1161 @section Lists of items
1164 Lists are given using special characters at the beginning of a line.
1165 Whitespace must occur before bullets or numbered items, to distinguish
1166 from the possibility of those characters occurring in a real sentence.
1168 @cindex lists, bullets
1169 These are rendered as a bullet list.
1178 @cindex lists, enumerated
1179 An enumerated list follows.
1188 @cindex lists, definitions
1189 Here is a definition list.
1193 This is a first definition
1194 And it has two lines;
1195 no, make that three.
1197 Term2 :: This is a second definition
1200 @subheading Nested lists
1202 @cindex lists, nested
1203 It is possible to nest lists of the same or different kinds. The
1204 ``level'' of the list is determined by the amount of initial whitespace.
1209 - Level 1, bullet item one
1210 1. Level 2, enum item one
1211 2. Level 2, enum item two
1212 - Level 1, bullet item two
1213 1. Level 2, enum item three
1214 2. Level 2, enum item four
1218 @subheading Breaking list items
1220 @cindex lists, breaking lines
1221 If you want to break up a line within any list type, just put one blank
1222 line between the end of the previous line and the beginning of the next
1223 line, using the same amount of initial indentation.
1226 - bullet item 1, line 1
1228 bullet item 1, line 2
1234 - bullet item 2, line 1
1236 bullet item 2, line 2
1239 @node Tables, Explicit Links, Lists, Markup Rules
1240 @comment node-name, next, previous, up
1241 @section Generation of data tables
1244 @cindex tables, simple
1245 Only very simple tables are supported. The syntax is as follows.
1248 Double bars || Separate header fields
1250 Single bars | Separate body fields
1251 Here are more | body fields
1253 Triple bars ||| Separate footer fields
1256 Some publishing styles require header fields to come first, then footer
1257 fields, and then the body fields. You can use any order for these
1258 sections that you like, and Muse will re-order them for you at
1261 If you wish to disable table generation for one Muse file, add the
1262 directive @samp{#disable-tables t} to the top of the file.
1264 @subheading Other table formats
1266 @cindex tables, orgtbl-mode style
1267 It is possible to publish very basic Orgtbl-mode style tables.
1270 | org | style | table |
1271 |------+-------+-------|
1275 |------+-------+-------|
1279 If you are used to the way that Org Mode publishes these tables, then
1280 customize `muse-html-table-attributes' to the following, in order to get
1281 a similar kind of output.
1284 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1287 @cindex tables, table.el style
1288 @file{table.el} style tables are also supported, as long as
1289 @file{table.el} itself supports outputting tables for a particular
1290 publishing style. At the time of this writing, the ``html'', ``latex'',
1291 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1292 from these styles will also work.
1304 @node Explicit Links, Implicit Links, Tables, Markup Rules
1305 @comment node-name, next, previous, up
1306 @section Hyperlinks and email addresses with descriptions
1307 @cindex links, explicit
1309 A hyperlink can reference a URL, or another page within a Muse
1310 project. In addition, descriptive text can be specified, which should
1311 be displayed rather than the link text in output styles that supports
1312 link descriptions. The syntax is as follows.
1315 [[link target][link description]]
1316 [[link target without description]]
1319 Thus, the current maintainer's homepage for Muse can be found
1320 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1321 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1323 @node Implicit Links, Images, Explicit Links, Markup Rules
1324 @comment node-name, next, previous, up
1325 @section Bare URLs, WikiNames, and InterWiki links
1326 @cindex links, implicit
1330 @cindex Email addresses
1332 A URL or email address encountered in the input text is published as a
1333 hyperlink. These kind of links are called @dfn{implicit links} because
1334 they are not separated from the rest of the Muse document in any way.
1336 Some characters in URLs will prevent Muse from recognizing them as
1337 implicit links. If you want to link to a URL containing spaces or any of
1338 the characters ``][,"'`()<>^'', you will have to make the link
1339 explicit. The punctuation characters ``.,;:'' are also not recognized as
1340 part of a URL when they appear at its end. For information on how to
1341 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1342 addresses with descriptions}.
1345 If the @command{muse-wiki} module is loaded, another form of implicit
1346 link will be made available. WikiNames, which are typed in CamelCase,
1347 are highlighted and published as links, provided that the file they
1350 Customization of WikiName recognition may be accomplished by editing the
1351 @code{muse-wiki-wikiword-regexp} option and subsequently running
1352 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1353 If you use the Customize interface, the latter will be done
1356 @cindex InterWiki links
1357 @cindex inter-project links
1358 The @command{muse-wiki} module also allows for InterWiki links. These
1359 are similar to WikiWords, but they specify both the project and page of
1360 a file. The names of your project entries in @code{muse-project-alist}
1361 will be used as InterWiki names by default. Several examples follow.
1364 Blog::DocumentingMuse
1369 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1370 the project name, and @samp{DocumentingMuse} is the page name. In the
1371 second example, @samp{#} is the interwiki delimiter. If the name of a
1372 project occurs by itself in text, like the third case, it will be
1373 colorized and published as a link to the default page of the given
1376 Customization of interwiki links may be accomplished by editing the
1377 @code{muse-wiki-interwiki-alist} option.
1379 It is also possible to link to an anchor in an interwiki document. This
1380 is called a ``three-part link''. Examples of this follow.
1383 Blog::DocumentingMuse#anchor1
1384 Projects#EmacsMuse#anchor2
1387 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1388 @comment node-name, next, previous, up
1389 @section Publishing and displaying images
1391 @cindex links, with images
1392 @subheading Image links
1394 Links to images may be used in either the target or the description, or
1395 both. Thus, the following code will publish as a clickable image that
1396 points to @url{http://mwolson.org/}.
1399 [[http://mwolson.org/][/static/logos/site-logo.png]]
1402 Normally, images in the link part will be inlined.
1404 If you want these images to be published as links instead, place the
1405 text ``URL:'' immediately in front of the link text. An example
1409 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1412 @cindex images, displaying
1413 @cindex images, local
1414 @subheading Displaying images in Muse mode
1415 If a link to a locally-available image is encountered in the link
1416 description, Muse mode will attempt to display it if your version of
1419 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1420 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1422 The method for finding images may be altered by customizing the
1423 @code{muse-colors-inline-image-method} option. One useful value for
1424 this option is @code{muse-colors-use-publishing-directory}, which tells
1425 Muse mode to look in the directory where the current file will be
1426 published. The default is to look in the current directory. Relative
1427 paths like @samp{../pics/} should work for either setting.
1429 Eventually, it is hoped that Muse will be able to copy images from the a
1430 ``source'' directory to a publishing directory by customizing
1431 @code{muse-project-alist}, but this has not been implemented yet.
1433 @cindex images, without descriptions
1434 @cindex images, inlined
1435 @subheading Publishing simple images
1436 The following example will display correctly and publish correctly if a
1437 @acronym{PNG} file called @file{TestLogo.png} exists in the
1438 @file{../pics/} directory. If text is on the same line as the picture,
1439 it will remain so in the output.
1445 @cindex images, captions
1446 @subheading Publishing images with captions
1447 If you want to add a caption to an image, use the following syntax.
1448 This will center the image (if the output format supports it) and add a
1449 centered caption below the picture. Formats that do not support
1450 centering the image will instead leave it against the left margin.
1453 [[../pics/mycat.png][My cat Dexter]]
1456 Images with captions may only occur in their own paragraphs, with no
1457 text on the same line. Otherwise, the published output will not be
1458 syntactically correct.
1460 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1461 @comment node-name, next, previous, up
1462 @section Inserting a horizontal line or anchor
1464 @cindex horizontal rules
1466 @subheading Horizontal Rules
1468 Four or more dashes indicate a horizontal rule. Be sure to put blank
1469 lines around it, or it will be considered part of the proceeding or
1470 following paragraph!
1473 @cindex links, with target on same page
1476 If you begin a line with "#anchor" -- where "anchor" can be any word
1477 that doesn't contain whitespace -- it defines an anchor at that point
1478 into the document. This point can be referenced using "page#anchor" as
1479 the target in a Muse link.
1481 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
1482 @comment node-name, next, previous, up
1483 @section Evaluating Emacs Lisp code in documents for extensibility
1484 @cindex lisp, embedded
1486 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1487 which is the only Muse tag supported in a style's header and footer
1488 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1489 text you wish. The inserted output will get marked up, if the
1490 @verb{|<lisp>|} tag appears within the main text of the document.
1493 <lisp>(concat "This form gets " "inserted")</lisp>
1496 @cindex lisp, and insert command
1497 Note that you should not use the @code{insert} command within a set of
1498 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1499 tags will be automatically inserted into the document.
1501 It is also possible to treat the output as if it were surrounded by the
1502 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1503 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1504 attribute of the @verb{|<lisp>|} tag.
1507 <lisp markup="example">
1508 (concat "Insert" " me")
1512 Other languages also have tags that cause source code to be evaluated.
1513 @xref{Tag Summary}, for details.
1515 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
1516 @comment node-name, next, previous, up
1517 @section Lines to omit from published output
1519 @cindex publishing, omitting lines
1521 Use the following syntax to indicate a comment. Comments will not be
1525 ; Comment text goes here.
1528 That is, only a semi-colon at the beginning of a line, followed by a
1529 literal space, will cause that line to be treated as a comment.
1531 You can alternatively surround the region with the @verb{|<comment>|}
1534 If you wish the comment to be published, but just commented out using
1535 the comment syntax of the output format, then set
1536 @option{muse-publish-comments-p} to non-nil.
1538 @node Tag Summary, , Comments, Markup Rules
1539 @comment node-name, next, previous, up
1540 @section Tags that Muse recognizes
1542 @cindex inserting files at publish time
1543 @cindex publishing, including markup in headers and footers
1544 @cindex publishing, inserting files
1546 Muse has several built-in tags that may prove useful during publishing.
1547 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1548 Muse uses, as well as make your own tags.
1552 If a tag takes arguments, it will look like this, where ``tagname'' is
1553 the name of the tag.
1556 <tagname arg1="string1" arg2="string2">
1559 If you want the tag to look like it came straight from an XHTML
1560 document, you can alternatively do the following.
1563 <tagname arg1="string1" arg2="string2" />
1566 If a tag surrounds some text, it will look like this.
1569 <tagname>Some text</tagname>
1572 If a tag surrounds a large region, it will look like this.
1581 @subheading Tag listing
1583 This is the complete list of tags that Muse accepts, including those
1584 that were mentioned in previous sections.
1589 If publishing to HTML, surround the given text with a @verb{|<span>|}
1590 tag. It takes one argument called ``name'' that specifies the class
1591 attribute of the @verb{|<span>|} tag.
1593 If publishing to a different format, do nothing extra to the text.
1596 Treat the text surrounded by the tag as if they were enclosed in equal
1597 signs, that is, make it monospace.
1600 Run a command on the region, replacing the region with the result of the
1601 command. The command is specified with the ``interp'' argument. If no
1602 value for ``interp'' is given, pass the entire region to the shell.
1604 The ``markup'' argument controls how this section is marked up.
1606 If it is omitted, publish the region with the normal Muse rules.
1608 If "nil", do not mark up the region at all, but prevent Muse from
1609 further interpreting it.
1611 If "example", treat the region as if it was surrounded by the
1612 @verb{|<example>|} tag.
1614 If "src", treat the included text as if it was surrounded by the
1615 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1618 If "verse", treat the region as if it was surrounded by the
1619 @verb{|<verse>|} tag, to preserve newlines.
1621 Otherwise, it should be the name of a function to call, with the buffer
1622 narrowed to the region.
1625 Treat the entire region as a comment. If the option
1626 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1627 publish it using the comment syntax of the current publishing style.
1630 Publish a Table of Contents. This will either be inserted in-place or
1631 at the beginning of the document, depending on your publishing style.
1632 It does not have a delimiting tag.
1634 By default, only 2 levels of headings will be included in the generated
1635 Table of Contents. To change this globally, customize the
1636 @var{muse-publish-contents-depth} option. To change this only for the
1637 current tag, use the ``depth'' argument.
1640 Publish the region in monospace, preserving the newlines in the region.
1641 This is useful for snippets of code.
1644 Insert the given file at the current location during publishing. The
1645 basic use of this tag is as follows, replacing ``included_file'' with
1646 the name of the file that you want to include.
1649 <include file="included_file">
1652 The ``markup'' argument controls how this section is marked up.
1654 If it is omitted, publish the included text with the normal Muse
1657 If "nil", do not mark up the included text at all.
1659 If "example", treat the included text as if it was surrounded by the
1660 @verb{|<example>|} tag.
1662 If "src", treat the included text as if it was surrounded by the
1663 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1666 If "verse", treat the included text as if it was surrounded by the
1667 @verb{|<verse>|} tag, to preserve newlines.
1669 Otherwise, it should be the name of a function to call after inserting
1670 the file with the buffer narrowed to the section inserted.
1673 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1674 The result is then inserted into the document, so you do not need to
1675 explicitly call @code{insert}. All text properties are removed from the
1678 This tag takes the ``markup'' argument. See the description of
1679 @verb{|<command>|} for details.
1682 Make sure that the text enclosed by this tag is published without
1683 escaping it in any way. This is useful for inserting markup directly
1684 into the published document, when Muse does not provide the desired
1688 Mark up the text between the initial and ending tags. The markup
1689 command to use may be specified by the ``function'' argument. The
1690 standard Muse markup routines are used by default if no ``function''
1691 argument is provided.
1693 This is useful for marking up regions in headers and footers. One
1694 example that comes to mind is generating a published index of all of the
1695 files in the current project by doing the following.
1698 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1702 Run the @command{perl} language interpreter on the region, replacing the
1703 region with the result of the command.
1705 This tag takes the ``markup'' argument. See the description of
1706 @verb{|<command>|} for details.
1709 Run the @command{python} language interpreter on the region, replacing
1710 the region with the result of the command.
1712 This tag takes the ``markup'' argument. See the description of
1713 @verb{|<command>|} for details.
1716 Publish the region as a blockquote. This will either be inserted
1717 in-place or at the beginning of the document, depending on your
1718 publishing style. It does not have a delimiting tag.
1721 Run the @command{ruby} language interpreter on the region, replacing the
1722 region with the result of the command.
1724 This tag takes the ``markup'' argument. See the description of
1725 @verb{|<command>|} for details.
1728 Publish the region using htmlize.
1729 The language to use may be specified by the ``lang'' attribute.
1731 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1732 the value of the ``lang'' attribute.
1734 This tag requires htmlize 1.34 or later in order to work. If this is
1735 not satisfied, or the current publishing style is not HTML-based, Muse
1736 will publish the region like an @verb{|<example>|} tag.
1739 This is used when you want to prevent Muse from trying to interpret some
1740 markup. Surround the markup in @verb{|<verbatim>|} and
1741 @verb{|</verbatim>|}, and it will not be interpreted.
1743 This tag was used often in previous versions of Muse because they did
1744 not support whole-document escaping of specials. Now, it will only be
1745 needed for other tags, and perhaps footnotes as well.
1748 Preserve the newlines in the region. In formats like HTML, newlines are
1749 removed by default, hence the need for this tag. In other publishing
1750 styles, this tag may cause the text to be indented slightly in a way
1751 that looks nice for poetry and prose.
1755 @node Publishing Styles, Extending Muse, Markup Rules, Top
1756 @comment node-name, next, previous, up
1757 @chapter Publishing Various Types of Documents
1758 @cindex publishing styles
1760 One of the principle features of Muse is the ability to publish a simple
1761 input text to a variety of different output styles. Muse also makes it
1762 easy to create new styles, or derive from an existing style.
1765 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1766 * Book:: Publishing entries into a compilation.
1767 * ConTeXt:: Publishing ConTeXt documents.
1768 * DocBook:: Publishing in DocBook XML form.
1769 * HTML:: Publishing in HTML or XHTML form.
1770 * Journal:: Keeping a journal or blog.
1771 * LaTeX:: Publishing LaTeX documents.
1772 * Poem:: Publish a poem to LaTex or PDF.
1773 * Texinfo:: Publish entries to Texinfo format or PDF.
1774 * XML:: Publish entries to XML.
1777 @node Blosxom, Book, Publishing Styles, Publishing Styles
1778 @comment node-name, next, previous, up
1779 @section Integrating Muse and pyblosxom.cgi
1780 @cindex blog, one-file-per-entry style
1782 The Blosxom publishing style publishes a tree of categorised files to a
1783 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1784 In other words, each blog entry corresponds with one file.
1787 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1788 * Blosxom Entries:: Format of a Blosxom entry and automation.
1789 * Blosxom Options:: Blosxom styles and options provided.
1792 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1793 @comment node-name, next, previous, up
1794 @subsection Other tools needed for the Blosxom style
1796 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1797 installed on a machine that you have upload access to.
1799 The following additional components are required in order to make the
1800 date of blog entries display as something sensible.
1804 A script to gather date directives from the entire blog tree into a
1805 single file. The file must associate a blog entry with a date.
1808 A plugin for (py)blosxom that reads this file.
1811 These 2 things are provided for @command{pyblosxom.cgi} in the
1812 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1813 former service, while @file{hardcodedates.py} provides the latter
1814 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1815 script will be found/written.
1817 Here is a sample listing from my @file{timestamps} file, which maps
1818 each file to a date. This can really be in any format, as long as your
1819 date-gathering script and your plugin can both understand it.
1822 2005-04-01-14-16 personal/paper_cranes
1823 2005-03-21 personal/spring_break_over
1824 2004-10-24 personal/finished_free_culture
1827 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1828 @file{getstamps.py}. Note that you will need to set the current
1829 directory to where your Muse files are, execute @file{getstamps.py}, and
1830 then move the generated timestamps file to your publishing directory.
1832 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1833 @comment node-name, next, previous, up
1834 @subsection Format of a Blosxom entry and automation
1836 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1837 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1838 plus whatever normal content is desired.
1840 The date directive is not used directly by @command{pyblosxom.cgi} or
1841 this program. You need to have the two additional items from the former
1842 section to make use of this feature.
1844 There is a function called @code{muse-blosxom-new-entry} that will
1845 automate the process of making a new blog entry. To make use of it, do
1850 Customize @code{muse-blosxom-base-directory} to the location that your
1851 blog entries are stored.
1854 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1855 use the following code to assign this function to @kbd{C-c p l'}.
1858 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1862 You should create your directory structure ahead of time under your base
1863 directory. These directories, which correspond with category names, may
1867 When you enter this key sequence, you will be prompted for the category
1868 of your entry and its title. Upon entering this information, a new file
1869 will be created that corresponds with the title, but in lowercase
1870 letters and having special characters converted to underscores. The
1871 title and date directives will be inserted automatically.
1874 @node Blosxom Options, , Blosxom Entries, Blosxom
1875 @comment node-name, next, previous, up
1876 @subsection Blosxom styles and options provided
1878 The following styles and options are available in the Blosxom publishing
1881 @subheading Styles provided
1885 @cindex publishing styles, blosxom-html
1887 Publish Blosxom entries in HTML form.
1889 @cindex publishing styles, blosxom-xhtml
1891 Publish Blosxom entries in XHTML form.
1895 @subheading Options provided
1899 @item muse-blosxom-extension
1900 Default file extension for publishing Blosxom files.
1902 @item muse-blosxom-header
1903 Header used for publishing Blosxom files.
1905 This may be text or a filename.
1907 @item muse-blosxom-footer
1908 Footer used for publishing Blosxom files.
1910 This may be text or a filename.
1912 @item muse-blosxom-base-directory
1913 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1915 This is the top-level directory where your blog entries may be found
1920 @node Book, ConTeXt, Blosxom, Publishing Styles
1921 @comment node-name, next, previous, up
1922 @section Publishing entries into a compilation
1924 This publishing style is used to output ``books'' in LaTeX or PDF
1927 Each page will become a separate chapter in the book, unless the style
1928 keyword @option{:nochapters} is used, in which case they are all run
1929 together as if one giant chapter.
1931 One way of publishing a book is to make a project for it, add the
1932 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1933 with a very specific @option{:include} value to specify some page whose
1934 contents will be checked for the values of @code{#title} and
1935 @code{#date}, and whose name will be used in the output file. Then to
1936 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1937 @kbd{C-c C-p} to trigger the publishing process. An example
1938 @code{muse-project-alist} for this method follows.
1941 (setq muse-project-alist
1942 '(("MyNotes" (:nochapters t ; do automatically add chapters
1943 :book-chapter "Computer Science"
1945 :book-chapter "Mathematics"
1947 :book-chapter "Emacs"
1949 :book-end t ; the rest will not be placed in the book
1950 "~/Notes" ; so we can find the notes-anthology page
1952 :force-publish ("index")
1955 :include "/notes-anthology[^/]*$"
1956 :path "~/public_html/notes")
1957 ;; other publishing styles for each directory go here,
1962 In this example, there would be a file called
1963 @file{~/Notes/notes-anthology.muse}, which would contain just the
1964 following. The resulting book would be published to
1965 @file{~/public_html/notes/notes-anthology.pdf}.
1968 #title My Technology Ramblings
1971 Another way is to call the @code{muse-book-publish-project} function
1972 manually, with a custom project entry. An example of this may be found
1973 in John Wiegley's configuration file at
1974 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
1977 @subheading Styles provided
1981 @cindex publishing styles, book-latex
1983 Publish a book in LaTeX form. The header and footer are different than
1984 the normal LaTeX publishing mode.
1986 @cindex publishing styles, book-pdf
1988 Publish a book in PDF form. The header and footer are different than
1989 the normal PDF publishing mode.
1993 @subheading Options provided
1997 @item muse-book-before-publish-hook
1998 A hook run in the book buffer before it is marked up.
2000 @item muse-book-after-publish-hook
2001 A hook run in the book buffer after it is marked up.
2003 @item muse-book-latex-header
2004 Header used for publishing books to LaTeX.
2006 This may be text or a filename.
2008 @item muse-book-latex-footer
2009 Footer used for publishing books to LaTeX.
2011 This may be text or a filename.
2014 @node ConTeXt, DocBook, Book, Publishing Styles
2015 @comment node-name, next, previous, up
2016 @section Publishing ConTeXt documents
2018 This publishing style is capable of producing ConTeXt or PDF documents.
2020 If you wish to publish PDF documents based on ConTeXt, you will need to
2021 have it installed. For Debian and Ubuntu, this can be accomplished by
2022 installing the ``texlive'' package.
2024 @subheading Styles provided
2028 @cindex publishing styles, context
2030 Publish a ConTeXt document.
2032 @cindex publishing styles, context-pdf
2034 Publish a PDF document, using an external ConTeXt document conversion
2037 @cindex publishing styles, context-slides
2038 @item context-slides
2039 Produce slides from a ConTeXt document.
2041 Here is an example of a slide.
2046 [[Some-sort-of-cute-image.png]]
2051 - Another bullet point.
2058 @cindex publishing styles, context-slides-pdf
2059 @item context-slides-pdf
2060 Publish a PDF document of ConTeXt slides.
2064 @subheading Options provided
2068 @item muse-context-extension
2069 Default file extension for publishing ConTeXt files.
2071 @item muse-context-pdf-extension
2072 Default file extension for publishing ConTeXt files to PDF.
2074 @item muse-context-pdf-program
2075 The program that is called to generate PDF content from ConTeXt content.
2077 @item muse-context-pdf-cruft
2078 Extensions of files to remove after generating PDF output successfully.
2080 @item muse-context-header
2081 Header used for publishing ConTeXt files.
2083 This may be text or a filename.
2085 @item muse-context-footer
2086 Footer used for publishing ConTeXt files.
2088 This may be text or a filename.
2090 @item muse-context-markup-regexps
2091 List of markup regexps for identifying regions in a Muse page.
2093 For more on the structure of this list,
2094 @xref{muse-publish-markup-regexps}.
2096 @item muse-context-markup-functions
2097 An alist of style types to custom functions for that kind of text.
2099 For more on the structure of this list,
2100 @xref{muse-publish-markup-functions}.
2102 @item muse-context-markup-strings
2103 Strings used for marking up text.
2105 These cover the most basic kinds of markup, the handling of which
2106 differs little between the various styles.
2108 @item muse-context-slides-header
2109 Header for publishing a presentation (slides) using ConTeXt.
2111 You can use any of the predefined modules, which are available in the
2112 tex/context/base of your distribution, provided it has TitlePage and
2113 Topic defined. Alternatively, you can use your own style (mystyle) by
2114 replacing ``\\usemodule[]'' with ``\\input mystyle''.
2116 This may be text or a filename.
2118 @item muse-context-slides-markup-strings
2119 Strings used for marking up text in ConTeXt slides.
2121 @item muse-context-markup-specials-document
2122 A table of characters which must be represented specially.
2123 These are applied to the entire document, sans already-escaped
2126 @item muse-context-markup-specials-example
2127 A table of characters which must be represented specially.
2128 These are applied to @verb{|example>|} regions.
2130 With the default interpretation of @verb{|<example>|} regions, no
2131 specials need to be escaped.
2133 @item muse-context-markup-specials-literal
2134 A table of characters which must be represented specially.
2135 This applies to =monospaced text= and @verb{|<code>|} regions.
2137 @item muse-context-markup-specials-url
2138 A table of characters which must be represented specially.
2139 These are applied to URLs.
2141 @item muse-context-markup-specials-image
2142 A table of characters which must be represented specially.
2143 These are applied to image filenames.
2145 @item muse-context-permit-contents-tag
2146 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2149 Most of the time, it is best to have a table of contents on the
2150 first page, with a new page immediately following. To make this
2151 work with documents published in both HTML and ConTeXt, we need to
2152 ignore the @verb{|<contents>|} tag.
2154 If you don't agree with this, then set this option to non-nil,
2155 and it will do what you expect.
2159 @node DocBook, HTML, ConTeXt, Publishing Styles
2160 @comment node-name, next, previous, up
2161 @section Publishing in DocBook XML form
2163 This publishing style is used to generate DocBook XML files.
2165 @subheading Styles provided
2169 @cindex publishing styles, docbook
2171 Publish a file in Docbook form.
2175 @subheading Options provided
2177 This publishing style uses the same options for markup up special
2178 characters as the ``xml'' publishing style. @xref{XML}, for details.
2182 @item muse-docbook-extension
2183 Default file extension for publishing DocBook XML files.
2185 @item muse-docbook-header
2186 Header used for publishing DocBook XML files.
2188 This may be text or a filename.
2190 @item muse-docbook-footer
2191 Footer used for publishing DocBook XML files.
2193 This may be text or a filename.
2195 @item muse-docbook-markup-regexps
2196 List of markup rules for publishing a Muse page to DocBook XML.
2198 @item muse-docbook-markup-functions
2199 An alist of style types to custom functions for that kind of text.
2201 @item muse-docbook-markup-strings
2202 Strings used for marking up text.
2204 These cover the most basic kinds of markup, the handling of which
2205 differs little between the various styles.
2207 @item muse-docbook-encoding-default
2208 The default Emacs buffer encoding to use in published files.
2209 This will be used if no special characters are found.
2211 @item muse-docbook-charset-default
2212 The default DocBook XML charset to use if no translation is
2213 found in @code{muse-xml-encoding-map}.
2217 @node HTML, Journal, DocBook, Publishing Styles
2218 @comment node-name, next, previous, up
2219 @section Publishing in HTML or XHTML form
2221 This publishing style is capable of producing HTML or XHTML documents.
2223 @subheading Styles provided
2227 @cindex publishing styles, html
2229 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2232 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2236 @subheading Options provided
2238 If an HTML option does not have a corresponding XHTML option, it will
2239 be used for both of these publishing styles.
2241 These publishing styles use the same options for markup up special
2242 characters as the ``xml'' publishing style. @xref{XML}, for details.
2246 @item muse-html-extension
2247 Default file extension for publishing HTML files.
2249 @item muse-xhtml-extension
2250 Default file extension for publishing XHTML files.
2252 @item muse-html-style-sheet
2253 Store your stylesheet definitions here.
2255 This is used in @code{muse-html-header}. You can put raw CSS in here or
2256 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2257 @verb{|<lisp>|} markup tags.
2259 If you are publishing to XHTML, then customize the
2260 @code{muse-xhtml-style-sheet} option instead.
2262 @item muse-xhtml-style-sheet
2263 Store your stylesheet definitions here.
2265 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2266 or a @verb{|<link>|} tag to an external stylesheet. This text may
2267 contain @verb{|<lisp>|} markup tags.
2269 @item muse-html-header
2270 Header used for publishing HTML files.
2272 This may be text or a filename.
2274 @item muse-html-footer
2275 Footer used for publishing HTML files.
2277 This may be text or a filename.
2279 @item muse-xhtml-header
2280 Header used for publishing XHTML files.
2282 This may be text or a filename.
2284 @item muse-xhtml-footer
2285 Footer used for publishing XHTML files.
2287 This may be text or a filename.
2289 @item muse-html-anchor-on-word
2290 When true, anchors surround the closest word.
2292 This allows you to select them in a browser (i.e. for pasting), but has
2293 the side-effect of marking up headers in multiple colors if your header
2294 style is different from your link style.
2296 @item muse-html-table-attributes
2297 The attribute to be used with HTML @verb{|<table>|} tags.
2299 If you want to make more-complicated tables in HTML, surround the HTML
2300 with the @verb{|literal|} tag, so that it does not get escaped.
2302 @item muse-html-markup-regexps
2303 List of markup rules for publishing a Muse page to HTML.
2305 @item muse-html-markup-functions
2306 An alist of style types to custom functions for that kind of text.
2308 @item muse-html-markup-strings
2309 Strings used for marking up text as HTML.
2311 These cover the most basic kinds of markup, the handling of which
2312 differs little between the various styles.
2314 @item muse-xhtml-markup-strings
2315 Strings used for marking up text as XHTML.
2317 These cover the most basic kinds of markup, the handling of which
2318 differs little between the various styles.
2320 @item muse-html-markup-tags
2321 A list of tag specifications, for specially marking up HTML.
2322 @xref{muse-publish-markup-tags}, for more information.
2324 @item muse-html-meta-http-equiv
2325 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2327 @item muse-html-meta-content-type
2328 The content type used for the HTML @verb{|<meta>|} tag.
2330 If you are striving for XHTML 1.1 compliance, you may want to change
2331 this to ``application/xhtml+xml''.
2333 @item muse-html-meta-content-encoding
2334 The charset to append to the HTML @verb{|<meta>|} tag.
2336 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2337 and determine the HTML charset from emacs's coding. If set to a string,
2338 this string will be used to force a particular charset.
2340 @item muse-html-charset-default
2341 The default HTML meta charset to use if no translation is found in
2342 @code{muse-xml-encoding-map}.
2344 @item muse-html-encoding-default
2345 The default Emacs buffer encoding to use in published files.
2346 This will be used if no special characters are found.
2350 @node Journal, LaTeX, HTML, Publishing Styles
2351 @comment node-name, next, previous, up
2352 @section Keeping a journal or blog
2354 @cindex blog, journal style
2356 The module facilitates the keeping and publication of a journal. When
2357 publishing to HTML, it assumes the form of a web log, or blog.
2359 The input format for each entry is as follows.
2362 * 20040317: Title of entry
2367 "You know who you are. It comes down to a simple gut check: You
2368 either love what you do or you don't. Period." -- P. Bronson
2372 The "qotd", or Quote of the Day, is entirely optional. When generated
2373 to HTML, this entry is rendered as the following.
2377 <div class="entry-qotd">
2378 <h3>Quote of the Day:</h3>
2379 <p>"You know who you are. It comes down to a simple gut
2380 check: You either love what you do or you don't. Period."
2383 <div class="entry-body">
2384 <div class="entry-head">
2385 <div class="entry-date">
2386 <span class="date">March 17, 2004</span>
2388 <div class="entry-title">
2389 <h2>Title of entry</h2>
2392 <div class="entry-text">
2393 <p>Text for the entry.</p>
2399 The plurality of "div" tags makes it possible to display the entries in
2400 any form you wish, using a CSS style.
2402 Also, an .RDF file can be generated from your journal by publishing it
2403 with the "rdf" style. It uses the first two sentences of the first
2404 paragraph of each entry as its "description", and auto-generates tags
2405 for linking to the various entries.
2407 @subheading muse-project-alist considerations
2409 If you wish to publish an RDF or RSS feed, it is important to include
2410 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2411 for your Journal projects. An example follows.
2414 (setq muse-project-alist
2415 '(("Journal" ("~/Journal/"
2417 (:base "journal-rss"
2418 :base-url "http://example.org/journal/"
2419 :path "~/public_html/journal"))))
2422 @subheading Styles provided
2426 @cindex publishing styles, journal-html
2428 Publish journal entries as an HTML document.
2430 @cindex publishing styles, journal-xhtml
2432 Publish journal entries as an XHTML document.
2434 @cindex publishing styles, journal-latex
2436 Publish journal entries as a LaTeX document.
2438 @cindex publishing styles, journal-pdf
2440 Publish journal entries as a PDF document.
2442 @cindex publishing styles, journal-book-latex
2443 @item journal-book-latex
2444 Publish journal entries as a LaTeX book.
2446 @cindex publishing styles, journal-book-pdf
2447 @item journal-book-pdf
2448 Publish journal entries as a PDF book.
2450 @cindex publishing styles, journal-rdf
2451 @cindex publishing styles, RSS 1.0
2453 Publish journal entries as an RDF file (RSS 1.0).
2455 @cindex publishing styles, journal-rss
2456 @cindex publishing styles, RSS 2.0
2458 Publish journal entries as an RSS file (RSS 2.0).
2460 @cindex publishing styles, journal-rss-entry
2461 @item journal-rss-entry
2462 Used internally by @code{journal-rss} and @code{journal-rdf} for
2463 publishing individual entries.
2467 @subheading Options provided
2471 @item muse-journal-heading-regexp
2472 A regexp that matches a journal heading.
2474 Paren group 1 is the ISO date, group 2 is the optional category, and
2475 group 3 is the optional heading for the entry.
2477 @item muse-journal-date-format
2478 Date format to use for journal entries.
2480 @item muse-journal-html-heading-regexp
2481 A regexp that matches a journal heading from an HTML document.
2483 Paren group 1 is the ISO date, group 2 is the optional category, and
2484 group 3 is the optional heading for the entry.
2486 @item muse-journal-html-entry-template
2487 Template used to publish individual journal entries as HTML.
2489 This may be text or a filename.
2491 @item muse-journal-latex-section
2492 Template used to publish a LaTeX section.
2494 @item muse-journal-latex-subsection
2495 Template used to publish a LaTeX subsection.
2497 @item muse-journal-markup-tags
2498 A list of tag specifications, for specially marking up Journal entries.
2500 @xref{muse-publish-markup-tags}, for more information.
2502 This is used by @code{journal-latex} and its related styles, as well as
2503 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2504 @code{journal-rss} use.
2506 @item muse-journal-rdf-extension
2507 Default file extension for publishing RDF (RSS 1.0) files.
2509 @item muse-journal-rdf-base-url
2510 The base URL of the website referenced by the RDF file.
2512 @item muse-journal-rdf-header
2513 Header used for publishing RDF (RSS 1.0) files.
2515 This may be text or a filename.
2517 @item muse-journal-rdf-footer
2518 Footer used for publishing RDF (RSS 1.0) files.
2520 This may be text or a filename.
2522 @item muse-journal-rdf-date-format
2523 Date format to use for RDF entries.
2525 @item muse-journal-rdf-entry-template
2526 Template used to publish individual journal entries as RDF.
2528 This may be text or a filename.
2530 @item muse-journal-rdf-summarize-entries
2531 If non-nil, include only summaries in the RDF file, not the full data.
2533 The default is nil, because this annoys some subscribers.
2535 @item muse-journal-rss-heading-regexp
2536 A regexp that matches a journal heading from an HTML document.
2538 Paren group 1 is the ISO date, group 2 is the optional category,
2539 and group 3 is the optional heading for the entry.
2541 @item muse-journal-rss-extension
2542 Default file extension for publishing RSS 2.0 files.
2544 @item muse-journal-rss-base-url
2545 The base URL of the website referenced by the RSS file.
2547 @item muse-journal-rss-header
2548 Header used for publishing RSS 2.0 files.
2550 This may be text or a filename.
2552 @item muse-journal-rss-footer
2553 Footer used for publishing RSS 2.0 files.
2555 This may be text or a filename.
2557 @item muse-journal-rss-date-format
2558 Date format to use for RSS 2.0 entries.
2560 @item muse-journal-rss-entry-template
2561 Template used to publish individual journal entries as RSS 2.0.
2563 This may be text or a filename.
2565 @item muse-journal-rss-enclosure-types-alist
2566 File types that are accepted as RSS enclosures.
2568 This is an alist that maps file extension to content type.
2570 Useful for podcasting.
2572 @item muse-journal-rss-summarize-entries
2573 If non-nil, include only summaries in the RSS file, not the full data.
2575 The default is nil, because this annoys some subscribers.
2577 @item muse-journal-rss-markup-regexps
2578 List of markup rules for publishing a Muse journal page to RSS.
2580 For more information on the structure of this list,
2581 @xref{muse-publish-markup-regexps}.
2583 @item muse-journal-rss-markup-functions
2584 An alist of style types to custom functions for that kind of text.
2586 For more on the structure of this list,
2587 @xref{muse-publish-markup-functions}.
2591 @node LaTeX, Poem, Journal, Publishing Styles
2592 @comment node-name, next, previous, up
2593 @section Publishing LaTeX documents
2595 This publishing style is capable of producing LaTeX or PDF documents.
2597 If you wish to publish PDF documents, you will need to have a good TeX
2598 installation. For Debian and Ubuntu, this can be accomplished by
2599 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2602 @subheading Styles provided
2606 @cindex publishing styles, latex
2608 Publish a LaTeX document.
2610 @cindex publishing styles, pdf
2612 Publish a PDF document, using an external LaTeX document conversion
2615 @cindex publishing styles, latexcjk
2617 Publish a LaTeX document with CJK (Chinese) encodings.
2619 @cindex publishing styles, pdfcjk
2621 Publish a PDF document with CJK (Chinese) encodings, using an external
2622 LaTeX document conversion tool.
2624 @cindex publishing styles, slides
2626 Publish a LaTeX document that uses the Beamer extension. This is
2627 suitable for producing slides.
2629 Here is an example of a slide.
2632 <slide title="First Slide">
2633 Everything between the slide tags composes this slide.
2635 [[Some-sort-of-cute-image.png]]
2638 - Another bullet point.
2642 @cindex publishing styles, slides-pdf
2644 Publish a PDF document of slides, using the Beamer extension.
2646 @cindex publishing styles, lecture-notes
2648 Publish a LaTeX document that uses the Beamer extension. This is
2649 suitable for producing lecture notes.
2651 This can also use the @verb{|<slide>|} tag.
2653 @cindex publishing styles, lecture-notes-pdf
2654 @item lecture-notes-pdf
2655 Publish a PDF document of lecture notes, using the Beamer extension.
2659 @subheading Options provided
2663 @item muse-latex-extension
2664 Default file extension for publishing LaTeX files.
2666 @item muse-latex-pdf-extension
2667 Default file extension for publishing LaTeX files to PDF.
2669 @item muse-latex-pdf-program
2670 The program that is called to generate PDF content from LaTeX content.
2672 @item muse-latex-pdf-cruft
2673 Extensions of files to remove after generating PDF output successfully.
2675 @item muse-latex-header
2676 Header used for publishing LaTeX files.
2678 This may be text or a filename.
2680 @item muse-latex-footer
2681 Footer used for publishing LaTeX files.
2683 This may be text or a filename.
2685 @item muse-latexcjk-header
2686 Header used for publishing LaTeX files (CJK).
2688 This may be text or a filename.
2690 @item muse-latexcjk-footer
2691 Footer used for publishing LaTeX files (CJK).
2693 This may be text or a filename.
2695 @item muse-latex-slides-header
2696 Header for publishing of slides using LaTeX.
2698 This may be text or a filename.
2700 You must have the Beamer extension for LaTeX installed for this to work.
2702 @item muse-latex-lecture-notes-header
2703 Header publishing of lecture notes using LaTeX.
2705 This may be text or a filename.
2707 You must have the Beamer extension for LaTeX installed for this to work.
2709 @item muse-latex-markup-regexps
2710 List of markup regexps for identifying regions in a Muse page.
2712 For more on the structure of this list,
2713 @xref{muse-publish-markup-regexps}.
2715 @item muse-latex-markup-functions
2716 An alist of style types to custom functions for that kind of text.
2718 For more on the structure of this list,
2719 @xref{muse-publish-markup-functions}.
2721 @item muse-latex-markup-strings
2722 Strings used for marking up text.
2724 These cover the most basic kinds of markup, the handling of which
2725 differs little between the various styles.
2727 @item muse-latex-slides-markup-tags
2728 A list of tag specifications, for specially marking up LaTeX slides.
2730 @item muse-latexcjk-encoding-map
2731 An alist mapping emacs coding systems to appropriate CJK codings.
2732 Use the base name of the coding system (ie, without the -unix).
2734 @item muse-latexcjk-encoding-default
2735 The default Emacs buffer encoding to use in published files.
2737 This will be used if no special characters are found.
2739 @item muse-latex-markup-specials-document
2740 A table of characters which must be represented specially.
2741 These are applied to the entire document, sans already-escaped
2744 @item muse-latex-markup-specials-example
2745 A table of characters which must be represented specially.
2746 These are applied to @verb{|example>|} regions.
2748 With the default interpretation of @verb{|<example>|} regions, no
2749 specials need to be escaped.
2751 @item muse-latex-markup-specials-literal
2752 A table of characters which must be represented specially.
2753 This applies to =monospaced text= and @verb{|<code>|} regions.
2755 @item muse-latex-markup-specials-url
2756 A table of characters which must be represented specially.
2757 These are applied to URLs.
2759 @item muse-latex-markup-specials-image
2760 A table of characters which must be represented specially.
2761 These are applied to image filenames.
2763 @item muse-latex-permit-contents-tag
2764 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2767 Most of the time, it is best to have a table of contents on the
2768 first page, with a new page immediately following. To make this
2769 work with documents published in both HTML and LaTeX, we need to
2770 ignore the @verb{|<contents>|} tag.
2772 If you don't agree with this, then set this option to non-nil,
2773 and it will do what you expect.
2777 @node Poem, Texinfo, LaTeX, Publishing Styles
2778 @comment node-name, next, previous, up
2779 @section Publish a poem to LaTex or PDF
2781 The @code{muse-poem} module makes it easy to attractively publish and
2782 reference poems in the following format, using the "memoir" module for
2783 LaTeX publishing. It will also markup poems for every other output
2784 style, though none are nearly as pretty.
2793 Annotations, history, notes, etc.
2796 Once a poem is written in this format, just publish it to PDF using the
2797 @code{poem-pdf} style. To make an inlined reference to a poem that
2798 you've written -- for example, from a blog page -- there is a "poem" tag
2799 defined by this module.
2802 <poem title="name.of.poem.page">
2805 Let's assume the template above was called @file{name.of.poem.page};
2806 then the above tag would result in this inclusion.
2814 John Wiegley uses this module for publishing all of the poems on his
2815 website, which are at
2816 @uref{http://www.newartisans.com/johnw/poems.html}.
2818 @subheading Styles provided
2822 @cindex publishing styles, poem-latex
2824 Publish a poem in LaTeX form.
2826 @cindex publishing styles, poem-pdf
2828 Publish a poem to a PDF document.
2830 @cindex publishing styles, chapbook-latex
2831 @item chapbook-latex
2832 Publish a book of poems in LaTeX form.
2834 @cindex publishing styles, chapbook-pdf
2836 Publish a book of poems to a PDF document.
2840 @subheading Options provided
2844 @item muse-poem-latex-header
2845 Header used for publishing LaTeX poems.
2847 This may be text or a filename.
2849 @item muse-poem-latex-footer
2850 Footer used for publishing LaTeX files.
2852 This may be text or a filename.
2854 @item muse-poem-markup-strings
2855 Strings used for marking up poems.
2857 These cover the most basic kinds of markup, the handling of which
2858 differs little between the various styles.
2860 @item muse-chapbook-latex-header
2861 Header used for publishing a book of poems in LaTeX form.
2863 This may be text or a filename.
2865 @item muse-chapbook-latex-footer
2866 Footer used for publishing a book of poems in LaTeX form.
2868 This may be text or a filename.
2870 @item muse-poem-chapbook-strings
2871 Strings used for marking up books of poems.
2873 These cover the most basic kinds of markup, the handling of which
2874 differs little between the various styles.
2878 @node Texinfo, XML, Poem, Publishing Styles
2879 @comment node-name, next, previous, up
2880 @section Publish entries to Texinfo format or PDF
2882 Rules for publishing a Muse file as a Texinfo article.
2884 @subheading Styles provided
2888 @cindex publishing styles, texi
2890 Publish a file in Texinfo form.
2892 @cindex publishing styles, texi
2894 Generate an Info file from a Muse file.
2896 @cindex publishing styles, info-pdf
2898 Publish a file in PDF form.
2902 @subheading Options provided
2906 @item muse-texinfo-process-natively
2907 If non-nil, use the Emacs `texinfmt' module to make Info files.
2909 @item muse-texinfo-extension
2910 Default file extension for publishing Texinfo files.
2912 @item muse-texinfo-info-extension
2913 Default file extension for publishing Info files.
2915 @item muse-texinfo-pdf-extension
2916 Default file extension for publishing PDF files.
2918 @item muse-texinfo-header
2919 Text to prepend to a Muse page being published as Texinfo.
2921 This may be text or a filename.
2922 It may contain @verb{|<lisp>|} markup tags.
2924 @item muse-texinfo-footer
2925 Text to append to a Muse page being published as Texinfo.
2927 This may be text or a filename.
2928 It may contain @verb{|<lisp>|} markup tags.
2930 @item muse-texinfo-markup-regexps
2931 List of markup rules for publishing a Muse page to Texinfo.
2933 For more on the structure of this list,
2934 @xref{muse-publish-markup-regexps}.
2936 @item muse-texinfo-markup-functions
2937 An alist of style types to custom functions for that kind of text.
2939 For more on the structure of this list,
2940 @xref{muse-publish-markup-functions}.
2942 @item muse-texinfo-markup-strings
2943 Strings used for marking up text.
2945 These cover the most basic kinds of markup, the handling of which
2946 differs little between the various styles.
2948 @item muse-texinfo-markup-specials
2949 A table of characters which must be represented specially.
2951 @item muse-texinfo-markup-specials
2952 A table of characters which must be represented specially.
2953 These are applied to URLs.
2957 @node XML, , Texinfo, Publishing Styles
2958 @comment node-name, next, previous, up
2959 @section Publish entries to XML
2961 Muse is capable of publishing XML documents, with the help of the
2962 @file{muse-xml.el} module.
2964 A RelaxNG schema is available as part of the Muse distribution in the
2965 @file{etc/muse.rnc} file.
2967 @subheading Styles provided
2971 @cindex publishing styles, xml
2973 Publish a file in XML form.
2977 @subheading Options provided
2981 @cindex muse-xml-encoding-map
2982 @item muse-xml-encoding-map
2983 An alist mapping Emacs coding systems to appropriate XML charsets.
2984 Use the base name of the coding system (i.e. without the -unix).
2986 @item muse-xml-markup-specials
2987 A table of characters which must be represented specially in all
2988 XML-like markup formats.
2990 @item muse-xml-markup-specials-url-extra
2991 A table of characters which must be represented specially in all
2992 XML-like markup formats.
2994 These are extra characters that are escaped within URLs.
2996 @item muse-xml-extension
2997 Default file extension used for publishing XML files.
2999 @item muse-xml-header
3000 Header used for publishing XML files.
3002 This may be text or a filename.
3004 @item muse-xml-footer
3005 Footer used for publishing XML files.
3007 This may be text or a filename.
3009 @item muse-xml-markup-regexps
3010 List of markup rules for publishing a Muse page to XML.
3012 For more on the structure of this list,
3013 @xref{muse-publish-markup-regexps}.
3015 @item muse-xml-markup-functions
3016 An alist of style types to custom functions for that kind of text.
3018 For more on the structure of this list,
3019 @xref{muse-publish-markup-functions}.
3021 @item muse-xml-markup-strings
3022 Strings used for marking up text.
3024 These cover the most basic kinds of markup, the handling of which
3025 differs little between the various styles.
3027 @item muse-xml-encoding-default
3028 The default Emacs buffer encoding to use in published files.
3030 This will be used if no special characters are found.
3032 @item muse-xml-charset-default
3033 The default XML charset to use if no translation is found in
3034 @code{muse-xml-encoding-map}.
3039 @node Extending Muse, Getting Help and Reporting Bugs, Publishing Styles, Top
3040 @comment node-name, next, previous, up
3041 @chapter Making your own publishing styles
3044 * Common Elements:: Common functionality shared by styles.
3045 * Deriving Styles:: Deriving a new style from an existing
3049 @node Common Elements, Deriving Styles, , Extending Muse
3050 @comment node-name, next, previous, up
3051 @section Common functionality shared by styles
3052 @cindex publishing styles, common
3055 * Markup Functions:: Specifying functions to mark up text.
3056 * Markup Regexps:: Markup rules for publishing.
3057 * Markup Strings:: Strings specific to a publishing style.
3058 * Markup Tags:: Tag specifications for special markup.
3059 * Style Elements:: Parameters used for defining styles.
3062 @node Markup Functions, Markup Regexps, , Common Elements
3063 @comment node-name, next, previous, up
3064 @subsection Specifying functions to mark up text
3065 @cindex publishing, markup functions
3067 @anchor{muse-publish-markup-functions}
3068 @code{muse-publish-markup-functions}
3070 An alist of style types to custom functions for that kind of text.
3072 This is used by publishing styles to attempt to minimize the amount of
3073 custom regexps that each has to define. @file{muse-publish} provides
3074 rules for the most common types of markup.
3076 Each member of the list is of the following form.
3084 Describes the type of text to associate with this rule.
3085 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3088 Function to use to mark up this kind of rule if no suitable function is
3089 found through the @option{:functions} tag of the current style.
3092 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3093 @comment node-name, next, previous, up
3094 @subsection Markup rules for publishing
3095 @cindex publishing, markup regexps
3096 @cindex publishing, rules
3098 @anchor{muse-publish-markup-regexps}
3099 @code{muse-publish-markup-regexps}
3101 List of markup rules for publishing a page with Muse.
3103 The rules given in this variable are invoked first, followed by whatever
3104 rules are specified by the current style.
3106 Each member of the list is either a function, or a list of the following
3110 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3115 A regular expression, or symbol whose value is a regular expression,
3116 which is searched for using `re-search-forward'.
3118 @item TEXT-BEGIN-GROUP
3119 The matching group within that regexp which denotes the beginning of the
3120 actual text to be marked up.
3122 @item REPLACEMENT-TEXT
3123 A string that will be passed to `replace-match'.
3125 If it is not a string, but a function, it will be called to determine
3126 what the replacement text should be (it must return a string). If it is
3127 a symbol, the value of that symbol should be a string.
3130 The replacements are done in order, one rule at a time. Writing
3131 the regular expressions can be a tricky business. Note that case
3132 is never ignored. `case-fold-search' is always bound to nil
3133 while processing the markup rules.
3135 @subheading Publishing order
3137 This is the order that the publishing rules are consulted, by default.
3138 This may be changed by customizing @code{muse-publish-markup-regexps}.
3142 @item trailing and leading whitespace
3143 Remove trailing and leading whitespace from a file.
3148 This is only recognized at the beginning of a file.
3151 @samp{; a commented line}
3159 @item explicit links
3160 Prevent emphasis characters in explicit links from being marked up.
3162 Don't actually publish them here, just add a special no-emphasis text
3166 Whitespace-delimited word, possibly with emphasis characters
3168 This function is responsible for marking up emphasis and escaping some
3174 Outline-mode style headings.
3179 These are ellipses with a dot at end.
3189 Horizontal rule or section separator.
3191 @item no-break-space
3194 Prevent lines from being split before or after these characters.
3199 beginning of footnotes section
3204 Footnote definition or reference. If at beginning of line, it is a
3219 Numbered list, item list, or term definition list.
3223 @file{table.el} style tables
3226 @samp{table | cells}
3228 Muse tables or orgtbl-mode style tables.
3231 spaces before beginning of text
3247 @samp{[[explicit][links]]}
3250 @samp{http://example.com/}
3253 @samp{bare-email@@example.com}
3257 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3258 @comment node-name, next, previous, up
3259 @subsection Strings specific to a publishing style
3260 @cindex publishing, markup strings
3262 @dfn{Markup strings} are strings used for marking up text for a
3265 These cover the most basic kinds of markup, the handling of which
3266 differs little between the various styles.
3268 @subheading Available markup strings
3272 @item image-with-desc
3273 An image and a description.
3275 Argument 1: image without extension. Argument 2: image extension.
3276 Argument 3: description.
3281 Argument 1: image without extension. Argument 2: image extension.
3284 An image with a link around it.
3286 Argument 1: link. Argument 2: image without extension.
3287 Argument 3: image extension.
3290 A reference to an anchor on the current page.
3292 Argument 1: anchor name. Argument 2: description if one exists, or the
3293 original link otherwise.
3296 A URL without a description.
3301 A link to a Muse page with a description.
3303 Argument 1: link. Argument 2: description if one exists, or the
3304 original link otherwise.
3306 @item link-and-anchor
3307 A link to a Muse page with an anchor, and a description.
3309 Argument 1: link. Argument 2: anchor name.
3310 Argument 3: description if one exists, or the original link otherwise.
3311 Argument 4: link without an extension.
3314 A link to an email address.
3316 Argument 1: email address. Argument 2: email address.
3321 Argument 1: name of anchor.
3326 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3329 Beginning of a comment.
3335 A horizontal line or space.
3337 @item no-break-space
3338 A space that separates two words which are not to be separated.
3341 Beginning of footnote.
3347 Mark a reference for the current footnote.
3349 Argument 1: number of this footnote.
3351 @item footnotemark-end
3352 End of a reference for the current footnote.
3355 Indicate the text of the current footnote.
3357 Argument 1: number of this footnote.
3359 @item footnotetext-end
3360 End of a footnote text line.
3363 Text used to replace ``Footnotes:'' line.
3372 Beginning of a part indicator line. This is used by book publishing.
3375 End of a part indicator line. This is used by book publishing.
3378 Beginning of a chapter indicator line. This is used by book publishing.
3381 End of a chapter indicator line. This is used by book publishing.
3384 Beginning of level 1 section indicator line.
3386 Argument 1: level of section; always 1.
3389 End of level 1 section indicator line.
3391 Argument 1: level of section; always 1.
3394 Beginning of level 2 section indicator line.
3396 Argument 1: level of section; always 2.
3398 @item subsection-end
3399 End of level 2 section indicator line.
3401 Argument 1: level of section; always 2.
3404 Beginning of level 3 section indicator line.
3406 Argument 1: level of section; always 3.
3408 @item subsubsection-end
3409 End of level 3 section indicator line.
3411 Argument 1: level of section; always 3.
3414 Beginning of section indicator line, where level is greater than 3.
3416 Argument 1: level of section.
3418 @item section-other-end
3419 End of section indicator line, where level is greater than 3.
3421 Argument 1: level of section.
3423 @item begin-underline
3424 Beginning of underlined text.
3427 End of underlined text.
3430 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3434 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3438 Beginning of the first level of emphasized text.
3441 End of the first level of emphasized text.
3443 @item begin-more-emph
3444 Beginning of the second level of emphasized text.
3447 End of the second level of emphasized text.
3449 @item begin-most-emph
3450 Beginning of the third (and final) level of emphasized text.
3453 End of the third (and final) level of emphasized text.
3456 Beginning of verse text.
3459 String used to each space that is further indented than the beginning of
3462 @item begin-verse-line
3463 Beginning of a line of verse.
3465 @item empty-verse-line
3466 End of a line of verse.
3468 @item begin-last-stanza-line
3469 Beginning of the last line of a verse stanza.
3471 @item end-last-stanza-line
3472 End of the last line of a verse stanza.
3478 Beginning of an example region. To make use of this, an
3479 @samp{<example>} tag is needed.
3482 End of an example region. To make use of this, an @samp{</example>} tag
3486 Begin a centered line.
3489 End a centered line.
3492 Begin a quoted region.
3495 End a quoted region.
3497 @item begin-quote-item
3498 Begin a quote paragraph.
3500 @item end-quote-item
3501 End a quote paragraph.
3504 Begin an unordered list.
3507 End an unordered list.
3509 @item begin-uli-item
3510 Begin an unordered list item.
3513 End an unordered list item.
3516 Begin an ordered list.
3519 End an ordered list.
3521 @item begin-oli-item
3522 Begin an ordered list item.
3525 End an ordered list item.
3528 Begin a definition list.
3531 End a definition list.
3534 Begin a definition list item.
3537 End a definition list item.
3540 Begin a definition list term.
3543 End a definition list term.
3546 Begin a definition list entry.
3549 End a definition list entry.
3557 @item begin-table-group
3558 Begin a table grouping.
3560 @item end-table-group
3561 End a table grouping.
3563 @item begin-table-row
3569 @item begin-table-entry
3570 Begin a table entry.
3572 @item end-table-entry
3577 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3578 @comment node-name, next, previous, up
3579 @subsection Tag specifications for special markup
3580 @cindex publishing, markup tags
3582 @anchor{muse-publish-markup-tags}
3583 @code{muse-publish-markup-tags}
3585 A list of tag specifications, for specially marking up text.
3587 XML-style tags are the best way to add custom markup to Muse. This is
3588 easily accomplished by customizing this list of markup tags.
3590 For each entry, the name of the tag is given, whether it expects a
3591 closing tag and/or an optional set of attributes, whether it is
3592 nestable, and a function that performs whatever action is desired within
3593 the delimited region.
3595 The tags themselves are deleted during publishing, before the function
3596 is called. The function is called with three arguments, the beginning
3597 and end of the region surrounded by the tags. If properties are
3598 allowed, they are passed as a third argument in the form of an alist.
3599 The `end' argument to the function is always a marker.
3601 Point is always at the beginning of the region within the tags, when the
3602 function is called. Wherever point is when the function finishes is
3603 where tag markup will resume.
3605 These tag rules are processed once at the beginning of markup, and once
3606 at the end, to catch any tags which may have been inserted in-between.
3608 @node Style Elements, , Markup Tags, Common Elements
3609 @comment node-name, next, previous, up
3610 @subsection Parameters used for defining styles
3611 @cindex publishing, style elements
3613 Style elements are tags that define a style. Use
3614 @code{muse-define-style} to create a new style.
3617 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3620 @subheading Usable elements
3625 File extension to use for publishing files with this style.
3628 File extension to use for publishing links to Muse files with this
3632 File extension to use for publishing second-stage files with this style.
3634 For example, PDF publishing generates a LaTeX file first, then a PDF
3635 from that LaTeX file.
3638 List of markup rules for publishing a page with Muse.
3639 @xref{muse-publish-markup-regexps}.
3642 An alist of style types to custom functions for that kind of text.
3643 @xref{muse-publish-markup-functions}.
3646 Strings used for marking up text with this style.
3648 These cover the most basic kinds of markup, the handling of which
3649 differs little between the various styles.
3652 A list of tag specifications, used for handling extra tags.
3653 @xref{muse-publish-markup-tags}.
3656 A table of characters which must be represented specially.
3659 A function that is to be executed on the newly-created publishing buffer
3660 (or the current region) before any publishing occurs.
3662 This is used to set extra parameters that direct the publishing process.
3665 A function that is to be executed on the publishing buffer (or the
3666 current region) immediately after applying all of the markup regexps.
3668 This is used to fix the order of table elements (header, footer, body)
3672 A function that is to be executed on the publishing buffer after
3673 :before-end, and immediately after inserting the header and footer.
3675 This is used for generating the table of contents as well as setting the
3679 A function that is to be executed after saving the published file, but
3680 while still in its buffer.
3682 This is used for generating second-stage documents like PDF files from
3683 just-published LaTeX files.
3686 Header used for publishing files of this style.
3688 This may be a variable, text, or a filename. It is inserted at the
3689 beginning of a file, after evaluating the publishing markup.
3692 Footer used for publishing files of this style.
3694 This may be a variable, text, or a filename. It is inserted at the end
3695 of a file, after evaluating the publishing markup.
3698 Style sheet used for publishing files of this style.
3700 This may be a variable or text. It is used in the header of HTML and
3701 XHTML based publishing styles.
3704 The function used to browse the published result of files of this style.
3708 @node Deriving Styles, , Common Elements, Extending Muse
3709 @comment node-name, next, previous, up
3710 @section Deriving a new style from an existing one
3711 @cindex publishing styles, deriving
3713 To create a new style from an existing one, use @code{muse-derive-style}
3714 as follows. This is a good way to fix something you don't like about a
3715 particular publishing style, or to personalize it.
3718 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3721 The derived name is a string defining the new style, such as "my-html".
3722 The base name must identify an existing style, such as "html" -- if you
3723 have loaded @file{muse-html}. The style parameters are the same as
3724 those used to create a style, except that they override whatever
3725 definitions exist in the base style. However, some definitions only
3726 partially override. The following parameters support partial
3729 @xref{Style Elements}, for a complete list of all parameters.
3734 If a markup function is not found in the derived style's function list,
3735 the base style's function list will be queried.
3738 All regexps in the current style and the base style(s) will be used.
3741 If a markup string is not found in the derived style's string list, the
3742 base style's string list will be queried.
3747 @node Getting Help and Reporting Bugs, History, Extending Muse, Top
3748 @comment node-name, next, previous, up
3749 @chapter Getting Help and Reporting Bugs
3750 @cindex help, getting
3751 @cindex bugs, reporting
3753 After you have read this guide, if you still have questions about
3754 Muse, or if you have bugs to report, there are several places you can
3760 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
3761 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
3765 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
3766 that Michael Olson (the current maintainer) made for Muse.
3769 Muse has several different mailing lists.
3773 @item muse-el-announce
3774 Low-traffic list for Muse-related announcements.
3776 You can join this mailing list (@email{muse-el-announce@@gna.org})
3777 using the subscription form at
3778 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
3779 mailing list is also available via Gmane (@url{http://gmane.org/}). The
3780 group is called @samp{gmane.emacs.muse.announce}.
3782 @item muse-el-discuss
3783 Discussion, bugfixes, suggestions, tips, and the like for Muse.
3784 This mailing list also includes the content of muse-el-announce.
3786 You can join this mailing list (@email{muse-el-discuss@@gna.org})
3787 using the subscription form at
3788 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
3789 list is also available via Gmane with the identifier
3790 @samp{gmane.emacs.muse.general}.
3793 Log messages for commits made to Muse.
3795 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
3796 the subscription form at
3797 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
3798 is also available via Gmane with the identifier
3799 @samp{gmane.emacs.muse.scm}.
3801 @item muse-el-commits
3802 Generated bug reports for Emacs Muse. If you use our bug-tracker at
3803 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
3804 sent to this list automatically.
3806 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
3807 the subscription form at
3808 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
3809 is also available via Gmane with the identifier
3810 @samp{gmane.emacs.muse.cvs}.
3812 @item muse-el-internationalization
3813 Discussion of translation of the Muse website and documentation into
3816 You can join this mailing list
3817 (@email{muse-el-internationalization@@gna.org}) using the subscription
3818 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
3819 mailing list is also available via Gmane with the identifier
3820 @samp{gmane.emacs.muse.internationalization}.
3825 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
3826 contributors are frequently around and willing to answer your
3827 questions. The @samp{#muse} channel is also available for
3828 Muse-specific help, and its current maintainer hangs out there.
3831 The maintainer of Emacs Muse, Michael Olson, may be contacted at
3832 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
3833 it is often better to use the muse-el-discuss mailing list.
3837 @node History, Contributors, Getting Help and Reporting Bugs, Top
3838 @comment node-name, next, previous, up
3839 @chapter History of This Document
3840 @cindex history, of Muse
3844 John Wiegley started Muse upon realizing that EmacsWiki had some serious
3845 limitations. Around February 2004, he started making "emacs-wiki version
3846 3.00 APLHA", which eventually became known as Muse.
3848 Most of those who frequent the emacs-wiki mailing list continued to use
3849 emacs-wiki, mainly because Planner hasn't been ported over to it.
3851 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
3852 John Wiegley's request.
3855 Michael Olson overhauled this document and added many new sections in
3856 preparation for the first release of Muse (3.01).
3860 @node Contributors, GNU Free Documentation License, History, Top
3861 @comment node-name, next, previous, up
3862 @chapter Contributors to This Documentation
3863 @cindex contributors
3865 The first draft of this document was taken from the emacs-wiki texinfo
3866 manual. Michael Olson adapted it for Muse and added most of its
3869 John Sullivan did a majority of the work on the emacs-wiki texinfo
3872 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
3873 emacs-wiki texinfo manual.
3876 @node GNU Free Documentation License, Concept Index, Contributors, Top
3877 @appendix GNU Free Documentation License
3878 @include doclicense.texi
3881 @node Concept Index, , GNU Free Documentation License, Top
3882 @comment node-name, next, previous, up