1 \input texinfo @c -*-texinfo-*-
9 * Muse: (muse). Authoring and publishing environment for Emacs.
15 This manual is for Emacs Muse version 3.10.
17 Copyright @copyright{} 2004, 2005, 2006,
18 2007 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU
25 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
26 license is included in the section entitled ``GNU Free Documentation
27 License'' in this manual.
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software. Copies published by the Free
31 Software Foundation raise funds for GNU development.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License. If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
38 All Emacs Lisp code contained in this document may be used, distributed,
39 and modified without restriction.
45 @subtitle an authoring and publishing environment
46 @subtitle for GNU Emacs and XEmacs
48 @c The following two commands
49 @c start the copyright page.
51 @vskip 0pt plus 1filll
55 @c So the toc is printed at the start
59 @node Top, Preface, (dir), (dir)
60 @comment node-name, next, previous, up
67 * Preface:: About the documentation.
68 * Introduction:: What is Muse?
69 * Obtaining Muse:: How to get Muse releases and development
71 * Installation:: Compiling and installing Muse.
72 * Getting Started:: Setting up Muse and editing files.
73 * Projects:: Creating and managing Muse projects.
74 * Keystroke Summary:: Keys used in Muse mode.
75 * Markup Rules:: Rules for using markup.
76 * Publishing Styles:: Publishing various types of documents.
77 * Extending Muse:: Making your own publishing styles.
78 * Miscellaneous:: Miscellaneous add-ons, like a minor mode.
79 * Getting Help and Reporting Bugs::
80 * History:: History of this document.
81 * Contributors:: Contributors to this documentation.
82 * GNU Free Documentation License:: The license for this documentation.
83 * Concept Index:: Search for terms.
86 --- The Detailed Node Listing ---
88 How to Get Muse Releases and Development Changes
90 * Releases:: Released versions of Muse.
91 * Development:: Latest unreleased development changes.
95 * Loading Muse:: How to load Muse.
96 * Using Muse Mode:: How to edit files in Muse.
97 * Publishing Files Overview:: Publishing a single file or project.
98 * File Extensions:: Using a different file extension.
100 Creating and Managing Muse Projects
102 * Single Project:: A single-project example.
103 * Multiple Projects:: A multiple-project example.
104 * Projects and Subdirectories:: Publishing subdirectories in projects.
105 * Options for Projects:: Listing of available options for projects.
107 Rules for Using Markup
109 * Paragraphs:: Paragraphs: centering and quoting.
110 * Headings:: Levels of headings.
111 * Directives:: Directives at the beginning of a
113 * Emphasizing Text:: Bold, italicized, and underlined text.
114 * Footnotes:: Making notes to be shown at the end.
115 * Verse:: Indicating poetic stanzas.
116 * Lists:: Lists of items.
117 * Tables:: Generation of data tables.
118 * Explicit Links:: Hyperlinks and email addresses with
120 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
122 * Images:: Publishing and displaying images.
123 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
124 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
126 * Comments:: Lines to omit from published output.
127 * Tag Summary:: Tags that Muse recognizes.
129 Publishing Various Types of Documents
131 * Blosxom:: Integrating Muse and pyblosxom.cgi.
132 * Book:: Publishing entries into a compilation.
133 * ConTeXt:: Publishing ConTeXt documents.
134 * DocBook:: Publishing in DocBook XML form.
135 * HTML:: Publishing in HTML or XHTML form.
136 * Journal:: Keeping a journal or blog.
137 * LaTeX:: Publishing LaTeX documents.
138 * Poem:: Publish a poem to LaTex or PDF.
139 * Texinfo:: Publish entries to Texinfo format or PDF.
140 * XML:: Publish entries to XML.
142 Integrating Muse and pyblosxom.cgi
144 * Blosxom Requirements:: Other tools needed for the Blosxom style.
145 * Blosxom Entries:: Format of a Blosxom entry and automation.
146 * Blosxom Options:: Blosxom styles and options provided.
148 Making your own publishing styles
150 * Common Elements:: Common functionality shared by styles.
151 * Deriving Styles:: Deriving a new style from an existing
154 Common functionality shared by styles
156 * Markup Functions:: Specifying functions to mark up text.
157 * Markup Regexps:: Markup rules for publishing.
158 * Markup Strings:: Strings specific to a publishing style.
159 * Markup Tags:: Tag specifications for special markup.
160 * Style Elements:: Parameters used for defining styles.
162 Miscellaneous add-ons, like a minor mode
164 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
169 @node Preface, Introduction, Top, Top
170 @comment node-name, next, previous, up
171 @chapter About the documentation
173 This document describes Muse, which was written by John Wiegley and is
174 now maintained by Michael Olson. Several versions of this manual are
178 @item PDF: http://mwolson.org/static/doc/muse.pdf
179 @item HTML (single file): http://mwolson.org/static/doc/muse.html
180 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
183 @node Introduction, Obtaining Muse, Preface, Top
184 @comment node-name, next, previous, up
185 @chapter What is Muse?
187 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
188 and publishing environment for Emacs. It simplifies the process of
189 writing documents and publishing them to various output formats.
191 Muse consists of two main parts: an enhanced text-mode for authoring
192 documents and navigating within Muse projects, and a set of publishing
193 styles for generating different kinds of output.
195 What makes Muse distinct from other text-publishing systems is a modular
196 environment, with a rather simple core, in which "styles" are derived
197 from to create new styles. Much of Muse's overall functionality is
198 optional. For example, you can use the publisher without the
199 major-mode, or the mode without doing any publishing; or if you don't
200 load the Texinfo or LaTeX modules, those styles won't be available.
202 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
203 code has been restructured and rewritten, especially its publishing
204 functions. The focus in this revision is on the authoring and
205 publishing aspects, and the "wikiness" has been removed as a default
206 behavior (available in the optional @file{muse-wiki} module). CamelCase
207 words are no longer special by default.
209 One of the principal aims in the development of Muse is to make it very
210 easy to produce good-looking, standards-compliant documents.
212 @node Obtaining Muse, Installation, Introduction, Top
213 @comment node-name, next, previous, up
214 @chapter How to Get Muse Releases and Development Changes
217 * Releases:: Released versions of Muse.
218 * Development:: Latest unreleased development changes.
221 @node Releases, Development, Obtaining Muse, Obtaining Muse
222 @comment node-name, next, previous, up
223 @section Released versions of Muse
225 Choose to install a release if you want to minimize risk.
227 Errors are corrected in development first. User-visible changes will be
228 announced on the @email{muse-el-discuss@@gna.org} mailing list.
229 @xref{Getting Help and Reporting Bugs}.
231 @cindex releases, Debian package
232 @cindex Debian package for Muse
233 Debian users can get Muse via apt-get. The @file{muse-el} package is
234 available both at Michael Olson's APT repository and the official Debian
235 repository. To make use of the former, add the following line to your
236 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
239 deb http://mwolson.org/debian/ ./
242 @cindex releases, Ubuntu package
243 @cindex Ubuntu package for Muse
244 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
245 is available both at Michael Olson's APT repository and the official
246 Ubuntu repository. To make use of the former, add the following line to
247 your @file{/etc/apt/sources.list} file and run @code{apt-get install
251 deb http://mwolson.org/ubuntu/ ./
254 The reason for making separate Debian and Ubuntu packages is that this
255 manual is under the GFDL, and Debian will not allow it to be distributed
256 in its main repository. Ubuntu, on the other hand, permits this manual
257 to be included with the @file{muse-el} package.
259 @cindex releases, from source
260 Alternatively, you can download the latest release from
261 @uref{http://download.gna.org/muse-el/} .
263 @node Development, , Releases, Obtaining Muse
264 @comment node-name, next, previous, up
265 @section Latest unreleased development changes
268 Choose the development version if you want to live on the bleeding edge
269 of Muse development or try out new features before release.
271 @cindex git version control system, using
272 The git version control system allows you to keep up-to-date with the
273 latest changes to the development version of Muse. It also allows you
274 to contribute changes (via commits, if you are have developer access to
275 the repository, or via patches, otherwise). If you would like to
276 contribute to Muse development, it is highly recommended that you use
279 If you are new to git, you might find this tutorial helpful:
280 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
282 Downloading the Muse module with git and staying up-to-date involves
289 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
290 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
291 @item Other operating systems: download, compile, and install the source
292 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
293 package for your operating system.
296 @item Download the Muse development branch.
298 If you have developer access to Muse, do:
301 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
307 git clone git://repo.or.cz/muse-el.git muse
310 If you are behind a restrictive firewall, and do not have developer
311 access, then do the following instead:
314 git clone http://repo.or.cz/r/muse-el.git muse
317 @item List upstream changes that are missing from your local copy.
318 Do this whenever you want to see whether new changes have been committed
319 to Muse. If you wish, you may skip this step and proceed directly to
323 # Change to the source directory you are interested in.
326 # Fetch new changes from the repository, but don't apply them yet
329 # Display log messages for the new changes
333 ``origin'' is git's name for the location where you originally got Muse
334 from. You can change this location at any time by editing the
335 @file{.git/config} file in the directory where the Muse source was
338 @cindex updating Muse with git
339 @item Update to the latest version by pulling in any missing changes.
346 git will show how many files changed, and will provide a visual display
347 for how many lines were changed in each file.
351 There are other ways to interact with the Muse repository.
354 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
355 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
356 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
359 The latest development snapshot can lag behind the git repo by as much
360 as 20 minutes, but never more than that.
362 @subheading Becoming a Muse developer
363 @cindex developer, becoming
365 If you want commit access to the shared Muse repository, then register
366 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
367 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
368 best to send some patches to the @email{muse-el-discuss@@gna.org}
369 mailing list first, so that he knows that you know what you are doing.
370 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
373 You must also be willing to sign a copyright assignment for your changes
374 to Muse, since Muse is a GNU project. The current maintainer will
375 assist you in this process if you contact him.
377 For information on committing changes to Muse and performing
378 development, please consult
379 @uref{http://emacswiki.org/cgi-bin/wiki/MuseDevelopment}.
381 @node Installation, Getting Started, Obtaining Muse, Top
382 @comment node-name, next, previous, up
383 @chapter Compiling and Installing Muse
385 Muse may be compiled and installed on your machine.
387 @subheading Compilation
388 @cindex compiling Muse
390 This is an optional step, since Emacs Lisp source code does not
391 necessarily have to be byte-compiled. Byte-compilation may yield a very
392 slight speed increase.
394 A working copy of Emacs or XEmacs is needed in order to compile Emacs
395 Muse. By default, the program that is installed with the name
396 @command{emacs} will be used.
398 If you want to use the @command{xemacs} binary to perform the
399 compilation, you must copy @file{Makefile.defs.default} to
400 @file{Makefile.defs} in the top-level directory, and then edit
401 @file{Makefile.defs} as follows. You can put either a full path to an
402 Emacs or XEmacs binary or just the command name, as long as it is in the
403 @env{PATH}. Depending on your setup, changes to the @option{PREFIX},
404 @option{ELISPDIR}, and/or @option{INFODIR} variables may also need to be
409 SITEFLAG = -no-site-file
410 # Edit the section as necessary
411 install_info = install-info --section "XEmacs 21.4" $(1).info \
415 Running @code{make} in the top-level directory should compile the Muse
416 source files in the @file{lisp} directory, and generate an autoloads
417 file in @file{lisp/muse-autoloads.el}.
419 @subheading Installation
420 @cindex installing Muse
422 Muse may be installed into your file hierarchy by doing the following.
424 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
425 top-level directory, if you haven't done so already. Then edit the
426 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
427 want the source and compiled Muse files to be installed and
428 @env{INFODIR} indicates where to put the Muse manual. As mentioned
429 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
430 in the Compilation section if you are using XEmacs.
432 If you are installing Muse on a Debian or Ubuntu system, you might want
433 to change the value of @env{INSTALLINFO} as specified in
434 @file{Makefile.defs}.
436 If you wish to install Muse to different locations than the defaults
437 specify, edit @file{Makefile.defs} accordingly.
439 Run @code{make} as a normal user, if you haven't done so already.
441 Run @code{make install} as the root user if you have chosen installation
442 locations that require root permissions.
445 @cindex ELPA package for Muse
447 For those used to installing software packages, there will be a
448 @code{muse} package available in the Emacs Lisp Package Archive
449 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
450 will be compiled and installed automatically in a user-specific
451 location. For more information on ELPA, see
452 @uref{http://tromey.com/elpa/}.
454 @node Getting Started, Projects, Installation, Top
455 @comment node-name, next, previous, up
456 @chapter Getting Started
460 * Loading Muse:: How to load Muse.
461 * Using Muse Mode:: How to edit files in Muse.
462 * Publishing Files Overview:: Publishing a single file or project.
463 * File Extensions:: Using a different file extension.
466 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
467 @comment node-name, next, previous, up
468 @section How to Load Muse
469 @cindex settings, init file
471 To use Muse, add the directory containing its files to your
472 @code{load-path} variable, in your @file{.emacs} file. Then, load in
473 the authoring mode, and the styles you wish to publish to. An example
477 (add-to-list 'load-path "<path to Muse>")
479 (require 'muse-mode) ; load authoring mode
481 (require 'muse-html) ; load publishing styles I use
482 (require 'muse-latex)
483 (require 'muse-texinfo)
484 (require 'muse-docbook)
486 (require 'muse-project) ; publish files in projects
489 An easy way of seeing which settings are available and changing settings
490 is to use the Muse customization interface. To do this, type
491 @kbd{M-x customize-group muse RET}. Each of the options has its own
492 documentation. Options are grouped logically according to what effect
495 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
496 @comment node-name, next, previous, up
497 @section How to Edit Files in Muse
498 @cindex editing Muse files
500 Muse Mode should automatically be activated when you visit a file with a
501 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
502 available in the @file{examples} directory of the Muse distribution.
503 You can tell that Muse Mose has been activated by checking for the text
504 ``Muse'' in your mode line. If Muse Mode has not been activated, you
505 may activate it by type @kbd{M-x muse-mode RET}.
507 You will notice that Muse files are highlighted very simply. Links are
508 colored blue, headings are large and bold text, and @verb{|<example>|}
509 tags are colored in grey.
511 There are several different ways to edit things like links, which hide
512 the underlying Muse markup. One way is to toggle font-locking off by
513 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
514 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
515 on. Another way is just to move into the text and edit it. Markup can
516 also be removed by normal deletion methods, though some side effects
517 might require a second deletion.
519 For the particular case of editing links, it is easiest to move to the
520 link and do @kbd{C-c C-e}, which is also @kbd{M-x
521 muse-edit-link-at-point}. This prompts you for the link and its
522 description, using the previous contents of the link as initial values.
523 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
524 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
525 followed by hitting @kbd{RET} on them.
527 If you want to add a new list item, this may by accomplished by hitting
528 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
529 dash is the Muse markup that indicates a list item. It is also possible
530 to created ``nested'' lists with this command, by adjusting the number
531 of spaces in front of the dashes. If you have lists with long lines,
532 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
535 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
536 @comment node-name, next, previous, up
537 @section Publishing a Single File or Project
538 @cindex editing Muse files
540 The command @kbd{M-x muse-project-publish-this-file} will publish the
541 current document to any available publishing style (a publishing style
542 is an output format, like HTML or Docbook), placing the output in the
543 current directory. If you are in Muse Mode, this command will be bound
544 to @kbd{C-c C-t}. If the file has been published recently, and its
545 contents have not changed, running @kbd{C-c C-t} again will not publish
546 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
548 If you have set up projects and are visiting a file that is part of a
549 project, then @kbd{C-c C-t} will restrict the output formats to those
550 which are used by the project, and will automatically publish to the
551 output directory defined by the project. If you want to publish to a
552 different directory or use a different format, then use @kbd{C-c M-C-t},
553 which is also @kbd{M-x muse-publish-this-file}.
555 If the currently opened file is part of a defined project in
556 @code{muse-project-alist}, it (and the rest of the changed files in a
557 project) may be published using @kbd{C-c C-p}.
559 @node File Extensions, , Publishing Files Overview, Getting Started
560 @comment node-name, next, previous, up
561 @section Using a Different File Extension
562 @cindex file extension, specifying
564 By default, Muse expects all project files to have the file extension
565 @file{.muse}. Files without this extension will not be associated with
566 Muse mode and will not be considered part of any project, even if they
567 are within a project directory.
569 If you don't want to use @file{.muse}, you can customize the extension
570 by setting the value of @code{muse-file-extension}.
572 If you don't want to use any extension at all, and want Muse to
573 autodetect project files based on their location, then add the following
574 to your Muse settings file.
577 (setq muse-file-extension nil
581 Note that if you chose to have @code{muse-file-extension} set to
582 @code{nil}, you may have trouble if your @file{.emacs} file or other
583 init scripts attempt to visit a Muse file. (A very common example of
584 this is if you use Planner with Muse and run @code{(plan)} from your
585 @file{.emacs}.) If you wish to visit Muse files from your
586 @file{.emacs}, be sure to also add the following additional code before
587 any such visits happen:
590 (add-hook 'find-file-hooks 'muse-mode-maybe)
594 @node Projects, Keystroke Summary, Getting Started, Top
595 @comment node-name, next, previous, up
596 @chapter Creating and Managing Muse Projects
599 Often you will want to publish all the files within a directory to a
600 particular set of output styles automatically. To support, Muse
601 allows for the creation of "projects".
604 * Single Project:: A single-project example.
605 * Multiple Projects:: A multiple-project example.
606 * Projects and Subdirectories:: Publishing subdirectories in projects.
607 * Options for Projects:: Listing of available options for projects.
610 @node Single Project, Multiple Projects, Projects, Projects
611 @comment node-name, next, previous, up
612 @section A Single-Project Example
613 @cindex projects, single
615 Here is a sample project, which may be defined in your @file{.emacs}
619 (setq muse-project-alist
620 '(("Website" ("~/Pages" :default "index")
621 (:base "html" :path "~/public_html")
622 (:base "pdf" :path "~/public_html/pdf"))))
625 The above defines a project named "website", whose files are located
626 in the directory @file{~/Pages}. The default page to visit is
627 @file{index}. When this project is published, each page will be
628 output as HTML to the directory @file{~/public_html}, and as PDF to
629 the directory @file{~/public_html/pdf}. Within any project page, you
630 may create a link to other pages using the syntax @samp{[[pagename]]}.
632 If you would like to include only some files from a directory in a Muse
633 project, you may use a regexp in place of @file{~/Pages} in the example.
635 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
636 @comment node-name, next, previous, up
637 @section A Multiple-Project Example
638 @cindex projects, multiple
640 It is possible to specify multiple projects. Here is an example of
641 three projects: a generic website, a projects area, and a day-planner
642 (the day-planner part requires Planner Mode---see
643 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
646 (setq muse-project-alist
647 '(("Website" ("~/Pages" :default "index")
648 (:base "html" :path "~/public_html"))
649 (("Projects" ("~/Projects" :default "index")
651 :path "~/public_html/projects"
652 :exclude "/TopSecret")
654 :path "~/public_html/projects/pdf"
655 :exclude "/TopSecret")))
658 :major-mode planner-mode
659 :visit-link planner-visit-link)
660 (:base "planner-xhtml"
661 :path "~/public_html/plans"))))
664 The @option{:major-mode} attribute specifies which major to use when
665 visiting files in this directory.
667 The @option{:visit-link} attribute specifies the function to call when
670 The @option{:exclude} attribute has a regexp that matches files to never
673 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
674 @comment node-name, next, previous, up
675 @section Publishing Subdirectories in Projects
676 @cindex projects, subdirectories
678 If you want to publish a directory and all of its subdirectories, Muse
679 provides two convenience functions that together generate the proper
680 rules for you. Note that we use the backtick to begin this
681 muse-project-alist definition, rather than a single quote.
684 (setq muse-project-alist
685 `(("Website" ("~/Pages" :default "index")
686 (:base "html" :path "~/public_html"))
687 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
689 ;; Publish this directory and its subdirectories. Arguments
690 ;; are as follows. The above `muse-project-alist-dirs' part
692 ;; 1. Source directory
693 ;; 2. Output directory
694 ;; 3. Publishing style
695 ;; remainder: Other things to put in every generated style
696 ,@@(muse-project-alist-styles "~/Blog"
701 The @code{muse-project-alist-dirs} function takes a directory and
702 returns it and all of its subdirectories in a list.
704 The @code{muse-project-alist-styles} function is explained by the
707 The ``blosxom'' text is the name of another publishing style, much like
708 ``html''. @xref{Blosxom}, for further information about it. You can
709 use any publishing style you like for the third argument to
710 @code{muse-project-alist-styles}.
712 @node Options for Projects, , Projects and Subdirectories, Projects
713 @comment node-name, next, previous, up
714 @section Listing of Available Options for Projects
715 @cindex projects, options
716 @cindex muse-project-alist, reference
718 This is a listing of all of the various options (or, more accurately:
719 attributes) that may be specified in @code{muse-project-alist}.
721 Each muse-project-alist entry looks like this:
724 (PROJECT-NAME (SOURCES)
728 We refer to these names below.
730 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
731 The first value is a keyword, like @option{:default}. The second part
732 is the value associated with that keyword, such as the text ``index''.
733 If you are familiar with Emacs Lisp property lists, the concept is
734 similar to that, except that in the SOURCES section, single directories
735 can be interspersed with two-value attributes.
737 @subheading Project Name
739 This is a string that indicates the name of the project. It is
740 primarily used for publishing interwiki links with the
741 @file{muse-wiki.el} module.
745 This part of a muse-project-alist entry consists of two-value
746 attributes, and also directory names. If you are publishing a book, the
747 order of directories and attributes is significant.
749 The minimal content for the sources section is a list of directories.
754 Indicates a new chapter of a book. The text of the title of the chapter
755 comes immediately after this keyword.
758 Indicates the end of a book. Directories listed after this one are
759 ignored when publishing a book. The value ``t'' (without quotes) should
760 come immediately after this keyword.
763 A function to call while publishing a book. This is useful for doing
764 something just after a particular chapter.
767 Indicates the beginning of a new part of the book. The text of the
768 title should come immediately after this keyword.
771 Indicate a particular publishing style to use for this part of the book.
772 If this is specified, it should come just after a @option{:part}
776 The default page to visit when browsing a project. Also, if you are
777 using the @file{muse-wiki.el} module, publishing a link to just a
778 project's name will cause it to link to this default file.
781 This specifies a list of pages which should be published every time a
782 project is published (by using @kbd{C-c C-p}, for example), regardless
783 of whether their contents have changed. This is useful for updating
784 Index pages, pages that use the @verb{|<include>|} tag, and other pages
785 that have dynamically-generated content.
788 This specifies the major mode to use when visiting files in this
789 project. The default is @code{muse-mode}.
792 This indicates that while publishing a book, do not automatically create
793 chapters. Values which may follow this are nil (the default, which
794 means that we automatically create chapters), or non-nil, which means
795 that we manually specify chapters with the @option{:book-chapter}
798 @item :publish-project
799 Indicates which function we should call when publishing a project.
802 This specifies a list of variables and values to set when publishing a
803 project. The list should be a property list, which is in the form:
806 (VAR1 VALUE1 VAR2 VALUE2 ...)
810 Specifies the function to call when visiting a link. The default is
811 @code{muse-visit-link-default}. The arguments for that function should
812 be (1) the link and (2) whether to visit the link in a new window.
818 This part of a muse-project-alist entry is composed of lists of
819 attributes. Each list is called an ``output style''.
821 The minimal content for an output style is a @option{:base} attribute
822 and a @option{:path} attribute.
827 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
830 An external URL which can be used to access published files. This is
831 mainly used by the @file{muse-wiki} module when publishing links between
832 two separate projects, if the projects are served on different domains.
834 It is also used by the @file{muse-journal} module to create the RSS or
838 Exclude items matching a regexp from being published. The regexp should
839 usually begin with "/".
842 Only include items matching a regexp when publishing. The regexp should
843 usually begin with "/".
846 The directory in which to store published files.
849 A file containing the timestamps (that is, time of creation) for files
850 in this project. It might eventually used by the @file{muse-blosxom}
851 module, but this option is not currently in use by any Muse code.
856 @node Keystroke Summary, Markup Rules, Projects, Top
857 @comment node-name, next, previous, up
858 @chapter Keys Used in Muse Mode
861 This is a summary of keystrokes available in every Muse buffer.
865 @item C-c C-a (`muse-index')
866 Display an index of all known Muse pages.
868 @item C-c C-b (`muse-find-backlinks')
869 Find all pages that link to this page.
871 @item C-c C-e (`muse-edit-link-at-point')
874 @item C-c C-f (`muse-project-find-file')
875 Open another Muse page. Prompt for the name.
877 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
878 Insert a link to a file interactively.
880 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
881 Insert a tag interactively.
883 @item C-c C-i u, C-c TAB u (`muse-insert-url')
884 Insert a URL interactively.
886 @item C-c C-l (`font-lock-mode')
887 Toggle font lock / highlighting for the current buffer.
889 @item C-c C-p (`muse-project-publish')
890 Publish any Muse pages that have changed.
892 @item C-c C-s (`muse-search')
893 Find text in all files of the current project.
895 @item C-c C-t (`muse-project-publish-this-file')
896 Publish the currently-visited file. Prompt for the style if the current
897 file can be published using more than one style.
899 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
900 Publish the currently-visited file. Prompt for both the style and
903 @item C-c C-v (`muse-browse-result')
904 Show the published result of this page.
906 @item C-c = (`muse-what-changed')
907 Diff this page against the last backup version.
910 Move to the next Wiki reference.
913 Move to the previous Wiki reference.
916 Complete the name of a page from the current project at point.
919 Insert a new list item at point, indenting properly.
922 Decrease the indentation of the list item at point.
925 Increase the indentation of the list item at point.
927 @item M-x muse-colors-toggle-inline-images RET
928 Toggle display of inlined images on/off.
933 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
934 @comment node-name, next, previous, up
935 @chapter Rules for Using Markup
938 A Muse document uses special, contextual markup rules to determine how
939 to format the output result. For example, if a paragraph is indented,
940 Muse assumes it should be quoted.
942 There are not too many markup rules, and all of them strive to be as
943 simple as possible so that you can focus on document creation, rather
947 * Paragraphs:: Paragraphs: centering and quoting.
948 * Headings:: Levels of headings.
949 * Directives:: Directives at the beginning of a
951 * Emphasizing Text:: Bold, italicized, and underlined text.
952 * Footnotes:: Making notes to be shown at the end.
953 * Verse:: Indicating poetic stanzas.
954 * Lists:: Lists of items.
955 * Tables:: Generation of data tables.
956 * Explicit Links:: Hyperlinks and email addresses with
958 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
960 * Images:: Publishing and displaying images.
961 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
962 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
964 * Comments:: Lines to omit from published output.
965 * Tag Summary:: Tags that Muse recognizes.
968 @node Paragraphs, Headings, Markup Rules, Markup Rules
969 @comment node-name, next, previous, up
970 @section Paragraphs: centering and quoting
973 Paragraphs in Muse must be separated by a blank line.
975 @cindex paragraphs, centered
976 @subheading Centered paragraphs and quotations
978 A line that begins with six or more columns of whitespace (either tabs
979 or spaces) indicates a centered paragraph. Alternatively, you can use
980 the @verb{|<center>|} tag to surround regions that are to be published as
983 @cindex paragraphs, quoted
985 But if a line begins with whitespace, though less than six columns, it
986 indicates a quoted paragraph. Alternatively, you can use the
987 @verb{|<quote>|} tag to surround regions that are to be published as
991 @cindex monospace, rendering blocks
992 @cindex HTML, rendering blocks in monospace
993 @subheading Literal paragraphs
995 The @verb{|<example>|} tag is used for examples, where whitespace should
996 be preserved, the text rendered in monospace, and any characters special
997 to the output style escaped.
1000 @cindex HTML, inserting a raw block
1001 There is also the @verb{|<literal>|} tag, which causes a marked block to
1002 be entirely left alone. This can be used for inserting a hand-coded
1003 HTML blocks into HTML output, for example.
1005 If you want some text to only be inserted when publishing to a
1006 particular publishing style, use the @option{style} attribute for the
1007 @verb{|<literal>|} tag. An example follows.
1010 <literal style="latex">
1011 A LaTeX-based style was used in the publishing of this document.
1015 This will leave the region alone if the current publishing style is
1016 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
1017 otherwise. It is also possible to leave the text alone only for one
1018 particular style, rather than its derivations, by adding
1019 @code{exact="t"} to the tag.
1021 @node Headings, Directives, Paragraphs, Markup Rules
1022 @comment node-name, next, previous, up
1023 @section Levels of headings
1026 A heading becomes a chapter or section in printed output -- depending on
1027 the style. To indicate a heading, start a new paragraph with one or
1028 more asterices, followed by a space and the heading title. Then begin
1029 another paragraph to enter the text for that section.
1031 All levels of headings will be published. Most publishing styles only
1032 distinguish the between the first 4 levels, however.
1044 @node Directives, Emphasizing Text, Headings, Markup Rules
1045 @comment node-name, next, previous, up
1046 @section Directives at the beginning of a document
1049 Directives are lines beginning with the @samp{#} character that come
1050 before any paragraphs or sections in the document. Directives are of
1051 the form ``#directive content of directive''. You can use any
1052 combination of uppercase and lowercase letters for directives, even if
1053 the directive is not in the list below.
1055 The @code{muse-publishing-directive} function may be used in header and
1056 footer text to access directives. For example, to access the
1057 @samp{#title} directive, use @code{(muse-publishing-directive "title")}.
1059 The following is a list of directives that Muse uses.
1064 The author of this document.
1066 If this is not specified, Muse will attempt to figure it out from the
1067 @code{user-full-name} variable.
1071 The date that the document was last modified.
1073 This is used by publishing styles that are able to embed the date
1078 A short description of this document.
1080 This is used by the @code{journal} publishing style to embed information
1081 inside of an RSS/RDF feed.
1085 The title of this document.
1087 If this is not specified, the name of the file is used.
1091 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1092 @comment node-name, next, previous, up
1093 @section Bold, italicized, and underlined text
1094 @cindex emphasizing text
1095 @cindex underlining text
1096 @cindex italicizing text
1097 @cindex verbatim text
1098 @cindex monospace, rendering words
1100 To emphasize text, surround it with certain specially recognized
1106 ***very strong emphasis***
1108 =verbatim and monospace=
1112 While editing a Muse document in Muse mode, these forms of emphasis will
1113 be highlighted in a WYSIWYG manner. Each of these forms may span
1116 Verbatim text will be colored as gray by default. To change this,
1117 customize @code{muse-verbatim-face}.
1119 You can also use the @verb{|<code>|} tag to indicate verbatim and
1120 monospace text. This is handy for regions that have an ``='' in them.
1122 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1123 @comment node-name, next, previous, up
1124 @section Making notes to be shown at the end
1127 A footnote reference is simply a number in square brackets. To define
1128 the footnote, place this definition at the bottom of your file.
1129 @samp{footnote-mode} can be used to greatly facilitate the creation of
1130 these kinds of footnotes.
1132 Footnotes are defined by the same number in brackets occurring at the
1133 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1134 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1135 the point of insertion.
1137 @node Verse, Lists, Footnotes, Markup Rules
1138 @comment node-name, next, previous, up
1139 @section Indicating poetic stanzas
1143 Poetry requires that whitespace be preserved, but without resorting to
1144 monospace. To indicate this, use the following markup, reminiscent of
1148 > A line of Emacs verse;
1149 > forgive its being so terse.
1152 You can also use the @verb{|<verse>|} tag, if you prefer.
1156 A line of Emacs verse;
1157 forgive its being so terse.
1161 @cindex verses, multiple stanzas
1162 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1167 A line of Emacs verse;
1168 forgive its being so terse.
1170 In terms of terse verse,
1175 @node Lists, Tables, Verse, Markup Rules
1176 @comment node-name, next, previous, up
1177 @section Lists of items
1180 Lists are given using special characters at the beginning of a line.
1181 Whitespace must occur before bullets or numbered items, to distinguish
1182 from the possibility of those characters occurring in a real sentence.
1184 @cindex lists, bullets
1185 These are rendered as a bullet list.
1194 @cindex lists, enumerated
1195 An enumerated list follows.
1204 @cindex lists, definitions
1205 Here is a definition list.
1209 This is a first definition
1210 And it has two lines;
1211 no, make that three.
1213 Term2 :: This is a second definition
1216 @subheading Nested lists
1218 @cindex lists, nested
1219 It is possible to nest lists of the same or different kinds. The
1220 ``level'' of the list is determined by the amount of initial whitespace.
1225 - Level 1, bullet item one
1226 1. Level 2, enum item one
1227 2. Level 2, enum item two
1228 - Level 1, bullet item two
1229 1. Level 2, enum item three
1230 2. Level 2, enum item four
1234 @subheading Breaking list items
1236 @cindex lists, breaking lines
1237 If you want to break up a line within any list type, just put one blank
1238 line between the end of the previous line and the beginning of the next
1239 line, using the same amount of initial indentation.
1242 - bullet item 1, line 1
1244 bullet item 1, line 2
1250 - bullet item 2, line 1
1252 bullet item 2, line 2
1255 @node Tables, Explicit Links, Lists, Markup Rules
1256 @comment node-name, next, previous, up
1257 @section Generation of data tables
1260 @cindex tables, simple
1261 Only very simple tables are supported. The syntax is as follows.
1264 Double bars || Separate header fields
1266 Single bars | Separate body fields
1267 Here are more | body fields
1269 Triple bars ||| Separate footer fields
1272 Some publishing styles require header fields to come first, then footer
1273 fields, and then the body fields. You can use any order for these
1274 sections that you like, and Muse will re-order them for you at
1277 If you wish to disable table generation for one Muse file, add the
1278 directive @samp{#disable-tables t} to the top of the file.
1280 @subheading Other table formats
1282 @cindex tables, orgtbl-mode style
1283 It is possible to publish very basic Orgtbl-mode style tables.
1286 | org | style | table |
1287 |------+-------+-------|
1291 |------+-------+-------|
1295 If you are used to the way that Org Mode publishes these tables, then
1296 customize `muse-html-table-attributes' to the following, in order to get
1297 a similar kind of output.
1300 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1303 @cindex tables, table.el style
1304 @file{table.el} style tables are also supported, as long as
1305 @file{table.el} itself supports outputting tables for a particular
1306 publishing style. At the time of this writing, the ``html'', ``latex'',
1307 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1308 from these styles will also work.
1320 @node Explicit Links, Implicit Links, Tables, Markup Rules
1321 @comment node-name, next, previous, up
1322 @section Hyperlinks and email addresses with descriptions
1323 @cindex links, explicit
1325 A hyperlink can reference a URL, or another page within a Muse
1326 project. In addition, descriptive text can be specified, which should
1327 be displayed rather than the link text in output styles that supports
1328 link descriptions. The syntax is as follows.
1331 [[link target][link description]]
1332 [[link target without description]]
1335 Thus, the current maintainer's homepage for Muse can be found
1336 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1337 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1339 @node Implicit Links, Images, Explicit Links, Markup Rules
1340 @comment node-name, next, previous, up
1341 @section Bare URLs, WikiNames, and InterWiki links
1342 @cindex links, implicit
1346 @cindex Email addresses
1348 A URL or email address encountered in the input text is published as a
1349 hyperlink. These kind of links are called @dfn{implicit links} because
1350 they are not separated from the rest of the Muse document in any way.
1352 Some characters in URLs will prevent Muse from recognizing them as
1353 implicit links. If you want to link to a URL containing spaces or any of
1354 the characters ``][,"'`()<>^'', you will have to make the link
1355 explicit. The punctuation characters ``.,;:'' are also not recognized as
1356 part of a URL when they appear at its end. For information on how to
1357 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1358 addresses with descriptions}.
1361 If the @command{muse-wiki} module is loaded, another form of implicit
1362 link will be made available. WikiNames, which are typed in CamelCase,
1363 are highlighted and published as links, provided that the file they
1366 Customization of WikiName recognition may be accomplished by editing the
1367 @code{muse-wiki-wikiword-regexp} option and subsequently running
1368 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1369 If you use the Customize interface, the latter will be done
1372 @cindex InterWiki links
1373 @cindex inter-project links
1374 The @command{muse-wiki} module also allows for InterWiki links. These
1375 are similar to WikiWords, but they specify both the project and page of
1376 a file. The names of your project entries in @code{muse-project-alist}
1377 will be used as InterWiki names by default. Several examples follow.
1380 Blog::DocumentingMuse
1385 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1386 the project name, and @samp{DocumentingMuse} is the page name. In the
1387 second example, @samp{#} is the interwiki delimiter. If the name of a
1388 project occurs by itself in text, like the third case, it will be
1389 colorized and published as a link to the default page of the given
1392 Customization of interwiki links may be accomplished by editing the
1393 @code{muse-wiki-interwiki-alist} option.
1395 It is also possible to link to an anchor in an interwiki document. This
1396 is called a ``three-part link''. Examples of this follow.
1399 Blog::DocumentingMuse#anchor1
1400 Projects#EmacsMuse#anchor2
1403 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1404 @comment node-name, next, previous, up
1405 @section Publishing and displaying images
1407 @cindex links, with images
1408 @subheading Image links
1410 Links to images may be used in either the target or the description, or
1411 both. Thus, the following code will publish as a clickable image that
1412 points to @url{http://mwolson.org/}.
1415 [[http://mwolson.org/][/static/logos/site-logo.png]]
1418 Normally, images in the link part will be inlined.
1420 If you want these images to be published as links instead, place the
1421 text ``URL:'' immediately in front of the link text. An example
1425 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1428 @cindex images, displaying
1429 @cindex images, local
1430 @subheading Displaying images in Muse mode
1431 If a link to a locally-available image is encountered in the link
1432 description, Muse mode will attempt to display it if your version of
1435 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1436 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1438 The method for finding images may be altered by customizing the
1439 @code{muse-colors-inline-image-method} option. One useful value for
1440 this option is @code{muse-colors-use-publishing-directory}, which tells
1441 Muse mode to look in the directory where the current file will be
1442 published. The default is to look in the current directory. Relative
1443 paths like @samp{../pics/} should work for either setting.
1445 Eventually, it is hoped that Muse will be able to copy images from the a
1446 ``source'' directory to a publishing directory by customizing
1447 @code{muse-project-alist}, but this has not been implemented yet.
1449 @cindex images, without descriptions
1450 @cindex images, inlined
1451 @subheading Publishing simple images
1452 The following example will display correctly and publish correctly if a
1453 @acronym{PNG} file called @file{TestLogo.png} exists in the
1454 @file{../pics/} directory. If text is on the same line as the picture,
1455 it will remain so in the output.
1461 @cindex images, captions
1462 @subheading Publishing images with captions
1463 If you want to add a caption to an image, use the following syntax.
1464 This will center the image (if the output format supports it) and add a
1465 centered caption below the picture. Formats that do not support
1466 centering the image will instead leave it against the left margin.
1469 [[../pics/mycat.png][My cat Dexter]]
1472 Images with captions may only occur in their own paragraphs, with no
1473 text on the same line. Otherwise, the published output will not be
1474 syntactically correct.
1476 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1477 @comment node-name, next, previous, up
1478 @section Inserting a horizontal line or anchor
1480 @cindex horizontal rules
1482 @subheading Horizontal Rules
1484 Four or more dashes indicate a horizontal rule. Be sure to put blank
1485 lines around it, or it will be considered part of the proceeding or
1486 following paragraph!
1489 @cindex links, with target on same page
1492 If you begin a line with "#anchor" -- where "anchor" can be any word
1493 that doesn't contain whitespace -- it defines an anchor at that point
1494 into the document. This point can be referenced using "page#anchor" as
1495 the target in a Muse link.
1497 @node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
1498 @comment node-name, next, previous, up
1499 @section Evaluating Emacs Lisp code in documents for extensibility
1500 @cindex lisp, embedded
1502 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1503 which is the only Muse tag supported in a style's header and footer
1504 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1505 text you wish. The inserted output will get marked up, if the
1506 @verb{|<lisp>|} tag appears within the main text of the document.
1509 <lisp>(concat "This form gets " "inserted")</lisp>
1512 @cindex lisp, and insert command
1513 Note that you should not use the @code{insert} command within a set of
1514 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1515 tags will be automatically inserted into the document.
1517 It is also possible to treat the output as if it were surrounded by the
1518 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1519 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1520 attribute of the @verb{|<lisp>|} tag.
1523 <lisp markup="example">
1524 (concat "Insert" " me")
1528 Other languages also have tags that cause source code to be evaluated.
1529 @xref{Tag Summary}, for details.
1531 @node Comments, Tag Summary, Embedded Lisp, Markup Rules
1532 @comment node-name, next, previous, up
1533 @section Lines to omit from published output
1535 @cindex publishing, omitting lines
1537 Use the following syntax to indicate a comment. Comments will not be
1541 ; Comment text goes here.
1544 That is, only a semi-colon at the beginning of a line, followed by a
1545 literal space, will cause that line to be treated as a comment.
1547 You can alternatively surround the region with the @verb{|<comment>|}
1550 If you wish the comment to be published, but just commented out using
1551 the comment syntax of the output format, then set
1552 @option{muse-publish-comments-p} to non-nil.
1554 @node Tag Summary, , Comments, Markup Rules
1555 @comment node-name, next, previous, up
1556 @section Tags that Muse recognizes
1558 @cindex inserting files at publish time
1559 @cindex publishing, including markup in headers and footers
1560 @cindex publishing, inserting files
1562 Muse has several built-in tags that may prove useful during publishing.
1563 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1564 Muse uses, as well as make your own tags.
1568 If a tag takes arguments, it will look like this, where ``tagname'' is
1569 the name of the tag.
1572 <tagname arg1="string1" arg2="string2">
1575 If you want the tag to look like it came straight from an XHTML
1576 document, you can alternatively do the following.
1579 <tagname arg1="string1" arg2="string2" />
1582 If a tag surrounds some text, it will look like this.
1585 <tagname>Some text</tagname>
1588 If a tag surrounds a large region, it will look like this.
1597 @subheading Tag listing
1599 This is the complete list of tags that Muse accepts, including those
1600 that were mentioned in previous sections.
1605 Insert a citation to another source.
1607 This takes the argument @option{type}, which indicates the type of
1608 citation. The valid types are "author" and "year". If this argument is
1609 omitted, include both author and year in the citation.
1611 The bibliography to use for the citation may be specified by the
1612 @option{#bibsource} directive.
1615 If publishing to HTML, surround the given text with a @verb{|<span>|}
1616 tag. It takes one argument called ``name'' that specifies the class
1617 attribute of the @verb{|<span>|} tag.
1619 If publishing to a different format, do nothing extra to the text.
1622 Treat the text surrounded by the tag as if they were enclosed in equal
1623 signs, that is, make it monospace.
1626 Run a command on the region, replacing the region with the result of the
1627 command. The command is specified with the ``interp'' argument. If no
1628 value for ``interp'' is given, pass the entire region to the shell.
1630 The ``markup'' argument controls how this section is marked up.
1632 If it is omitted, publish the region with the normal Muse rules.
1634 If "nil", do not mark up the region at all, but prevent Muse from
1635 further interpreting it.
1637 If "example", treat the region as if it was surrounded by the
1638 @verb{|<example>|} tag.
1640 If "src", treat the included text as if it was surrounded by the
1641 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1644 If "verse", treat the region as if it was surrounded by the
1645 @verb{|<verse>|} tag, to preserve newlines.
1647 Otherwise, it should be the name of a function to call, with the buffer
1648 narrowed to the region.
1651 Treat the entire region as a comment. If the option
1652 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1653 publish it using the comment syntax of the current publishing style.
1656 Publish a Table of Contents. This will either be inserted in-place or
1657 at the beginning of the document, depending on your publishing style.
1658 It does not have a delimiting tag.
1660 By default, only 2 levels of headings will be included in the generated
1661 Table of Contents. To change this globally, customize the
1662 @var{muse-publish-contents-depth} option. To change this only for the
1663 current tag, use the ``depth'' argument.
1666 Publish the region in monospace, preserving the newlines in the region.
1667 This is useful for snippets of code.
1670 Insert the given file at the current location during publishing. The
1671 basic use of this tag is as follows, replacing ``included_file'' with
1672 the name of the file that you want to include.
1675 <include file="included_file">
1678 The ``markup'' argument controls how this section is marked up.
1680 If it is omitted, publish the included text with the normal Muse
1683 If "nil", do not mark up the included text at all.
1685 If "example", treat the included text as if it was surrounded by the
1686 @verb{|<example>|} tag.
1688 If "src", treat the included text as if it was surrounded by the
1689 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1692 If "verse", treat the included text as if it was surrounded by the
1693 @verb{|<verse>|} tag, to preserve newlines.
1695 Otherwise, it should be the name of a function to call after inserting
1696 the file with the buffer narrowed to the section inserted.
1699 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1700 The result is then inserted into the document, so you do not need to
1701 explicitly call @code{insert}. All text properties are removed from the
1704 This tag takes the ``markup'' argument. See the description of
1705 @verb{|<command>|} for details.
1708 Make sure that the text enclosed by this tag is published without
1709 escaping it in any way. This is useful for inserting markup directly
1710 into the published document, when Muse does not provide the desired
1714 Mark up the text between the initial and ending tags. The markup
1715 command to use may be specified by the ``function'' argument. The
1716 standard Muse markup routines are used by default if no ``function''
1717 argument is provided.
1719 This is useful for marking up regions in headers and footers. One
1720 example that comes to mind is generating a published index of all of the
1721 files in the current project by doing the following.
1724 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1728 Run the @command{perl} language interpreter on the region, replacing the
1729 region with the result of the command.
1731 This tag takes the ``markup'' argument. See the description of
1732 @verb{|<command>|} for details.
1735 Run the @command{python} language interpreter on the region, replacing
1736 the region with the result of the command.
1738 This tag takes the ``markup'' argument. See the description of
1739 @verb{|<command>|} for details.
1742 Publish the region as a blockquote. This will either be inserted
1743 in-place or at the beginning of the document, depending on your
1744 publishing style. It does not have a delimiting tag.
1747 Run the @command{ruby} language interpreter on the region, replacing the
1748 region with the result of the command.
1750 This tag takes the ``markup'' argument. See the description of
1751 @verb{|<command>|} for details.
1754 Publish the region using htmlize.
1755 The language to use may be specified by the ``lang'' attribute.
1757 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1758 the value of the ``lang'' attribute.
1760 This tag requires htmlize 1.34 or later in order to work. If this is
1761 not satisfied, or the current publishing style is not HTML-based, Muse
1762 will publish the region like an @verb{|<example>|} tag.
1765 This is used when you want to prevent Muse from trying to interpret some
1766 markup. Surround the markup in @verb{|<verbatim>|} and
1767 @verb{|</verbatim>|}, and it will not be interpreted.
1769 This tag was used often in previous versions of Muse because they did
1770 not support whole-document escaping of specials. Now, it will only be
1771 needed for other tags, and perhaps footnotes as well.
1774 Preserve the newlines in the region. In formats like HTML, newlines are
1775 removed by default, hence the need for this tag. In other publishing
1776 styles, this tag may cause the text to be indented slightly in a way
1777 that looks nice for poetry and prose.
1781 @node Publishing Styles, Extending Muse, Markup Rules, Top
1782 @comment node-name, next, previous, up
1783 @chapter Publishing Various Types of Documents
1784 @cindex publishing styles
1786 One of the principle features of Muse is the ability to publish a simple
1787 input text to a variety of different output styles. Muse also makes it
1788 easy to create new styles, or derive from an existing style.
1791 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1792 * Book:: Publishing entries into a compilation.
1793 * ConTeXt:: Publishing ConTeXt documents.
1794 * DocBook:: Publishing in DocBook XML form.
1795 * HTML:: Publishing in HTML or XHTML form.
1796 * Journal:: Keeping a journal or blog.
1797 * LaTeX:: Publishing LaTeX documents.
1798 * Poem:: Publish a poem to LaTex or PDF.
1799 * Texinfo:: Publish entries to Texinfo format or PDF.
1800 * XML:: Publish entries to XML.
1803 @node Blosxom, Book, Publishing Styles, Publishing Styles
1804 @comment node-name, next, previous, up
1805 @section Integrating Muse and pyblosxom.cgi
1806 @cindex blog, one-file-per-entry style
1808 The Blosxom publishing style publishes a tree of categorised files to a
1809 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1810 In other words, each blog entry corresponds with one file.
1813 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1814 * Blosxom Entries:: Format of a Blosxom entry and automation.
1815 * Blosxom Options:: Blosxom styles and options provided.
1818 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1819 @comment node-name, next, previous, up
1820 @subsection Other tools needed for the Blosxom style
1822 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1823 installed on a machine that you have upload access to.
1825 The following additional components are required in order to make the
1826 date of blog entries display as something sensible.
1830 A script to gather date directives from the entire blog tree into a
1831 single file. The file must associate a blog entry with a date.
1834 A plugin for (py)blosxom that reads this file.
1837 These 2 things are provided for @command{pyblosxom.cgi} in the
1838 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1839 former service, while @file{hardcodedates.py} provides the latter
1840 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1841 script will be found/written.
1843 Here is a sample listing from my @file{timestamps} file, which maps
1844 each file to a date. This can really be in any format, as long as your
1845 date-gathering script and your plugin can both understand it.
1848 2005-04-01-14-16 personal/paper_cranes
1849 2005-03-21 personal/spring_break_over
1850 2004-10-24 personal/finished_free_culture
1853 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1854 @file{getstamps.py}. Note that you will need to set the current
1855 directory to where your Muse files are, execute @file{getstamps.py}, and
1856 then move the generated timestamps file to your publishing directory.
1858 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1859 @comment node-name, next, previous, up
1860 @subsection Format of a Blosxom entry and automation
1862 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1863 longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
1864 plus whatever normal content is desired.
1866 The date directive is not used directly by @command{pyblosxom.cgi} or
1867 this program. You need to have the two additional items from the former
1868 section to make use of this feature.
1870 There is a function called @code{muse-blosxom-new-entry} that will
1871 automate the process of making a new blog entry. To make use of it, do
1876 Customize @code{muse-blosxom-base-directory} to the location that your
1877 blog entries are stored.
1880 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1881 use the following code to assign this function to @kbd{C-c p l'}.
1884 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1888 You should create your directory structure ahead of time under your base
1889 directory. These directories, which correspond with category names, may
1893 When you enter this key sequence, you will be prompted for the category
1894 of your entry and its title. Upon entering this information, a new file
1895 will be created that corresponds with the title, but in lowercase
1896 letters and having special characters converted to underscores. The
1897 title and date directives will be inserted automatically.
1900 @node Blosxom Options, , Blosxom Entries, Blosxom
1901 @comment node-name, next, previous, up
1902 @subsection Blosxom styles and options provided
1904 The following styles and options are available in the Blosxom publishing
1907 @subheading Styles provided
1911 @cindex publishing styles, blosxom-html
1913 Publish Blosxom entries in HTML form.
1915 @cindex publishing styles, blosxom-xhtml
1917 Publish Blosxom entries in XHTML form.
1921 @subheading Options provided
1925 @item muse-blosxom-extension
1926 Default file extension for publishing Blosxom files.
1928 @item muse-blosxom-header
1929 Header used for publishing Blosxom files.
1931 This may be text or a filename.
1933 @item muse-blosxom-footer
1934 Footer used for publishing Blosxom files.
1936 This may be text or a filename.
1938 @item muse-blosxom-base-directory
1939 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1941 This is the top-level directory where your blog entries may be found
1946 @node Book, ConTeXt, Blosxom, Publishing Styles
1947 @comment node-name, next, previous, up
1948 @section Publishing entries into a compilation
1950 This publishing style is used to output ``books'' in LaTeX or PDF
1953 Each page will become a separate chapter in the book, unless the style
1954 keyword @option{:nochapters} is used, in which case they are all run
1955 together as if one giant chapter.
1957 One way of publishing a book is to make a project for it, add the
1958 project to @code{muse-project-alist}, and use the @code{book-pdf} style
1959 with a very specific @option{:include} value to specify some page whose
1960 contents will be checked for the values of @code{#title} and
1961 @code{#date}, and whose name will be used in the output file. Then to
1962 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
1963 @kbd{C-c C-p} to trigger the publishing process. An example
1964 @code{muse-project-alist} for this method follows.
1967 (setq muse-project-alist
1968 '(("MyNotes" (:nochapters t ; do automatically add chapters
1969 :book-chapter "Computer Science"
1971 :book-chapter "Mathematics"
1973 :book-chapter "Emacs"
1975 :book-end t ; the rest will not be placed in the book
1976 "~/Notes" ; so we can find the notes-anthology page
1978 :force-publish ("index")
1981 :include "/notes-anthology[^/]*$"
1982 :path "~/public_html/notes")
1983 ;; other publishing styles for each directory go here,
1988 In this example, there would be a file called
1989 @file{~/Notes/notes-anthology.muse}, which would contain just the
1990 following. The resulting book would be published to
1991 @file{~/public_html/notes/notes-anthology.pdf}.
1994 #title My Technology Ramblings
1997 Another way is to call the @code{muse-book-publish-project} function
1998 manually, with a custom project entry. An example of this may be found
1999 in John Wiegley's configuration file at
2000 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
2003 @subheading Styles provided
2007 @cindex publishing styles, book-latex
2009 Publish a book in LaTeX form. The header and footer are different than
2010 the normal LaTeX publishing mode.
2012 @cindex publishing styles, book-pdf
2014 Publish a book in PDF form. The header and footer are different than
2015 the normal PDF publishing mode.
2019 @subheading Options provided
2023 @item muse-book-before-publish-hook
2024 A hook run in the book buffer before it is marked up.
2026 @item muse-book-after-publish-hook
2027 A hook run in the book buffer after it is marked up.
2029 @item muse-book-latex-header
2030 Header used for publishing books to LaTeX.
2032 This may be text or a filename.
2034 @item muse-book-latex-footer
2035 Footer used for publishing books to LaTeX.
2037 This may be text or a filename.
2040 @node ConTeXt, DocBook, Book, Publishing Styles
2041 @comment node-name, next, previous, up
2042 @section Publishing ConTeXt documents
2044 This publishing style is capable of producing ConTeXt or PDF documents.
2046 If you wish to publish PDF documents based on ConTeXt, you will need to
2047 have it installed. For Debian and Ubuntu, this can be accomplished by
2048 installing the ``texlive'' package.
2050 @subheading Styles provided
2054 @cindex publishing styles, context
2056 Publish a ConTeXt document.
2058 @cindex publishing styles, context-pdf
2060 Publish a PDF document, using an external ConTeXt document conversion
2063 @cindex publishing styles, context-slides
2064 @item context-slides
2065 Produce slides from a ConTeXt document.
2067 Here is an example of a slide.
2072 [[Some-sort-of-cute-image.png]]
2077 - Another bullet point.
2084 @cindex publishing styles, context-slides-pdf
2085 @item context-slides-pdf
2086 Publish a PDF document of ConTeXt slides.
2090 @subheading Options provided
2094 @item muse-context-extension
2095 Default file extension for publishing ConTeXt files.
2097 @item muse-context-pdf-extension
2098 Default file extension for publishing ConTeXt files to PDF.
2100 @item muse-context-pdf-program
2101 The program that is called to generate PDF content from ConTeXt content.
2103 @item muse-context-pdf-cruft
2104 Extensions of files to remove after generating PDF output successfully.
2106 @item muse-context-header
2107 Header used for publishing ConTeXt files.
2109 This may be text or a filename.
2111 @item muse-context-footer
2112 Footer used for publishing ConTeXt files.
2114 This may be text or a filename.
2116 @item muse-context-markup-regexps
2117 List of markup regexps for identifying regions in a Muse page.
2119 For more on the structure of this list,
2120 @xref{muse-publish-markup-regexps}.
2122 @item muse-context-markup-functions
2123 An alist of style types to custom functions for that kind of text.
2125 For more on the structure of this list,
2126 @xref{muse-publish-markup-functions}.
2128 @item muse-context-markup-strings
2129 Strings used for marking up text.
2131 These cover the most basic kinds of markup, the handling of which
2132 differs little between the various styles.
2134 @item muse-context-slides-header
2135 Header for publishing a presentation (slides) using ConTeXt.
2137 You can use any of the predefined modules, which are available in the
2138 tex/context/base of your distribution, provided it has TitlePage and
2139 Topic defined. Alternatively, you can use your own style (mystyle) by
2140 replacing ``\\usemodule[]'' with ``\\input mystyle''.
2142 This may be text or a filename.
2144 @item muse-context-slides-markup-strings
2145 Strings used for marking up text in ConTeXt slides.
2147 @item muse-context-markup-specials-document
2148 A table of characters which must be represented specially.
2149 These are applied to the entire document, sans already-escaped
2152 @item muse-context-markup-specials-example
2153 A table of characters which must be represented specially.
2154 These are applied to @verb{|example>|} regions.
2156 With the default interpretation of @verb{|<example>|} regions, no
2157 specials need to be escaped.
2159 @item muse-context-markup-specials-literal
2160 A table of characters which must be represented specially.
2161 This applies to =monospaced text= and @verb{|<code>|} regions.
2163 @item muse-context-markup-specials-url
2164 A table of characters which must be represented specially.
2165 These are applied to URLs.
2167 @item muse-context-markup-specials-image
2168 A table of characters which must be represented specially.
2169 These are applied to image filenames.
2171 @item muse-context-permit-contents-tag
2172 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2175 Most of the time, it is best to have a table of contents on the
2176 first page, with a new page immediately following. To make this
2177 work with documents published in both HTML and ConTeXt, we need to
2178 ignore the @verb{|<contents>|} tag.
2180 If you don't agree with this, then set this option to non-nil,
2181 and it will do what you expect.
2185 @node DocBook, HTML, ConTeXt, Publishing Styles
2186 @comment node-name, next, previous, up
2187 @section Publishing in DocBook XML form
2189 This publishing style is used to generate DocBook XML files.
2191 @subheading Styles provided
2195 @cindex publishing styles, docbook
2197 Publish a file in Docbook form.
2201 @subheading Options provided
2203 This publishing style uses the same options for markup up special
2204 characters as the ``xml'' publishing style. @xref{XML}, for details.
2208 @item muse-docbook-extension
2209 Default file extension for publishing DocBook XML files.
2211 @item muse-docbook-header
2212 Header used for publishing DocBook XML files.
2214 This may be text or a filename.
2216 @item muse-docbook-footer
2217 Footer used for publishing DocBook XML files.
2219 This may be text or a filename.
2221 @item muse-docbook-markup-regexps
2222 List of markup rules for publishing a Muse page to DocBook XML.
2224 @item muse-docbook-markup-functions
2225 An alist of style types to custom functions for that kind of text.
2227 @item muse-docbook-markup-strings
2228 Strings used for marking up text.
2230 These cover the most basic kinds of markup, the handling of which
2231 differs little between the various styles.
2233 @item muse-docbook-encoding-default
2234 The default Emacs buffer encoding to use in published files.
2235 This will be used if no special characters are found.
2237 @item muse-docbook-charset-default
2238 The default DocBook XML charset to use if no translation is
2239 found in @code{muse-xml-encoding-map}.
2243 @node HTML, Journal, DocBook, Publishing Styles
2244 @comment node-name, next, previous, up
2245 @section Publishing in HTML or XHTML form
2247 This publishing style is capable of producing HTML or XHTML documents.
2249 @subheading Styles provided
2253 @cindex publishing styles, html
2255 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2258 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2262 @subheading Options provided
2264 If an HTML option does not have a corresponding XHTML option, it will
2265 be used for both of these publishing styles.
2267 These publishing styles use the same options for markup up special
2268 characters as the ``xml'' publishing style. @xref{XML}, for details.
2272 @item muse-html-extension
2273 Default file extension for publishing HTML files.
2275 @item muse-xhtml-extension
2276 Default file extension for publishing XHTML files.
2278 @item muse-html-style-sheet
2279 Store your stylesheet definitions here.
2281 This is used in @code{muse-html-header}. You can put raw CSS in here or
2282 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2283 @verb{|<lisp>|} markup tags.
2285 If you are publishing to XHTML, then customize the
2286 @code{muse-xhtml-style-sheet} option instead.
2288 @item muse-xhtml-style-sheet
2289 Store your stylesheet definitions here.
2291 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2292 or a @verb{|<link>|} tag to an external stylesheet. This text may
2293 contain @verb{|<lisp>|} markup tags.
2295 @item muse-html-header
2296 Header used for publishing HTML files.
2298 This may be text or a filename.
2300 @item muse-html-footer
2301 Footer used for publishing HTML files.
2303 This may be text or a filename.
2305 @item muse-xhtml-header
2306 Header used for publishing XHTML files.
2308 This may be text or a filename.
2310 @item muse-xhtml-footer
2311 Footer used for publishing XHTML files.
2313 This may be text or a filename.
2315 @item muse-html-anchor-on-word
2316 When true, anchors surround the closest word.
2318 This allows you to select them in a browser (i.e. for pasting), but has
2319 the side-effect of marking up headers in multiple colors if your header
2320 style is different from your link style.
2322 @item muse-html-table-attributes
2323 The attribute to be used with HTML @verb{|<table>|} tags.
2325 If you want to make more-complicated tables in HTML, surround the HTML
2326 with the @verb{|literal|} tag, so that it does not get escaped.
2328 @item muse-html-markup-regexps
2329 List of markup rules for publishing a Muse page to HTML.
2331 @item muse-html-markup-functions
2332 An alist of style types to custom functions for that kind of text.
2334 @item muse-html-markup-strings
2335 Strings used for marking up text as HTML.
2337 These cover the most basic kinds of markup, the handling of which
2338 differs little between the various styles.
2340 @item muse-xhtml-markup-strings
2341 Strings used for marking up text as XHTML.
2343 These cover the most basic kinds of markup, the handling of which
2344 differs little between the various styles.
2346 @item muse-html-markup-tags
2347 A list of tag specifications, for specially marking up HTML.
2348 @xref{muse-publish-markup-tags}, for more information.
2350 @item muse-html-meta-http-equiv
2351 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2353 @item muse-html-meta-content-type
2354 The content type used for the HTML @verb{|<meta>|} tag.
2356 If you are striving for XHTML 1.1 compliance, you may want to change
2357 this to ``application/xhtml+xml''.
2359 @item muse-html-meta-content-encoding
2360 The charset to append to the HTML @verb{|<meta>|} tag.
2362 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2363 and determine the HTML charset from emacs's coding. If set to a string,
2364 this string will be used to force a particular charset.
2366 @item muse-html-charset-default
2367 The default HTML meta charset to use if no translation is found in
2368 @code{muse-xml-encoding-map}.
2370 @item muse-html-encoding-default
2371 The default Emacs buffer encoding to use in published files.
2372 This will be used if no special characters are found.
2376 @node Journal, LaTeX, HTML, Publishing Styles
2377 @comment node-name, next, previous, up
2378 @section Keeping a journal or blog
2380 @cindex blog, journal style
2382 The module facilitates the keeping and publication of a journal. When
2383 publishing to HTML, it assumes the form of a web log, or blog.
2385 The input format for each entry is as follows.
2388 * 20040317: Title of entry
2393 "You know who you are. It comes down to a simple gut check: You
2394 either love what you do or you don't. Period." -- P. Bronson
2398 The "qotd", or Quote of the Day, is entirely optional. When generated
2399 to HTML, this entry is rendered as the following.
2403 <div class="entry-qotd">
2404 <h3>Quote of the Day:</h3>
2405 <p>"You know who you are. It comes down to a simple gut
2406 check: You either love what you do or you don't. Period."
2409 <div class="entry-body">
2410 <div class="entry-head">
2411 <div class="entry-date">
2412 <span class="date">March 17, 2004</span>
2414 <div class="entry-title">
2415 <h2>Title of entry</h2>
2418 <div class="entry-text">
2419 <p>Text for the entry.</p>
2425 The plurality of "div" tags makes it possible to display the entries in
2426 any form you wish, using a CSS style.
2428 Also, an .RDF file can be generated from your journal by publishing it
2429 with the "rdf" style. It uses the first two sentences of the first
2430 paragraph of each entry as its "description", and auto-generates tags
2431 for linking to the various entries.
2433 @subheading muse-project-alist considerations
2435 If you wish to publish an RDF or RSS feed, it is important to include
2436 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2437 for your Journal projects. An example follows.
2440 (setq muse-project-alist
2441 '(("Journal" ("~/Journal/"
2443 (:base "journal-rss"
2444 :base-url "http://example.org/journal/"
2445 :path "~/public_html/journal"))))
2448 @subheading Styles provided
2452 @cindex publishing styles, journal-html
2454 Publish journal entries as an HTML document.
2456 @cindex publishing styles, journal-xhtml
2458 Publish journal entries as an XHTML document.
2460 @cindex publishing styles, journal-latex
2462 Publish journal entries as a LaTeX document.
2464 @cindex publishing styles, journal-pdf
2466 Publish journal entries as a PDF document.
2468 @cindex publishing styles, journal-book-latex
2469 @item journal-book-latex
2470 Publish journal entries as a LaTeX book.
2472 @cindex publishing styles, journal-book-pdf
2473 @item journal-book-pdf
2474 Publish journal entries as a PDF book.
2476 @cindex publishing styles, journal-rdf
2477 @cindex publishing styles, RSS 1.0
2479 Publish journal entries as an RDF file (RSS 1.0).
2481 @cindex publishing styles, journal-rss
2482 @cindex publishing styles, RSS 2.0
2484 Publish journal entries as an RSS file (RSS 2.0).
2486 @cindex publishing styles, journal-rss-entry
2487 @item journal-rss-entry
2488 Used internally by @code{journal-rss} and @code{journal-rdf} for
2489 publishing individual entries.
2493 @subheading Options provided
2497 @item muse-journal-heading-regexp
2498 A regexp that matches a journal heading.
2500 Paren group 1 is the ISO date, group 2 is the optional category, and
2501 group 3 is the optional heading for the entry.
2503 @item muse-journal-date-format
2504 Date format to use for journal entries.
2506 @item muse-journal-html-heading-regexp
2507 A regexp that matches a journal heading from an HTML document.
2509 Paren group 1 is the ISO date, group 2 is the optional category, and
2510 group 3 is the optional heading for the entry.
2512 @item muse-journal-html-entry-template
2513 Template used to publish individual journal entries as HTML.
2515 This may be text or a filename.
2517 @item muse-journal-latex-section
2518 Template used to publish a LaTeX section.
2520 @item muse-journal-latex-subsection
2521 Template used to publish a LaTeX subsection.
2523 @item muse-journal-markup-tags
2524 A list of tag specifications, for specially marking up Journal entries.
2526 @xref{muse-publish-markup-tags}, for more information.
2528 This is used by @code{journal-latex} and its related styles, as well as
2529 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2530 @code{journal-rss} use.
2532 @item muse-journal-rdf-extension
2533 Default file extension for publishing RDF (RSS 1.0) files.
2535 @item muse-journal-rdf-base-url
2536 The base URL of the website referenced by the RDF file.
2538 @item muse-journal-rdf-header
2539 Header used for publishing RDF (RSS 1.0) files.
2541 This may be text or a filename.
2543 @item muse-journal-rdf-footer
2544 Footer used for publishing RDF (RSS 1.0) files.
2546 This may be text or a filename.
2548 @item muse-journal-rdf-date-format
2549 Date format to use for RDF entries.
2551 @item muse-journal-rdf-entry-template
2552 Template used to publish individual journal entries as RDF.
2554 This may be text or a filename.
2556 @item muse-journal-rdf-summarize-entries
2557 If non-nil, include only summaries in the RDF file, not the full data.
2559 The default is nil, because this annoys some subscribers.
2561 @item muse-journal-rss-heading-regexp
2562 A regexp that matches a journal heading from an HTML document.
2564 Paren group 1 is the ISO date, group 2 is the optional category,
2565 and group 3 is the optional heading for the entry.
2567 @item muse-journal-rss-extension
2568 Default file extension for publishing RSS 2.0 files.
2570 @item muse-journal-rss-base-url
2571 The base URL of the website referenced by the RSS file.
2573 @item muse-journal-rss-header
2574 Header used for publishing RSS 2.0 files.
2576 This may be text or a filename.
2578 @item muse-journal-rss-footer
2579 Footer used for publishing RSS 2.0 files.
2581 This may be text or a filename.
2583 @item muse-journal-rss-date-format
2584 Date format to use for RSS 2.0 entries.
2586 @item muse-journal-rss-entry-template
2587 Template used to publish individual journal entries as RSS 2.0.
2589 This may be text or a filename.
2591 @item muse-journal-rss-enclosure-types-alist
2592 File types that are accepted as RSS enclosures.
2594 This is an alist that maps file extension to content type.
2596 Useful for podcasting.
2598 @item muse-journal-rss-summarize-entries
2599 If non-nil, include only summaries in the RSS file, not the full data.
2601 The default is nil, because this annoys some subscribers.
2603 @item muse-journal-rss-markup-regexps
2604 List of markup rules for publishing a Muse journal page to RSS.
2606 For more information on the structure of this list,
2607 @xref{muse-publish-markup-regexps}.
2609 @item muse-journal-rss-markup-functions
2610 An alist of style types to custom functions for that kind of text.
2612 For more on the structure of this list,
2613 @xref{muse-publish-markup-functions}.
2617 @node LaTeX, Poem, Journal, Publishing Styles
2618 @comment node-name, next, previous, up
2619 @section Publishing LaTeX documents
2621 This publishing style is capable of producing LaTeX or PDF documents.
2623 If you wish to publish PDF documents, you will need to have a good TeX
2624 installation. For Debian and Ubuntu, this can be accomplished by
2625 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2628 @subheading Styles provided
2632 @cindex publishing styles, latex
2634 Publish a LaTeX document.
2636 @cindex publishing styles, pdf
2638 Publish a PDF document, using an external LaTeX document conversion
2641 @cindex publishing styles, latexcjk
2643 Publish a LaTeX document with CJK (Chinese) encodings.
2645 @cindex publishing styles, pdfcjk
2647 Publish a PDF document with CJK (Chinese) encodings, using an external
2648 LaTeX document conversion tool.
2650 @cindex publishing styles, slides
2652 Publish a LaTeX document that uses the Beamer extension. This is
2653 suitable for producing slides.
2655 Here is an example of a slide.
2658 <slide title="First Slide">
2659 Everything between the slide tags composes this slide.
2661 [[Some-sort-of-cute-image.png]]
2664 - Another bullet point.
2668 @cindex publishing styles, slides-pdf
2670 Publish a PDF document of slides, using the Beamer extension.
2672 @cindex publishing styles, lecture-notes
2674 Publish a LaTeX document that uses the Beamer extension. This is
2675 suitable for producing lecture notes.
2677 This can also use the @verb{|<slide>|} tag.
2679 @cindex publishing styles, lecture-notes-pdf
2680 @item lecture-notes-pdf
2681 Publish a PDF document of lecture notes, using the Beamer extension.
2685 @subheading Options provided
2689 @item muse-latex-extension
2690 Default file extension for publishing LaTeX files.
2692 @item muse-latex-pdf-extension
2693 Default file extension for publishing LaTeX files to PDF.
2695 @item muse-latex-pdf-program
2696 The program that is called to generate PDF content from LaTeX content.
2698 @item muse-latex-pdf-cruft
2699 Extensions of files to remove after generating PDF output successfully.
2701 @item muse-latex-header
2702 Header used for publishing LaTeX files.
2704 This may be text or a filename.
2706 @item muse-latex-footer
2707 Footer used for publishing LaTeX files.
2709 This may be text or a filename.
2711 @item muse-latexcjk-header
2712 Header used for publishing LaTeX files (CJK).
2714 This may be text or a filename.
2716 @item muse-latexcjk-footer
2717 Footer used for publishing LaTeX files (CJK).
2719 This may be text or a filename.
2721 @item muse-latex-slides-header
2722 Header for publishing of slides using LaTeX.
2724 This may be text or a filename.
2726 You must have the Beamer extension for LaTeX installed for this to work.
2728 @item muse-latex-lecture-notes-header
2729 Header publishing of lecture notes using LaTeX.
2731 This may be text or a filename.
2733 You must have the Beamer extension for LaTeX installed for this to work.
2735 @item muse-latex-markup-regexps
2736 List of markup regexps for identifying regions in a Muse page.
2738 For more on the structure of this list,
2739 @xref{muse-publish-markup-regexps}.
2741 @item muse-latex-markup-functions
2742 An alist of style types to custom functions for that kind of text.
2744 For more on the structure of this list,
2745 @xref{muse-publish-markup-functions}.
2747 @item muse-latex-markup-strings
2748 Strings used for marking up text.
2750 These cover the most basic kinds of markup, the handling of which
2751 differs little between the various styles.
2753 @item muse-latex-slides-markup-tags
2754 A list of tag specifications, for specially marking up LaTeX slides.
2756 @item muse-latexcjk-encoding-map
2757 An alist mapping emacs coding systems to appropriate CJK codings.
2758 Use the base name of the coding system (ie, without the -unix).
2760 @item muse-latexcjk-encoding-default
2761 The default Emacs buffer encoding to use in published files.
2763 This will be used if no special characters are found.
2765 @item muse-latex-markup-specials-document
2766 A table of characters which must be represented specially.
2767 These are applied to the entire document, sans already-escaped
2770 @item muse-latex-markup-specials-example
2771 A table of characters which must be represented specially.
2772 These are applied to @verb{|example>|} regions.
2774 With the default interpretation of @verb{|<example>|} regions, no
2775 specials need to be escaped.
2777 @item muse-latex-markup-specials-literal
2778 A table of characters which must be represented specially.
2779 This applies to =monospaced text= and @verb{|<code>|} regions.
2781 @item muse-latex-markup-specials-url
2782 A table of characters which must be represented specially.
2783 These are applied to URLs.
2785 @item muse-latex-markup-specials-image
2786 A table of characters which must be represented specially.
2787 These are applied to image filenames.
2789 @item muse-latex-permit-contents-tag
2790 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2793 Most of the time, it is best to have a table of contents on the
2794 first page, with a new page immediately following. To make this
2795 work with documents published in both HTML and LaTeX, we need to
2796 ignore the @verb{|<contents>|} tag.
2798 If you don't agree with this, then set this option to non-nil,
2799 and it will do what you expect.
2803 @node Poem, Texinfo, LaTeX, Publishing Styles
2804 @comment node-name, next, previous, up
2805 @section Publish a poem to LaTex or PDF
2807 The @code{muse-poem} module makes it easy to attractively publish and
2808 reference poems in the following format, using the "memoir" module for
2809 LaTeX publishing. It will also markup poems for every other output
2810 style, though none are nearly as pretty.
2819 Annotations, history, notes, etc.
2822 Once a poem is written in this format, just publish it to PDF using the
2823 @code{poem-pdf} style. To make an inlined reference to a poem that
2824 you've written -- for example, from a blog page -- there is a "poem" tag
2825 defined by this module.
2828 <poem title="name.of.poem.page">
2831 Let's assume the template above was called @file{name.of.poem.page};
2832 then the above tag would result in this inclusion.
2840 John Wiegley uses this module for publishing all of the poems on his
2841 website, which are at
2842 @uref{http://www.newartisans.com/johnw/poems.html}.
2844 @subheading Styles provided
2848 @cindex publishing styles, poem-latex
2850 Publish a poem in LaTeX form.
2852 @cindex publishing styles, poem-pdf
2854 Publish a poem to a PDF document.
2856 @cindex publishing styles, chapbook-latex
2857 @item chapbook-latex
2858 Publish a book of poems in LaTeX form.
2860 @cindex publishing styles, chapbook-pdf
2862 Publish a book of poems to a PDF document.
2866 @subheading Options provided
2870 @item muse-poem-latex-header
2871 Header used for publishing LaTeX poems.
2873 This may be text or a filename.
2875 @item muse-poem-latex-footer
2876 Footer used for publishing LaTeX files.
2878 This may be text or a filename.
2880 @item muse-poem-markup-strings
2881 Strings used for marking up poems.
2883 These cover the most basic kinds of markup, the handling of which
2884 differs little between the various styles.
2886 @item muse-chapbook-latex-header
2887 Header used for publishing a book of poems in LaTeX form.
2889 This may be text or a filename.
2891 @item muse-chapbook-latex-footer
2892 Footer used for publishing a book of poems in LaTeX form.
2894 This may be text or a filename.
2896 @item muse-poem-chapbook-strings
2897 Strings used for marking up books of poems.
2899 These cover the most basic kinds of markup, the handling of which
2900 differs little between the various styles.
2904 @node Texinfo, XML, Poem, Publishing Styles
2905 @comment node-name, next, previous, up
2906 @section Publish entries to Texinfo format or PDF
2908 Rules for publishing a Muse file as a Texinfo article.
2910 @subheading Styles provided
2914 @cindex publishing styles, texi
2916 Publish a file in Texinfo form.
2918 @cindex publishing styles, texi
2920 Generate an Info file from a Muse file.
2922 @cindex publishing styles, info-pdf
2924 Publish a file in PDF form.
2928 @subheading Options provided
2932 @item muse-texinfo-process-natively
2933 If non-nil, use the Emacs `texinfmt' module to make Info files.
2935 @item muse-texinfo-extension
2936 Default file extension for publishing Texinfo files.
2938 @item muse-texinfo-info-extension
2939 Default file extension for publishing Info files.
2941 @item muse-texinfo-pdf-extension
2942 Default file extension for publishing PDF files.
2944 @item muse-texinfo-header
2945 Text to prepend to a Muse page being published as Texinfo.
2947 This may be text or a filename.
2948 It may contain @verb{|<lisp>|} markup tags.
2950 @item muse-texinfo-footer
2951 Text to append to a Muse page being published as Texinfo.
2953 This may be text or a filename.
2954 It may contain @verb{|<lisp>|} markup tags.
2956 @item muse-texinfo-markup-regexps
2957 List of markup rules for publishing a Muse page to Texinfo.
2959 For more on the structure of this list,
2960 @xref{muse-publish-markup-regexps}.
2962 @item muse-texinfo-markup-functions
2963 An alist of style types to custom functions for that kind of text.
2965 For more on the structure of this list,
2966 @xref{muse-publish-markup-functions}.
2968 @item muse-texinfo-markup-strings
2969 Strings used for marking up text.
2971 These cover the most basic kinds of markup, the handling of which
2972 differs little between the various styles.
2974 @item muse-texinfo-markup-specials
2975 A table of characters which must be represented specially.
2977 @item muse-texinfo-markup-specials
2978 A table of characters which must be represented specially.
2979 These are applied to URLs.
2983 @node XML, , Texinfo, Publishing Styles
2984 @comment node-name, next, previous, up
2985 @section Publish entries to XML
2987 Muse is capable of publishing XML documents, with the help of the
2988 @file{muse-xml.el} module.
2990 A RelaxNG schema is available as part of the Muse distribution in the
2991 @file{etc/muse.rnc} file.
2993 @subheading Styles provided
2997 @cindex publishing styles, xml
2999 Publish a file in XML form.
3003 @subheading Options provided
3007 @cindex muse-xml-encoding-map
3008 @item muse-xml-encoding-map
3009 An alist mapping Emacs coding systems to appropriate XML charsets.
3010 Use the base name of the coding system (i.e. without the -unix).
3012 @item muse-xml-markup-specials
3013 A table of characters which must be represented specially in all
3014 XML-like markup formats.
3016 @item muse-xml-markup-specials-url-extra
3017 A table of characters which must be represented specially in all
3018 XML-like markup formats.
3020 These are extra characters that are escaped within URLs.
3022 @item muse-xml-extension
3023 Default file extension used for publishing XML files.
3025 @item muse-xml-header
3026 Header used for publishing XML files.
3028 This may be text or a filename.
3030 @item muse-xml-footer
3031 Footer used for publishing XML files.
3033 This may be text or a filename.
3035 @item muse-xml-markup-regexps
3036 List of markup rules for publishing a Muse page to XML.
3038 For more on the structure of this list,
3039 @xref{muse-publish-markup-regexps}.
3041 @item muse-xml-markup-functions
3042 An alist of style types to custom functions for that kind of text.
3044 For more on the structure of this list,
3045 @xref{muse-publish-markup-functions}.
3047 @item muse-xml-markup-strings
3048 Strings used for marking up text.
3050 These cover the most basic kinds of markup, the handling of which
3051 differs little between the various styles.
3053 @item muse-xml-encoding-default
3054 The default Emacs buffer encoding to use in published files.
3056 This will be used if no special characters are found.
3058 @item muse-xml-charset-default
3059 The default XML charset to use if no translation is found in
3060 @code{muse-xml-encoding-map}.
3065 @node Extending Muse, Miscellaneous, Publishing Styles, Top
3066 @comment node-name, next, previous, up
3067 @chapter Making your own publishing styles
3070 * Common Elements:: Common functionality shared by styles.
3071 * Deriving Styles:: Deriving a new style from an existing
3075 @node Common Elements, Deriving Styles, , Extending Muse
3076 @comment node-name, next, previous, up
3077 @section Common functionality shared by styles
3078 @cindex publishing styles, common
3081 * Markup Functions:: Specifying functions to mark up text.
3082 * Markup Regexps:: Markup rules for publishing.
3083 * Markup Strings:: Strings specific to a publishing style.
3084 * Markup Tags:: Tag specifications for special markup.
3085 * Style Elements:: Parameters used for defining styles.
3088 @node Markup Functions, Markup Regexps, , Common Elements
3089 @comment node-name, next, previous, up
3090 @subsection Specifying functions to mark up text
3091 @cindex publishing, markup functions
3093 @anchor{muse-publish-markup-functions}
3094 @code{muse-publish-markup-functions}
3096 An alist of style types to custom functions for that kind of text.
3098 This is used by publishing styles to attempt to minimize the amount of
3099 custom regexps that each has to define. @file{muse-publish} provides
3100 rules for the most common types of markup.
3102 Each member of the list is of the following form.
3110 Describes the type of text to associate with this rule.
3111 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3114 Function to use to mark up this kind of rule if no suitable function is
3115 found through the @option{:functions} tag of the current style.
3118 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3119 @comment node-name, next, previous, up
3120 @subsection Markup rules for publishing
3121 @cindex publishing, markup regexps
3122 @cindex publishing, rules
3124 @anchor{muse-publish-markup-regexps}
3125 @code{muse-publish-markup-regexps}
3127 List of markup rules for publishing a page with Muse.
3129 The rules given in this variable are invoked first, followed by whatever
3130 rules are specified by the current style.
3132 Each member of the list is either a function, or a list of the following
3136 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3141 A regular expression, or symbol whose value is a regular expression,
3142 which is searched for using `re-search-forward'.
3144 @item TEXT-BEGIN-GROUP
3145 The matching group within that regexp which denotes the beginning of the
3146 actual text to be marked up.
3148 @item REPLACEMENT-TEXT
3149 A string that will be passed to `replace-match'.
3151 If it is not a string, but a function, it will be called to determine
3152 what the replacement text should be (it must return a string). If it is
3153 a symbol, the value of that symbol should be a string.
3156 The replacements are done in order, one rule at a time. Writing
3157 the regular expressions can be a tricky business. Note that case
3158 is never ignored. `case-fold-search' is always bound to nil
3159 while processing the markup rules.
3161 @subheading Publishing order
3163 This is the order that the publishing rules are consulted, by default.
3164 This may be changed by customizing @code{muse-publish-markup-regexps}.
3168 @item trailing and leading whitespace
3169 Remove trailing and leading whitespace from a file.
3174 This is only recognized at the beginning of a file.
3177 @samp{; a commented line}
3185 @item explicit links
3186 Prevent emphasis characters in explicit links from being marked up.
3188 Don't actually publish them here, just add a special no-emphasis text
3192 Whitespace-delimited word, possibly with emphasis characters
3194 This function is responsible for marking up emphasis and escaping some
3200 Outline-mode style headings.
3205 These are ellipses with a dot at end.
3215 Horizontal rule or section separator.
3217 @item no-break-space
3220 Prevent lines from being split before or after these characters.
3225 beginning of footnotes section
3230 Footnote definition or reference. If at beginning of line, it is a
3245 Numbered list, item list, or term definition list.
3249 @file{table.el} style tables
3252 @samp{table | cells}
3254 Muse tables or orgtbl-mode style tables.
3257 spaces before beginning of text
3273 @samp{[[explicit][links]]}
3276 @samp{http://example.com/}
3279 @samp{bare-email@@example.com}
3283 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3284 @comment node-name, next, previous, up
3285 @subsection Strings specific to a publishing style
3286 @cindex publishing, markup strings
3288 @dfn{Markup strings} are strings used for marking up text for a
3291 These cover the most basic kinds of markup, the handling of which
3292 differs little between the various styles.
3294 @subheading Available markup strings
3298 @item image-with-desc
3299 An image and a description.
3301 Argument 1: image without extension. Argument 2: image extension.
3302 Argument 3: description.
3307 Argument 1: image without extension. Argument 2: image extension.
3310 An image with a link around it.
3312 Argument 1: link. Argument 2: image without extension.
3313 Argument 3: image extension.
3316 A reference to an anchor on the current page.
3318 Argument 1: anchor name. Argument 2: description if one exists, or the
3319 original link otherwise.
3322 A URL without a description.
3327 A link to a Muse page with a description.
3329 Argument 1: link. Argument 2: description if one exists, or the
3330 original link otherwise.
3332 @item link-and-anchor
3333 A link to a Muse page with an anchor, and a description.
3335 Argument 1: link. Argument 2: anchor name.
3336 Argument 3: description if one exists, or the original link otherwise.
3337 Argument 4: link without an extension.
3340 A link to an email address.
3342 Argument 1: email address. Argument 2: email address.
3347 Argument 1: name of anchor.
3352 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3355 Beginning of a comment.
3361 A horizontal line or space.
3363 @item no-break-space
3364 A space that separates two words which are not to be separated.
3367 Beginning of footnote.
3373 Mark a reference for the current footnote.
3375 Argument 1: number of this footnote.
3377 @item footnotemark-end
3378 End of a reference for the current footnote.
3381 Indicate the text of the current footnote.
3383 Argument 1: number of this footnote.
3385 @item footnotetext-end
3386 End of a footnote text line.
3389 Text used to replace ``Footnotes:'' line.
3398 Beginning of a part indicator line. This is used by book publishing.
3401 End of a part indicator line. This is used by book publishing.
3404 Beginning of a chapter indicator line. This is used by book publishing.
3407 End of a chapter indicator line. This is used by book publishing.
3410 Beginning of level 1 section indicator line.
3412 Argument 1: level of section; always 1.
3415 End of level 1 section indicator line.
3417 Argument 1: level of section; always 1.
3420 Beginning of level 2 section indicator line.
3422 Argument 1: level of section; always 2.
3424 @item subsection-end
3425 End of level 2 section indicator line.
3427 Argument 1: level of section; always 2.
3430 Beginning of level 3 section indicator line.
3432 Argument 1: level of section; always 3.
3434 @item subsubsection-end
3435 End of level 3 section indicator line.
3437 Argument 1: level of section; always 3.
3440 Beginning of section indicator line, where level is greater than 3.
3442 Argument 1: level of section.
3444 @item section-other-end
3445 End of section indicator line, where level is greater than 3.
3447 Argument 1: level of section.
3449 @item begin-underline
3450 Beginning of underlined text.
3453 End of underlined text.
3456 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3460 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3464 Beginning of the first level of emphasized text.
3467 End of the first level of emphasized text.
3469 @item begin-more-emph
3470 Beginning of the second level of emphasized text.
3473 End of the second level of emphasized text.
3475 @item begin-most-emph
3476 Beginning of the third (and final) level of emphasized text.
3479 End of the third (and final) level of emphasized text.
3482 Beginning of verse text.
3485 String used to each space that is further indented than the beginning of
3488 @item begin-verse-line
3489 Beginning of a line of verse.
3491 @item empty-verse-line
3492 End of a line of verse.
3494 @item begin-last-stanza-line
3495 Beginning of the last line of a verse stanza.
3497 @item end-last-stanza-line
3498 End of the last line of a verse stanza.
3504 Beginning of an example region. To make use of this, an
3505 @samp{<example>} tag is needed.
3508 End of an example region. To make use of this, an @samp{</example>} tag
3512 Begin a centered line.
3515 End a centered line.
3518 Begin a quoted region.
3521 End a quoted region.
3523 @item begin-quote-item
3524 Begin a quote paragraph.
3526 @item end-quote-item
3527 End a quote paragraph.
3530 Begin an unordered list.
3533 End an unordered list.
3535 @item begin-uli-item
3536 Begin an unordered list item.
3539 End an unordered list item.
3542 Begin an ordered list.
3545 End an ordered list.
3547 @item begin-oli-item
3548 Begin an ordered list item.
3551 End an ordered list item.
3554 Begin a definition list.
3557 End a definition list.
3560 Begin a definition list item.
3563 End a definition list item.
3566 Begin a definition list term.
3569 End a definition list term.
3572 Begin a definition list entry.
3575 End a definition list entry.
3583 @item begin-table-group
3584 Begin a table grouping.
3586 @item end-table-group
3587 End a table grouping.
3589 @item begin-table-row
3595 @item begin-table-entry
3596 Begin a table entry.
3598 @item end-table-entry
3603 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3604 @comment node-name, next, previous, up
3605 @subsection Tag specifications for special markup
3606 @cindex publishing, markup tags
3608 @anchor{muse-publish-markup-tags}
3609 @code{muse-publish-markup-tags}
3611 A list of tag specifications, for specially marking up text.
3613 XML-style tags are the best way to add custom markup to Muse. This is
3614 easily accomplished by customizing this list of markup tags.
3616 For each entry, the name of the tag is given, whether it expects a
3617 closing tag and/or an optional set of attributes, whether it is
3618 nestable, and a function that performs whatever action is desired within
3619 the delimited region.
3621 The tags themselves are deleted during publishing, before the function
3622 is called. The function is called with three arguments, the beginning
3623 and end of the region surrounded by the tags. If properties are
3624 allowed, they are passed as a third argument in the form of an alist.
3625 The `end' argument to the function is always a marker.
3627 Point is always at the beginning of the region within the tags, when the
3628 function is called. Wherever point is when the function finishes is
3629 where tag markup will resume.
3631 These tag rules are processed once at the beginning of markup, and once
3632 at the end, to catch any tags which may have been inserted in-between.
3634 @node Style Elements, , Markup Tags, Common Elements
3635 @comment node-name, next, previous, up
3636 @subsection Parameters used for defining styles
3637 @cindex publishing, style elements
3639 Style elements are tags that define a style. Use
3640 @code{muse-define-style} to create a new style.
3643 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3646 @subheading Usable elements
3651 File extension to use for publishing files with this style.
3654 File extension to use for publishing links to Muse files with this
3658 File extension to use for publishing second-stage files with this style.
3660 For example, PDF publishing generates a LaTeX file first, then a PDF
3661 from that LaTeX file.
3664 List of markup rules for publishing a page with Muse.
3665 @xref{muse-publish-markup-regexps}.
3668 An alist of style types to custom functions for that kind of text.
3669 @xref{muse-publish-markup-functions}.
3672 Strings used for marking up text with this style.
3674 These cover the most basic kinds of markup, the handling of which
3675 differs little between the various styles.
3678 A list of tag specifications, used for handling extra tags.
3679 @xref{muse-publish-markup-tags}.
3682 A table of characters which must be represented specially.
3685 A function that is to be executed on the newly-created publishing buffer
3686 (or the current region) before any publishing occurs.
3688 This is used to set extra parameters that direct the publishing process.
3691 A function that is to be executed on the publishing buffer (or the
3692 current region) immediately after applying all of the markup regexps.
3694 This is used to fix the order of table elements (header, footer, body)
3698 A function that is to be executed on the publishing buffer after
3699 :before-end, and immediately after inserting the header and footer.
3701 This is used for generating the table of contents as well as setting the
3705 A function that is to be executed after saving the published file, but
3706 while still in its buffer.
3708 This is used for generating second-stage documents like PDF files from
3709 just-published LaTeX files.
3712 Header used for publishing files of this style.
3714 This may be a variable, text, or a filename. It is inserted at the
3715 beginning of a file, after evaluating the publishing markup.
3718 Footer used for publishing files of this style.
3720 This may be a variable, text, or a filename. It is inserted at the end
3721 of a file, after evaluating the publishing markup.
3724 Style sheet used for publishing files of this style.
3726 This may be a variable or text. It is used in the header of HTML and
3727 XHTML based publishing styles.
3730 The function used to browse the published result of files of this style.
3734 @node Deriving Styles, , Common Elements, Extending Muse
3735 @comment node-name, next, previous, up
3736 @section Deriving a new style from an existing one
3737 @cindex publishing styles, deriving
3739 To create a new style from an existing one, use @code{muse-derive-style}
3740 as follows. This is a good way to fix something you don't like about a
3741 particular publishing style, or to personalize it.
3744 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3747 The derived name is a string defining the new style, such as "my-html".
3748 The base name must identify an existing style, such as "html" -- if you
3749 have loaded @file{muse-html}. The style parameters are the same as
3750 those used to create a style, except that they override whatever
3751 definitions exist in the base style. However, some definitions only
3752 partially override. The following parameters support partial
3755 @xref{Style Elements}, for a complete list of all parameters.
3760 If a markup function is not found in the derived style's function list,
3761 the base style's function list will be queried.
3764 All regexps in the current style and the base style(s) will be used.
3767 If a markup string is not found in the derived style's string list, the
3768 base style's string list will be queried.
3772 @node Miscellaneous, Getting Help and Reporting Bugs, Extending Muse, Top
3773 @comment node-name, next, previous, up
3774 @chapter Miscellaneous add-ons, like a minor mode
3777 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
3780 @node Muse List Edit Minor Mode, , , Miscellaneous
3781 @comment node-name, next, previous, up
3782 @section Edit lists easily in other major modes
3783 @cindex muse-list-edit-minor-mode
3785 @code{muse-list-edit-minor-mode} is meant to be used with other major
3786 modes, such as Message (for composing email) and debian-changelog-mode
3787 (for editing debian/changelog files).
3789 It implements practically perfect support for editing and filling lists.
3790 It can even handle nested lists. In addition to Muse-specific list
3791 items ("-", numbers, definition lists, footnotes), it can also handle
3792 items that begin with "*" or "+". Filling list items behaves in the
3793 same way that it does in Muse, regardless of whether filladapt is also
3794 enabled, which is the primary reason to use this tool.
3796 @subheading Installation
3798 To use it, add ``(require 'muse-mode)'' to your Emacs customization file
3799 and add the function @code{turn-on-muse-list-edit-minor-mode} to any
3800 mode hooks where you wish to enable this minor mode.
3802 @subheading Keybindings
3804 @code{muse-list-edit-minor-mode} uses the following keybindings.
3808 @item M-RET (`muse-l-e-m-m-insert-list-item')
3809 Insert a new list item at point, using the indentation level of the
3812 @item C-< (`muse-l-e-m-m-decrease-list-item-indent')
3813 Decrease indentation of the current list item.
3815 @item C-> (`muse-l-e-m-m-increase-list-item-indent')
3816 Increase indentation of the current list item.
3820 @subheading Functions
3822 @defun muse-list-edit-minor-mode
3823 This is a global minor mode for editing files with lists.
3824 It is meant to be used with other major modes, and not with Muse mode.
3826 Interactively, with no prefix argument, toggle the mode.
3827 With universal prefix @var{arg} turn mode on.
3828 With zero or negative @var{arg} turn mode off.
3830 This minor mode provides the Muse keybindings for editing lists,
3831 and support for filling lists properly.
3833 It recognizes not only Muse-style lists, which use the "-"
3834 character or numbers, but also lists that use asterisks or plus
3835 signs. This should make the minor mode generally useful.
3837 Definition lists and footnotes are also recognized.
3839 Note that list items may omit leading spaces, for compatibility
3840 with modes that set @code{left-margin}, such as
3841 @code{debian-changelog-mode}.
3844 @defun turn-on-muse-list-edit-minor-mode
3845 Unconditionally turn on Muse list edit minor mode.
3848 @defun turn-off-muse-list-edit-minor-mode
3849 Unconditionally turn off Muse list edit minor mode.
3852 @node Getting Help and Reporting Bugs, History, Miscellaneous, Top
3853 @comment node-name, next, previous, up
3854 @chapter Getting Help and Reporting Bugs
3855 @cindex help, getting
3856 @cindex bugs, reporting
3858 After you have read this guide, if you still have questions about
3859 Muse, or if you have bugs to report, there are several places you can
3865 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
3866 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
3870 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
3871 that Michael Olson (the current maintainer) made for Muse.
3874 Muse has several different mailing lists.
3878 @item muse-el-announce
3879 Low-traffic list for Muse-related announcements.
3881 You can join this mailing list (@email{muse-el-announce@@gna.org})
3882 using the subscription form at
3883 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
3884 mailing list is also available via Gmane (@url{http://gmane.org/}). The
3885 group is called @samp{gmane.emacs.muse.announce}.
3887 @item muse-el-discuss
3888 Discussion, bugfixes, suggestions, tips, and the like for Muse.
3889 This mailing list also includes the content of muse-el-announce.
3891 You can join this mailing list (@email{muse-el-discuss@@gna.org})
3892 using the subscription form at
3893 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
3894 list is also available via Gmane with the identifier
3895 @samp{gmane.emacs.muse.general}.
3898 Log messages for commits made to Muse.
3900 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
3901 the subscription form at
3902 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
3903 is also available via Gmane with the identifier
3904 @samp{gmane.emacs.muse.scm}.
3906 @item muse-el-commits
3907 Generated bug reports for Emacs Muse. If you use our bug-tracker at
3908 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
3909 sent to this list automatically.
3911 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
3912 the subscription form at
3913 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
3914 is also available via Gmane with the identifier
3915 @samp{gmane.emacs.muse.cvs}.
3917 @item muse-el-internationalization
3918 Discussion of translation of the Muse website and documentation into
3921 You can join this mailing list
3922 (@email{muse-el-internationalization@@gna.org}) using the subscription
3923 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
3924 mailing list is also available via Gmane with the identifier
3925 @samp{gmane.emacs.muse.internationalization}.
3930 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
3931 contributors are frequently around and willing to answer your
3932 questions. The @samp{#muse} channel is also available for
3933 Muse-specific help, and its current maintainer hangs out there.
3936 The maintainer of Emacs Muse, Michael Olson, may be contacted at
3937 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
3938 it is often better to use the muse-el-discuss mailing list.
3942 @node History, Contributors, Getting Help and Reporting Bugs, Top
3943 @comment node-name, next, previous, up
3944 @chapter History of This Document
3945 @cindex history, of Muse
3949 John Wiegley started Muse upon realizing that EmacsWiki had some serious
3950 limitations. Around February 2004, he started making "emacs-wiki version
3951 3.00 APLHA", which eventually became known as Muse.
3953 Most of those who frequent the emacs-wiki mailing list continued to use
3954 emacs-wiki, mainly because Planner hasn't been ported over to it.
3956 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
3957 John Wiegley's request.
3960 Michael Olson overhauled this document and added many new sections in
3961 preparation for the first release of Muse (3.01).
3965 @node Contributors, GNU Free Documentation License, History, Top
3966 @comment node-name, next, previous, up
3967 @chapter Contributors to This Documentation
3968 @cindex contributors
3970 The first draft of this document was taken from the emacs-wiki texinfo
3971 manual. Michael Olson adapted it for Muse and added most of its
3974 John Sullivan did a majority of the work on the emacs-wiki texinfo
3977 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
3978 emacs-wiki texinfo manual.
3981 @node GNU Free Documentation License, Concept Index, Contributors, Top
3982 @appendix GNU Free Documentation License
3983 @include doclicense.texi
3986 @node Concept Index, , GNU Free Documentation License, Top
3987 @comment node-name, next, previous, up