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 * Citations:: Support for citing other resources.
127 * Comments:: Lines to omit from published output.
128 * Tag Summary:: Tags that Muse recognizes.
130 Publishing Various Types of Documents
132 * Blosxom:: Integrating Muse and pyblosxom.cgi.
133 * Book:: Publishing entries into a compilation.
134 * ConTeXt:: Publishing ConTeXt documents.
135 * DocBook:: Publishing in DocBook XML form.
136 * HTML:: Publishing in HTML or XHTML form.
137 * Journal:: Keeping a journal or blog.
138 * LaTeX:: Publishing LaTeX documents.
139 * Poem:: Publish a poem to LaTex or PDF.
140 * Texinfo:: Publish entries to Texinfo format or PDF.
141 * XML:: Publish entries to XML.
143 Integrating Muse and pyblosxom.cgi
145 * Blosxom Requirements:: Other tools needed for the Blosxom style.
146 * Blosxom Entries:: Format of a Blosxom entry and automation.
147 * Blosxom Options:: Blosxom styles and options provided.
149 Making your own publishing styles
151 * Common Elements:: Common functionality shared by styles.
152 * Deriving Styles:: Deriving a new style from an existing
155 Common functionality shared by styles
157 * Markup Functions:: Specifying functions to mark up text.
158 * Markup Regexps:: Markup rules for publishing.
159 * Markup Strings:: Strings specific to a publishing style.
160 * Markup Tags:: Tag specifications for special markup.
161 * Style Elements:: Parameters used for defining styles.
163 Miscellaneous add-ons, like a minor mode
165 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
170 @node Preface, Introduction, Top, Top
171 @comment node-name, next, previous, up
172 @chapter About the documentation
174 This document describes Muse, which was written by John Wiegley and is
175 now maintained by Michael Olson. Several versions of this manual are
179 @item PDF: http://mwolson.org/static/doc/muse.pdf
180 @item HTML (single file): http://mwolson.org/static/doc/muse.html
181 @item HTML (multiple files): http://mwolson.org/static/doc/muse/
184 @node Introduction, Obtaining Muse, Preface, Top
185 @comment node-name, next, previous, up
186 @chapter What is Muse?
188 Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring
189 and publishing environment for Emacs. It simplifies the process of
190 writing documents and publishing them to various output formats.
192 Muse consists of two main parts: an enhanced text-mode for authoring
193 documents and navigating within Muse projects, and a set of publishing
194 styles for generating different kinds of output.
196 What makes Muse distinct from other text-publishing systems is a modular
197 environment, with a rather simple core, in which "styles" are derived
198 from to create new styles. Much of Muse's overall functionality is
199 optional. For example, you can use the publisher without the
200 major-mode, or the mode without doing any publishing; or if you don't
201 load the Texinfo or LaTeX modules, those styles won't be available.
203 The Muse codebase is a departure from emacs-wiki.el version 2.44. The
204 code has been restructured and rewritten, especially its publishing
205 functions. The focus in this revision is on the authoring and
206 publishing aspects, and the "wikiness" has been removed as a default
207 behavior (available in the optional @file{muse-wiki} module). CamelCase
208 words are no longer special by default.
210 One of the principal aims in the development of Muse is to make it very
211 easy to produce good-looking, standards-compliant documents.
213 @node Obtaining Muse, Installation, Introduction, Top
214 @comment node-name, next, previous, up
215 @chapter How to Get Muse Releases and Development Changes
218 * Releases:: Released versions of Muse.
219 * Development:: Latest unreleased development changes.
222 @node Releases, Development, Obtaining Muse, Obtaining Muse
223 @comment node-name, next, previous, up
224 @section Released versions of Muse
226 Choose to install a release if you want to minimize risk.
228 Errors are corrected in development first. User-visible changes will be
229 announced on the @email{muse-el-discuss@@gna.org} mailing list.
230 @xref{Getting Help and Reporting Bugs}.
232 @cindex releases, Debian package
233 @cindex Debian package for Muse
234 Debian users can get Muse via apt-get. The @file{muse-el} package is
235 available both at Michael Olson's APT repository and the official Debian
236 repository. To make use of the former, add the following line to your
237 @file{/etc/apt/sources.list} file and run @code{apt-get install muse}.
240 deb http://mwolson.org/debian/ ./
243 @cindex releases, Ubuntu package
244 @cindex Ubuntu package for Muse
245 Ubuntu users can also get Muse via apt-get. The @file{muse-el} package
246 is available both at Michael Olson's APT repository and the official
247 Ubuntu repository. To make use of the former, add the following line to
248 your @file{/etc/apt/sources.list} file and run @code{apt-get install
252 deb http://mwolson.org/ubuntu/ ./
255 The reason for making separate Debian and Ubuntu packages is that this
256 manual is under the GFDL, and Debian will not allow it to be distributed
257 in its main repository. Ubuntu, on the other hand, permits this manual
258 to be included with the @file{muse-el} package.
260 @cindex releases, from source
261 Alternatively, you can download the latest release from
262 @uref{http://download.gna.org/muse-el/} .
264 @node Development, , Releases, Obtaining Muse
265 @comment node-name, next, previous, up
266 @section Latest unreleased development changes
269 Choose the development version if you want to live on the bleeding edge
270 of Muse development or try out new features before release.
272 @cindex git version control system, using
273 The git version control system allows you to keep up-to-date with the
274 latest changes to the development version of Muse. It also allows you
275 to contribute changes (via commits, if you are have developer access to
276 the repository, or via patches, otherwise). If you would like to
277 contribute to Muse development, it is highly recommended that you use
280 If you are new to git, you might find this tutorial helpful:
281 @uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}.
283 Downloading the Muse module with git and staying up-to-date involves
290 @item Debian and Ubuntu: @kbd{apt-get install git-core}.
291 @item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
292 @item Other operating systems: download, compile, and install the source
293 from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
294 package for your operating system.
297 @item Download the Muse development branch.
299 If you have developer access to Muse, do:
302 git clone ssh://repo.or.cz/srv/git/muse-el.git muse
308 git clone git://repo.or.cz/muse-el.git muse
311 If you are behind a restrictive firewall, and do not have developer
312 access, then do the following instead:
315 git clone http://repo.or.cz/r/muse-el.git muse
318 @item List upstream changes that are missing from your local copy.
319 Do this whenever you want to see whether new changes have been committed
320 to Muse. If you wish, you may skip this step and proceed directly to
324 # Change to the source directory you are interested in.
327 # Fetch new changes from the repository, but don't apply them yet
330 # Display log messages for the new changes
334 ``origin'' is git's name for the location where you originally got Muse
335 from. You can change this location at any time by editing the
336 @file{.git/config} file in the directory where the Muse source was
339 @cindex updating Muse with git
340 @item Update to the latest version by pulling in any missing changes.
347 git will show how many files changed, and will provide a visual display
348 for how many lines were changed in each file.
352 There are other ways to interact with the Muse repository.
355 @item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git}
356 @item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz}
357 @item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip}
360 The latest development snapshot can lag behind the git repo by as much
361 as 20 minutes, but never more than that.
363 @subheading Becoming a Muse developer
364 @cindex developer, becoming
366 If you want commit access to the shared Muse repository, then register
367 an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and
368 contact the current maintainer at @email{mwolson@@gnu.org}. It would be
369 best to send some patches to the @email{muse-el-discuss@@gna.org}
370 mailing list first, so that he knows that you know what you are doing.
371 @xref{Getting Help and Reporting Bugs}, for instructions on subscribing
374 You must also be willing to sign a copyright assignment for your changes
375 to Muse, since Muse is a GNU project. The current maintainer will
376 assist you in this process if you contact him.
378 For information on committing changes to Muse and performing
379 development, please consult
380 @uref{http://emacswiki.org/cgi-bin/wiki/MuseDevelopment}.
382 @node Installation, Getting Started, Obtaining Muse, Top
383 @comment node-name, next, previous, up
384 @chapter Compiling and Installing Muse
386 Muse may be compiled and installed on your machine.
388 @subheading Compilation
389 @cindex compiling Muse
391 This is an optional step, since Emacs Lisp source code does not
392 necessarily have to be byte-compiled. Byte-compilation may yield a very
393 slight speed increase.
395 A working copy of Emacs or XEmacs is needed in order to compile Emacs
396 Muse. By default, the program that is installed with the name
397 @command{emacs} will be used.
399 If you want to use the @command{xemacs} binary to perform the
400 compilation, you must copy @file{Makefile.defs.default} to
401 @file{Makefile.defs} in the top-level directory, and then edit
402 @file{Makefile.defs} as follows. You can put either a full path to an
403 Emacs or XEmacs binary or just the command name, as long as it is in the
404 @env{PATH}. Depending on your setup, changes to the @option{PREFIX},
405 @option{ELISPDIR}, and/or @option{INFODIR} variables may also need to be
410 SITEFLAG = -no-site-file
411 # Edit the section as necessary
412 install_info = install-info --section "XEmacs 21.4" $(1).info \
416 Running @code{make} in the top-level directory should compile the Muse
417 source files in the @file{lisp} directory, and generate an autoloads
418 file in @file{lisp/muse-autoloads.el}.
420 @subheading Installation
421 @cindex installing Muse
423 Muse may be installed into your file hierarchy by doing the following.
425 Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the
426 top-level directory, if you haven't done so already. Then edit the
427 @file{Makefile.defs} file so that @env{ELISPDIR} points to where you
428 want the source and compiled Muse files to be installed and
429 @env{INFODIR} indicates where to put the Muse manual. As mentioned
430 earlier, you will want to edit @env{EMACS} and @env{SITEFLAG} as shown
431 in the Compilation section if you are using XEmacs.
433 If you are installing Muse on a Debian or Ubuntu system, you might want
434 to change the value of @env{INSTALLINFO} as specified in
435 @file{Makefile.defs}.
437 If you wish to install Muse to different locations than the defaults
438 specify, edit @file{Makefile.defs} accordingly.
440 Run @code{make} as a normal user, if you haven't done so already.
442 Run @code{make install} as the root user if you have chosen installation
443 locations that require root permissions.
446 @cindex ELPA package for Muse
448 For those used to installing software packages, there will be a
449 @code{muse} package available in the Emacs Lisp Package Archive
450 (abbreviated ``ELPA'') as of the 3.10 release of Muse. This package
451 will be compiled and installed automatically in a user-specific
452 location. For more information on ELPA, see
453 @uref{http://tromey.com/elpa/}.
455 @node Getting Started, Projects, Installation, Top
456 @comment node-name, next, previous, up
457 @chapter Getting Started
461 * Loading Muse:: How to load Muse.
462 * Using Muse Mode:: How to edit files in Muse.
463 * Publishing Files Overview:: Publishing a single file or project.
464 * File Extensions:: Using a different file extension.
467 @node Loading Muse, Using Muse Mode, Getting Started, Getting Started
468 @comment node-name, next, previous, up
469 @section How to Load Muse
470 @cindex settings, init file
472 To use Muse, add the directory containing its files to your
473 @code{load-path} variable, in your @file{.emacs} file. Then, load in
474 the authoring mode, and the styles you wish to publish to. An example
478 (add-to-list 'load-path "<path to Muse>")
480 (require 'muse-mode) ; load authoring mode
482 (require 'muse-html) ; load publishing styles I use
483 (require 'muse-latex)
484 (require 'muse-texinfo)
485 (require 'muse-docbook)
487 (require 'muse-project) ; publish files in projects
490 An easy way of seeing which settings are available and changing settings
491 is to use the Muse customization interface. To do this, type
492 @kbd{M-x customize-group muse RET}. Each of the options has its own
493 documentation. Options are grouped logically according to what effect
496 @node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started
497 @comment node-name, next, previous, up
498 @section How to Edit Files in Muse
499 @cindex editing Muse files
501 Muse Mode should automatically be activated when you visit a file with a
502 ``.muse'' extension. One such file is @file{QuickStart.muse}, which is
503 available in the @file{examples} directory of the Muse distribution.
504 You can tell that Muse Mose has been activated by checking for the text
505 ``Muse'' in your mode line. If Muse Mode has not been activated, you
506 may activate it by type @kbd{M-x muse-mode RET}.
508 You will notice that Muse files are highlighted very simply. Links are
509 colored blue, headings are large and bold text, and @verb{|<example>|}
510 tags are colored in grey.
512 There are several different ways to edit things like links, which hide
513 the underlying Muse markup. One way is to toggle font-locking off by
514 hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make
515 changes, and then hit @kbd{C-c C-l} again to toggle font-locking back
516 on. Another way is just to move into the text and edit it. Markup can
517 also be removed by normal deletion methods, though some side effects
518 might require a second deletion.
520 For the particular case of editing links, it is easiest to move to the
521 link and do @kbd{C-c C-e}, which is also @kbd{M-x
522 muse-edit-link-at-point}. This prompts you for the link and its
523 description, using the previous contents of the link as initial values.
524 A link to another Muse file may be created by hitting @kbd{C-c TAB l}.
525 A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be
526 followed by hitting @kbd{RET} on them.
528 If you want to add a new list item, this may by accomplished by hitting
529 @kbd{M-RET}. This will put a dash and some spaces on the screen. The
530 dash is the Muse markup that indicates a list item. It is also possible
531 to created ``nested'' lists with this command, by adjusting the number
532 of spaces in front of the dashes. If you have lists with long lines,
533 you can move to a list item and hit @kbd{M-q} to wrap it onto multiple
536 @node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started
537 @comment node-name, next, previous, up
538 @section Publishing a Single File or Project
539 @cindex editing Muse files
541 The command @kbd{M-x muse-project-publish-this-file} will publish the
542 current document to any available publishing style (a publishing style
543 is an output format, like HTML or Docbook), placing the output in the
544 current directory. If you are in Muse Mode, this command will be bound
545 to @kbd{C-c C-t}. If the file has been published recently, and its
546 contents have not changed, running @kbd{C-c C-t} again will not publish
547 the file. To force publishing in this case, do @kbd{C-u C-c C-t}.
549 If you have set up projects and are visiting a file that is part of a
550 project, then @kbd{C-c C-t} will restrict the output formats to those
551 which are used by the project, and will automatically publish to the
552 output directory defined by the project. If you want to publish to a
553 different directory or use a different format, then use @kbd{C-c M-C-t},
554 which is also @kbd{M-x muse-publish-this-file}.
556 If the currently opened file is part of a defined project in
557 @code{muse-project-alist}, it (and the rest of the changed files in a
558 project) may be published using @kbd{C-c C-p}.
560 @node File Extensions, , Publishing Files Overview, Getting Started
561 @comment node-name, next, previous, up
562 @section Using a Different File Extension
563 @cindex file extension, specifying
565 By default, Muse expects all project files to have the file extension
566 @file{.muse}. Files without this extension will not be associated with
567 Muse mode and will not be considered part of any project, even if they
568 are within a project directory.
570 If you don't want to use @file{.muse}, you can customize the extension
571 by setting the value of @code{muse-file-extension}.
573 If you don't want to use any extension at all, and want Muse to
574 autodetect project files based on their location, then add the following
575 to your Muse settings file.
578 (setq muse-file-extension nil
582 Note that if you chose to have @code{muse-file-extension} set to
583 @code{nil}, you may have trouble if your @file{.emacs} file or other
584 init scripts attempt to visit a Muse file. (A very common example of
585 this is if you use Planner with Muse and run @code{(plan)} from your
586 @file{.emacs}.) If you wish to visit Muse files from your
587 @file{.emacs}, be sure to also add the following additional code before
588 any such visits happen:
591 (add-hook 'find-file-hooks 'muse-mode-maybe)
595 @node Projects, Keystroke Summary, Getting Started, Top
596 @comment node-name, next, previous, up
597 @chapter Creating and Managing Muse Projects
600 Often you will want to publish all the files within a directory to a
601 particular set of output styles automatically. To support, Muse
602 allows for the creation of "projects".
605 * Single Project:: A single-project example.
606 * Multiple Projects:: A multiple-project example.
607 * Projects and Subdirectories:: Publishing subdirectories in projects.
608 * Options for Projects:: Listing of available options for projects.
611 @node Single Project, Multiple Projects, Projects, Projects
612 @comment node-name, next, previous, up
613 @section A Single-Project Example
614 @cindex projects, single
616 Here is a sample project, which may be defined in your @file{.emacs}
620 (setq muse-project-alist
621 '(("Website" ("~/Pages" :default "index")
622 (:base "html" :path "~/public_html")
623 (:base "pdf" :path "~/public_html/pdf"))))
626 The above defines a project named "website", whose files are located
627 in the directory @file{~/Pages}. The default page to visit is
628 @file{index}. When this project is published, each page will be
629 output as HTML to the directory @file{~/public_html}, and as PDF to
630 the directory @file{~/public_html/pdf}. Within any project page, you
631 may create a link to other pages using the syntax @samp{[[pagename]]}.
633 If you would like to include only some files from a directory in a Muse
634 project, you may use a regexp in place of @file{~/Pages} in the example.
636 @node Multiple Projects, Projects and Subdirectories, Single Project, Projects
637 @comment node-name, next, previous, up
638 @section A Multiple-Project Example
639 @cindex projects, multiple
641 It is possible to specify multiple projects. Here is an example of
642 three projects: a generic website, a projects area, and a day-planner
643 (the day-planner part requires Planner Mode---see
644 @uref{http://wjsullivan.net/PlannerMode.html} to get it).
647 (setq muse-project-alist
648 '(("Website" ("~/Pages" :default "index")
649 (:base "html" :path "~/public_html"))
650 (("Projects" ("~/Projects" :default "index")
652 :path "~/public_html/projects"
653 :exclude "/TopSecret")
655 :path "~/public_html/projects/pdf"
656 :exclude "/TopSecret")))
659 :major-mode planner-mode
660 :visit-link planner-visit-link)
661 (:base "planner-xhtml"
662 :path "~/public_html/plans"))))
665 The @option{:major-mode} attribute specifies which major to use when
666 visiting files in this directory.
668 The @option{:visit-link} attribute specifies the function to call when
671 The @option{:exclude} attribute has a regexp that matches files to never
674 @node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects
675 @comment node-name, next, previous, up
676 @section Publishing Subdirectories in Projects
677 @cindex projects, subdirectories
679 If you want to publish a directory and all of its subdirectories, Muse
680 provides two convenience functions that together generate the proper
681 rules for you. Note that we use the backtick to begin this
682 muse-project-alist definition, rather than a single quote.
685 (setq muse-project-alist
686 `(("Website" ("~/Pages" :default "index")
687 (:base "html" :path "~/public_html"))
688 ("Blog" (,@@(muse-project-alist-dirs "~/Blog")
690 ;; Publish this directory and its subdirectories. Arguments
691 ;; are as follows. The above `muse-project-alist-dirs' part
693 ;; 1. Source directory
694 ;; 2. Output directory
695 ;; 3. Publishing style
696 ;; remainder: Other things to put in every generated style
697 ,@@(muse-project-alist-styles "~/Blog"
702 The @code{muse-project-alist-dirs} function takes a directory and
703 returns it and all of its subdirectories in a list.
705 The @code{muse-project-alist-styles} function is explained by the
708 The ``blosxom'' text is the name of another publishing style, much like
709 ``html''. @xref{Blosxom}, for further information about it. You can
710 use any publishing style you like for the third argument to
711 @code{muse-project-alist-styles}.
713 @node Options for Projects, , Projects and Subdirectories, Projects
714 @comment node-name, next, previous, up
715 @section Listing of Available Options for Projects
716 @cindex projects, options
717 @cindex muse-project-alist, reference
719 This is a listing of all of the various options (or, more accurately:
720 attributes) that may be specified in @code{muse-project-alist}.
722 Each muse-project-alist entry looks like this:
725 (PROJECT-NAME (SOURCES)
729 We refer to these names below.
731 ``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values.
732 The first value is a keyword, like @option{:default}. The second part
733 is the value associated with that keyword, such as the text ``index''.
734 If you are familiar with Emacs Lisp property lists, the concept is
735 similar to that, except that in the SOURCES section, single directories
736 can be interspersed with two-value attributes.
738 @subheading Project Name
740 This is a string that indicates the name of the project. It is
741 primarily used for publishing interwiki links with the
742 @file{muse-wiki.el} module.
746 This part of a muse-project-alist entry consists of two-value
747 attributes, and also directory names. If you are publishing a book, the
748 order of directories and attributes is significant.
750 The minimal content for the sources section is a list of directories.
755 Indicates a new chapter of a book. The text of the title of the chapter
756 comes immediately after this keyword.
759 Indicates the end of a book. Directories listed after this one are
760 ignored when publishing a book. The value ``t'' (without quotes) should
761 come immediately after this keyword.
764 A function to call while publishing a book. This is useful for doing
765 something just after a particular chapter.
768 Indicates the beginning of a new part of the book. The text of the
769 title should come immediately after this keyword.
772 Indicate a particular publishing style to use for this part of the book.
773 If this is specified, it should come just after a @option{:part}
777 The default page to visit when browsing a project. Also, if you are
778 using the @file{muse-wiki.el} module, publishing a link to just a
779 project's name will cause it to link to this default file.
782 This specifies a list of pages which should be published every time a
783 project is published (by using @kbd{C-c C-p}, for example), regardless
784 of whether their contents have changed. This is useful for updating
785 Index pages, pages that use the @verb{|<include>|} tag, and other pages
786 that have dynamically-generated content.
789 This specifies the major mode to use when visiting files in this
790 project. The default is @code{muse-mode}.
793 This indicates that while publishing a book, do not automatically create
794 chapters. Values which may follow this are nil (the default, which
795 means that we automatically create chapters), or non-nil, which means
796 that we manually specify chapters with the @option{:book-chapter}
799 @item :publish-project
800 Indicates which function we should call when publishing a project.
803 This specifies a list of variables and values to set when publishing a
804 project. The list should be a property list, which is in the form:
807 (VAR1 VALUE1 VAR2 VALUE2 ...)
811 Specifies the function to call when visiting a link. The default is
812 @code{muse-visit-link-default}. The arguments for that function should
813 be (1) the link and (2) whether to visit the link in a new window.
819 This part of a muse-project-alist entry is composed of lists of
820 attributes. Each list is called an ``output style''.
822 The minimal content for an output style is a @option{:base} attribute
823 and a @option{:path} attribute.
828 Publishing style to use, such as ``html'', ``docbook'', or ``pdf''.
831 An external URL which can be used to access published files. This is
832 mainly used by the @file{muse-wiki} module when publishing links between
833 two separate projects, if the projects are served on different domains.
835 It is also used by the @file{muse-journal} module to create the RSS or
839 Exclude items matching a regexp from being published. The regexp should
840 usually begin with "/".
843 Only include items matching a regexp when publishing. The regexp should
844 usually begin with "/".
847 The directory in which to store published files.
850 A file containing the timestamps (that is, time of creation) for files
851 in this project. It might eventually used by the @file{muse-blosxom}
852 module, but this option is not currently in use by any Muse code.
857 @node Keystroke Summary, Markup Rules, Projects, Top
858 @comment node-name, next, previous, up
859 @chapter Keys Used in Muse Mode
862 This is a summary of keystrokes available in every Muse buffer.
866 @item C-c C-a (`muse-index')
867 Display an index of all known Muse pages.
869 @item C-c C-b (`muse-find-backlinks')
870 Find all pages that link to this page.
872 @item C-c C-e (`muse-edit-link-at-point')
875 @item C-c C-f (`muse-project-find-file')
876 Open another Muse page. Prompt for the name.
878 @item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file')
879 Insert a link to a file interactively.
881 @item C-c C-i t, C-c TAB t (`muse-insert-tag')
882 Insert a tag interactively.
884 @item C-c C-i u, C-c TAB u (`muse-insert-url')
885 Insert a URL interactively.
887 @item C-c C-l (`font-lock-mode')
888 Toggle font lock / highlighting for the current buffer.
890 @item C-c C-p (`muse-project-publish')
891 Publish any Muse pages that have changed.
893 @item C-c C-s (`muse-search')
894 Find text in all files of the current project.
896 @item C-c C-t (`muse-project-publish-this-file')
897 Publish the currently-visited file. Prompt for the style if the current
898 file can be published using more than one style.
900 @item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file')
901 Publish the currently-visited file. Prompt for both the style and
904 @item C-c C-v (`muse-browse-result')
905 Show the published result of this page.
907 @item C-c = (`muse-what-changed')
908 Diff this page against the last backup version.
911 Move to the next Wiki reference.
914 Move to the previous Wiki reference.
917 Complete the name of a page from the current project at point.
920 Insert a new list item at point, indenting properly.
923 Decrease the indentation of the list item at point.
926 Increase the indentation of the list item at point.
928 @item M-x muse-colors-toggle-inline-images RET
929 Toggle display of inlined images on/off.
934 @node Markup Rules, Publishing Styles, Keystroke Summary, Top
935 @comment node-name, next, previous, up
936 @chapter Rules for Using Markup
939 A Muse document uses special, contextual markup rules to determine how
940 to format the output result. For example, if a paragraph is indented,
941 Muse assumes it should be quoted.
943 There are not too many markup rules, and all of them strive to be as
944 simple as possible so that you can focus on document creation, rather
948 * Paragraphs:: Paragraphs: centering and quoting.
949 * Headings:: Levels of headings.
950 * Directives:: Directives at the beginning of a
952 * Emphasizing Text:: Bold, italicized, and underlined text.
953 * Footnotes:: Making notes to be shown at the end.
954 * Verse:: Indicating poetic stanzas.
955 * Lists:: Lists of items.
956 * Tables:: Generation of data tables.
957 * Explicit Links:: Hyperlinks and email addresses with
959 * Implicit Links:: Bare URLs, WikiNames, and InterWiki
961 * Images:: Publishing and displaying images.
962 * Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
963 * Embedded Lisp:: Evaluating Emacs Lisp code in documents
965 * Citations:: Support for citing other resources.
966 * Comments:: Lines to omit from published output.
967 * Tag Summary:: Tags that Muse recognizes.
970 @node Paragraphs, Headings, Markup Rules, Markup Rules
971 @comment node-name, next, previous, up
972 @section Paragraphs: centering and quoting
975 Paragraphs in Muse must be separated by a blank line.
977 @cindex paragraphs, centered
978 @subheading Centered paragraphs and quotations
980 A line that begins with six or more columns of whitespace (either tabs
981 or spaces) indicates a centered paragraph. Alternatively, you can use
982 the @verb{|<center>|} tag to surround regions that are to be published as
985 @cindex paragraphs, quoted
987 But if a line begins with whitespace, though less than six columns, it
988 indicates a quoted paragraph. Alternatively, you can use the
989 @verb{|<quote>|} tag to surround regions that are to be published as
993 @cindex monospace, rendering blocks
994 @cindex HTML, rendering blocks in monospace
995 @subheading Literal paragraphs
997 The @verb{|<example>|} tag is used for examples, where whitespace should
998 be preserved, the text rendered in monospace, and any characters special
999 to the output style escaped.
1001 @cindex literal text
1002 @cindex HTML, inserting a raw block
1003 There is also the @verb{|<literal>|} tag, which causes a marked block to
1004 be entirely left alone. This can be used for inserting a hand-coded
1005 HTML blocks into HTML output, for example.
1007 If you want some text to only be inserted when publishing to a
1008 particular publishing style, use the @option{style} attribute for the
1009 @verb{|<literal>|} tag. An example follows.
1012 <literal style="latex">
1013 A LaTeX-based style was used in the publishing of this document.
1017 This will leave the region alone if the current publishing style is
1018 ``latex'' or based on ``latex'', such as ``pdf'', and delete the region
1019 otherwise. It is also possible to leave the text alone only for one
1020 particular style, rather than its derivations, by adding
1021 @code{exact="t"} to the tag.
1023 @node Headings, Directives, Paragraphs, Markup Rules
1024 @comment node-name, next, previous, up
1025 @section Levels of headings
1028 A heading becomes a chapter or section in printed output -- depending on
1029 the style. To indicate a heading, start a new paragraph with one or
1030 more asterices, followed by a space and the heading title. Then begin
1031 another paragraph to enter the text for that section.
1033 All levels of headings will be published. Most publishing styles only
1034 distinguish the between the first 4 levels, however.
1046 @node Directives, Emphasizing Text, Headings, Markup Rules
1047 @comment node-name, next, previous, up
1048 @section Directives at the beginning of a document
1051 Directives are lines beginning with the @samp{#} character that come
1052 before any paragraphs or sections in the document. Directives are of
1053 the form ``#directive content of directive''. You can use any
1054 combination of uppercase and lowercase letters for directives, even if
1055 the directive is not in the list below.
1057 The @code{muse-publishing-directive} function may be used in header and
1058 footer text to access directives. For example, to access the
1059 @code{#title} directive, use @code{(muse-publishing-directive "title")}.
1061 The following is a list of directives that Muse uses.
1066 The author of this document.
1068 If this is not specified, Muse will attempt to figure it out from the
1069 @code{user-full-name} variable.
1073 The date that the document was last modified.
1075 This is used by publishing styles that are able to embed the date
1080 A short description of this document.
1082 This is used by the @code{journal} publishing style to embed information
1083 inside of an RSS/RDF feed.
1087 The title of this document.
1089 If this is not specified, the name of the file is used.
1093 @node Emphasizing Text, Footnotes, Directives, Markup Rules
1094 @comment node-name, next, previous, up
1095 @section Bold, italicized, and underlined text
1096 @cindex emphasizing text
1097 @cindex underlining text
1098 @cindex italicizing text
1099 @cindex verbatim text
1100 @cindex monospace, rendering words
1102 To emphasize text, surround it with certain specially recognized
1108 ***very strong emphasis***
1110 =verbatim and monospace=
1114 While editing a Muse document in Muse mode, these forms of emphasis will
1115 be highlighted in a WYSIWYG manner. Each of these forms may span
1118 Verbatim text will be colored as gray by default. To change this,
1119 customize @code{muse-verbatim-face}.
1121 You can also use the @verb{|<code>|} tag to indicate verbatim and
1122 monospace text. This is handy for regions that have an ``='' in them.
1124 @node Footnotes, Verse, Emphasizing Text, Markup Rules
1125 @comment node-name, next, previous, up
1126 @section Making notes to be shown at the end
1129 A footnote reference is simply a number in square brackets. To define
1130 the footnote, place this definition at the bottom of your file.
1131 @samp{footnote-mode} can be used to greatly facilitate the creation of
1132 these kinds of footnotes.
1134 Footnotes are defined by the same number in brackets occurring at the
1135 beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
1136 easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
1137 the point of insertion.
1139 @node Verse, Lists, Footnotes, Markup Rules
1140 @comment node-name, next, previous, up
1141 @section Indicating poetic stanzas
1145 Poetry requires that whitespace be preserved, but without resorting to
1146 monospace. To indicate this, use the following markup, reminiscent of
1150 > A line of Emacs verse;
1151 > forgive its being so terse.
1154 You can also use the @verb{|<verse>|} tag, if you prefer.
1158 A line of Emacs verse;
1159 forgive its being so terse.
1163 @cindex verses, multiple stanzas
1164 Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
1169 A line of Emacs verse;
1170 forgive its being so terse.
1172 In terms of terse verse,
1177 @node Lists, Tables, Verse, Markup Rules
1178 @comment node-name, next, previous, up
1179 @section Lists of items
1182 Lists are given using special characters at the beginning of a line.
1183 Whitespace must occur before bullets or numbered items, to distinguish
1184 from the possibility of those characters occurring in a real sentence.
1186 @cindex lists, bullets
1187 These are rendered as a bullet list.
1196 @cindex lists, enumerated
1197 An enumerated list follows.
1206 @cindex lists, definitions
1207 Here is a definition list.
1211 This is a first definition
1212 And it has two lines;
1213 no, make that three.
1215 Term2 :: This is a second definition
1218 @subheading Nested lists
1220 @cindex lists, nested
1221 It is possible to nest lists of the same or different kinds. The
1222 ``level'' of the list is determined by the amount of initial whitespace.
1227 - Level 1, bullet item one
1228 1. Level 2, enum item one
1229 2. Level 2, enum item two
1230 - Level 1, bullet item two
1231 1. Level 2, enum item three
1232 2. Level 2, enum item four
1236 @subheading Breaking list items
1238 @cindex lists, breaking lines
1239 If you want to break up a line within any list type, just put one blank
1240 line between the end of the previous line and the beginning of the next
1241 line, using the same amount of initial indentation.
1244 - bullet item 1, line 1
1246 bullet item 1, line 2
1252 - bullet item 2, line 1
1254 bullet item 2, line 2
1257 @node Tables, Explicit Links, Lists, Markup Rules
1258 @comment node-name, next, previous, up
1259 @section Generation of data tables
1262 @cindex tables, simple
1263 Only very simple tables are supported. The syntax is as follows.
1266 Double bars || Separate header fields
1268 Single bars | Separate body fields
1269 Here are more | body fields
1271 Triple bars ||| Separate footer fields
1274 Some publishing styles require header fields to come first, then footer
1275 fields, and then the body fields. You can use any order for these
1276 sections that you like, and Muse will re-order them for you at
1279 If you wish to disable table generation for one Muse file, add the
1280 directive @samp{#disable-tables t} to the top of the file.
1282 @subheading Other table formats
1284 @cindex tables, orgtbl-mode style
1285 It is possible to publish very basic Orgtbl-mode style tables.
1288 | org | style | table |
1289 |------+-------+-------|
1293 |------+-------+-------|
1297 If you are used to the way that Org Mode publishes these tables, then
1298 customize `muse-html-table-attributes' to the following, in order to get
1299 a similar kind of output.
1302 border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"
1305 @cindex tables, table.el style
1306 @file{table.el} style tables are also supported, as long as
1307 @file{table.el} itself supports outputting tables for a particular
1308 publishing style. At the time of this writing, the ``html'', ``latex'',
1309 and ``docbook'' styles are supported by @file{table.el}. Styles derived
1310 from these styles will also work.
1322 @node Explicit Links, Implicit Links, Tables, Markup Rules
1323 @comment node-name, next, previous, up
1324 @section Hyperlinks and email addresses with descriptions
1325 @cindex links, explicit
1327 A hyperlink can reference a URL, or another page within a Muse
1328 project. In addition, descriptive text can be specified, which should
1329 be displayed rather than the link text in output styles that supports
1330 link descriptions. The syntax is as follows.
1333 [[link target][link description]]
1334 [[link target without description]]
1337 Thus, the current maintainer's homepage for Muse can be found
1338 @samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]},
1339 or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}.
1341 @node Implicit Links, Images, Explicit Links, Markup Rules
1342 @comment node-name, next, previous, up
1343 @section Bare URLs, WikiNames, and InterWiki links
1344 @cindex links, implicit
1348 @cindex Email addresses
1350 A URL or email address encountered in the input text is published as a
1351 hyperlink. These kind of links are called @dfn{implicit links} because
1352 they are not separated from the rest of the Muse document in any way.
1354 Some characters in URLs will prevent Muse from recognizing them as
1355 implicit links. If you want to link to a URL containing spaces or any of
1356 the characters ``][,"'`()<>^'', you will have to make the link
1357 explicit. The punctuation characters ``.,;:'' are also not recognized as
1358 part of a URL when they appear at its end. For information on how to
1359 make an explicit link, see @ref{Explicit Links,,Hyperlinks and email
1360 addresses with descriptions}.
1363 If the @command{muse-wiki} module is loaded, another form of implicit
1364 link will be made available. WikiNames, which are typed in CamelCase,
1365 are highlighted and published as links, provided that the file they
1368 Customization of WikiName recognition may be accomplished by editing the
1369 @code{muse-wiki-wikiword-regexp} option and subsequently running
1370 @code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}.
1371 If you use the Customize interface, the latter will be done
1374 @cindex InterWiki links
1375 @cindex inter-project links
1376 The @command{muse-wiki} module also allows for InterWiki links. These
1377 are similar to WikiWords, but they specify both the project and page of
1378 a file. The names of your project entries in @code{muse-project-alist}
1379 will be used as InterWiki names by default. Several examples follow.
1382 Blog::DocumentingMuse
1387 In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
1388 the project name, and @samp{DocumentingMuse} is the page name. In the
1389 second example, @samp{#} is the interwiki delimiter. If the name of a
1390 project occurs by itself in text, like the third case, it will be
1391 colorized and published as a link to the default page of the given
1394 Customization of interwiki links may be accomplished by editing the
1395 @code{muse-wiki-interwiki-alist} option.
1397 It is also possible to link to an anchor in an interwiki document. This
1398 is called a ``three-part link''. Examples of this follow.
1401 Blog::DocumentingMuse#anchor1
1402 Projects#EmacsMuse#anchor2
1405 @node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
1406 @comment node-name, next, previous, up
1407 @section Publishing and displaying images
1409 @cindex links, with images
1410 @subheading Image links
1412 Links to images may be used in either the target or the description, or
1413 both. Thus, the following code will publish as a clickable image that
1414 points to @url{http://mwolson.org/}.
1417 [[http://mwolson.org/][/static/logos/site-logo.png]]
1420 Normally, images in the link part will be inlined.
1422 If you want these images to be published as links instead, place the
1423 text ``URL:'' immediately in front of the link text. An example
1427 [[URL:http://mwolson.org/static/logos/site-logo.png]]
1430 @cindex images, displaying
1431 @cindex images, local
1432 @subheading Displaying images in Muse mode
1433 If a link to a locally-available image is encountered in the link
1434 description, Muse mode will attempt to display it if your version of
1437 This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently
1438 by setting the @code{muse-colors-inline-images} option to @code{nil}.
1440 The method for finding images may be altered by customizing the
1441 @code{muse-colors-inline-image-method} option. One useful value for
1442 this option is @code{muse-colors-use-publishing-directory}, which tells
1443 Muse mode to look in the directory where the current file will be
1444 published. The default is to look in the current directory. Relative
1445 paths like @samp{../pics/} should work for either setting.
1447 Eventually, it is hoped that Muse will be able to copy images from the a
1448 ``source'' directory to a publishing directory by customizing
1449 @code{muse-project-alist}, but this has not been implemented yet.
1451 @cindex images, without descriptions
1452 @cindex images, inlined
1453 @subheading Publishing simple images
1454 The following example will display correctly and publish correctly if a
1455 @acronym{PNG} file called @file{TestLogo.png} exists in the
1456 @file{../pics/} directory. If text is on the same line as the picture,
1457 it will remain so in the output.
1463 @cindex images, captions
1464 @subheading Publishing images with captions
1465 If you want to add a caption to an image, use the following syntax.
1466 This will center the image (if the output format supports it) and add a
1467 centered caption below the picture. Formats that do not support
1468 centering the image will instead leave it against the left margin.
1471 [[../pics/mycat.png][My cat Dexter]]
1474 Images with captions may only occur in their own paragraphs, with no
1475 text on the same line. Otherwise, the published output will not be
1476 syntactically correct.
1478 @node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
1479 @comment node-name, next, previous, up
1480 @section Inserting a horizontal line or anchor
1482 @cindex horizontal rules
1484 @subheading Horizontal Rules
1486 Four or more dashes indicate a horizontal rule. Be sure to put blank
1487 lines around it, or it will be considered part of the proceeding or
1488 following paragraph!
1491 @cindex links, with target on same page
1494 If you begin a line with "#anchor" -- where "anchor" can be any word
1495 that doesn't contain whitespace -- it defines an anchor at that point
1496 into the document. This point can be referenced using "page#anchor" as
1497 the target in a Muse link.
1499 @node Embedded Lisp, Citations, Horizontal Rules and Anchors, Markup Rules
1500 @comment node-name, next, previous, up
1501 @section Evaluating Emacs Lisp code in documents for extensibility
1502 @cindex lisp, embedded
1504 Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
1505 which is the only Muse tag supported in a style's header and footer
1506 text. With the @verb{|<lisp>|} tag, you may generated whatever output
1507 text you wish. The inserted output will get marked up, if the
1508 @verb{|<lisp>|} tag appears within the main text of the document.
1511 <lisp>(concat "This form gets " "inserted")</lisp>
1514 @cindex lisp, and insert command
1515 Note that you should not use the @code{insert} command within a set of
1516 @verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
1517 tags will be automatically inserted into the document.
1519 It is also possible to treat the output as if it were surrounded by the
1520 @verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by
1521 specifying ``example'', ``src'', or ``verse'' as the @option{markup}
1522 attribute of the @verb{|<lisp>|} tag.
1525 <lisp markup="example">
1526 (concat "Insert" " me")
1530 Other languages also have tags that cause source code to be evaluated.
1531 @xref{Tag Summary}, for details.
1533 @node Citations, Comments, Embedded Lisp, Markup Rules
1534 @comment node-name, next, previous, up
1535 @section Support for citing other resources
1537 @cindex tags, <cite>
1541 Here is an example of what citations look like in a Muse document.
1549 Some text before <cite>Miller1999</cite> and after the citation.
1551 This is an author-only citation <cite type="author">Miller1999</cite>.
1553 And this is a year-only citation <cite type="year">Miller1999</cite>.
1555 Finally, this is a multi-head citation
1556 <cite>Miller1999,Andrews2005</cite>.
1559 @subheading Overview
1561 The @code{#bibsource} directive defines the source of the
1562 bibliographies. The following sources are possible.
1565 @item DocBook + RefDB:
1568 @item LaTeX + bibtex:
1569 the name of an appropriate bibtex file
1571 @item LaTeX + RefDB:
1572 if the input file is called "foo.muse", then set this to "foo.bib"
1575 Citations are encoded as @verb{|<cite>|} elements which enclose the
1576 citation keys as they are defined in the bibliography file or database.
1577 In multi-head citations, the citation keys have to be separated by
1578 colons or semicolons. The @code{latex} and @code{docbook} styles
1579 translate these to the proper separator automatically.
1581 The @verb{|<cite>|} elements take an optional ``type'' attribute that
1582 defines how the citation is rendered. If the attribute is missing,
1583 you'll get a regular citation according to the bibliography style,
1584 e.g.'' (Miller et al., 1999)''. If the attribute is set to "author",
1585 only the name of the author(s) will be rendered. Accordingly, "year"
1586 will cause the year to be printed. This is useful to create citations
1590 Miller et al. had already shown in a previous publication (1999) that
1591 this is not going to work.
1594 Remember that refdb-mode (the Emacs interface to RefDB) can retrieve
1595 references by simply marking the citation key and running the
1596 @code{refdb-getref-by-field-on-region} command. Later versions of
1597 @code{refdb-mode} will also allow to insert references as Muse citations
1598 (which is already implemented for DocBook, TEI, and LaTeX documents).
1600 You may have noticed that there is no element to indicate the position
1601 of the bibliography. The latter is always created at a valid position
1602 close to the end of the document. The functions
1603 @code{muse-docbook-bibliography} and @code{muse-latex-bibliography} are
1604 called in the header or footer to generate this content, so it is
1605 possible to change the exact position.
1607 @node Comments, Tag Summary, Citations, Markup Rules
1608 @comment node-name, next, previous, up
1609 @section Lines to omit from published output
1611 @cindex publishing, omitting lines
1613 Use the following syntax to indicate a comment. Comments will not be
1617 ; Comment text goes here.
1620 That is, only a semi-colon at the beginning of a line, followed by a
1621 literal space, will cause that line to be treated as a comment.
1623 You can alternatively surround the region with the @verb{|<comment>|}
1626 If you wish the comment to be published, but just commented out using
1627 the comment syntax of the output format, then set
1628 @option{muse-publish-comments-p} to non-nil.
1630 @node Tag Summary, , Comments, Markup Rules
1631 @comment node-name, next, previous, up
1632 @section Tags that Muse recognizes
1634 @cindex inserting files at publish time
1635 @cindex publishing, including markup in headers and footers
1636 @cindex publishing, inserting files
1638 Muse has several built-in tags that may prove useful during publishing.
1639 @xref{muse-publish-markup-tags}, to see how to customize the tags that
1640 Muse uses, as well as make your own tags.
1644 If a tag takes arguments, it will look like this, where ``tagname'' is
1645 the name of the tag.
1648 <tagname arg1="string1" arg2="string2">
1651 If you want the tag to look like it came straight from an XHTML
1652 document, you can alternatively do the following.
1655 <tagname arg1="string1" arg2="string2" />
1658 If a tag surrounds some text, it will look like this.
1661 <tagname>Some text</tagname>
1664 If a tag surrounds a large region, it will look like this.
1673 @subheading Tag listing
1675 This is the complete list of tags that Muse accepts, including those
1676 that were mentioned in previous sections.
1681 Insert a citation to another source.
1683 This takes the argument @option{type}, which indicates the type of
1684 citation. The valid types are "author" and "year". If this argument is
1685 omitted, include both author and year in the citation.
1687 The bibliography to use for the citation may be specified by the
1688 @option{#bibsource} directive.
1690 @xref{Citations}, for additional information.
1693 If publishing to HTML, surround the given text with a @verb{|<span>|}
1694 tag. It takes one argument called ``name'' that specifies the ``class''
1695 attribute of the @verb{|<span>|} tag.
1697 If publishing to a different format, do nothing extra to the text.
1700 Treat the text surrounded by the tag as if they were enclosed in equal
1701 signs, that is, make it monospace.
1704 Run a command on the region, replacing the region with the result of the
1705 command. The command is specified with the ``interp'' argument. If no
1706 value for ``interp'' is given, pass the entire region to the shell.
1708 The ``markup'' argument controls how this section is marked up.
1710 If it is omitted, publish the region with the normal Muse rules.
1712 If "nil", do not mark up the region at all, but prevent Muse from
1713 further interpreting it.
1715 If "example", treat the region as if it was surrounded by the
1716 @verb{|<example>|} tag.
1718 If "src", treat the included text as if it was surrounded by the
1719 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1722 If "verse", treat the region as if it was surrounded by the
1723 @verb{|<verse>|} tag, to preserve newlines.
1725 Otherwise, it should be the name of a function to call, with the buffer
1726 narrowed to the region.
1729 Treat the entire region as a comment. If the option
1730 @var{muse-publish-comments-p} is nil, delete the region, otherwise
1731 publish it using the comment syntax of the current publishing style.
1734 Publish a Table of Contents. This will either be inserted in-place or
1735 at the beginning of the document, depending on your publishing style.
1736 It does not have a delimiting tag.
1738 By default, only 2 levels of headings will be included in the generated
1739 Table of Contents. To change this globally, customize the
1740 @var{muse-publish-contents-depth} option. To change this only for the
1741 current tag, use the ``depth'' argument.
1744 Publish the region in monospace, preserving the newlines in the region.
1745 This is useful for snippets of code.
1748 Insert the given file at the current location during publishing. The
1749 basic use of this tag is as follows, replacing ``included_file'' with
1750 the name of the file that you want to include.
1753 <include file="included_file">
1756 The ``markup'' argument controls how this section is marked up.
1758 If it is omitted, publish the included text with the normal Muse
1761 If "nil", do not mark up the included text at all.
1763 If "example", treat the included text as if it was surrounded by the
1764 @verb{|<example>|} tag.
1766 If "src", treat the included text as if it was surrounded by the
1767 @verb{|<src>|} tag. You should also specify the ``lang'' attribute if
1770 If "verse", treat the included text as if it was surrounded by the
1771 @verb{|<verse>|} tag, to preserve newlines.
1773 Otherwise, it should be the name of a function to call after inserting
1774 the file with the buffer narrowed to the section inserted.
1777 Evaluate the Emacs Lisp expressions between the initial and ending tags.
1778 The result is then inserted into the document, so you do not need to
1779 explicitly call @code{insert}. All text properties are removed from the
1782 This tag takes the ``markup'' argument. See the description of
1783 @verb{|<command>|} for details.
1786 Make sure that the text enclosed by this tag is published without
1787 escaping it in any way. This is useful for inserting markup directly
1788 into the published document, when Muse does not provide the desired
1792 Mark up the text between the initial and ending tags. The markup
1793 command to use may be specified by the ``function'' argument. The
1794 standard Muse markup routines are used by default if no ``function''
1795 argument is provided.
1797 This is useful for marking up regions in headers and footers. One
1798 example that comes to mind is generating a published index of all of the
1799 files in the current project by doing the following.
1802 <markup><lisp>(muse-index-as-string t t)</lisp></markup>
1806 Run the @command{perl} language interpreter on the region, replacing the
1807 region with the result of the command.
1809 This tag takes the ``markup'' argument. See the description of
1810 @verb{|<command>|} for details.
1813 Run the @command{python} language interpreter on the region, replacing
1814 the region with the result of the command.
1816 This tag takes the ``markup'' argument. See the description of
1817 @verb{|<command>|} for details.
1820 Publish the region as a blockquote. This will either be inserted
1821 in-place or at the beginning of the document, depending on your
1822 publishing style. It does not have a delimiting tag.
1825 Run the @command{ruby} language interpreter on the region, replacing the
1826 region with the result of the command.
1828 This tag takes the ``markup'' argument. See the description of
1829 @verb{|<command>|} for details.
1832 Publish the region using htmlize.
1833 The language to use may be specified by the ``lang'' attribute.
1835 Muse will look for a function named @var{lang}-mode, where @var{lang} is
1836 the value of the ``lang'' attribute.
1838 This tag requires htmlize 1.34 or later in order to work. If this is
1839 not satisfied, or the current publishing style is not HTML-based, Muse
1840 will publish the region like an @verb{|<example>|} tag.
1843 This is used when you want to prevent Muse from trying to interpret some
1844 markup. Surround the markup in @verb{|<verbatim>|} and
1845 @verb{|</verbatim>|}, and it will not be interpreted.
1847 This tag was used often in previous versions of Muse because they did
1848 not support whole-document escaping of specials. Now, it will only be
1849 needed for other tags, and perhaps footnotes as well.
1852 Preserve the newlines in the region. In formats like HTML, newlines are
1853 removed by default, hence the need for this tag. In other publishing
1854 styles, this tag may cause the text to be indented slightly in a way
1855 that looks nice for poetry and prose.
1859 @node Publishing Styles, Extending Muse, Markup Rules, Top
1860 @comment node-name, next, previous, up
1861 @chapter Publishing Various Types of Documents
1862 @cindex publishing styles
1864 One of the principle features of Muse is the ability to publish a simple
1865 input text to a variety of different output styles. Muse also makes it
1866 easy to create new styles, or derive from an existing style.
1869 * Blosxom:: Integrating Muse and pyblosxom.cgi.
1870 * Book:: Publishing entries into a compilation.
1871 * ConTeXt:: Publishing ConTeXt documents.
1872 * DocBook:: Publishing in DocBook XML form.
1873 * HTML:: Publishing in HTML or XHTML form.
1874 * Journal:: Keeping a journal or blog.
1875 * LaTeX:: Publishing LaTeX documents.
1876 * Poem:: Publish a poem to LaTex or PDF.
1877 * Texinfo:: Publish entries to Texinfo format or PDF.
1878 * XML:: Publish entries to XML.
1881 @node Blosxom, Book, Publishing Styles, Publishing Styles
1882 @comment node-name, next, previous, up
1883 @section Integrating Muse and pyblosxom.cgi
1884 @cindex blog, one-file-per-entry style
1886 The Blosxom publishing style publishes a tree of categorised files to a
1887 mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
1888 In other words, each blog entry corresponds with one file.
1891 * Blosxom Requirements:: Other tools needed for the Blosxom style.
1892 * Blosxom Entries:: Format of a Blosxom entry and automation.
1893 * Blosxom Options:: Blosxom styles and options provided.
1896 @node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
1897 @comment node-name, next, previous, up
1898 @subsection Other tools needed for the Blosxom style
1900 You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
1901 installed on a machine that you have upload access to.
1903 The following additional components are required in order to make the
1904 date of blog entries display as something sensible.
1908 A script to gather date directives from the entire blog tree into a
1909 single file. The file must associate a blog entry with a date.
1912 A plugin for (py)blosxom that reads this file.
1915 These 2 things are provided for @command{pyblosxom.cgi} in the
1916 @file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
1917 former service, while @file{hardcodedates.py} provides the latter
1918 service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
1919 script will be found/written.
1921 Here is a sample listing from my @file{timestamps} file, which maps
1922 each file to a date. This can really be in any format, as long as your
1923 date-gathering script and your plugin can both understand it.
1926 2005-04-01-14-16 personal/paper_cranes
1927 2005-03-21 personal/spring_break_over
1928 2004-10-24 personal/finished_free_culture
1931 The script @file{contrib/pyblosxom/make-blog} demonstrates how to call
1932 @file{getstamps.py}. Note that you will need to set the current
1933 directory to where your Muse files are, execute @file{getstamps.py}, and
1934 then move the generated timestamps file to your publishing directory.
1936 @node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
1937 @comment node-name, next, previous, up
1938 @subsection Format of a Blosxom entry and automation
1940 Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
1941 longer `#date yyyy-mm-dd-hh-mm', a title (using the @code{#title}
1942 directive), plus whatever normal content is desired.
1944 The date directive is not used directly by @command{pyblosxom.cgi} or
1945 this program. You need to have the two additional items from the former
1946 section to make use of this feature.
1948 There is a function called @code{muse-blosxom-new-entry} that will
1949 automate the process of making a new blog entry. To make use of it, do
1954 Customize @code{muse-blosxom-base-directory} to the location that your
1955 blog entries are stored.
1958 Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
1959 use the following code to assign this function to @kbd{C-c p l'}.
1962 (global-set-key "\C-cpl" 'muse-blosxom-new-entry)
1966 You should create your directory structure ahead of time under your base
1967 directory. These directories, which correspond with category names, may
1971 When you enter this key sequence, you will be prompted for the category
1972 of your entry and its title. Upon entering this information, a new file
1973 will be created that corresponds with the title, but in lowercase
1974 letters and having special characters converted to underscores. The
1975 title and date directives will be inserted automatically.
1978 @node Blosxom Options, , Blosxom Entries, Blosxom
1979 @comment node-name, next, previous, up
1980 @subsection Blosxom styles and options provided
1982 The following styles and options are available in the Blosxom publishing
1985 @subheading Styles provided
1989 @cindex publishing styles, blosxom-html
1991 Publish Blosxom entries in HTML form.
1993 @cindex publishing styles, blosxom-xhtml
1995 Publish Blosxom entries in XHTML form.
1999 @subheading Options provided
2003 @item muse-blosxom-extension
2004 Default file extension for publishing Blosxom files.
2006 @item muse-blosxom-header
2007 Header used for publishing Blosxom files.
2009 This may be text or a filename.
2011 @item muse-blosxom-footer
2012 Footer used for publishing Blosxom files.
2014 This may be text or a filename.
2016 @item muse-blosxom-base-directory
2017 Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
2019 This is the top-level directory where your blog entries may be found
2024 @node Book, ConTeXt, Blosxom, Publishing Styles
2025 @comment node-name, next, previous, up
2026 @section Publishing entries into a compilation
2028 This publishing style is used to output ``books'' in LaTeX or PDF
2031 Each page will become a separate chapter in the book, unless the style
2032 keyword @option{:nochapters} is used, in which case they are all run
2033 together as if one giant chapter.
2035 One way of publishing a book is to make a project for it, add the
2036 project to @code{muse-project-alist}, and use the @code{book-pdf} style
2037 with a very specific @option{:include} value to specify some page whose
2038 contents will be checked for the values of @code{#title} and
2039 @code{#date}, and whose name will be used in the output file. Then to
2040 publish the book, visit the aforementioned page and use @kbd{C-c C-t} or
2041 @kbd{C-c C-p} to trigger the publishing process. An example
2042 @code{muse-project-alist} for this method follows.
2045 (setq muse-project-alist
2046 '(("MyNotes" (:nochapters t ; do automatically add chapters
2047 :book-chapter "Computer Science"
2049 :book-chapter "Mathematics"
2051 :book-chapter "Emacs"
2053 :book-end t ; the rest will not be placed in the book
2054 "~/Notes" ; so we can find the notes-anthology page
2056 :force-publish ("index")
2059 :include "/notes-anthology[^/]*$"
2060 :path "~/public_html/notes")
2061 ;; other publishing styles for each directory go here,
2066 In this example, there would be a file called
2067 @file{~/Notes/notes-anthology.muse}, which would contain just the
2068 following. The resulting book would be published to
2069 @file{~/public_html/notes/notes-anthology.pdf}.
2072 #title My Technology Ramblings
2075 Another way is to call the @code{muse-book-publish-project} function
2076 manually, with a custom project entry. An example of this may be found
2077 in John Wiegley's configuration file at
2078 @file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books}
2081 @subheading Styles provided
2085 @cindex publishing styles, book-latex
2087 Publish a book in LaTeX form. The header and footer are different than
2088 the normal LaTeX publishing mode.
2090 @cindex publishing styles, book-pdf
2092 Publish a book in PDF form. The header and footer are different than
2093 the normal PDF publishing mode.
2097 @subheading Options provided
2101 @item muse-book-before-publish-hook
2102 A hook run in the book buffer before it is marked up.
2104 @item muse-book-after-publish-hook
2105 A hook run in the book buffer after it is marked up.
2107 @item muse-book-latex-header
2108 Header used for publishing books to LaTeX.
2110 This may be text or a filename.
2112 @item muse-book-latex-footer
2113 Footer used for publishing books to LaTeX.
2115 This may be text or a filename.
2118 @node ConTeXt, DocBook, Book, Publishing Styles
2119 @comment node-name, next, previous, up
2120 @section Publishing ConTeXt documents
2122 This publishing style is capable of producing ConTeXt or PDF documents.
2124 If you wish to publish PDF documents based on ConTeXt, you will need to
2125 have it installed. For Debian and Ubuntu, this can be accomplished by
2126 installing the ``texlive'' package.
2128 @subheading Styles provided
2132 @cindex publishing styles, context
2134 Publish a ConTeXt document.
2136 @cindex publishing styles, context-pdf
2138 Publish a PDF document, using an external ConTeXt document conversion
2141 @cindex publishing styles, context-slides
2142 @item context-slides
2143 Produce slides from a ConTeXt document.
2145 Here is an example of a slide.
2150 [[Some-sort-of-cute-image.png]]
2155 - Another bullet point.
2162 @cindex publishing styles, context-slides-pdf
2163 @item context-slides-pdf
2164 Publish a PDF document of ConTeXt slides.
2168 @subheading Options provided
2172 @item muse-context-extension
2173 Default file extension for publishing ConTeXt files.
2175 @item muse-context-pdf-extension
2176 Default file extension for publishing ConTeXt files to PDF.
2178 @item muse-context-pdf-program
2179 The program that is called to generate PDF content from ConTeXt content.
2181 @item muse-context-pdf-cruft
2182 Extensions of files to remove after generating PDF output successfully.
2184 @item muse-context-header
2185 Header used for publishing ConTeXt files.
2187 This may be text or a filename.
2189 @item muse-context-footer
2190 Footer used for publishing ConTeXt files.
2192 This may be text or a filename.
2194 @item muse-context-markup-regexps
2195 List of markup regexps for identifying regions in a Muse page.
2197 For more on the structure of this list,
2198 @xref{muse-publish-markup-regexps}.
2200 @item muse-context-markup-functions
2201 An alist of style types to custom functions for that kind of text.
2203 For more on the structure of this list,
2204 @xref{muse-publish-markup-functions}.
2206 @item muse-context-markup-strings
2207 Strings used for marking up text.
2209 These cover the most basic kinds of markup, the handling of which
2210 differs little between the various styles.
2212 @item muse-context-slides-header
2213 Header for publishing a presentation (slides) using ConTeXt.
2215 Any of the predefined modules, which are available in the
2216 tex/context/base directory, can be used by writing a "module" directive
2217 at the top of the Muse file; if no such directive is provided, module
2218 pre-01 is used. Alternatively, you can use your own style ("mystyle",
2219 in this example) by replacing "\usemodule[]" with "\input mystyle".
2221 This may be text or a filename.
2223 @item muse-context-slides-markup-strings
2224 Strings used for marking up text in ConTeXt slides.
2226 @item muse-context-markup-specials-document
2227 A table of characters which must be represented specially.
2228 These are applied to the entire document, sans already-escaped
2231 @item muse-context-markup-specials-example
2232 A table of characters which must be represented specially.
2233 These are applied to @verb{|example>|} regions.
2235 With the default interpretation of @verb{|<example>|} regions, no
2236 specials need to be escaped.
2238 @item muse-context-markup-specials-literal
2239 A table of characters which must be represented specially.
2240 This applies to =monospaced text= and @verb{|<code>|} regions.
2242 @item muse-context-markup-specials-url
2243 A table of characters which must be represented specially.
2244 These are applied to URLs.
2246 @item muse-context-markup-specials-image
2247 A table of characters which must be represented specially.
2248 These are applied to image filenames.
2250 @item muse-context-permit-contents-tag
2251 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2254 Most of the time, it is best to have a table of contents on the
2255 first page, with a new page immediately following. To make this
2256 work with documents published in both HTML and ConTeXt, we need to
2257 ignore the @verb{|<contents>|} tag.
2259 If you don't agree with this, then set this option to non-nil,
2260 and it will do what you expect.
2264 @node DocBook, HTML, ConTeXt, Publishing Styles
2265 @comment node-name, next, previous, up
2266 @section Publishing in DocBook XML form
2268 This publishing style is used to generate DocBook XML files.
2270 @subheading Styles provided
2274 @cindex publishing styles, docbook
2276 Publish a file in Docbook form.
2280 @subheading Options provided
2282 This publishing style uses the same options for markup up special
2283 characters as the ``xml'' publishing style. @xref{XML}, for details.
2287 @item muse-docbook-extension
2288 Default file extension for publishing DocBook XML files.
2290 @item muse-docbook-header
2291 Header used for publishing DocBook XML files.
2293 This may be text or a filename.
2295 @item muse-docbook-footer
2296 Footer used for publishing DocBook XML files.
2298 This may be text or a filename.
2300 @item muse-docbook-markup-regexps
2301 List of markup rules for publishing a Muse page to DocBook XML.
2303 @item muse-docbook-markup-functions
2304 An alist of style types to custom functions for that kind of text.
2306 @item muse-docbook-markup-strings
2307 Strings used for marking up text.
2309 These cover the most basic kinds of markup, the handling of which
2310 differs little between the various styles.
2312 @item muse-docbook-encoding-default
2313 The default Emacs buffer encoding to use in published files.
2314 This will be used if no special characters are found.
2316 @item muse-docbook-charset-default
2317 The default DocBook XML charset to use if no translation is
2318 found in @code{muse-xml-encoding-map}.
2322 @node HTML, Journal, DocBook, Publishing Styles
2323 @comment node-name, next, previous, up
2324 @section Publishing in HTML or XHTML form
2326 This publishing style is capable of producing HTML or XHTML documents.
2328 @subheading Styles provided
2332 @cindex publishing styles, html
2334 Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
2337 Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
2341 @subheading Options provided
2343 If an HTML option does not have a corresponding XHTML option, it will
2344 be used for both of these publishing styles.
2346 These publishing styles use the same options for markup up special
2347 characters as the ``xml'' publishing style. @xref{XML}, for details.
2351 @item muse-html-extension
2352 Default file extension for publishing HTML files.
2354 @item muse-xhtml-extension
2355 Default file extension for publishing XHTML files.
2357 @item muse-html-style-sheet
2358 Store your stylesheet definitions here.
2360 This is used in @code{muse-html-header}. You can put raw CSS in here or
2361 a @verb{|<link>|} tag to an external stylesheet. This text may contain
2362 @verb{|<lisp>|} markup tags.
2364 If you are publishing to XHTML, then customize the
2365 @code{muse-xhtml-style-sheet} option instead.
2367 @item muse-xhtml-style-sheet
2368 Store your stylesheet definitions here.
2370 This is used in @code{muse-xhtml-header}. You can put raw CSS in here
2371 or a @verb{|<link>|} tag to an external stylesheet. This text may
2372 contain @verb{|<lisp>|} markup tags.
2374 @item muse-html-header
2375 Header used for publishing HTML files.
2377 This may be text or a filename.
2379 @item muse-html-footer
2380 Footer used for publishing HTML files.
2382 This may be text or a filename.
2384 @item muse-xhtml-header
2385 Header used for publishing XHTML files.
2387 This may be text or a filename.
2389 @item muse-xhtml-footer
2390 Footer used for publishing XHTML files.
2392 This may be text or a filename.
2394 @item muse-html-anchor-on-word
2395 When true, anchors surround the closest word.
2397 This allows you to select them in a browser (i.e. for pasting), but has
2398 the side-effect of marking up headers in multiple colors if your header
2399 style is different from your link style.
2401 @item muse-html-table-attributes
2402 The attribute to be used with HTML @verb{|<table>|} tags.
2404 If you want to make more-complicated tables in HTML, surround the HTML
2405 with the @verb{|literal|} tag, so that it does not get escaped.
2407 @item muse-html-markup-regexps
2408 List of markup rules for publishing a Muse page to HTML.
2410 @item muse-html-markup-functions
2411 An alist of style types to custom functions for that kind of text.
2413 @item muse-html-markup-strings
2414 Strings used for marking up text as HTML.
2416 These cover the most basic kinds of markup, the handling of which
2417 differs little between the various styles.
2419 @item muse-xhtml-markup-strings
2420 Strings used for marking up text as XHTML.
2422 These cover the most basic kinds of markup, the handling of which
2423 differs little between the various styles.
2425 @item muse-html-markup-tags
2426 A list of tag specifications, for specially marking up HTML.
2427 @xref{muse-publish-markup-tags}, for more information.
2429 @item muse-html-meta-http-equiv
2430 The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
2432 @item muse-html-meta-content-type
2433 The content type used for the HTML @verb{|<meta>|} tag.
2435 If you are striving for XHTML 1.1 compliance, you may want to change
2436 this to ``application/xhtml+xml''.
2438 @item muse-html-meta-content-encoding
2439 The charset to append to the HTML @verb{|<meta>|} tag.
2441 If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try
2442 and determine the HTML charset from emacs's coding. If set to a string,
2443 this string will be used to force a particular charset.
2445 @item muse-html-charset-default
2446 The default HTML meta charset to use if no translation is found in
2447 @code{muse-xml-encoding-map}.
2449 @item muse-html-encoding-default
2450 The default Emacs buffer encoding to use in published files.
2451 This will be used if no special characters are found.
2455 @node Journal, LaTeX, HTML, Publishing Styles
2456 @comment node-name, next, previous, up
2457 @section Keeping a journal or blog
2459 @cindex blog, journal style
2461 The module facilitates the keeping and publication of a journal. When
2462 publishing to HTML, it assumes the form of a web log, or blog.
2464 The input format for each entry is as follows.
2467 * 20040317: Title of entry
2472 "You know who you are. It comes down to a simple gut check: You
2473 either love what you do or you don't. Period." -- P. Bronson
2477 The "qotd", or Quote of the Day, is entirely optional. When generated
2478 to HTML, this entry is rendered as the following.
2482 <div class="entry-qotd">
2483 <h3>Quote of the Day:</h3>
2484 <p>"You know who you are. It comes down to a simple gut
2485 check: You either love what you do or you don't. Period."
2488 <div class="entry-body">
2489 <div class="entry-head">
2490 <div class="entry-date">
2491 <span class="date">March 17, 2004</span>
2493 <div class="entry-title">
2494 <h2>Title of entry</h2>
2497 <div class="entry-text">
2498 <p>Text for the entry.</p>
2504 The plurality of "div" tags makes it possible to display the entries in
2505 any form you wish, using a CSS style.
2507 Also, an .RDF file can be generated from your journal by publishing it
2508 with the "rdf" style. It uses the first two sentences of the first
2509 paragraph of each entry as its "description", and auto-generates tags
2510 for linking to the various entries.
2512 @subheading muse-project-alist considerations
2514 If you wish to publish an RDF or RSS feed, it is important to include
2515 the @option{:base-url} attribute in your @code{muse-project-alist} entry
2516 for your Journal projects. An example follows.
2519 (setq muse-project-alist
2520 '(("Journal" ("~/Journal/"
2522 (:base "journal-rss"
2523 :base-url "http://example.org/journal/"
2524 :path "~/public_html/journal"))))
2527 @subheading Styles provided
2531 @cindex publishing styles, journal-html
2533 Publish journal entries as an HTML document.
2535 @cindex publishing styles, journal-xhtml
2537 Publish journal entries as an XHTML document.
2539 @cindex publishing styles, journal-latex
2541 Publish journal entries as a LaTeX document.
2543 @cindex publishing styles, journal-pdf
2545 Publish journal entries as a PDF document.
2547 @cindex publishing styles, journal-book-latex
2548 @item journal-book-latex
2549 Publish journal entries as a LaTeX book.
2551 @cindex publishing styles, journal-book-pdf
2552 @item journal-book-pdf
2553 Publish journal entries as a PDF book.
2555 @cindex publishing styles, journal-rdf
2556 @cindex publishing styles, RSS 1.0
2558 Publish journal entries as an RDF file (RSS 1.0).
2560 @cindex publishing styles, journal-rss
2561 @cindex publishing styles, RSS 2.0
2563 Publish journal entries as an RSS file (RSS 2.0).
2565 @cindex publishing styles, journal-rss-entry
2566 @item journal-rss-entry
2567 Used internally by @code{journal-rss} and @code{journal-rdf} for
2568 publishing individual entries.
2572 @subheading Options provided
2576 @item muse-journal-heading-regexp
2577 A regexp that matches a journal heading.
2579 Paren group 1 is the ISO date, group 2 is the optional category, and
2580 group 3 is the optional heading for the entry.
2582 @item muse-journal-date-format
2583 Date format to use for journal entries.
2585 @item muse-journal-html-heading-regexp
2586 A regexp that matches a journal heading from an HTML document.
2588 Paren group 1 is the ISO date, group 2 is the optional category, and
2589 group 3 is the optional heading for the entry.
2591 @item muse-journal-html-entry-template
2592 Template used to publish individual journal entries as HTML.
2594 This may be text or a filename.
2596 @item muse-journal-latex-section
2597 Template used to publish a LaTeX section.
2599 @item muse-journal-latex-subsection
2600 Template used to publish a LaTeX subsection.
2602 @item muse-journal-markup-tags
2603 A list of tag specifications, for specially marking up Journal entries.
2605 @xref{muse-publish-markup-tags}, for more information.
2607 This is used by @code{journal-latex} and its related styles, as well as
2608 the @code{journal-rss-entry} style, which both @code{journal-rdf} and
2609 @code{journal-rss} use.
2611 @item muse-journal-rdf-extension
2612 Default file extension for publishing RDF (RSS 1.0) files.
2614 @item muse-journal-rdf-base-url
2615 The base URL of the website referenced by the RDF file.
2617 @item muse-journal-rdf-header
2618 Header used for publishing RDF (RSS 1.0) files.
2620 This may be text or a filename.
2622 @item muse-journal-rdf-footer
2623 Footer used for publishing RDF (RSS 1.0) files.
2625 This may be text or a filename.
2627 @item muse-journal-rdf-date-format
2628 Date format to use for RDF entries.
2630 @item muse-journal-rdf-entry-template
2631 Template used to publish individual journal entries as RDF.
2633 This may be text or a filename.
2635 @item muse-journal-rdf-summarize-entries
2636 If non-nil, include only summaries in the RDF file, not the full data.
2638 The default is nil, because this annoys some subscribers.
2640 @item muse-journal-rss-heading-regexp
2641 A regexp that matches a journal heading from an HTML document.
2643 Paren group 1 is the ISO date, group 2 is the optional category,
2644 and group 3 is the optional heading for the entry.
2646 @item muse-journal-rss-extension
2647 Default file extension for publishing RSS 2.0 files.
2649 @item muse-journal-rss-base-url
2650 The base URL of the website referenced by the RSS file.
2652 @item muse-journal-rss-header
2653 Header used for publishing RSS 2.0 files.
2655 This may be text or a filename.
2657 @item muse-journal-rss-footer
2658 Footer used for publishing RSS 2.0 files.
2660 This may be text or a filename.
2662 @item muse-journal-rss-date-format
2663 Date format to use for RSS 2.0 entries.
2665 @item muse-journal-rss-entry-template
2666 Template used to publish individual journal entries as RSS 2.0.
2668 This may be text or a filename.
2670 @item muse-journal-rss-enclosure-types-alist
2671 File types that are accepted as RSS enclosures.
2673 This is an alist that maps file extension to content type.
2675 Useful for podcasting.
2677 @item muse-journal-rss-summarize-entries
2678 If non-nil, include only summaries in the RSS file, not the full data.
2680 The default is nil, because this annoys some subscribers.
2682 @item muse-journal-rss-markup-regexps
2683 List of markup rules for publishing a Muse journal page to RSS.
2685 For more information on the structure of this list,
2686 @xref{muse-publish-markup-regexps}.
2688 @item muse-journal-rss-markup-functions
2689 An alist of style types to custom functions for that kind of text.
2691 For more on the structure of this list,
2692 @xref{muse-publish-markup-functions}.
2696 @node LaTeX, Poem, Journal, Publishing Styles
2697 @comment node-name, next, previous, up
2698 @section Publishing LaTeX documents
2700 This publishing style is capable of producing LaTeX or PDF documents.
2702 If you wish to publish PDF documents, you will need to have a good TeX
2703 installation. For Debian and Ubuntu, this can be accomplished by
2704 installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts
2707 @subheading Styles provided
2711 @cindex publishing styles, latex
2713 Publish a LaTeX document.
2715 @cindex publishing styles, pdf
2717 Publish a PDF document, using an external LaTeX document conversion
2720 @cindex publishing styles, latexcjk
2722 Publish a LaTeX document with CJK (Chinese) encodings.
2724 @cindex publishing styles, pdfcjk
2726 Publish a PDF document with CJK (Chinese) encodings, using an external
2727 LaTeX document conversion tool.
2729 @cindex publishing styles, slides
2731 Publish a LaTeX document that uses the Beamer extension. This is
2732 suitable for producing slides.
2734 Here is an example of a slide.
2737 <slide title="First Slide">
2738 Everything between the slide tags composes this slide.
2740 [[Some-sort-of-cute-image.png]]
2743 - Another bullet point.
2747 @cindex publishing styles, slides-pdf
2749 Publish a PDF document of slides, using the Beamer extension.
2751 @cindex publishing styles, lecture-notes
2753 Publish a LaTeX document that uses the Beamer extension. This is
2754 suitable for producing lecture notes.
2756 This can also use the @verb{|<slide>|} tag.
2758 @cindex publishing styles, lecture-notes-pdf
2759 @item lecture-notes-pdf
2760 Publish a PDF document of lecture notes, using the Beamer extension.
2764 @subheading Options provided
2768 @item muse-latex-extension
2769 Default file extension for publishing LaTeX files.
2771 @item muse-latex-pdf-extension
2772 Default file extension for publishing LaTeX files to PDF.
2774 @item muse-latex-pdf-program
2775 The program that is called to generate PDF content from LaTeX content.
2777 @item muse-latex-pdf-cruft
2778 Extensions of files to remove after generating PDF output successfully.
2780 @item muse-latex-header
2781 Header used for publishing LaTeX files.
2783 This may be text or a filename.
2785 @item muse-latex-footer
2786 Footer used for publishing LaTeX files.
2788 This may be text or a filename.
2790 @item muse-latexcjk-header
2791 Header used for publishing LaTeX files (CJK).
2793 This may be text or a filename.
2795 @item muse-latexcjk-footer
2796 Footer used for publishing LaTeX files (CJK).
2798 This may be text or a filename.
2800 @item muse-latex-slides-header
2801 Header for publishing of slides using LaTeX.
2803 This may be text or a filename.
2805 You must have the Beamer extension for LaTeX installed for this to work.
2807 @item muse-latex-lecture-notes-header
2808 Header publishing of lecture notes using LaTeX.
2810 This may be text or a filename.
2812 You must have the Beamer extension for LaTeX installed for this to work.
2814 @item muse-latex-markup-regexps
2815 List of markup regexps for identifying regions in a Muse page.
2817 For more on the structure of this list,
2818 @xref{muse-publish-markup-regexps}.
2820 @item muse-latex-markup-functions
2821 An alist of style types to custom functions for that kind of text.
2823 For more on the structure of this list,
2824 @xref{muse-publish-markup-functions}.
2826 @item muse-latex-markup-strings
2827 Strings used for marking up text.
2829 These cover the most basic kinds of markup, the handling of which
2830 differs little between the various styles.
2832 @item muse-latex-slides-markup-tags
2833 A list of tag specifications, for specially marking up LaTeX slides.
2835 @item muse-latexcjk-encoding-map
2836 An alist mapping emacs coding systems to appropriate CJK codings.
2837 Use the base name of the coding system (ie, without the -unix).
2839 @item muse-latexcjk-encoding-default
2840 The default Emacs buffer encoding to use in published files.
2842 This will be used if no special characters are found.
2844 @item muse-latex-markup-specials-document
2845 A table of characters which must be represented specially.
2846 These are applied to the entire document, sans already-escaped
2849 @item muse-latex-markup-specials-example
2850 A table of characters which must be represented specially.
2851 These are applied to @verb{|example>|} regions.
2853 With the default interpretation of @verb{|<example>|} regions, no
2854 specials need to be escaped.
2856 @item muse-latex-markup-specials-literal
2857 A table of characters which must be represented specially.
2858 This applies to =monospaced text= and @verb{|<code>|} regions.
2860 @item muse-latex-markup-specials-url
2861 A table of characters which must be represented specially.
2862 These are applied to URLs.
2864 @item muse-latex-markup-specials-image
2865 A table of characters which must be represented specially.
2866 These are applied to image filenames.
2868 @item muse-latex-permit-contents-tag
2869 If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of
2872 Most of the time, it is best to have a table of contents on the
2873 first page, with a new page immediately following. To make this
2874 work with documents published in both HTML and LaTeX, we need to
2875 ignore the @verb{|<contents>|} tag.
2877 If you don't agree with this, then set this option to non-nil,
2878 and it will do what you expect.
2882 @node Poem, Texinfo, LaTeX, Publishing Styles
2883 @comment node-name, next, previous, up
2884 @section Publish a poem to LaTex or PDF
2886 The @code{muse-poem} module makes it easy to attractively publish and
2887 reference poems in the following format, using the "memoir" module for
2888 LaTeX publishing. It will also markup poems for every other output
2889 style, though none are nearly as pretty.
2898 Annotations, history, notes, etc.
2901 Once a poem is written in this format, just publish it to PDF using the
2902 @code{poem-pdf} style. To make an inlined reference to a poem that
2903 you've written -- for example, from a blog page -- there is a "poem" tag
2904 defined by this module.
2907 <poem title="name.of.poem.page">
2910 Let's assume the template above was called @file{name.of.poem.page};
2911 then the above tag would result in this inclusion.
2919 John Wiegley uses this module for publishing all of the poems on his
2920 website, which are at
2921 @uref{http://www.newartisans.com/johnw/poems.html}.
2923 @subheading Styles provided
2927 @cindex publishing styles, poem-latex
2929 Publish a poem in LaTeX form.
2931 @cindex publishing styles, poem-pdf
2933 Publish a poem to a PDF document.
2935 @cindex publishing styles, chapbook-latex
2936 @item chapbook-latex
2937 Publish a book of poems in LaTeX form.
2939 @cindex publishing styles, chapbook-pdf
2941 Publish a book of poems to a PDF document.
2945 @subheading Options provided
2949 @item muse-poem-latex-header
2950 Header used for publishing LaTeX poems.
2952 This may be text or a filename.
2954 @item muse-poem-latex-footer
2955 Footer used for publishing LaTeX files.
2957 This may be text or a filename.
2959 @item muse-poem-markup-strings
2960 Strings used for marking up poems.
2962 These cover the most basic kinds of markup, the handling of which
2963 differs little between the various styles.
2965 @item muse-chapbook-latex-header
2966 Header used for publishing a book of poems in LaTeX form.
2968 This may be text or a filename.
2970 @item muse-chapbook-latex-footer
2971 Footer used for publishing a book of poems in LaTeX form.
2973 This may be text or a filename.
2975 @item muse-poem-chapbook-strings
2976 Strings used for marking up books of poems.
2978 These cover the most basic kinds of markup, the handling of which
2979 differs little between the various styles.
2983 @node Texinfo, XML, Poem, Publishing Styles
2984 @comment node-name, next, previous, up
2985 @section Publish entries to Texinfo format or PDF
2987 Rules for publishing a Muse file as a Texinfo article.
2989 @subheading Styles provided
2993 @cindex publishing styles, texi
2995 Publish a file in Texinfo form.
2997 @cindex publishing styles, texi
2999 Generate an Info file from a Muse file.
3001 @cindex publishing styles, info-pdf
3003 Publish a file in PDF form.
3007 @subheading Options provided
3011 @item muse-texinfo-process-natively
3012 If non-nil, use the Emacs `texinfmt' module to make Info files.
3014 @item muse-texinfo-extension
3015 Default file extension for publishing Texinfo files.
3017 @item muse-texinfo-info-extension
3018 Default file extension for publishing Info files.
3020 @item muse-texinfo-pdf-extension
3021 Default file extension for publishing PDF files.
3023 @item muse-texinfo-header
3024 Text to prepend to a Muse page being published as Texinfo.
3026 This may be text or a filename.
3027 It may contain @verb{|<lisp>|} markup tags.
3029 @item muse-texinfo-footer
3030 Text to append to a Muse page being published as Texinfo.
3032 This may be text or a filename.
3033 It may contain @verb{|<lisp>|} markup tags.
3035 @item muse-texinfo-markup-regexps
3036 List of markup rules for publishing a Muse page to Texinfo.
3038 For more on the structure of this list,
3039 @xref{muse-publish-markup-regexps}.
3041 @item muse-texinfo-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-texinfo-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-texinfo-markup-specials
3054 A table of characters which must be represented specially.
3056 @item muse-texinfo-markup-specials
3057 A table of characters which must be represented specially.
3058 These are applied to URLs.
3062 @node XML, , Texinfo, Publishing Styles
3063 @comment node-name, next, previous, up
3064 @section Publish entries to XML
3066 Muse is capable of publishing XML documents, with the help of the
3067 @file{muse-xml.el} module.
3069 A RelaxNG schema is available as part of the Muse distribution in the
3070 @file{etc/muse.rnc} file.
3072 @subheading Styles provided
3076 @cindex publishing styles, xml
3078 Publish a file in XML form.
3082 @subheading Options provided
3086 @cindex muse-xml-encoding-map
3087 @item muse-xml-encoding-map
3088 An alist mapping Emacs coding systems to appropriate XML charsets.
3089 Use the base name of the coding system (i.e. without the -unix).
3091 @item muse-xml-markup-specials
3092 A table of characters which must be represented specially in all
3093 XML-like markup formats.
3095 @item muse-xml-markup-specials-url-extra
3096 A table of characters which must be represented specially in all
3097 XML-like markup formats.
3099 These are extra characters that are escaped within URLs.
3101 @item muse-xml-extension
3102 Default file extension used for publishing XML files.
3104 @item muse-xml-header
3105 Header used for publishing XML files.
3107 This may be text or a filename.
3109 @item muse-xml-footer
3110 Footer used for publishing XML files.
3112 This may be text or a filename.
3114 @item muse-xml-markup-regexps
3115 List of markup rules for publishing a Muse page to XML.
3117 For more on the structure of this list,
3118 @xref{muse-publish-markup-regexps}.
3120 @item muse-xml-markup-functions
3121 An alist of style types to custom functions for that kind of text.
3123 For more on the structure of this list,
3124 @xref{muse-publish-markup-functions}.
3126 @item muse-xml-markup-strings
3127 Strings used for marking up text.
3129 These cover the most basic kinds of markup, the handling of which
3130 differs little between the various styles.
3132 @item muse-xml-encoding-default
3133 The default Emacs buffer encoding to use in published files.
3135 This will be used if no special characters are found.
3137 @item muse-xml-charset-default
3138 The default XML charset to use if no translation is found in
3139 @code{muse-xml-encoding-map}.
3144 @node Extending Muse, Miscellaneous, Publishing Styles, Top
3145 @comment node-name, next, previous, up
3146 @chapter Making your own publishing styles
3149 * Common Elements:: Common functionality shared by styles.
3150 * Deriving Styles:: Deriving a new style from an existing
3154 @node Common Elements, Deriving Styles, , Extending Muse
3155 @comment node-name, next, previous, up
3156 @section Common functionality shared by styles
3157 @cindex publishing styles, common
3160 * Markup Functions:: Specifying functions to mark up text.
3161 * Markup Regexps:: Markup rules for publishing.
3162 * Markup Strings:: Strings specific to a publishing style.
3163 * Markup Tags:: Tag specifications for special markup.
3164 * Style Elements:: Parameters used for defining styles.
3167 @node Markup Functions, Markup Regexps, , Common Elements
3168 @comment node-name, next, previous, up
3169 @subsection Specifying functions to mark up text
3170 @cindex publishing, markup functions
3172 @anchor{muse-publish-markup-functions}
3173 @code{muse-publish-markup-functions}
3175 An alist of style types to custom functions for that kind of text.
3177 This is used by publishing styles to attempt to minimize the amount of
3178 custom regexps that each has to define. @file{muse-publish} provides
3179 rules for the most common types of markup.
3181 Each member of the list is of the following form.
3189 Describes the type of text to associate with this rule.
3190 @code{muse-publish-markup-regexps} maps regexps to these symbols.
3193 Function to use to mark up this kind of rule if no suitable function is
3194 found through the @option{:functions} tag of the current style.
3197 @node Markup Regexps, Markup Strings, Markup Functions, Common Elements
3198 @comment node-name, next, previous, up
3199 @subsection Markup rules for publishing
3200 @cindex publishing, markup regexps
3201 @cindex publishing, rules
3203 @anchor{muse-publish-markup-regexps}
3204 @code{muse-publish-markup-regexps}
3206 List of markup rules for publishing a page with Muse.
3208 The rules given in this variable are invoked first, followed by whatever
3209 rules are specified by the current style.
3211 Each member of the list is either a function, or a list of the following
3215 (REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
3220 A regular expression, or symbol whose value is a regular expression,
3221 which is searched for using `re-search-forward'.
3223 @item TEXT-BEGIN-GROUP
3224 The matching group within that regexp which denotes the beginning of the
3225 actual text to be marked up.
3227 @item REPLACEMENT-TEXT
3228 A string that will be passed to `replace-match'.
3230 If it is not a string, but a function, it will be called to determine
3231 what the replacement text should be (it must return a string). If it is
3232 a symbol, the value of that symbol should be a string.
3235 The replacements are done in order, one rule at a time. Writing
3236 the regular expressions can be a tricky business. Note that case
3237 is never ignored. `case-fold-search' is always bound to nil
3238 while processing the markup rules.
3240 @subheading Publishing order
3242 This is the order that the publishing rules are consulted, by default.
3243 This may be changed by customizing @code{muse-publish-markup-regexps}.
3247 @item trailing and leading whitespace
3248 Remove trailing and leading whitespace from a file.
3253 This is only recognized at the beginning of a file.
3256 @samp{; a commented line}
3264 @item explicit links
3265 Prevent emphasis characters in explicit links from being marked up.
3267 Don't actually publish them here, just add a special no-emphasis text
3271 Whitespace-delimited word, possibly with emphasis characters
3273 This function is responsible for marking up emphasis and escaping some
3279 Outline-mode style headings.
3284 These are ellipses with a dot at end.
3294 Horizontal rule or section separator.
3296 @item no-break-space
3299 Prevent lines from being split before or after these characters.
3304 beginning of footnotes section
3309 Footnote definition or reference. If at beginning of line, it is a
3324 Numbered list, item list, or term definition list.
3328 @file{table.el} style tables
3331 @samp{table | cells}
3333 Muse tables or orgtbl-mode style tables.
3336 spaces before beginning of text
3352 @samp{[[explicit][links]]}
3355 @samp{http://example.com/}
3358 @samp{bare-email@@example.com}
3362 @node Markup Strings, Markup Tags, Markup Regexps, Common Elements
3363 @comment node-name, next, previous, up
3364 @subsection Strings specific to a publishing style
3365 @cindex publishing, markup strings
3367 @dfn{Markup strings} are strings used for marking up text for a
3370 These cover the most basic kinds of markup, the handling of which
3371 differs little between the various styles.
3373 @subheading Available markup strings
3377 @item image-with-desc
3378 An image and a description.
3380 Argument 1: image without extension. Argument 2: image extension.
3381 Argument 3: description.
3386 Argument 1: image without extension. Argument 2: image extension.
3389 An image with a link around it.
3391 Argument 1: link. Argument 2: image without extension.
3392 Argument 3: image extension.
3395 A reference to an anchor on the current page.
3397 Argument 1: anchor name. Argument 2: description if one exists, or the
3398 original link otherwise.
3401 A URL without a description.
3406 A link to a Muse page with a description.
3408 Argument 1: link. Argument 2: description if one exists, or the
3409 original link otherwise.
3411 @item link-and-anchor
3412 A link to a Muse page with an anchor, and a description.
3414 Argument 1: link. Argument 2: anchor name.
3415 Argument 3: description if one exists, or the original link otherwise.
3416 Argument 4: link without an extension.
3419 A link to an email address.
3421 Argument 1: email address. Argument 2: email address.
3426 Argument 1: name of anchor.
3431 Argument 1: Initial whitespace. Argument 2: Terminating whitespace.
3434 Beginning of a comment.
3440 A horizontal line or space.
3442 @item no-break-space
3443 A space that separates two words which are not to be separated.
3446 Beginning of footnote.
3452 Mark a reference for the current footnote.
3454 Argument 1: number of this footnote.
3456 @item footnotemark-end
3457 End of a reference for the current footnote.
3460 Indicate the text of the current footnote.
3462 Argument 1: number of this footnote.
3464 @item footnotetext-end
3465 End of a footnote text line.
3468 Text used to replace ``Footnotes:'' line.
3477 Beginning of a part indicator line. This is used by book publishing.
3480 End of a part indicator line. This is used by book publishing.
3483 Beginning of a chapter indicator line. This is used by book publishing.
3486 End of a chapter indicator line. This is used by book publishing.
3489 Beginning of level 1 section indicator line.
3491 Argument 1: level of section; always 1.
3494 End of level 1 section indicator line.
3496 Argument 1: level of section; always 1.
3499 Beginning of level 2 section indicator line.
3501 Argument 1: level of section; always 2.
3503 @item subsection-end
3504 End of level 2 section indicator line.
3506 Argument 1: level of section; always 2.
3509 Beginning of level 3 section indicator line.
3511 Argument 1: level of section; always 3.
3513 @item subsubsection-end
3514 End of level 3 section indicator line.
3516 Argument 1: level of section; always 3.
3519 Beginning of section indicator line, where level is greater than 3.
3521 Argument 1: level of section.
3523 @item section-other-end
3524 End of section indicator line, where level is greater than 3.
3526 Argument 1: level of section.
3528 @item begin-underline
3529 Beginning of underlined text.
3532 End of underlined text.
3535 Beginning of verbatim text. This includes @verb{|<code>|} tags and
3539 End of verbatim text. This includes @verb{|<code>|} tags and =teletype
3543 Beginning of the first level of emphasized text.
3546 End of the first level of emphasized text.
3548 @item begin-more-emph
3549 Beginning of the second level of emphasized text.
3552 End of the second level of emphasized text.
3554 @item begin-most-emph
3555 Beginning of the third (and final) level of emphasized text.
3558 End of the third (and final) level of emphasized text.
3561 Beginning of verse text.
3564 String used to each space that is further indented than the beginning of
3567 @item begin-verse-line
3568 Beginning of a line of verse.
3570 @item empty-verse-line
3571 End of a line of verse.
3573 @item begin-last-stanza-line
3574 Beginning of the last line of a verse stanza.
3576 @item end-last-stanza-line
3577 End of the last line of a verse stanza.
3583 Beginning of an example region. To make use of this, an
3584 @samp{<example>} tag is needed.
3587 End of an example region. To make use of this, an @samp{</example>} tag
3591 Begin a centered line.
3594 End a centered line.
3597 Begin a quoted region.
3600 End a quoted region.
3602 @item begin-quote-item
3603 Begin a quote paragraph.
3605 @item end-quote-item
3606 End a quote paragraph.
3609 Begin an unordered list.
3612 End an unordered list.
3614 @item begin-uli-item
3615 Begin an unordered list item.
3618 End an unordered list item.
3621 Begin an ordered list.
3624 End an ordered list.
3626 @item begin-oli-item
3627 Begin an ordered list item.
3630 End an ordered list item.
3633 Begin a definition list.
3636 End a definition list.
3639 Begin a definition list item.
3642 End a definition list item.
3645 Begin a definition list term.
3648 End a definition list term.
3651 Begin a definition list entry.
3654 End a definition list entry.
3662 @item begin-table-group
3663 Begin a table grouping.
3665 @item end-table-group
3666 End a table grouping.
3668 @item begin-table-row
3674 @item begin-table-entry
3675 Begin a table entry.
3677 @item end-table-entry
3682 @node Markup Tags, Style Elements, Markup Strings, Common Elements
3683 @comment node-name, next, previous, up
3684 @subsection Tag specifications for special markup
3685 @cindex publishing, markup tags
3687 @anchor{muse-publish-markup-tags}
3688 @code{muse-publish-markup-tags}
3690 A list of tag specifications, for specially marking up text.
3692 XML-style tags are the best way to add custom markup to Muse. This is
3693 easily accomplished by customizing this list of markup tags.
3695 For each entry, the name of the tag is given, whether it expects a
3696 closing tag and/or an optional set of attributes, whether it is
3697 nestable, and a function that performs whatever action is desired within
3698 the delimited region.
3700 The tags themselves are deleted during publishing, before the function
3701 is called. The function is called with three arguments, the beginning
3702 and end of the region surrounded by the tags. If properties are
3703 allowed, they are passed as a third argument in the form of an alist.
3704 The `end' argument to the function is always a marker.
3706 Point is always at the beginning of the region within the tags, when the
3707 function is called. Wherever point is when the function finishes is
3708 where tag markup will resume.
3710 These tag rules are processed once at the beginning of markup, and once
3711 at the end, to catch any tags which may have been inserted in-between.
3713 @node Style Elements, , Markup Tags, Common Elements
3714 @comment node-name, next, previous, up
3715 @subsection Parameters used for defining styles
3716 @cindex publishing, style elements
3718 Style elements are tags that define a style. Use
3719 @code{muse-define-style} to create a new style.
3722 (muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3725 @subheading Usable elements
3730 File extension to use for publishing files with this style.
3733 File extension to use for publishing links to Muse files with this
3737 File extension to use for publishing second-stage files with this style.
3739 For example, PDF publishing generates a LaTeX file first, then a PDF
3740 from that LaTeX file.
3743 List of markup rules for publishing a page with Muse.
3744 @xref{muse-publish-markup-regexps}.
3747 An alist of style types to custom functions for that kind of text.
3748 @xref{muse-publish-markup-functions}.
3751 Strings used for marking up text with this style.
3753 These cover the most basic kinds of markup, the handling of which
3754 differs little between the various styles.
3757 A list of tag specifications, used for handling extra tags.
3758 @xref{muse-publish-markup-tags}.
3761 A table of characters which must be represented specially.
3764 A function that is to be executed on the newly-created publishing buffer
3765 (or the current region) before any publishing occurs.
3767 This is used to set extra parameters that direct the publishing process.
3770 A function that is to be executed on the publishing buffer (or the
3771 current region) immediately after applying all of the markup regexps.
3773 This is used to fix the order of table elements (header, footer, body)
3777 A function that is to be executed on the publishing buffer after
3778 :before-end, and immediately after inserting the header and footer.
3780 This is used for generating the table of contents as well as setting the
3784 A function that is to be executed after saving the published file, but
3785 while still in its buffer.
3787 This is used for generating second-stage documents like PDF files from
3788 just-published LaTeX files.
3791 Header used for publishing files of this style.
3793 This may be a variable, text, or a filename. It is inserted at the
3794 beginning of a file, after evaluating the publishing markup.
3797 Footer used for publishing files of this style.
3799 This may be a variable, text, or a filename. It is inserted at the end
3800 of a file, after evaluating the publishing markup.
3803 Style sheet used for publishing files of this style.
3805 This may be a variable or text. It is used in the header of HTML and
3806 XHTML based publishing styles.
3809 The function used to browse the published result of files of this style.
3813 @node Deriving Styles, , Common Elements, Extending Muse
3814 @comment node-name, next, previous, up
3815 @section Deriving a new style from an existing one
3816 @cindex publishing styles, deriving
3818 To create a new style from an existing one, use @code{muse-derive-style}
3819 as follows. This is a good way to fix something you don't like about a
3820 particular publishing style, or to personalize it.
3823 (muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
3826 The derived name is a string defining the new style, such as "my-html".
3827 The base name must identify an existing style, such as "html" -- if you
3828 have loaded @file{muse-html}. The style parameters are the same as
3829 those used to create a style, except that they override whatever
3830 definitions exist in the base style. However, some definitions only
3831 partially override. The following parameters support partial
3834 @xref{Style Elements}, for a complete list of all parameters.
3839 If a markup function is not found in the derived style's function list,
3840 the base style's function list will be queried.
3843 All regexps in the current style and the base style(s) will be used.
3846 If a markup string is not found in the derived style's string list, the
3847 base style's string list will be queried.
3851 @node Miscellaneous, Getting Help and Reporting Bugs, Extending Muse, Top
3852 @comment node-name, next, previous, up
3853 @chapter Miscellaneous add-ons, like a minor mode
3856 * Muse List Edit Minor Mode:: Edit lists easily in other major modes.
3859 @node Muse List Edit Minor Mode, , , Miscellaneous
3860 @comment node-name, next, previous, up
3861 @section Edit lists easily in other major modes
3862 @cindex muse-list-edit-minor-mode
3864 @code{muse-list-edit-minor-mode} is meant to be used with other major
3865 modes, such as Message (for composing email) and debian-changelog-mode
3866 (for editing debian/changelog files).
3868 It implements practically perfect support for editing and filling lists.
3869 It can even handle nested lists. In addition to Muse-specific list
3870 items ("-", numbers, definition lists, footnotes), it can also handle
3871 items that begin with "*" or "+". Filling list items behaves in the
3872 same way that it does in Muse, regardless of whether filladapt is also
3873 enabled, which is the primary reason to use this tool.
3875 @subheading Installation
3877 To use it, add ``(require 'muse-mode)'' to your Emacs customization file
3878 and add the function @code{turn-on-muse-list-edit-minor-mode} to any
3879 mode hooks where you wish to enable this minor mode.
3881 @subheading Keybindings
3883 @code{muse-list-edit-minor-mode} uses the following keybindings.
3887 @item M-RET (`muse-l-e-m-m-insert-list-item')
3888 Insert a new list item at point, using the indentation level of the
3891 @item C-< (`muse-l-e-m-m-decrease-list-item-indent')
3892 Decrease indentation of the current list item.
3894 @item C-> (`muse-l-e-m-m-increase-list-item-indent')
3895 Increase indentation of the current list item.
3899 @subheading Functions
3901 @defun muse-list-edit-minor-mode
3902 This is a global minor mode for editing files with lists.
3903 It is meant to be used with other major modes, and not with Muse mode.
3905 Interactively, with no prefix argument, toggle the mode.
3906 With universal prefix @var{arg} turn mode on.
3907 With zero or negative @var{arg} turn mode off.
3909 This minor mode provides the Muse keybindings for editing lists,
3910 and support for filling lists properly.
3912 It recognizes not only Muse-style lists, which use the "-"
3913 character or numbers, but also lists that use asterisks or plus
3914 signs. This should make the minor mode generally useful.
3916 Definition lists and footnotes are also recognized.
3918 Note that list items may omit leading spaces, for compatibility
3919 with modes that set @code{left-margin}, such as
3920 @code{debian-changelog-mode}.
3923 @defun turn-on-muse-list-edit-minor-mode
3924 Unconditionally turn on Muse list edit minor mode.
3927 @defun turn-off-muse-list-edit-minor-mode
3928 Unconditionally turn off Muse list edit minor mode.
3931 @node Getting Help and Reporting Bugs, History, Miscellaneous, Top
3932 @comment node-name, next, previous, up
3933 @chapter Getting Help and Reporting Bugs
3934 @cindex help, getting
3935 @cindex bugs, reporting
3937 After you have read this guide, if you still have questions about
3938 Muse, or if you have bugs to report, there are several places you can
3944 @uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the
3945 emacswiki.org page, and anyone may add tips, hints, or bug descriptions
3949 @uref{http://mwolson.org/projects/EmacsMuse.html} is the web page
3950 that Michael Olson (the current maintainer) made for Muse.
3953 Muse has several different mailing lists.
3957 @item muse-el-announce
3958 Low-traffic list for Muse-related announcements.
3960 You can join this mailing list (@email{muse-el-announce@@gna.org})
3961 using the subscription form at
3962 @url{http://mail.gna.org/listinfo/muse-el-announce/}. This
3963 mailing list is also available via Gmane (@url{http://gmane.org/}). The
3964 group is called @samp{gmane.emacs.muse.announce}.
3966 @item muse-el-discuss
3967 Discussion, bugfixes, suggestions, tips, and the like for Muse.
3968 This mailing list also includes the content of muse-el-announce.
3970 You can join this mailing list (@email{muse-el-discuss@@gna.org})
3971 using the subscription form at
3972 @url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing
3973 list is also available via Gmane with the identifier
3974 @samp{gmane.emacs.muse.general}.
3977 Log messages for commits made to Muse.
3979 You can join this mailing list (@email{muse-el-logs@@gna.org}) using
3980 the subscription form at
3981 @url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list
3982 is also available via Gmane with the identifier
3983 @samp{gmane.emacs.muse.scm}.
3985 @item muse-el-commits
3986 Generated bug reports for Emacs Muse. If you use our bug-tracker at
3987 @url{https://gna.org/bugs/?group=muse-el}, the bug reports will be
3988 sent to this list automatically.
3990 You can join this mailing list (@email{muse-el-commits@@gna.org}) using
3991 the subscription form at
3992 @url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list
3993 is also available via Gmane with the identifier
3994 @samp{gmane.emacs.muse.cvs}.
3996 @item muse-el-internationalization
3997 Discussion of translation of the Muse website and documentation into
4000 You can join this mailing list
4001 (@email{muse-el-internationalization@@gna.org}) using the subscription
4002 form at @url{http://mail.gna.org/listinfo/internationalization/}. This
4003 mailing list is also available via Gmane with the identifier
4004 @samp{gmane.emacs.muse.internationalization}.
4009 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
4010 contributors are frequently around and willing to answer your
4011 questions. The @samp{#muse} channel is also available for
4012 Muse-specific help, and its current maintainer hangs out there.
4015 The maintainer of Emacs Muse, Michael Olson, may be contacted at
4016 @email{mwolson@@gnu.org}. He can be rather slow at answering email, so
4017 it is often better to use the muse-el-discuss mailing list.
4021 @node History, Contributors, Getting Help and Reporting Bugs, Top
4022 @comment node-name, next, previous, up
4023 @chapter History of This Document
4024 @cindex history, of Muse
4028 John Wiegley started Muse upon realizing that EmacsWiki had some serious
4029 limitations. Around February 2004, he started making "emacs-wiki version
4030 3.00 APLHA", which eventually became known as Muse.
4032 Most of those who frequent the emacs-wiki mailing list continued to use
4033 emacs-wiki, mainly because Planner hasn't been ported over to it.
4035 As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
4036 John Wiegley's request.
4039 Michael Olson overhauled this document and added many new sections in
4040 preparation for the first release of Muse (3.01).
4044 @node Contributors, GNU Free Documentation License, History, Top
4045 @comment node-name, next, previous, up
4046 @chapter Contributors to This Documentation
4047 @cindex contributors
4049 The first draft of this document was taken from the emacs-wiki texinfo
4050 manual. Michael Olson adapted it for Muse and added most of its
4053 John Sullivan did a majority of the work on the emacs-wiki texinfo
4056 While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
4057 emacs-wiki texinfo manual.
4060 @node GNU Free Documentation License, Concept Index, Contributors, Top
4061 @appendix GNU Free Documentation License
4062 @include doclicense.texi
4065 @node Concept Index, , GNU Free Documentation License, Top
4066 @comment node-name, next, previous, up