1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename muse.info 4@settitle Muse 5@c %**end of header 6 7@dircategory Emacs 8@direntry 9* Muse: (muse). Authoring and publishing environment for Emacs. 10@end direntry 11 12@syncodeindex fn cp 13 14@copying 15This manual is for Emacs Muse version 3.20. 16 17Copyright @copyright{} 2004, 2005, 2006, 2007, 182008, 2009, 2010 Free Software Foundation, Inc. 19 20@quotation 21Permission is granted to copy, distribute and/or modify this document 22under the terms of the GNU Free Documentation License, Version 1.2 or 23any later version published by the Free Software Foundation; with no 24Invariant Sections, with the Front-Cover texts being ``A GNU 25Manual'', and with the Back-Cover Texts as in (a) below. A copy of the 26license is included in the section entitled ``GNU Free Documentation 27License'' in this manual. 28 29(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 30this GNU Manual, like GNU software. Copies published by the Free 31Software Foundation raise funds for GNU development.'' 32 33This document is part of a collection distributed under the GNU Free 34Documentation License. If you want to distribute this document 35separately from the collection, you can do so by adding a copy of the 36license to the document, as described in section 6 of the license. 37 38All Emacs Lisp code contained in this document may be used, distributed, 39and modified without restriction. 40@end quotation 41@end copying 42 43@titlepage 44@title Muse manual 45@subtitle an authoring and publishing environment 46@subtitle for GNU Emacs and XEmacs 47 48@c The following two commands 49@c start the copyright page. 50@page 51@vskip 0pt plus 1filll 52@insertcopying 53@end titlepage 54 55@c So the toc is printed at the start 56@contents 57 58@ifnottex 59@node Top, Preface, (dir), (dir) 60@comment node-name, next, previous, up 61@top Muse 62 63@insertcopying 64@end ifnottex 65 66@menu 67* Preface:: About the documentation. 68* Introduction:: What is Muse? 69* Obtaining Muse:: How to get Muse releases and development 70 changes. 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. 84 85@detailmenu 86 --- The Detailed Node Listing --- 87 88How to Get Muse Releases and Development Changes 89 90* Releases:: Released versions of Muse. 91* Development:: Latest unreleased development changes. 92 93Getting Started 94 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. 99 100Creating and Managing Muse Projects 101 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. 106 107Rules for Using Markup 108 109* Paragraphs:: Paragraphs: centering and quoting. 110* Headings:: Levels of headings. 111* Directives:: Directives at the beginning of a 112 document. 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 119 descriptions. 120* Implicit Links:: Bare URLs, WikiNames, and InterWiki 121 links. 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 125 for extensibility. 126* Citations:: Support for citing other resources. 127* Comments:: Lines to omit from published output. 128* Tag Summary:: Tags that Muse recognizes. 129 130Publishing Various Types of Documents 131 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* Ikiwiki:: Integrating with ikiwiki. 138* Journal:: Keeping a journal or blog. 139* LaTeX:: Publishing LaTeX documents. 140* Poem:: Publish a poem to LaTeX or PDF. 141* Texinfo:: Publish entries to Texinfo format or PDF. 142* XML:: Publish entries to XML. 143 144Integrating Muse and pyblosxom.cgi 145 146* Blosxom Requirements:: Other tools needed for the Blosxom style. 147* Blosxom Entries:: Format of a Blosxom entry and automation. 148* Blosxom Options:: Blosxom styles and options provided. 149 150Making your own publishing styles 151 152* Markup Functions:: Specifying functions to mark up text. 153* Markup Regexps:: Markup rules for publishing. 154* Markup Strings:: Strings specific to a publishing style. 155* Markup Tags:: Tag specifications for special markup. 156* Style Elements:: Parameters used for defining styles. 157* Deriving Styles:: Deriving a new style from an existing 158 one. 159 160Miscellaneous add-ons, like a minor mode 161 162* Muse List Edit Minor Mode:: Edit lists easily in other major modes. 163 164@end detailmenu 165@end menu 166 167@node Preface, Introduction, Top, Top 168@comment node-name, next, previous, up 169@chapter About the documentation 170 171This document describes Muse, which was written by John Wiegley and is 172now maintained by Michael Olson. Several versions of this manual are 173available on-line. 174 175@itemize @bullet 176@item PDF: http://mwolson.org/static/doc/muse.pdf 177@item HTML (single file): http://mwolson.org/static/doc/muse.html 178@item HTML (multiple files): http://mwolson.org/static/doc/muse/ 179@end itemize 180 181@node Introduction, Obtaining Muse, Preface, Top 182@comment node-name, next, previous, up 183@chapter What is Muse? 184 185Emacs Muse (also known as ``Muse'' or ``Emacs-Muse'') is an authoring 186and publishing environment for Emacs. It simplifies the process of 187writing documents and publishing them to various output formats. 188 189Muse consists of two main parts: an enhanced text-mode for authoring 190documents and navigating within Muse projects, and a set of publishing 191styles for generating different kinds of output. 192 193What makes Muse distinct from other text-publishing systems is a modular 194environment, with a rather simple core, in which "styles" are derived 195from to create new styles. Much of Muse's overall functionality is 196optional. For example, you can use the publisher without the 197major-mode, or the mode without doing any publishing; or if you don't 198load the Texinfo or LaTeX modules, those styles won't be available. 199 200The Muse codebase is a departure from emacs-wiki.el version 2.44. The 201code has been restructured and rewritten, especially its publishing 202functions. The focus in this revision is on the authoring and 203publishing aspects, and the "wikiness" has been removed as a default 204behavior (available in the optional @file{muse-wiki} module). CamelCase 205words are no longer special by default. 206 207One of the principal aims in the development of Muse is to make it very 208easy to produce good-looking, standards-compliant documents. 209 210@node Obtaining Muse, Installation, Introduction, Top 211@comment node-name, next, previous, up 212@chapter How to Get Muse Releases and Development Changes 213 214@menu 215* Releases:: Released versions of Muse. 216* Development:: Latest unreleased development changes. 217@end menu 218 219@node Releases, Development, Obtaining Muse, Obtaining Muse 220@comment node-name, next, previous, up 221@section Released versions of Muse 222 223Choose to install a release if you want to minimize risk. 224 225Errors are corrected in development first. User-visible changes will be 226announced on the @email{muse-el-discuss@@gna.org} mailing list. 227@xref{Getting Help and Reporting Bugs}. 228 229@cindex releases, Debian package 230@cindex Debian package for Muse 231Debian users can get Muse via apt-get. The @file{muse-el} package is 232available both at Michael Olson's APT repository and the official Debian 233repository. To make use of the former, add the following line to your 234@file{/etc/apt/sources.list} file and run @code{apt-get install muse}. 235 236@example 237deb http://mwolson.org/debian/ ./ 238@end example 239 240@cindex releases, Ubuntu package 241@cindex Ubuntu package for Muse 242Ubuntu users can also get Muse via apt-get. The @file{muse-el} package 243is available both at Michael Olson's APT repository and the official 244Ubuntu repository. To make use of the former, add the following line to 245your @file{/etc/apt/sources.list} file and run @code{apt-get install 246muse}. 247 248@example 249deb http://mwolson.org/ubuntu/ ./ 250@end example 251 252The reason for making separate Debian and Ubuntu packages is that this 253manual is under the GFDL, and Debian will not allow it to be distributed 254in its main repository. Ubuntu, on the other hand, permits this manual 255to be included with the @file{muse-el} package. 256 257@cindex releases, from source 258Alternatively, you can download the latest release from 259@uref{http://download.gna.org/muse-el/} . 260 261@node Development, , Releases, Obtaining Muse 262@comment node-name, next, previous, up 263@section Latest unreleased development changes 264@cindex development 265 266Choose the development version if you want to live on the bleeding edge 267of Muse development or try out new features before release. 268 269@cindex git version control system, using 270The git version control system allows you to keep up-to-date with the 271latest changes to the development version of Muse. It also allows you 272to contribute changes (via commits, if you are have developer access to 273the repository, or via patches, otherwise). If you would like to 274contribute to Muse development, it is highly recommended that you use 275git. 276 277If you are new to git, you might find this tutorial helpful: 278@uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}. 279 280Downloading the Muse module with git and staying up-to-date involves 281the following steps. 282 283@enumerate 284@item Install git. 285 286@itemize @bullet 287@item Debian and Ubuntu: @kbd{apt-get install git-core}. 288@item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}. 289@item Other operating systems: download, compile, and install the source 290from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git 291package for your operating system. 292@end itemize 293 294@item Download the Muse development branch. 295 296If you have developer access to Muse, do: 297 298@example 299git clone ssh://repo.or.cz/srv/git/muse-el.git muse 300@end example 301 302otherwise, do: 303 304@example 305git clone git://repo.or.cz/muse-el.git muse 306@end example 307 308If you are behind a restrictive firewall, and do not have developer 309access, then do the following instead: 310 311@example 312git clone http://repo.or.cz/r/muse-el.git muse 313@end example 314 315@item List upstream changes that are missing from your local copy. 316Do this whenever you want to see whether new changes have been committed 317to Muse. If you wish, you may skip this step and proceed directly to 318the ``update'' step. 319 320@example 321# Change to the source directory you are interested in. 322cd muse 323 324# Fetch new changes from the repository, but don't apply them yet 325git fetch origin 326 327# Display log messages for the new changes 328git log HEAD..origin 329@end example 330 331``origin'' is git's name for the location where you originally got Muse 332from. You can change this location at any time by editing the 333@file{.git/config} file in the directory where the Muse source was 334placed. 335 336@cindex updating Muse with git 337@item Update to the latest version by pulling in any missing changes. 338 339@example 340cd muse 341git pull origin 342@end example 343 344git will show how many files changed, and will provide a visual display 345for how many lines were changed in each file. 346 347@end enumerate 348 349There are other ways to interact with the Muse repository. 350 351@itemize 352@item Browse git repo: @uref{http://repo.or.cz/w/muse-el.git} 353@item Latest development snapshot: @uref{http://mwolson.org/static/dist/muse-latest.tar.gz} 354@item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/muse-latest.zip} 355@end itemize 356 357The latest development snapshot can lag behind the git repo by as much 358as 20 minutes, but never more than that. 359 360@subheading Becoming a Muse developer 361@cindex developer, becoming 362 363If you want commit access to the shared Muse repository, then register 364an account at @uref{http://repo.or.cz} (be sure to add an SSH key), and 365contact the current maintainer at @email{mwolson@@gnu.org}. It would be 366best to send some patches to the @email{muse-el-discuss@@gna.org} 367mailing list first, so that he knows that you know what you are doing. 368@xref{Getting Help and Reporting Bugs}, for instructions on subscribing 369to the mailing list. 370 371You must also be willing to sign a copyright assignment for your changes 372to Muse, since Muse is a GNU project. The current maintainer will 373assist you in this process if you contact him. 374 375For information on committing changes to Muse and performing 376development, please consult 377@uref{http://emacswiki.org/cgi-bin/wiki/MuseDevelopment}. 378 379@node Installation, Getting Started, Obtaining Muse, Top 380@comment node-name, next, previous, up 381@chapter Compiling and Installing Muse 382 383Muse may be compiled and installed on your machine. 384 385@subheading Compilation 386@cindex compiling Muse 387 388This is an optional step, since Emacs Lisp source code does not 389necessarily have to be byte-compiled. Byte-compilation may yield a very 390slight speed increase. 391 392A working copy of Emacs or XEmacs is needed in order to compile Emacs 393Muse. By default, the program that is installed with the name 394@command{emacs} will be used. 395 396If you want to use the @command{xemacs} binary to perform the 397compilation, you must copy @file{Makefile.defs.default} to 398@file{Makefile.defs} in the top-level directory, and then edit 399@file{Makefile.defs} as follows. You can put either a full path to an 400Emacs or XEmacs binary or just the command name, as long as it is in the 401@env{PATH}. 402 403@example 404EMACS = xemacs 405SITEFLAG = -no-site-file 406# Edit the section as necessary 407install_info = install-info --section "XEmacs 21.4" $(1).info \ 408 $(INFODIR)/dir || : 409@end example 410 411Running @code{make} in the top-level directory should compile the Muse 412source files in the @file{lisp} directory, and generate an autoloads 413file in @file{lisp/muse-autoloads.el}. 414 415@subheading Installation 416@cindex installing Muse 417 418Muse may be installed into your file hierarchy by doing the following. 419 420Copy @file{Makefile.defs.default} to @file{Makefile.defs} in the 421top-level directory, if you haven't done so already. Then edit the 422@file{Makefile.defs} file so that @env{ELISPDIR} points to where you 423want the source and compiled Muse files to be installed and 424@env{INFODIR} indicates where to put the Muse manual. You may use a 425combination of @env{DESTDIR} and @env{PREFIX} to further determine where 426the installed files should be placed. As mentioned earlier, you will 427want to edit @env{EMACS} and @env{SITEFLAG} as shown in the Compilation 428section if you are using XEmacs. 429 430If you are installing Muse on a Debian or Ubuntu system, you might want 431to change the value of @env{INSTALLINFO} as specified in 432@file{Makefile.defs}. 433 434If you wish to install Muse to different locations than the defaults 435specify, edit @file{Makefile.defs} accordingly. 436 437Run @code{make} as a normal user, if you haven't done so already. 438 439Run @code{make install} as the root user if you have chosen installation 440locations that require root permissions. 441 442@subheading ELPA 443@cindex ELPA package for Muse 444 445For those used to installing software packages, there will be a 446@code{muse} package available in the Emacs Lisp Package Archive 447(abbreviated ``ELPA'') as of the 3.10 release of Muse. This package 448will be compiled and installed automatically in a user-specific 449location. For more information on ELPA, see 450@uref{http://tromey.com/elpa/}. 451 452@node Getting Started, Projects, Installation, Top 453@comment node-name, next, previous, up 454@chapter Getting Started 455@cindex settings 456 457@menu 458* Loading Muse:: How to load Muse. 459* Using Muse Mode:: How to edit files in Muse. 460* Publishing Files Overview:: Publishing a single file or project. 461* File Extensions:: Using a different file extension. 462@end menu 463 464@node Loading Muse, Using Muse Mode, Getting Started, Getting Started 465@comment node-name, next, previous, up 466@section How to Load Muse 467@cindex settings, init file 468 469To use Muse, add the directory containing its files to your 470@code{load-path} variable, in your @file{.emacs} file. Then, load in 471the authoring mode, and the styles you wish to publish to. An example 472follows. 473 474@lisp 475(add-to-list 'load-path "<path to Muse>") 476 477(require 'muse-mode) ; load authoring mode 478 479(require 'muse-html) ; load publishing styles I use 480(require 'muse-latex) 481(require 'muse-texinfo) 482(require 'muse-docbook) 483 484(require 'muse-project) ; publish files in projects 485@end lisp 486 487An easy way of seeing which settings are available and changing settings 488is to use the Muse customization interface. To do this, type 489@kbd{M-x customize-group muse RET}. Each of the options has its own 490documentation. Options are grouped logically according to what effect 491they have. 492 493@node Using Muse Mode, Publishing Files Overview, Loading Muse, Getting Started 494@comment node-name, next, previous, up 495@section How to Edit Files in Muse 496@cindex editing Muse files 497 498Muse Mode should automatically be activated when you visit a file with a 499``.muse'' extension. One such file is @file{QuickStart.muse}, which is 500available in the @file{examples} directory of the Muse distribution. 501You can tell that Muse Mode has been activated by checking for the text 502``Muse'' in your mode line. If Muse Mode has not been activated, you 503may activate it by type @kbd{M-x muse-mode RET}. 504 505You will notice that Muse files are highlighted very simply. Links are 506colored blue, headings are large and bold text, and @verb{|<example>|} 507tags are colored in grey. 508 509There are several different ways to edit things like links, which hide 510the underlying Muse markup. One way is to toggle font-locking off by 511hitting @kbd{C-c C-l}, which is also @kbd{M-x font-lock-mode}, make 512changes, and then hit @kbd{C-c C-l} again to toggle font-locking back 513on. Another way is just to move into the text and edit it. Markup can 514also be removed by normal deletion methods, though some side effects 515might require a second deletion. 516 517For the particular case of editing links, it is easiest to move to the 518link and do @kbd{C-c C-e}, which is also @kbd{M-x 519muse-edit-link-at-point}. This prompts you for the link and its 520description, using the previous contents of the link as initial values. 521A link to another Muse file may be created by hitting @kbd{C-c TAB l}. 522A link to a URL may be created by hitting @kbd{C-c TAB u}. Links may be 523followed by hitting @kbd{RET} on them. 524 525If you want to add a new list item, this may by accomplished by hitting 526@kbd{M-RET}. This will put a dash and some spaces on the screen. The 527dash is the Muse markup that indicates a list item. It is also possible 528to created ``nested'' lists with this command, by adjusting the number 529of spaces in front of the dashes. If you have lists with long lines, 530you can move to a list item and hit @kbd{M-q} to wrap it onto multiple 531lines. 532 533@node Publishing Files Overview, File Extensions, Using Muse Mode, Getting Started 534@comment node-name, next, previous, up 535@section Publishing a Single File or Project 536@cindex editing Muse files 537 538The command @kbd{M-x muse-project-publish-this-file} will publish the 539current document to any available publishing style (a publishing style 540is an output format, like HTML or Docbook), placing the output in the 541current directory. If you are in Muse Mode, this command will be bound 542to @kbd{C-c C-t}. If the file has been published recently, and its 543contents have not changed, running @kbd{C-c C-t} again will not publish 544the file. To force publishing in this case, do @kbd{C-u C-c C-t}. 545 546If you have set up projects and are visiting a file that is part of a 547project, then @kbd{C-c C-t} will restrict the output formats to those 548which are used by the project, and will automatically publish to the 549output directory defined by the project. If you want to publish to a 550different directory or use a different format, then use @kbd{C-c M-C-t}, 551which is also @kbd{M-x muse-publish-this-file}. 552 553If the currently opened file is part of a defined project in 554@code{muse-project-alist}, it (and the rest of the changed files in a 555project) may be published using @kbd{C-c C-p}. 556 557@node File Extensions, , Publishing Files Overview, Getting Started 558@comment node-name, next, previous, up 559@section Using a Different File Extension 560@cindex file extension, specifying 561 562By default, Muse expects all project files to have the file extension 563@file{.muse}. Files without this extension will not be associated with 564Muse mode and will not be considered part of any project, even if they 565are within a project directory. 566 567If you don't want to use @file{.muse}, you can customize the extension 568by setting the value of @code{muse-file-extension}. 569 570If you don't want to use any extension at all, and want Muse to 571autodetect project files based on their location, then add the following 572to your Muse settings file. 573 574@lisp 575(setq muse-file-extension nil 576 muse-mode-auto-p t) 577@end lisp 578 579Note that if you chose to have @code{muse-file-extension} set to 580@code{nil}, you may have trouble if your @file{.emacs} file or other 581init scripts attempt to visit a Muse file. (A very common example of 582this is if you use Planner with Muse and run @code{(plan)} from your 583@file{.emacs}.) If you wish to visit Muse files from your 584@file{.emacs}, be sure to also add the following additional code before 585any such visits happen: 586 587@lisp 588(add-hook 'find-file-hooks 'muse-mode-maybe) 589@end lisp 590 591 592@node Projects, Keystroke Summary, Getting Started, Top 593@comment node-name, next, previous, up 594@chapter Creating and Managing Muse Projects 595@cindex projects 596 597Often you will want to publish all the files within a directory to a 598particular set of output styles automatically. To support, Muse 599allows for the creation of "projects". 600 601@menu 602* Single Project:: A single-project example. 603* Multiple Projects:: A multiple-project example. 604* Projects and Subdirectories:: Publishing subdirectories in projects. 605* Options for Projects:: Listing of available options for projects. 606@end menu 607 608@node Single Project, Multiple Projects, Projects, Projects 609@comment node-name, next, previous, up 610@section A Single-Project Example 611@cindex projects, single 612 613Here is a sample project, which may be defined in your @file{.emacs} 614file. 615 616@lisp 617(setq muse-project-alist 618 '(("Website" ("~/Pages" :default "index") 619 (:base "html" :path "~/public_html") 620 (:base "pdf" :path "~/public_html/pdf")))) 621@end lisp 622 623The above defines a project named "website", whose files are located 624in the directory @file{~/Pages}. The default page to visit is 625@file{index}. When this project is published, each page will be 626output as HTML to the directory @file{~/public_html}, and as PDF to 627the directory @file{~/public_html/pdf}. Within any project page, you 628may create a link to other pages using the syntax @samp{[[pagename]]}. 629 630If you would like to include only some files from a directory in a Muse 631project, you may use a regexp in place of @file{~/Pages} in the example. 632 633@node Multiple Projects, Projects and Subdirectories, Single Project, Projects 634@comment node-name, next, previous, up 635@section A Multiple-Project Example 636@cindex projects, multiple 637 638It is possible to specify multiple projects. Here is an example of 639three projects: a generic website, a projects area, and a day-planner 640(the day-planner part requires Planner Mode---see 641@uref{http://wjsullivan.net/PlannerMode.html} to get it). 642 643@lisp 644(setq muse-project-alist 645 '(("Website" ("~/Pages" :default "index") 646 (:base "html" :path "~/public_html")) 647 (("Projects" ("~/Projects" :default "index") 648 (:base "xhtml" 649 :path "~/public_html/projects" 650 :exclude "/TopSecret") 651 (:base "pdf" 652 :path "~/public_html/projects/pdf" 653 :exclude "/TopSecret"))) 654 ("Plans" ("~/Plans" 655 :default "TaskPool" 656 :major-mode planner-mode 657 :visit-link planner-visit-link) 658 (:base "planner-xhtml" 659 :path "~/public_html/plans")))) 660@end lisp 661 662The @option{:major-mode} attribute specifies which major to use when 663visiting files in this directory. 664 665The @option{:visit-link} attribute specifies the function to call when 666visiting links. 667 668The @option{:exclude} attribute has a regexp that matches files to never 669publish. 670 671@node Projects and Subdirectories, Options for Projects, Multiple Projects, Projects 672@comment node-name, next, previous, up 673@section Publishing Subdirectories in Projects 674@cindex projects, subdirectories 675 676If you want to publish a directory and all of its subdirectories, Muse 677provides two convenience functions that together generate the proper 678rules for you. Note that we use the backtick to begin this 679muse-project-alist definition, rather than a single quote. 680 681@lisp 682(setq muse-project-alist 683 `(("Website" ("~/Pages" :default "index") 684 (:base "html" :path "~/public_html")) 685 ("Blog" (,@@(muse-project-alist-dirs "~/Blog") 686 :default "index") 687 ;; Publish this directory and its subdirectories. Arguments 688 ;; are as follows. The above `muse-project-alist-dirs' part 689 ;; is also needed. 690 ;; 1. Source directory 691 ;; 2. Output directory 692 ;; 3. Publishing style 693 ;; remainder: Other things to put in every generated style 694 ,@@(muse-project-alist-styles "~/Blog" 695 "~/public_html/blog" 696 "blosxom")))) 697@end lisp 698 699The @code{muse-project-alist-dirs} function takes a directory and 700returns it and all of its subdirectories in a list. 701 702The @code{muse-project-alist-styles} function is explained by the 703comments above. 704 705The ``blosxom'' text is the name of another publishing style, much like 706``html''. @xref{Blosxom}, for further information about it. You can 707use any publishing style you like for the third argument to 708@code{muse-project-alist-styles}. 709 710@node Options for Projects, , Projects and Subdirectories, Projects 711@comment node-name, next, previous, up 712@section Listing of Available Options for Projects 713@cindex projects, options 714@cindex muse-project-alist, reference 715 716This is a listing of all of the various options (or, more accurately: 717attributes) that may be specified in @code{muse-project-alist}. 718 719Each muse-project-alist entry looks like this: 720 721@example 722 (PROJECT-NAME (SOURCES) 723 OUTPUTS) 724@end example 725 726We refer to these names below. 727 728``Attributes'', which compose SOURCES and OUTPUTS, are a pair of values. 729The first value is a keyword, like @option{:default}. The second part 730is the value associated with that keyword, such as the text ``index''. 731If you are familiar with Emacs Lisp property lists, the concept is 732similar to that, except that in the SOURCES section, single directories 733can be interspersed with two-value attributes. 734 735@subheading Project Name 736 737This is a string that indicates the name of the project. It is 738primarily used for publishing interwiki links with the 739@file{muse-wiki.el} module. 740 741@subheading Sources 742 743This part of a muse-project-alist entry consists of two-value 744attributes, and also directory names. If you are publishing a book, the 745order of directories and attributes is significant. 746 747The minimal content for the sources section is a list of directories. 748 749@table @option 750 751@item :book-chapter 752Indicates a new chapter of a book. The text of the title of the chapter 753comes immediately after this keyword. 754 755@item :book-end 756Indicates the end of a book. Directories listed after this one are 757ignored when publishing a book. The value ``t'' (without quotes) should 758come immediately after this keyword. 759 760@item :book-funcall 761A function to call while publishing a book. This is useful for doing 762something just after a particular chapter. 763 764@item :book-part 765Indicates the beginning of a new part of the book. The text of the 766title should come immediately after this keyword. 767 768@item :book-style 769Indicate a particular publishing style to use for this part of the book. 770If this is specified, it should come just after a @option{:part} 771attribute. 772 773@item :default 774The default page to visit when browsing a project. Also, if you are 775using the @file{muse-wiki.el} module, publishing a link to just a 776project's name will cause it to link to this default file. 777 778@item :force-publish 779This specifies a list of pages which should be published every time a 780project is published (by using @kbd{C-c C-p}, for example), regardless 781of whether their contents have changed. This is useful for updating 782Index pages, pages that use the @verb{|<include>|} tag, and other pages 783that have dynamically-generated content. 784 785@item :major-mode 786This specifies the major mode to use when visiting files in this 787project. The default is @code{muse-mode}. 788 789@item :nochapters 790This indicates that while publishing a book, do not automatically create 791chapters. Values which may follow this are nil (the default, which 792means that we automatically create chapters), or non-nil, which means 793that we manually specify chapters with the @option{:book-chapter} 794attribute, 795 796@item :publish-project 797Indicates which function we should call when publishing a project. 798 799@item :set 800This specifies a list of variables and values to set when publishing a 801project. The list should be a property list, which is in the form: 802 803@example 804(VAR1 VALUE1 VAR2 VALUE2 ...) 805@end example 806 807@item :visit-link 808Specifies the function to call when visiting a link. The default is 809@code{muse-visit-link-default}. The arguments for that function should 810be (1) the link and (2) whether to visit the link in a new window. 811 812@end table 813 814@subheading Outputs 815 816This part of a muse-project-alist entry is composed of lists of 817attributes. Each list is called an ``output style''. 818 819The minimal content for an output style is a @option{:base} attribute 820and a @option{:path} attribute. 821 822@table @option 823 824@item :base 825Publishing style to use, such as ``html'', ``docbook'', or ``pdf''. 826 827@item :base-url 828An external URL which can be used to access published files. This is 829mainly used by the @file{muse-wiki} module when publishing links between 830two separate projects, if the projects are served on different domains. 831 832It is also used by the @file{muse-journal} module to create the RSS or 833RDF output. 834 835@item :exclude 836Exclude items matching a regexp from being published. The regexp should 837usually begin with "/". 838 839@item :include 840Only include items matching a regexp when publishing. The regexp should 841usually begin with "/". 842 843@item :path 844The directory in which to store published files. 845 846@item :timestamps 847A file containing the timestamps (that is, time of creation) for files 848in this project. It might eventually used by the @file{muse-blosxom} 849module, but this option is not currently in use by any Muse code. 850 851@end table 852 853 854@node Keystroke Summary, Markup Rules, Projects, Top 855@comment node-name, next, previous, up 856@chapter Keys Used in Muse Mode 857@cindex keystrokes 858 859This is a summary of keystrokes available in every Muse buffer. 860 861@table @kbd 862 863@item C-c C-a (`muse-index') 864Display an index of all known Muse pages. 865 866@item C-c C-b (`muse-find-backlinks') 867Find all pages that link to this page. 868 869@item C-c C-e (`muse-edit-link-at-point') 870Edit link at point. 871 872@item C-c C-f (`muse-project-find-file') 873Open another Muse page. Prompt for the name. 874 875@item C-c C-i l, C-c TAB l (`muse-insert-relative-link-to-file') 876Insert a link to a file interactively. 877 878@item C-c C-i t, C-c TAB t (`muse-insert-tag') 879Insert a tag interactively. 880 881@item C-c C-i u, C-c TAB u (`muse-insert-url') 882Insert a URL interactively. 883 884@item C-c C-l (`font-lock-mode') 885Toggle font lock / highlighting for the current buffer. 886 887@item C-c C-p (`muse-project-publish') 888Publish any Muse pages that have changed. 889 890@item C-c C-s (`muse-search') 891Find text in all files of the current project. 892 893@item C-c C-t (`muse-project-publish-this-file') 894Publish the currently-visited file. Prompt for the style if the current 895file can be published using more than one style. 896 897@item C-c C-S-t, or C-c C-M-t (`muse-publish-this-file') 898Publish the currently-visited file. Prompt for both the style and 899output directory. 900 901@item C-c C-v (`muse-browse-result') 902Show the published result of this page. 903 904@item C-c = (`muse-what-changed') 905Diff this page against the last backup version. 906 907@item TAB 908Move to the next Wiki reference. 909 910@item S-TAB 911Move to the previous Wiki reference. 912 913@item M-TAB 914Complete the name of a page from the current project at point. 915 916@item M-RET 917Insert a new list item at point, indenting properly. 918 919@item C-< 920Decrease the indentation of the list item at point. 921 922@item C-> 923Increase the indentation of the list item at point. 924 925@item M-x muse-colors-toggle-inline-images RET 926Toggle display of inlined images on/off. 927 928@item M-x muse-update-values RET 929Update various values that are automatically generated. 930 931Call this after changing @code{muse-project-alist}. 932@end table 933 934 935@node Markup Rules, Publishing Styles, Keystroke Summary, Top 936@comment node-name, next, previous, up 937@chapter Rules for Using Markup 938@cindex markup 939 940A Muse document uses special, contextual markup rules to determine how 941to format the output result. For example, if a paragraph is indented, 942Muse assumes it should be quoted. 943 944There are not too many markup rules, and all of them strive to be as 945simple as possible so that you can focus on document creation, rather 946than formatting. 947 948@menu 949* Paragraphs:: Paragraphs: centering and quoting. 950* Headings:: Levels of headings. 951* Directives:: Directives at the beginning of a 952 document. 953* Emphasizing Text:: Bold, italicized, and underlined text. 954* Footnotes:: Making notes to be shown at the end. 955* Verse:: Indicating poetic stanzas. 956* Lists:: Lists of items. 957* Tables:: Generation of data tables. 958* Explicit Links:: Hyperlinks and email addresses with 959 descriptions. 960* Implicit Links:: Bare URLs, WikiNames, and InterWiki 961 links. 962* Images:: Publishing and displaying images. 963* Horizontal Rules and Anchors:: Inserting a horizontal line or anchor. 964* Embedded Lisp:: Evaluating Emacs Lisp code in documents 965 for extensibility. 966* Citations:: Support for citing other resources. 967* Comments:: Lines to omit from published output. 968* Tag Summary:: Tags that Muse recognizes. 969@end menu 970 971@node Paragraphs, Headings, Markup Rules, Markup Rules 972@comment node-name, next, previous, up 973@section Paragraphs: centering and quoting 974@cindex paragraphs 975 976Paragraphs in Muse must be separated by a blank line. 977 978@cindex paragraphs, centered 979@subheading Centered paragraphs and quotations 980 981A line that begins with six or more columns of whitespace (either tabs 982or spaces) indicates a centered paragraph. Alternatively, you can use 983the @verb{|<center>|} tag to surround regions that are to be published 984as centered paragraphs. 985 986@cindex paragraphs, quoted 987@cindex quotations 988But if a line begins with whitespace, though less than six columns, it 989indicates a quoted paragraph. Alternatively, you can use the 990@verb{|<quote>|} tag to surround regions that are to be published as 991quoted paragraphs. 992 993@cindex examples 994@cindex monospace, rendering blocks 995@cindex HTML, rendering blocks in monospace 996@subheading Literal paragraphs 997 998The @verb{|<example>|} tag is used for examples, where whitespace should 999be preserved, the text rendered in monospace, and any characters special 1000to the output style escaped. 1001 1002@cindex literal text 1003@cindex HTML, inserting a raw block 1004There is also the @verb{|<literal>|} tag, which causes a marked block to 1005be entirely left alone. This can be used for inserting a hand-coded 1006HTML blocks into HTML output, for example. 1007 1008If you want some text to only be inserted when publishing to a 1009particular publishing style, use the @option{style} attribute for the 1010@verb{|<literal>|} tag. An example follows. 1011 1012@example 1013<literal style="latex"> 1014A LaTeX-based style was used in the publishing of this document. 1015</literal> 1016@end example 1017 1018This will leave the region alone if the current publishing style is 1019``latex'' or based on ``latex'', such as ``pdf'', and delete the region 1020otherwise. It is also possible to leave the text alone only for one 1021particular style, rather than its derivations, by adding 1022@code{exact="t"} to the tag. 1023 1024@cindex line breaks 1025@subheading Line breaks 1026 1027If you need a line break, then use the @samp{<br>} tag. Most of the 1028time this tag is unnecessary, because Muse will automatically detect 1029paragraphs by means of blank lines. If you want to preserve newlines in 1030several lines of text, then use verse markup instead (@pxref{Verse}). 1031 1032@node Headings, Directives, Paragraphs, Markup Rules 1033@comment node-name, next, previous, up 1034@section Levels of headings 1035@cindex headings 1036 1037A heading becomes a chapter or section in printed output -- depending on 1038the style. To indicate a heading, start a new paragraph with one or 1039more asterices, followed by a space and the heading title. Then begin 1040another paragraph to enter the text for that section. 1041 1042All levels of headings will be published. Most publishing styles only 1043distinguish the between the first 4 levels, however. 1044 1045@example 1046* First level 1047 1048** Second level 1049 1050*** Third level 1051 1052**** Fourth level 1053@end example 1054 1055@node Directives, Emphasizing Text, Headings, Markup Rules 1056@comment node-name, next, previous, up 1057@section Directives at the beginning of a document 1058@cindex directives 1059 1060Directives are lines beginning with the @samp{#} character that come 1061before any paragraphs or sections in the document. Directives are of 1062the form ``#directive content of directive''. You can use any 1063combination of uppercase and lowercase letters for directives, even if 1064the directive is not in the list below. 1065 1066The @code{muse-publishing-directive} function may be used in header and 1067footer text to access directives. For example, to access the 1068@code{#title} directive, use @code{(muse-publishing-directive "title")}. 1069 1070The following is a list of directives that Muse uses. 1071 1072@table @code 1073@cindex #author 1074@item #author 1075The author of this document. 1076 1077If this is not specified, Muse will attempt to figure it out from the 1078@code{user-full-name} variable. 1079 1080@cindex #date 1081@item #date 1082The date that the document was last modified. 1083 1084This is used by publishing styles that are able to embed the date 1085information. 1086 1087@cindex #desc 1088@item #desc 1089A short description of this document. 1090 1091This is used by the @code{journal} publishing style to embed information 1092inside of an RSS/RDF feed. 1093 1094@cindex #title 1095@item #title 1096The title of this document. 1097 1098If this is not specified, the name of the file is used. 1099 1100@end table 1101 1102@node Emphasizing Text, Footnotes, Directives, Markup Rules 1103@comment node-name, next, previous, up 1104@section Bold, italicized, and underlined text 1105@cindex emphasizing text 1106@cindex underlining text 1107@cindex italicizing text 1108@cindex verbatim text 1109@cindex monospace, rendering words 1110 1111To emphasize text, surround it with certain specially recognized 1112characters. 1113 1114@example 1115*emphasis* 1116**strong emphasis** 1117***very strong emphasis*** 1118_underlined_ 1119=verbatim and monospace= 1120@end example 1121 1122@cindex WYSIWYG 1123While editing a Muse document in Muse mode, these forms of emphasis will 1124be highlighted in a WYSIWYG manner. Each of these forms may span 1125multiple lines. 1126 1127Verbatim text will be colored as gray by default. To change this, 1128customize @code{muse-verbatim-face}. 1129 1130You can also use the @verb{|<code>|} tag to indicate verbatim and 1131monospace text. This is handy for regions that have an ``='' in them. 1132 1133@node Footnotes, Verse, Emphasizing Text, Markup Rules 1134@comment node-name, next, previous, up 1135@section Making notes to be shown at the end 1136@cindex footnotes 1137 1138A footnote reference is simply a number in square brackets. To define 1139the footnote, place this definition at the bottom of your file. 1140@samp{footnote-mode} can be used to greatly facilitate the creation of 1141these kinds of footnotes. 1142 1143Footnotes are defined by the same number in brackets occurring at the 1144beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very 1145easily insert footnotes while typing. Use @kbd{C-x C-x} to return to 1146the point of insertion. 1147 1148@node Verse, Lists, Footnotes, Markup Rules 1149@comment node-name, next, previous, up 1150@section Indicating poetic stanzas 1151@cindex verses 1152@cindex poetry 1153 1154Poetry requires that whitespace be preserved, but without resorting to 1155monospace. To indicate this, use the following markup, reminiscent of 1156email quotations. 1157 1158@example 1159> A line of Emacs verse; 1160> forgive its being so terse. 1161@end example 1162 1163You can also use the @verb{|<verse>|} tag, if you prefer. 1164 1165@example 1166<verse> 1167A line of Emacs verse; 1168 forgive its being so terse. 1169</verse> 1170@end example 1171 1172@cindex verses, multiple stanzas 1173Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as 1174follows. 1175 1176@example 1177<verse> 1178A line of Emacs verse; 1179 forgive its being so terse. 1180 1181In terms of terse verse, 1182 you could do worse. 1183</verse> 1184@end example 1185 1186@node Lists, Tables, Verse, Markup Rules 1187@comment node-name, next, previous, up 1188@section Lists of items 1189@cindex lists 1190 1191Lists are given using special characters at the beginning of a line. 1192Whitespace must occur before bullets or numbered items, to distinguish 1193from the possibility of those characters occurring in a real sentence. 1194 1195@cindex lists, bullets 1196These are rendered as a bullet list. 1197 1198@example 1199Normal text. 1200 1201 - bullet item one 1202 - bullet item two 1203@end example 1204 1205@cindex lists, enumerated 1206An enumerated list follows. 1207 1208@example 1209Normal text. 1210 1211 1. Enum item one 1212 2. Enum item two 1213@end example 1214 1215@cindex lists, definitions 1216Here is a definition list. 1217 1218@example 1219Term1 :: 1220 This is a first definition 1221 And it has two lines; 1222 no, make that three. 1223 1224Term2 :: This is a second definition 1225@end example 1226 1227@subheading Nested lists 1228 1229@cindex lists, nested 1230It is possible to nest lists of the same or different kinds. The 1231``level'' of the list is determined by the amount of initial whitespace. 1232 1233@example 1234Normal text. 1235 1236 - Level 1, bullet item one 1237 1. Level 2, enum item one 1238 2. Level 2, enum item two 1239 - Level 1, bullet item two 1240 1. Level 2, enum item three 1241 2. Level 2, enum item four 1242 term :: definition 1243@end example 1244 1245@subheading Breaking list items 1246 1247@cindex lists, breaking lines 1248If you want to break up a line within any list type, just put one blank 1249line between the end of the previous line and the beginning of the next 1250line, using the same amount of initial indentation. 1251 1252@example 1253 - bullet item 1, line 1 1254 1255 bullet item 1, line 2 1256 1257 1. Enum line 1 1258 1259 Enum line 2 1260 1261 - bullet item 2, line 1 1262 1263 bullet item 2, line 2 1264@end example 1265 1266@node Tables, Explicit Links, Lists, Markup Rules 1267@comment node-name, next, previous, up 1268@section Generation of data tables 1269@cindex tables 1270 1271@cindex tables, simple 1272Only very simple tables are supported. The syntax is as follows. 1273 1274@example 1275Double bars || Separate header fields 1276 1277Single bars | Separate body fields 1278Here are more | body fields 1279 1280Triple bars ||| Separate footer fields 1281@end example 1282 1283Some publishing styles require header fields to come first, then footer 1284fields, and then the body fields. You can use any order for these 1285sections that you like, and Muse will re-order them for you at 1286publish-time. 1287 1288If you wish to disable table generation for one Muse file, add the 1289directive @samp{#disable-tables t} to the top of the file. 1290 1291@subheading Other table formats 1292 1293@cindex tables, orgtbl-mode style 1294It is possible to publish very basic Orgtbl-mode style tables. 1295 1296@example 1297| org | style | table | 1298|------+-------+-------| 1299| one | | one | 1300| two | two | | 1301| | three | three | 1302|------+-------+-------| 1303| more | stuff | | 1304@end example 1305 1306If you are used to the way that Org Mode publishes these tables, then 1307customize `muse-html-table-attributes' to the following, in order to get 1308a similar kind of output. 1309 1310@example 1311border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides" 1312@end example 1313 1314@cindex tables, table.el style 1315@file{table.el} style tables are also supported, as long as 1316@file{table.el} itself supports outputting tables for a particular 1317publishing style. At the time of this writing, the ``html'', ``latex'', 1318and ``docbook'' styles are supported by @file{table.el}. Styles derived 1319from these styles will also work. 1320 1321@example 1322+---+-----+---+ 1323| | one | 1 | 1324+---+-----+---+ 1325| b | two | | 1326+---+-----+---+ 1327| c | | 3 | 1328+---+-----+---+ 1329@end example 1330 1331@node Explicit Links, Implicit Links, Tables, Markup Rules 1332@comment node-name, next, previous, up 1333@section Hyperlinks and email addresses with descriptions 1334@cindex links, explicit 1335 1336A hyperlink can reference a URL, or another page within a Muse 1337project. In addition, descriptive text can be specified, which should 1338be displayed rather than the link text in output styles that supports 1339link descriptions. The syntax is as follows. 1340 1341@example 1342[[link target][link description]] 1343[[link target without description]] 1344@end example 1345 1346Thus, the current maintainer's homepage for Muse can be found 1347@samp{[[http://mwolson.org/projects/EmacsMuse.html][here]]}, 1348or at @samp{[[http://mwolson.org/projects/EmacsMuse.html]]}. 1349 1350@node Implicit Links, Images, Explicit Links, Markup Rules 1351@comment node-name, next, previous, up 1352@section Bare URLs, WikiNames, and InterWiki links 1353@cindex links, implicit 1354@cindex links, raw 1355 1356@cindex URLs 1357@cindex Email addresses 1358 1359A URL or email address encountered in the input text is published as a 1360hyperlink. These kind of links are called @dfn{implicit links} because 1361they are not separated from the rest of the Muse document in any way. 1362 1363Some characters in URLs will prevent Muse from recognizing them as 1364implicit links. If you want to link to a URL containing spaces or any of 1365the characters ``][,"'`()<>^'', you will have to make the link 1366explicit. The punctuation characters ``.,;:'' are also not recognized as 1367part of a URL when they appear at its end. For information on how to 1368make an explicit link, see @ref{Explicit Links,,Hyperlinks and email 1369addresses with descriptions}. 1370 1371@cindex WikiNames 1372If the @command{muse-wiki} module is loaded, another form of implicit 1373link will be made available. WikiNames, which are typed in CamelCase, 1374are highlighted and published as links, provided that the file they 1375refer to exists. 1376 1377Customization of WikiName recognition may be accomplished by editing the 1378@code{muse-wiki-wikiword-regexp} option and subsequently running 1379@code{(muse-configure-highlighting 'muse-colors-markupmuse-colors-markup)}. 1380If you use the Customize interface, the latter will be done 1381automatically. 1382 1383@cindex InterWiki links 1384@cindex inter-project links 1385The @command{muse-wiki} module also allows for InterWiki links. These 1386are similar to WikiWords, but they specify both the project and page of 1387a file. The names of your project entries in @code{muse-project-alist} 1388will be used as InterWiki names by default. Several examples follow. 1389 1390@example 1391Blog::DocumentingMuse 1392Projects#EmacsMuse 1393Website 1394@end example 1395 1396In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is 1397the project name, and @samp{DocumentingMuse} is the page name. In the 1398second example, @samp{#} is the interwiki delimiter. If the name of a 1399project occurs by itself in text, like the third case, it will be 1400colorized and published as a link to the default page of the given 1401project. 1402 1403Customization of interwiki links may be accomplished by editing the 1404@code{muse-wiki-interwiki-alist} option. 1405 1406It is also possible to link to an anchor in an interwiki document. This 1407is called a ``three-part link''. Examples of this follow. 1408 1409@example 1410Blog::DocumentingMuse#anchor1 1411Projects#EmacsMuse#anchor2 1412@end example 1413 1414@node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules 1415@comment node-name, next, previous, up 1416@section Publishing and displaying images 1417@cindex images 1418@cindex links, with images 1419@subheading Image links 1420 1421Links to images may be used in either the target or the description, or 1422both. Thus, the following code will publish as a clickable image that 1423points to @url{http://mwolson.org/}. 1424 1425@example 1426[[http://mwolson.org/][/static/logos/site-logo.png]] 1427@end example 1428 1429Normally, images in the link part will be inlined. 1430 1431If you want these images to be published as links instead, place the 1432text ``URL:'' immediately in front of the link text. An example 1433follows. 1434 1435@example 1436[[URL:http://mwolson.org/static/logos/site-logo.png]] 1437@end example 1438 1439@cindex images, displaying 1440@cindex images, local 1441@subheading Displaying images in Muse mode 1442If a link to a locally-available image is encountered in the link 1443description, Muse mode will attempt to display it if your version of 1444Emacs permits this. 1445 1446This behavior may be toggled with @kbd{C-c C-i}, or disabled permanently 1447by setting the @code{muse-colors-inline-images} option to @code{nil}. 1448 1449The method for finding images may be altered by customizing the 1450@code{muse-colors-inline-image-method} option. One useful value for 1451this option is @code{muse-colors-use-publishing-directory}, which tells 1452Muse mode to look in the directory where the current file will be 1453published. The default is to look in the current directory. Relative 1454paths like @samp{../pics/} should work for either setting. 1455 1456Eventually, it is hoped that Muse will be able to copy images from the a 1457``source'' directory to a publishing directory by customizing 1458@code{muse-project-alist}, but this has not been implemented yet. 1459 1460@cindex images, without descriptions 1461@cindex images, inlined 1462@subheading Publishing simple images 1463The following example will display correctly and publish correctly if a 1464@acronym{PNG} file called @file{TestLogo.png} exists in the 1465@file{../pics/} directory. If text is on the same line as the picture, 1466it will remain so in the output. 1467 1468@example 1469[[../myimage.png]] 1470@end example 1471 1472@cindex images, captions 1473@subheading Publishing images with captions 1474If you want to add a caption to an image, use the following syntax. 1475This will center the image (if the output format supports it) and add a 1476centered caption below the picture. Formats that do not support 1477centering the image will instead leave it against the left margin. 1478 1479@example 1480[[../pics/mycat.png][My cat Dexter]] 1481@end example 1482 1483Images with captions may only occur in their own paragraphs, with no 1484text on the same line. Otherwise, the published output will not be 1485syntactically correct. 1486 1487@node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules 1488@comment node-name, next, previous, up 1489@section Inserting a horizontal line or anchor 1490 1491@cindex horizontal rules 1492@cindex dashes 1493@subheading Horizontal Rules 1494 1495Four or more dashes indicate a horizontal rule. Be sure to put blank 1496lines around it, or it will be considered part of the proceeding or 1497following paragraph! 1498 1499@cindex anchors 1500@cindex links, with target on same page 1501@subheading Anchors 1502 1503If you begin a line with "#anchor" -- where "anchor" can be any word 1504that doesn't contain whitespace -- it defines an anchor at that point 1505into the document. This point can be referenced using "page#anchor" as 1506the target in a Muse link. 1507 1508@node Embedded Lisp, Citations, Horizontal Rules and Anchors, Markup Rules 1509@comment node-name, next, previous, up 1510@section Evaluating Emacs Lisp code in documents for extensibility 1511@cindex lisp, embedded 1512 1513Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag. 1514With the @verb{|<lisp>|} tag, you may generate whatever output text you 1515wish. The inserted output will get marked up if the @verb{|<lisp>|} 1516tag appears within the main text of the document. 1517 1518@example 1519<lisp>(concat "This form gets " "inserted")</lisp> 1520@end example 1521 1522@cindex lisp, and insert command 1523Note that you should not use the @code{insert} command within a set of 1524@verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|} 1525tags will be automatically inserted into the document. 1526 1527It is also possible to treat the output as if it were surrounded by the 1528@verb{|<example>|}, @verb{|<src>|}, or @verb{|<verse>|} tags, by 1529specifying ``example'', ``src'', or ``verse'' as the @option{markup} 1530attribute of the @verb{|<lisp>|} tag. 1531 1532@example 1533<lisp markup="example"> 1534(concat "Insert" " me") 1535</lisp> 1536@end example 1537 1538Other languages also have tags that cause source code to be evaluated. 1539@xref{Tag Summary}, for details. 1540 1541@node Citations, Comments, Embedded Lisp, Markup Rules 1542@comment node-name, next, previous, up 1543@section Support for citing other resources 1544@cindex citations 1545@cindex tags, <cite> 1546 1547@subheading Example 1548 1549Here is an example of what citations look like in a Muse document. 1550 1551@example 1552#bibsource REFDB 1553 1554* Title 1555** Subtitle 1556 1557Some text before <cite>Miller1999</cite> and after the citation. 1558 1559This is an author-only citation <cite type="author">Miller1999</cite>. 1560 1561And this is a year-only citation <cite type="year">Miller1999</cite>. 1562 1563Finally, this is a multi-head citation 1564<cite>Miller1999,Andrews2005</cite>. 1565@end example 1566 1567@subheading Overview 1568 1569The @code{#bibsource} directive defines the source of the 1570bibliographies. The following sources are possible. 1571 1572@itemize @bullet 1573@item DocBook + RefDB: 1574the string "REFDB" 1575 1576@item LaTeX + bibtex: 1577the name of an appropriate bibtex file 1578 1579@item LaTeX + RefDB: 1580if the input file is called "foo.muse", then set this to "foo.bib" 1581@end itemize 1582 1583Citations are encoded as @verb{|<cite>|} elements which enclose the 1584citation keys as they are defined in the bibliography file or database. 1585In multi-head citations, the citation keys have to be separated by 1586colons or semicolons. The @code{latex} and @code{docbook} styles 1587translate these to the proper separator automatically. 1588 1589The @verb{|<cite>|} elements take an optional ``type'' attribute that 1590defines how the citation is rendered. If the attribute is missing, 1591you'll get a regular citation according to the bibliography style, 1592e.g.'' (Miller et al., 1999)''. If the attribute is set to "author", 1593only the name of the author(s) will be rendered. Accordingly, "year" 1594will cause the year to be printed. This is useful to create citations 1595like this: 1596 1597@example 1598Miller et al. had already shown in a previous publication (1999) that 1599this is not going to work. 1600@end example 1601 1602Remember that refdb-mode (the Emacs interface to RefDB) can retrieve 1603references by simply marking the citation key and running the 1604@code{refdb-getref-by-field-on-region} command. Later versions of 1605@code{refdb-mode} will also allow to insert references as Muse citations 1606(which is already implemented for DocBook, TEI, and LaTeX documents). 1607 1608You may have noticed that there is no element to indicate the position 1609of the bibliography. The latter is always created at a valid position 1610close to the end of the document. The functions 1611@code{muse-docbook-bibliography} and @code{muse-latex-bibliography} are 1612called in the header or footer to generate this content, so it is 1613possible to change the exact position. 1614 1615@node Comments, Tag Summary, Citations, Markup Rules 1616@comment node-name, next, previous, up 1617@section Lines to omit from published output 1618@cindex comments 1619@cindex publishing, omitting lines 1620 1621Use the following syntax to indicate a comment. Comments will not be 1622published. 1623 1624@example 1625; Comment text goes here. 1626@end example 1627 1628That is, only a semi-colon at the beginning of a line, followed by a 1629literal space, will cause that line to be treated as a comment. 1630 1631You can alternatively surround the region with the @verb{|<comment>|} 1632tag. 1633 1634If you wish the comment to be published, but just commented out using 1635the comment syntax of the output format, then set 1636@option{muse-publish-comments-p} to non-nil. 1637 1638@node Tag Summary, , Comments, Markup Rules 1639@comment node-name, next, previous, up 1640@section Tags that Muse recognizes 1641@cindex tags 1642@cindex inserting files at publish time 1643@cindex publishing, including markup in headers and footers 1644@cindex publishing, inserting files 1645 1646Muse has several built-in tags that may prove useful during publishing. 1647@xref{muse-publish-markup-tags}, to see how to customize the tags that 1648Muse uses, as well as make your own tags. 1649 1650Only a small subset of these tags are available in header and footer 1651text. The @code{muse-publish-markup-header-footer-tags} option lists 1652the tags that are allowed in headers and footers. 1653 1654@subheading Syntax 1655 1656If a tag takes arguments, it will look like this, where ``tagname'' is 1657the name of the tag. 1658 1659@example 1660<tagname arg1="string1" arg2="string2"> 1661@end example 1662 1663If you want the tag to look like it came straight from an XHTML 1664document, you can alternatively do the following. 1665 1666@example 1667<tagname arg1="string1" arg2="string2" /> 1668@end example 1669 1670If a tag surrounds some text, it will look like this. 1671 1672@example 1673<tagname>Some text</tagname> 1674@end example 1675 1676If a tag surrounds a large region, it will look like this. 1677 1678@example 1679<tagname> 1680Some text. 1681Some more text. 1682</tagname> 1683@end example 1684 1685@subheading Tag listing 1686 1687This is the complete list of tags that Muse accepts, including those 1688that were mentioned in previous sections. 1689 1690@table @samp 1691 1692@item <br> 1693Insert a line break. 1694 1695Muse will automatically detect paragraphs when publishing by means of 1696blank lines, so this tag is usually unnecessary. 1697 1698@item <cite> 1699Insert a citation to another source. 1700 1701This takes the argument @option{type}, which indicates the type of 1702citation. The valid types are "author" and "year". If this argument is 1703omitted, include both author and year in the citation. 1704 1705The bibliography to use for the citation may be specified by the 1706@option{#bibsource} directive. 1707 1708@xref{Citations}, for additional information. 1709 1710@item <class> 1711If publishing to HTML, surround the given text with a @verb{|<span>|} 1712tag. It takes one argument called ``name'' that specifies the ``class'' 1713attribute of the @verb{|<span>|} tag. 1714 1715If publishing to a different format, do nothing extra to the text. 1716 1717@item <code> 1718Treat the text surrounded by the tag as if they were enclosed in equal 1719signs, that is, make it monospace. 1720 1721@item <command> 1722Run a command on the region, replacing the region with the result of the 1723command. The command is specified with the ``interp'' argument. If no 1724value for ``interp'' is given, pass the entire region to the shell. 1725 1726The ``markup'' argument controls how this section is marked up. 1727 1728If it is omitted, publish the region with the normal Muse rules. 1729 1730If "nil", do not mark up the region at all, but prevent Muse from 1731further interpreting it. 1732 1733If "example", treat the region as if it was surrounded by the 1734@verb{|<example>|} tag. 1735 1736If "src", treat the included text as if it was surrounded by the 1737@verb{|<src>|} tag. You should also specify the ``lang'' attribute if 1738doing this. 1739 1740If "verse", treat the region as if it was surrounded by the 1741@verb{|<verse>|} tag, to preserve newlines. 1742 1743Otherwise, it should be the name of a function to call, with the buffer 1744narrowed to the region. 1745 1746@item <comment> 1747Treat the entire region as a comment. If the option 1748@var{muse-publish-comments-p} is nil, delete the region, otherwise 1749publish it using the comment syntax of the current publishing style. 1750 1751@item <contents> 1752Publish a Table of Contents. This will either be inserted in-place or 1753at the beginning of the document, depending on your publishing style. 1754It does not have a delimiting tag. 1755 1756By default, only 2 levels of headings will be included in the generated 1757Table of Contents. To change this globally, customize the 1758@var{muse-publish-contents-depth} option. To change this only for the 1759current tag, use the ``depth'' argument. 1760 1761@item <div> 1762Insert a <div> tag into HTML documents, and do not insert anything 1763special for other non-HTML publishing formats. 1764 1765If the ``style'' argument is provided, include it with the published 1766@verb{|<div>|} tag. Likewise for the ``id'' argument. 1767 1768@item <example> 1769Publish the region in monospace, preserving the newlines in the region. 1770This is useful for snippets of code. 1771 1772@item <include> 1773Insert the given file at the current location during publishing. The 1774basic use of this tag is as follows, replacing ``included_file'' with 1775the name of the file that you want to include. 1776 1777@example 1778<include file="included_file"> 1779@end example 1780 1781The ``markup'' argument controls how this section is marked up. 1782 1783If it is omitted, publish the included text with the normal Muse 1784rules. 1785 1786If "nil", do not mark up the included text at all. 1787 1788If "example", treat the included text as if it was surrounded by the 1789@verb{|<example>|} tag. 1790 1791If "src", treat the included text as if it was surrounded by the 1792@verb{|<src>|} tag. You should also specify the ``lang'' attribute if 1793doing this. 1794 1795If "verse", treat the included text as if it was surrounded by the 1796@verb{|<verse>|} tag, to preserve newlines. 1797 1798Otherwise, it should be the name of a function to call after inserting 1799the file with the buffer narrowed to the section inserted. 1800 1801@item <lisp> 1802Evaluate the Emacs Lisp expressions between the initial and ending tags. 1803The result is then inserted into the document, so you do not need to 1804explicitly call @code{insert}. All text properties are removed from the 1805resulting text. 1806 1807This tag takes the ``markup'' argument. See the description of 1808@verb{|<command>|} for details. 1809 1810@item <literal> 1811Make sure that the text enclosed by this tag is published without 1812escaping it in any way. This is useful for inserting markup directly 1813into the published document, when Muse does not provide the desired 1814functionality. 1815 1816@item <markup> 1817Mark up the text between the initial and ending tags. The markup 1818command to use may be specified by the ``function'' argument. The 1819standard Muse markup routines are used by default if no ``function'' 1820argument is provided. 1821 1822This is useful for marking up regions in headers and footers. One 1823example that comes to mind is generating a published index of all of the 1824files in the current project by doing the following. 1825 1826@example 1827<markup><lisp>(muse-index-as-string t t)</lisp></markup> 1828@end example 1829 1830@item <perl> 1831Run the @command{perl} language interpreter on the region, replacing the 1832region with the result of the command. 1833 1834This tag takes the ``markup'' argument. See the description of 1835@verb{|<command>|} for details. 1836 1837@item <python> 1838Run the @command{python} language interpreter on the region, replacing 1839the region with the result of the command. 1840 1841This tag takes the ``markup'' argument. See the description of 1842@verb{|<command>|} for details. 1843 1844@item <quote> 1845Publish the region as a blockquote. This will either be inserted 1846in-place or at the beginning of the document, depending on your 1847publishing style. It does not have a delimiting tag. 1848 1849@item <ruby> 1850Run the @command{ruby} language interpreter on the region, replacing the 1851region with the result of the command. 1852 1853This tag takes the ``markup'' argument. See the description of 1854@verb{|<command>|} for details. 1855 1856@item <src> 1857Publish the region using htmlize. 1858The language to use may be specified by the ``lang'' attribute. 1859 1860Muse will look for a function named @var{lang}-mode, where @var{lang} is 1861the value of the ``lang'' attribute. 1862 1863This tag requires htmlize 1.34 or later in order to work. If this is 1864not satisfied, or the current publishing style is not HTML-based, Muse 1865will publish the region like an @verb{|<example>|} tag. 1866 1867@item <verbatim> 1868This is used when you want to prevent Muse from trying to interpret some 1869markup. Surround the markup in @verb{|<verbatim>|} and 1870@verb{|</verbatim>|}, and it will not be interpreted. 1871 1872This tag was used often in previous versions of Muse because they did 1873not support whole-document escaping of specials. Now, it will only be 1874needed for other tags, and perhaps footnotes as well. 1875 1876@item <verse> 1877Preserve the newlines in the region. In formats like HTML, newlines are 1878removed by default, hence the need for this tag. In other publishing 1879styles, this tag may cause the text to be indented slightly in a way 1880that looks nice for poetry and prose. 1881 1882@end table 1883 1884@node Publishing Styles, Extending Muse, Markup Rules, Top 1885@comment node-name, next, previous, up 1886@chapter Publishing Various Types of Documents 1887@cindex publishing styles 1888 1889One of the principle features of Muse is the ability to publish a simple 1890input text to a variety of different output styles. Muse also makes it 1891easy to create new styles, or derive from an existing style. 1892 1893@menu 1894* Blosxom:: Integrating Muse and pyblosxom.cgi. 1895* Book:: Publishing entries into a compilation. 1896* ConTeXt:: Publishing ConTeXt documents. 1897* DocBook:: Publishing in DocBook XML form. 1898* HTML:: Publishing in HTML or XHTML form. 1899* Ikiwiki:: Integrating with ikiwiki. 1900* Journal:: Keeping a journal or blog. 1901* LaTeX:: Publishing LaTeX documents. 1902* Poem:: Publish a poem to LaTeX or PDF. 1903* Texinfo:: Publish entries to Texinfo format or PDF. 1904* XML:: Publish entries to XML. 1905@end menu 1906 1907@node Blosxom, Book, Publishing Styles, Publishing Styles 1908@comment node-name, next, previous, up 1909@section Integrating Muse and pyblosxom.cgi 1910@cindex blog, one-file-per-entry style 1911 1912The Blosxom publishing style publishes a tree of categorised files to a 1913mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi. 1914In other words, each blog entry corresponds with one file. 1915 1916@menu 1917* Blosxom Requirements:: Other tools needed for the Blosxom style. 1918* Blosxom Entries:: Format of a Blosxom entry and automation. 1919* Blosxom Options:: Blosxom styles and options provided. 1920@end menu 1921 1922@node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom 1923@comment node-name, next, previous, up 1924@subsection Other tools needed for the Blosxom style 1925 1926You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi} 1927installed on a machine that you have upload access to. 1928 1929The major difficulty in both of these programs is specifying the date of 1930the entries. Both programs rely on the file modification time rather 1931than any data contained in the entries themselves. A plugin is needed 1932in order for these programs to be able to get the correct date. 1933 1934@subheading PyBlosxom 1935 1936There are two different ways of accomplishing this in pyblosxom. The 1937first way involves gathering the timestamps (as specified by the 1938@code{#date} directive) into one file and then sending that file along 1939with published entries to the webserver. 1940 1941The second will read each file at render time and parse the 1942@code{#postdate} directive. Muse will translate the @code{#date} 1943directive into @code{#postdate} at publish time, so you don't have to do 1944any extra work. 1945 1946@subsubheading Placing timestamps in one file 1947 1948The following additional components are required in order to make the 1949date of blog entries display as something sensible. 1950 1951@enumerate 1952@item 1953A script to gather date directives from the entire blog tree into a 1954single file. The file must associate a blog entry with a date. 1955 1956@item 1957A plugin for (py)blosxom that reads this file. 1958@end enumerate 1959 1960These 2 things are provided for @command{pyblosxom.cgi} in the 1961@file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the 1962former service, while @file{hardcodedates.py} provides the latter 1963service. 1964 1965Here is a sample listing from my @file{timestamps} file, which maps 1966each file to a date. This can really be in any format, as long as your 1967date-gathering script and your plugin can both understand it. 1968 1969@example 19702005-04-01-14-16 personal/paper_cranes 19712005-03-21 personal/spring_break_over 19722004-10-24 personal/finished_free_culture 1973@end example 1974 1975The script @file{contrib/pyblosxom/make-blog} demonstrates how to call 1976@file{getstamps.py}. Note that you will need to set the current 1977directory to where your Muse files are, execute @file{getstamps.py}, and 1978then move the generated timestamps file to your publishing directory. 1979 1980@subsubheading Getting timestamp from entry while rendering 1981 1982Alternately, the pyblosxom metadate plugin may be used. On the plus 1983side, there is no need to run a script to gather the date. On the 1984downside, each entry is read twice rather than once when the page is 1985rendered. Set the value of @code{muse-blosxom-use-metadate} to non-nil 1986to enable adding a @code{#postdate} directive to all published files. 1987You can do this by: 1988 1989@example 1990M-x customize-variable RET muse-blosxom-use-metadate RET 1991@end example 1992 1993With the metadate plugin installed in pyblosxom, the date set in this 1994directive will be used instead of the file's modification time. The 1995plugin is included with Muse at @file{contrib/pyblosxom/metadate.py}. 1996 1997@subheading Blosxom 1998 1999It is also possible to use Blosxom, which is written in Perl, to serve 2000blog entries that were published with Muse. The steps are as follows. 2001 2002@enumerate 2003@item 2004Download and install blosxom from @url{http://blosxom.sourceforge.net/}. 2005 2006@item 2007Install the metadate plugin. It is available in 2008@file{contrib/blosxom/metadate_0_0_3}. 2009 2010@item 2011Every time you make a new blog entry, change to the blosxom data 2012directory and execute the @file{contrib/blosxom/getstamps.pl} script. 2013This script has only recently been made, and may still have some bugs, 2014so use with caution. 2015 2016@end enumerate 2017 2018@node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom 2019@comment node-name, next, previous, up 2020@subsection Format of a Blosxom entry and automation 2021 2022Each Blosxom file must include `#date yyyy-mm-dd', or optionally the 2023longer `#date yyyy-mm-dd-hh-mm', a title (using the @code{#title} 2024directive), plus whatever normal content is desired. 2025 2026The date directive is not used directly by @command{pyblosxom.cgi} or 2027this program. You need to have the two additional items from the former 2028section to make use of this feature. 2029 2030There is a function called @code{muse-blosxom-new-entry} that will 2031automate the process of making a new blog entry. To make use of it, do 2032the following. 2033 2034@itemize @bullet 2035@item 2036Customize @code{muse-blosxom-base-directory} to the location that your 2037blog entries are stored. 2038 2039@item 2040Assign the @code{muse-blosxom-new-entry} function to a key sequence. I 2041use the following code to assign this function to @kbd{C-c p l'}. 2042 2043@example 2044(global-set-key "\C-cpl" 'muse-blosxom-new-entry) 2045@end example 2046 2047@item 2048You should create your directory structure ahead of time under your base 2049directory. These directories, which correspond with category names, may 2050be nested. 2051 2052@item 2053When you enter this key sequence, you will be prompted for the category 2054of your entry and its title. Upon entering this information, a new file 2055will be created that corresponds with the title, but in lowercase 2056letters and having special characters converted to underscores. The 2057title and date directives will be inserted automatically. 2058@end itemize 2059 2060@node Blosxom Options, , Blosxom Entries, Blosxom 2061@comment node-name, next, previous, up 2062@subsection Blosxom styles and options provided 2063 2064The following styles and options are available in the Blosxom publishing 2065style. 2066 2067@subheading Styles provided 2068 2069@table @code 2070 2071@cindex publishing styles, blosxom-html 2072@item blosxom-html 2073Publish Blosxom entries in HTML form. 2074 2075@cindex publishing styles, blosxom-xhtml 2076@item blosxom-xhtml 2077Publish Blosxom entries in XHTML form. 2078 2079@end table 2080 2081@subheading Options provided 2082 2083@table @code 2084 2085@item muse-blosxom-extension 2086Default file extension for publishing Blosxom files. 2087 2088@item muse-blosxom-header 2089Header used for publishing Blosxom files. 2090 2091This may be text or a filename. 2092 2093@item muse-blosxom-footer 2094Footer used for publishing Blosxom files. 2095 2096This may be text or a filename. 2097 2098@item muse-blosxom-base-directory 2099Base directory of blog entries, used by @code{muse-blosxom-new-entry}. 2100 2101This is the top-level directory where your blog entries may be found 2102locally. 2103 2104@end table 2105 2106@node Book, ConTeXt, Blosxom, Publishing Styles 2107@comment node-name, next, previous, up 2108@section Publishing entries into a compilation 2109 2110This publishing style is used to output ``books'' in LaTeX or PDF 2111format. 2112 2113Each page will become a separate chapter in the book, unless the style 2114keyword @option{:nochapters} is used, in which case they are all run 2115together as if one giant chapter. 2116 2117One way of publishing a book is to make a project for it, add the 2118project to @code{muse-project-alist}, and use the @code{book-pdf} style 2119with a very specific @option{:include} value to specify some page whose 2120contents will be checked for the values of @code{#title} and 2121@code{#date}, and whose name will be used in the output file. Then to 2122publish the book, visit the aforementioned page and use @kbd{C-c C-t} or 2123@kbd{C-c C-p} to trigger the publishing process. An example 2124@code{muse-project-alist} for this method follows. 2125 2126@example 2127(setq muse-project-alist 2128 '(("MyNotes" (:nochapters t ; do automatically add chapters 2129 :book-chapter "Computer Science" 2130 "~/Notes/cs" 2131 :book-chapter "Mathematics" 2132 "~/Notes/math" 2133 :book-chapter "Emacs" 2134 "~/Notes/emacs" 2135 :book-end t ; the rest will not be placed in the book 2136 "~/Notes" ; so we can find the notes-anthology page 2137 "~/Notes/private" 2138 :force-publish ("index") 2139 :default "index") 2140 (:base "book-pdf" 2141 :include "/notes-anthology[^/]*$" 2142 :path "~/public_html/notes") 2143 ;; other publishing styles for each directory go here, 2144 ;; if desired 2145 ))) 2146@end example 2147 2148In this example, there would be a file called 2149@file{~/Notes/notes-anthology.muse}, which would contain just the 2150following. The resulting book would be published to 2151@file{~/public_html/notes/notes-anthology.pdf}. 2152 2153@example 2154#title My Technology Ramblings 2155@end example 2156 2157Another way is to call the @code{muse-book-publish-project} function 2158manually, with a custom project entry. An example of this may be found 2159in John Wiegley's configuration file at 2160@file{examples/johnw/muse-init.el}, in the @code{muse-publish-my-books} 2161function. 2162 2163@subheading Styles provided 2164 2165@table @code 2166 2167@cindex publishing styles, book-latex 2168@item book-latex 2169Publish a book in LaTeX form. The header and footer are different than 2170the normal LaTeX publishing mode. 2171 2172@cindex publishing styles, book-pdf 2173@item book-pdf 2174Publish a book in PDF form. The header and footer are different than 2175the normal PDF publishing mode. 2176 2177@end table 2178 2179@subheading Options provided 2180 2181@table @code 2182 2183@item muse-book-before-publish-hook 2184A hook run in the book buffer before it is marked up. 2185 2186@item muse-book-after-publish-hook 2187A hook run in the book buffer after it is marked up. 2188 2189@item muse-book-latex-header 2190Header used for publishing books to LaTeX. 2191 2192This may be text or a filename. 2193 2194@item muse-book-latex-footer 2195Footer used for publishing books to LaTeX. 2196 2197This may be text or a filename. 2198 2199@end table 2200@node ConTeXt, DocBook, Book, Publishing Styles 2201@comment node-name, next, previous, up 2202@section Publishing ConTeXt documents 2203 2204This publishing style is capable of producing ConTeXt or PDF documents. 2205 2206If you wish to publish PDF documents based on ConTeXt, you will need to 2207have it installed. For Debian and Ubuntu, this can be accomplished by 2208installing the ``texlive'' package. 2209 2210@subheading Styles provided 2211 2212@table @code 2213 2214@cindex publishing styles, context 2215@item context 2216Publish a ConTeXt document. 2217 2218@cindex publishing styles, context-pdf 2219@item context-pdf 2220Publish a PDF document, using an external ConTeXt document conversion 2221tool. 2222 2223@cindex publishing styles, context-slides 2224@item context-slides 2225Produce slides from a ConTeXt document. 2226 2227Here is an example of a slide. 2228 2229@example 2230* First Slide 2231 2232[[Some-sort-of-cute-image.png]] 2233 2234** A subheading 2235 2236 - A bullet point. 2237 - Another bullet point. 2238 2239* Second Slide 2240 2241... and so on 2242@end example 2243 2244@cindex publishing styles, context-slides-pdf 2245@item context-slides-pdf 2246Publish a PDF document of ConTeXt slides. 2247 2248@end table 2249 2250@subheading Options provided 2251 2252@table @code 2253 2254@item muse-context-extension 2255Default file extension for publishing ConTeXt files. 2256 2257@item muse-context-pdf-extension 2258Default file extension for publishing ConTeXt files to PDF. 2259 2260@item muse-context-pdf-program 2261The program that is called to generate PDF content from ConTeXt content. 2262 2263@item muse-context-pdf-cruft 2264Extensions of files to remove after generating PDF output successfully. 2265 2266@item muse-context-header 2267Header used for publishing ConTeXt files. 2268 2269This may be text or a filename. 2270 2271@item muse-context-footer 2272Footer used for publishing ConTeXt files. 2273 2274This may be text or a filename. 2275 2276@item muse-context-markup-regexps 2277List of markup regexps for identifying regions in a Muse page. 2278 2279For more on the structure of this list, 2280@xref{muse-publish-markup-regexps}. 2281 2282@item muse-context-markup-functions 2283An alist of style types to custom functions for that kind of text. 2284 2285For more on the structure of this list, 2286@xref{muse-publish-markup-functions}. 2287 2288@item muse-context-markup-strings 2289Strings used for marking up text. 2290 2291These cover the most basic kinds of markup, the handling of which 2292differs little between the various styles. 2293 2294@item muse-context-slides-header 2295Header for publishing a presentation (slides) using ConTeXt. 2296 2297Any of the predefined modules, which are available in the 2298tex/context/base directory, can be used by writing a "module" directive 2299at the top of the Muse file; if no such directive is provided, module 2300pre-01 is used. Alternatively, you can use your own style ("mystyle", 2301in this example) by replacing "\usemodule[]" with "\input mystyle". 2302 2303This may be text or a filename. 2304 2305@item muse-context-slides-markup-strings 2306Strings used for marking up text in ConTeXt slides. 2307 2308@item muse-context-markup-specials-document 2309A table of characters which must be represented specially. 2310These are applied to the entire document, sans already-escaped 2311regions. 2312 2313@item muse-context-markup-specials-example 2314A table of characters which must be represented specially. 2315These are applied to @verb{|example>|} regions. 2316 2317With the default interpretation of @verb{|<example>|} regions, no 2318specials need to be escaped. 2319 2320@item muse-context-markup-specials-literal 2321A table of characters which must be represented specially. 2322This applies to =monospaced text= and @verb{|<code>|} regions. 2323 2324@item muse-context-markup-specials-url 2325A table of characters which must be represented specially. 2326These are applied to URLs. 2327 2328@item muse-context-markup-specials-image 2329A table of characters which must be represented specially. 2330These are applied to image filenames. 2331 2332@item muse-context-permit-contents-tag 2333If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of 2334contents. 2335 2336Most of the time, it is best to have a table of contents on the 2337first page, with a new page immediately following. To make this 2338work with documents published in both HTML and ConTeXt, we need to 2339ignore the @verb{|<contents>|} tag. 2340 2341If you don't agree with this, then set this option to non-nil, 2342and it will do what you expect. 2343 2344@end table 2345 2346@node DocBook, HTML, ConTeXt, Publishing Styles 2347@comment node-name, next, previous, up 2348@section Publishing in DocBook XML form 2349 2350This publishing style is used to generate DocBook XML files. 2351 2352@subheading Styles provided 2353 2354@table @code 2355 2356@cindex publishing styles, docbook 2357@item docbook 2358Publish a file in Docbook form. 2359 2360@end table 2361 2362@subheading Options provided 2363 2364This publishing style uses the same options for markup up special 2365characters as the ``xml'' publishing style. @xref{XML}, for details. 2366 2367@table @code 2368 2369@item muse-docbook-extension 2370Default file extension for publishing DocBook XML files. 2371 2372@item muse-docbook-header 2373Header used for publishing DocBook XML files. 2374 2375This may be text or a filename. 2376 2377@item muse-docbook-footer 2378Footer used for publishing DocBook XML files. 2379 2380This may be text or a filename. 2381 2382@item muse-docbook-markup-regexps 2383List of markup rules for publishing a Muse page to DocBook XML. 2384 2385@item muse-docbook-markup-functions 2386An alist of style types to custom functions for that kind of text. 2387 2388@item muse-docbook-markup-strings 2389Strings used for marking up text. 2390 2391These cover the most basic kinds of markup, the handling of which 2392differs little between the various styles. 2393 2394@item muse-docbook-encoding-default 2395The default Emacs buffer encoding to use in published files. 2396This will be used if no special characters are found. 2397 2398@item muse-docbook-charset-default 2399The default DocBook XML charset to use if no translation is 2400found in @code{muse-xml-encoding-map}. 2401 2402@end table 2403 2404@node HTML, Ikiwiki, DocBook, Publishing Styles 2405@comment node-name, next, previous, up 2406@section Publishing in HTML or XHTML form 2407 2408This publishing style is capable of producing HTML or XHTML documents. 2409 2410@subheading Styles provided 2411 2412@table @code 2413 2414@cindex publishing styles, html 2415@item html 2416Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional. 2417 2418@item xhtml 2419Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional. 2420 2421@end table 2422 2423@subheading Options provided 2424 2425If an HTML option does not have a corresponding XHTML option, it will 2426be used for both of these publishing styles. 2427 2428These publishing styles use the same options for markup up special 2429characters as the ``xml'' publishing style. @xref{XML}, for details. 2430 2431@table @code 2432 2433@item muse-html-extension 2434Default file extension for publishing HTML files. 2435 2436@item muse-xhtml-extension 2437Default file extension for publishing XHTML files. 2438 2439@item muse-html-style-sheet 2440Store your stylesheet definitions here. 2441 2442This is used in @code{muse-html-header}. You can put raw CSS in here or 2443a @verb{|<link>|} tag to an external stylesheet. This text may contain 2444@verb{|<lisp>|} markup tags. 2445 2446If you are publishing to XHTML, then customize the 2447@code{muse-xhtml-style-sheet} option instead. 2448 2449@item muse-xhtml-style-sheet 2450Store your stylesheet definitions here. 2451 2452This is used in @code{muse-xhtml-header}. You can put raw CSS in here 2453or a @verb{|<link>|} tag to an external stylesheet. This text may 2454contain @verb{|<lisp>|} markup tags. 2455 2456@item muse-html-header 2457Header used for publishing HTML files. 2458 2459This may be text or a filename. 2460 2461@item muse-html-footer 2462Footer used for publishing HTML files. 2463 2464This may be text or a filename. 2465 2466@item muse-xhtml-header 2467Header used for publishing XHTML files. 2468 2469This may be text or a filename. 2470 2471@item muse-xhtml-footer 2472Footer used for publishing XHTML files. 2473 2474This may be text or a filename. 2475 2476@item muse-html-anchor-on-word 2477When true, anchors surround the closest word. 2478 2479This allows you to select them in a browser (i.e. for pasting), but has 2480the side-effect of marking up headers in multiple colors if your header 2481style is different from your link style. 2482 2483@item muse-html-table-attributes 2484The attribute to be used with HTML @verb{|<table>|} tags. 2485 2486If you want to make more-complicated tables in HTML, surround the HTML 2487with the @verb{|literal|} tag, so that it does not get escaped. 2488 2489@item muse-html-markup-regexps 2490List of markup rules for publishing a Muse page to HTML. 2491 2492@item muse-html-markup-functions 2493An alist of style types to custom functions for that kind of text. 2494 2495@item muse-html-markup-strings 2496Strings used for marking up text as HTML. 2497 2498These cover the most basic kinds of markup, the handling of which 2499differs little between the various styles. 2500 2501@item muse-xhtml-markup-strings 2502Strings used for marking up text as XHTML. 2503 2504These cover the most basic kinds of markup, the handling of which 2505differs little between the various styles. 2506 2507@item muse-html-markup-tags 2508A list of tag specifications, for specially marking up HTML. 2509@xref{muse-publish-markup-tags}, for more information. 2510 2511@item muse-html-meta-http-equiv 2512The http-equiv attribute used for the HTML @verb{|<meta>|} tag. 2513 2514@item muse-html-meta-content-type 2515The content type used for the HTML @verb{|<meta>|} tag. 2516 2517If you are striving for XHTML 1.1 compliance, you may want to change 2518this to ``application/xhtml+xml''. 2519 2520@item muse-html-meta-content-encoding 2521The charset to append to the HTML @verb{|<meta>|} tag. 2522 2523If set to the symbol 'detect, use @code{muse-xml-encoding-map} to try 2524and determine the HTML charset from emacs's coding. If set to a string, 2525this string will be used to force a particular charset. 2526 2527@item muse-html-charset-default 2528The default HTML meta charset to use if no translation is found in 2529@code{muse-xml-encoding-map}. 2530 2531@item muse-html-encoding-default 2532The default Emacs buffer encoding to use in published files. 2533This will be used if no special characters are found. 2534 2535@end table 2536 2537@node Ikiwiki, Journal, HTML, Publishing Styles 2538@comment node-name, next, previous, up 2539@section Integrating with ikiwiki 2540 2541Note: Support for Ikiwiki is not yet complete. Use at your own risk. 2542 2543Ikiwiki is a wiki compiler (@url{http://ikiwiki.info/}). Emacs Muse can 2544(not yet) be used as a source format for Ikiwiki pages with the plugin 2545@file{IkiWiki::Plugin::muse}. 2546 2547The @file{lisp/muse-ikiwiki.el} file provides publishing functions and 2548styles for Ikiwiki. The plugin for Ikiwiki to recognize Muse files is 2549provided by the @file{contrib/ikiwiki/IkiWiki/Plugin/muse.pm} file. Two 2550sample init files are available in the @file{examples/ikiwiki} 2551directory. Configure your @file{ikiwiki.setup} file so that the 2552@code{muse_init} variable has the location of your Muse init file. 2553 2554If you are using CGI, The directory @file{contrib/ikiwiki/IkiWiki} must 2555be copied to the same directory as the CGI script that Ikiwiki 2556generates. When publishing your wiki, the @var{PERL5LIB} environment 2557variable must contain the path to the @file{contrib/ikiwiki/IkiWiki} 2558directory. 2559 2560@subheading Styles provided 2561 2562@table @code 2563 2564@cindex publishing styles, ikiwiki 2565@item ikiwiki 2566Supports publishing XHTML output that Ikiwiki can understand. 2567 2568@end table 2569 2570@subheading Options provided 2571 2572@table @code 2573 2574@item muse-ikiwiki-header 2575Header used for publishing Ikiwiki output files. 2576 2577This may be text or a filename. 2578 2579@item muse-ikiwiki-footer 2580Footer used for publishing Ikiwiki output files. 2581 2582This may be text or a filename. 2583 2584@end table 2585 2586@subheading Other relevant options 2587 2588@table @code 2589 2590@item muse-colors-evaluate-lisp-tags 2591Specify whether to evaluate the contents of @verb{|<lisp>|} tags at 2592display time. If nil, don't evaluate them. If non-nil, evaluate 2593them. 2594 2595The actual contents of the buffer are not changed, only the 2596displayed text. 2597 2598@item muse-html-src-allowed-modes 2599Modes that we allow the @verb{|<src>|} tag to colorize. If @code{t}, 2600permit the @verb{|<src>|} tag to colorize any mode. 2601 2602If a list of mode names, such as @code{'("html" "latex")}, and the lang 2603argument to @verb{|<src>|} is not in the list, then use fundamental mode 2604instead. 2605 2606@item muse-publish-enable-dangerous-tags 2607If non-nil, publish tags like @verb{|<lisp>|} and @verb{|<command>|} 2608that can call external programs or expose sensitive information. 2609Otherwise, ignore tags like this. 2610 2611This is useful to set to @code{nil} when the file to publish is coming 2612from an untrusted source. 2613 2614@end table 2615 2616@node Journal, LaTeX, Ikiwiki, Publishing Styles 2617@comment node-name, next, previous, up 2618@section Keeping a journal or blog 2619@cindex journal 2620@cindex blog, journal style 2621 2622The module facilitates the keeping and publication of a journal. When 2623publishing to HTML, it assumes the form of a web log, or blog. 2624 2625The input format for each entry is as follows. 2626 2627@example 2628* 20040317: Title of entry 2629 2630text for the entry. 2631 2632<qotd> 2633"You know who you are. It comes down to a simple gut check: You 2634either love what you do or you don't. Period." -- P. Bronson 2635</qotd> 2636@end example 2637 2638The "qotd", or Quote of the Day, is entirely optional. When generated 2639to HTML, this entry is rendered as the following. 2640 2641@example 2642<div class="entry"> 2643 <div class="entry-qotd"> 2644 <h3>Quote of the Day:</h3> 2645 <p>"You know who you are. It comes down to a simple gut 2646 check: You either love what you do or you don't. Period." 2647 -- P. Bronson</p> 2648 </div> 2649 <div class="entry-body"> 2650 <div class="entry-head"> 2651 <div class="entry-date"> 2652 <span class="date">March 17, 2004</span> 2653 </div> 2654 <div class="entry-title"> 2655 <h2>Title of entry</h2> 2656 </div> 2657 </div> 2658 <div class="entry-text"> 2659 <p>Text for the entry.</p> 2660 </div> 2661 </div> 2662</div> 2663@end example 2664 2665The plurality of "div" tags makes it possible to display the entries in 2666any form you wish, using a CSS style. 2667 2668Also, an .RDF file can be generated from your journal by publishing it 2669with the "rdf" style. It uses the first two sentences of the first 2670paragraph of each entry as its "description", and auto-generates tags 2671for linking to the various entries. 2672 2673@subheading muse-project-alist considerations 2674 2675If you wish to publish an RDF or RSS feed, it is important to include 2676the @option{:base-url} attribute in your @code{muse-project-alist} entry 2677for your Journal projects. An example follows. 2678 2679@example 2680(setq muse-project-alist 2681 '(("Journal" ("~/Journal/" 2682 :default "journal") 2683 (:base "journal-rss" 2684 :base-url "http://example.org/journal/" 2685 :path "~/public_html/journal")))) 2686@end example 2687 2688@subheading Styles provided 2689 2690@table @code 2691 2692@cindex publishing styles, journal-html 2693@item journal-html 2694Publish journal entries as an HTML document. 2695 2696@cindex publishing styles, journal-xhtml 2697@item journal-xhtml 2698Publish journal entries as an XHTML document. 2699 2700@cindex publishing styles, journal-latex 2701@item journal-latex 2702Publish journal entries as a LaTeX document. 2703 2704@cindex publishing styles, journal-pdf 2705@item journal-pdf 2706Publish journal entries as a PDF document. 2707 2708@cindex publishing styles, journal-book-latex 2709@item journal-book-latex 2710Publish journal entries as a LaTeX book. 2711 2712@cindex publishing styles, journal-book-pdf 2713@item journal-book-pdf 2714Publish journal entries as a PDF book. 2715 2716@cindex publishing styles, journal-rdf 2717@cindex publishing styles, RSS 1.0 2718@item journal-rdf 2719Publish journal entries as an RDF file (RSS 1.0). 2720 2721@cindex publishing styles, journal-rss 2722@cindex publishing styles, RSS 2.0 2723@item journal-rss 2724Publish journal entries as an RSS file (RSS 2.0). 2725 2726@cindex publishing styles, journal-rss-entry 2727@item journal-rss-entry 2728Used internally by @code{journal-rss} and @code{journal-rdf} for 2729publishing individual entries. 2730 2731@end table 2732 2733@subheading Options provided 2734 2735@table @code 2736 2737@item muse-journal-heading-regexp 2738A regexp that matches a journal heading. 2739 2740Paren group 1 is the ISO date, group 2 is the optional category, and 2741group 3 is the optional heading for the entry. 2742 2743@item muse-journal-date-format 2744Date format to use for journal entries. 2745 2746@item muse-journal-html-heading-regexp 2747A regexp that matches a journal heading from an HTML document. 2748 2749Paren group 1 is the ISO date, group 2 is the optional category, and 2750group 3 is the optional heading for the entry. 2751 2752@item muse-journal-html-entry-template 2753Template used to publish individual journal entries as HTML. 2754 2755This may be text or a filename. 2756 2757@item muse-journal-latex-section 2758Template used to publish a LaTeX section. 2759 2760@item muse-journal-latex-subsection 2761Template used to publish a LaTeX subsection. 2762 2763@item muse-journal-markup-tags 2764A list of tag specifications, for specially marking up Journal entries. 2765 2766@xref{muse-publish-markup-tags}, for more information. 2767 2768This is used by @code{journal-latex} and its related styles, as well as 2769the @code{journal-rss-entry} style, which both @code{journal-rdf} and 2770@code{journal-rss} use. 2771 2772@item muse-journal-rdf-extension 2773Default file extension for publishing RDF (RSS 1.0) files. 2774 2775@item muse-journal-rdf-base-url 2776The base URL of the website referenced by the RDF file. 2777 2778@item muse-journal-rdf-header 2779Header used for publishing RDF (RSS 1.0) files. 2780 2781This may be text or a filename. 2782 2783@item muse-journal-rdf-footer 2784Footer used for publishing RDF (RSS 1.0) files. 2785 2786This may be text or a filename. 2787 2788@item muse-journal-rdf-date-format 2789Date format to use for RDF entries. 2790 2791@item muse-journal-rdf-entry-template 2792Template used to publish individual journal entries as RDF. 2793 2794This may be text or a filename. 2795 2796@item muse-journal-rdf-summarize-entries 2797If non-nil, include only summaries in the RDF file, not the full data. 2798 2799The default is nil, because this annoys some subscribers. 2800 2801@item muse-journal-rss-heading-regexp 2802A regexp that matches a journal heading from an HTML document. 2803 2804Paren group 1 is the ISO date, group 2 is the optional category, 2805and group 3 is the optional heading for the entry. 2806 2807@item muse-journal-rss-extension 2808Default file extension for publishing RSS 2.0 files. 2809 2810@item muse-journal-rss-base-url 2811The base URL of the website referenced by the RSS file. 2812 2813@item muse-journal-rss-header 2814Header used for publishing RSS 2.0 files. 2815 2816This may be text or a filename. 2817 2818@item muse-journal-rss-footer 2819Footer used for publishing RSS 2.0 files. 2820 2821This may be text or a filename. 2822 2823@item muse-journal-rss-date-format 2824Date format to use for RSS 2.0 entries. 2825 2826@item muse-journal-rss-entry-template 2827Template used to publish individual journal entries as RSS 2.0. 2828 2829This may be text or a filename. 2830 2831@item muse-journal-rss-enclosure-types-alist 2832File types that are accepted as RSS enclosures. 2833 2834This is an alist that maps file extension to content type. 2835 2836Useful for podcasting. 2837 2838@item muse-journal-rss-summarize-entries 2839If non-nil, include only summaries in the RSS file, not the full data. 2840 2841The default is nil, because this annoys some subscribers. 2842 2843@item muse-journal-rss-markup-regexps 2844List of markup rules for publishing a Muse journal page to RSS. 2845 2846For more information on the structure of this list, 2847@xref{muse-publish-markup-regexps}. 2848 2849@item muse-journal-rss-markup-functions 2850An alist of style types to custom functions for that kind of text. 2851 2852For more on the structure of this list, 2853@xref{muse-publish-markup-functions}. 2854 2855@end table 2856 2857@node LaTeX, Poem, Journal, Publishing Styles 2858@comment node-name, next, previous, up 2859@section Publishing LaTeX documents 2860 2861This publishing style is capable of producing LaTeX or PDF documents. 2862 2863If you wish to publish PDF documents, you will need to have a good LaTeX 2864installation. For Debian and Ubuntu, this can be accomplished by 2865installing the ``tetex-bin'' and ``tetex-extra'' packages. TeX fonts 2866are also a must. 2867 2868If your LaTeX installation has the file @file{grffile.sty}, which may be 2869found in the @file{texlive-latex-recommended} package for Debian and 2870Ubuntu, then consider using it by adding the following to your header 2871file. This allows spaces in filenames to work. 2872 2873@example 2874\usepackage@{grffile@} 2875@end example 2876 2877@subheading Styles provided 2878 2879@table @code 2880 2881@cindex publishing styles, latex 2882@item latex 2883Publish a LaTeX document. 2884 2885@cindex publishing styles, pdf 2886@item pdf 2887Publish a PDF document, using an external LaTeX document conversion 2888tool. 2889 2890@cindex publishing styles, latexcjk 2891@item latexcjk 2892Publish a LaTeX document with CJK (Chinese) encodings. 2893 2894@cindex publishing styles, pdfcjk 2895@item pdfcjk 2896Publish a PDF document with CJK (Chinese) encodings, using an external 2897LaTeX document conversion tool. 2898 2899@cindex publishing styles, slides 2900@item slides 2901Publish a LaTeX document that uses the Beamer extension. This is 2902suitable for producing slides. 2903 2904Here is an example of a slide. 2905 2906@example 2907<slide title="First Slide"> 2908Everything between the slide tags composes this slide. 2909 2910[[Some-sort-of-cute-image.png]] 2911 2912 - A bullet point. 2913 - Another bullet point. 2914</slide> 2915@end example 2916 2917@cindex publishing styles, slides-pdf 2918@item slides-pdf 2919Publish a PDF document of slides, using the Beamer extension. 2920 2921@cindex publishing styles, lecture-notes 2922@item lecture-notes 2923Publish a LaTeX document that uses the Beamer extension. This is 2924suitable for producing lecture notes. 2925 2926This can also use the @verb{|<slide>|} tag. 2927 2928@cindex publishing styles, lecture-notes-pdf 2929@item lecture-notes-pdf 2930Publish a PDF document of lecture notes, using the Beamer extension. 2931 2932@end table 2933 2934@subheading Options provided 2935 2936@table @code 2937 2938@item muse-latex-extension 2939Default file extension for publishing LaTeX files. 2940 2941@item muse-latex-pdf-extension 2942Default file extension for publishing LaTeX files to PDF. 2943 2944@item muse-latex-pdf-browser 2945The program to use when browsing a published PDF file. 2946 2947This should be a format string. 2948 2949@item muse-latex-pdf-program 2950The program that is called to generate PDF content from LaTeX content. 2951 2952@item muse-latex-pdf-cruft 2953Extensions of files to remove after generating PDF output successfully. 2954 2955@item muse-latex-header 2956Header used for publishing LaTeX files. 2957 2958This may be text or a filename. 2959 2960@item muse-latex-footer 2961Footer used for publishing LaTeX files. 2962 2963This may be text or a filename. 2964 2965@item muse-latexcjk-header 2966Header used for publishing LaTeX files (CJK). 2967 2968This may be text or a filename. 2969 2970@item muse-latexcjk-footer 2971Footer used for publishing LaTeX files (CJK). 2972 2973This may be text or a filename. 2974 2975@item muse-latex-slides-header 2976Header for publishing of slides using LaTeX. 2977 2978This may be text or a filename. 2979 2980You must have the Beamer extension for LaTeX installed for this to work. 2981 2982@item muse-latex-lecture-notes-header 2983Header publishing of lecture notes using LaTeX. 2984 2985This may be text or a filename. 2986 2987You must have the Beamer extension for LaTeX installed for this to work. 2988 2989@item muse-latex-markup-regexps 2990List of markup regexps for identifying regions in a Muse page. 2991 2992For more on the structure of this list, 2993@xref{muse-publish-markup-regexps}. 2994 2995@item muse-latex-markup-functions 2996An alist of style types to custom functions for that kind of text. 2997 2998For more on the structure of this list, 2999@xref{muse-publish-markup-functions}. 3000 3001@item muse-latex-markup-strings 3002Strings used for marking up text. 3003 3004These cover the most basic kinds of markup, the handling of which 3005differs little between the various styles. 3006 3007@item muse-latex-slides-markup-tags 3008A list of tag specifications, for specially marking up LaTeX slides. 3009 3010@item muse-latexcjk-encoding-map 3011An alist mapping emacs coding systems to appropriate CJK codings. 3012Use the base name of the coding system (ie, without the -unix). 3013 3014@item muse-latexcjk-encoding-default 3015The default Emacs buffer encoding to use in published files. 3016 3017This will be used if no special characters are found. 3018 3019@item muse-latex-markup-specials-document 3020A table of characters which must be represented specially. 3021These are applied to the entire document, sans already-escaped 3022regions. 3023 3024@item muse-latex-markup-specials-example 3025A table of characters which must be represented specially. 3026These are applied to @verb{|example>|} regions. 3027 3028With the default interpretation of @verb{|<example>|} regions, no 3029specials need to be escaped. 3030 3031@item muse-latex-markup-specials-literal 3032A table of characters which must be represented specially. 3033This applies to =monospaced text= and @verb{|<code>|} regions. 3034 3035@item muse-latex-markup-specials-url 3036A table of characters which must be represented specially. 3037These are applied to URLs. 3038 3039@item muse-latex-markup-specials-image 3040A table of characters which must be represented specially. 3041These are applied to image filenames. 3042 3043@item muse-latex-permit-contents-tag 3044If nil, ignore @verb{|<contents>|} tags. Otherwise, insert table of 3045contents. 3046 3047Most of the time, it is best to have a table of contents on the 3048first page, with a new page immediately following. To make this 3049work with documents published in both HTML and LaTeX, we need to 3050ignore the @verb{|<contents>|} tag. 3051 3052If you don't agree with this, then set this option to non-nil, 3053and it will do what you expect. 3054 3055@end table 3056 3057@node Poem, Texinfo, LaTeX, Publishing Styles 3058@comment node-name, next, previous, up 3059@section Publish a poem to LaTeX or PDF 3060 3061The @code{muse-poem} module makes it easy to attractively publish and 3062reference poems in the following format, using the "memoir" module for 3063LaTeX publishing. It will also markup poems for every other output 3064style, though none are nearly as pretty. 3065 3066@example 3067Title 3068 3069 3070Body of poem 3071 3072 3073Annotations, history, notes, etc. 3074@end example 3075 3076Once a poem is written in this format, just publish it to PDF using the 3077@code{poem-pdf} style. To make an inlined reference to a poem that 3078you've written -- for example, from a blog page -- there is a "poem" tag 3079defined by this module. 3080 3081@example 3082<poem title="name.of.poem.page"> 3083@end example 3084 3085Let's assume the template above was called @file{name.of.poem.page}; 3086then the above tag would result in this inclusion. 3087 3088@example 3089** Title 3090 3091> Body of poem 3092@end example 3093 3094John Wiegley uses this module for publishing all of the poems on his 3095website, which are at 3096@uref{http://www.newartisans.com/johnw/poems.html}. 3097 3098@subheading Styles provided 3099 3100@table @code 3101 3102@cindex publishing styles, poem-latex 3103@item poem-latex 3104Publish a poem in LaTeX form. 3105 3106@cindex publishing styles, poem-pdf 3107@item poem-pdf 3108Publish a poem to a PDF document. 3109 3110@cindex publishing styles, chapbook-latex 3111@item chapbook-latex 3112Publish a book of poems in LaTeX form. 3113 3114@cindex publishing styles, chapbook-pdf 3115@item chapbook-pdf 3116Publish a book of poems to a PDF document. 3117 3118@end table 3119 3120@subheading Options provided 3121 3122@table @code 3123 3124@item muse-poem-latex-header 3125Header used for publishing LaTeX poems. 3126 3127This may be text or a filename. 3128 3129@item muse-poem-latex-footer 3130Footer used for publishing LaTeX files. 3131 3132This may be text or a filename. 3133 3134@item muse-poem-markup-strings 3135Strings used for marking up poems. 3136 3137These cover the most basic kinds of markup, the handling of which 3138differs little between the various styles. 3139 3140@item muse-chapbook-latex-header 3141Header used for publishing a book of poems in LaTeX form. 3142 3143This may be text or a filename. 3144 3145@item muse-chapbook-latex-footer 3146Footer used for publishing a book of poems in LaTeX form. 3147 3148This may be text or a filename. 3149 3150@item muse-poem-chapbook-strings 3151Strings used for marking up books of poems. 3152 3153These cover the most basic kinds of markup, the handling of which 3154differs little between the various styles. 3155 3156@end table 3157 3158@node Texinfo, XML, Poem, Publishing Styles 3159@comment node-name, next, previous, up 3160@section Publish entries to Texinfo format or PDF 3161 3162Rules for publishing a Muse file as a Texinfo article. 3163 3164@subheading Styles provided 3165 3166@table @code 3167 3168@cindex publishing styles, texi 3169@item texi 3170Publish a file in Texinfo form. 3171 3172@cindex publishing styles, texi 3173@item info 3174Generate an Info file from a Muse file. 3175 3176@cindex publishing styles, info-pdf 3177@item info-pdf 3178Publish a file in PDF form. 3179 3180@end table 3181 3182@subheading Options provided 3183 3184@table @code 3185 3186@item muse-texinfo-process-natively 3187If non-nil, use the Emacs `texinfmt' module to make Info files. 3188 3189@item muse-texinfo-extension 3190Default file extension for publishing Texinfo files. 3191 3192@item muse-texinfo-info-extension 3193Default file extension for publishing Info files. 3194 3195@item muse-texinfo-pdf-extension 3196Default file extension for publishing PDF files. 3197 3198@item muse-texinfo-header 3199Text to prepend to a Muse page being published as Texinfo. 3200 3201This may be text or a filename. 3202It may contain @verb{|<lisp>|} markup tags. 3203 3204@item muse-texinfo-footer 3205Text to append to a Muse page being published as Texinfo. 3206 3207This may be text or a filename. 3208It may contain @verb{|<lisp>|} markup tags. 3209 3210@item muse-texinfo-markup-regexps 3211List of markup rules for publishing a Muse page to Texinfo. 3212 3213For more on the structure of this list, 3214@xref{muse-publish-markup-regexps}. 3215 3216@item muse-texinfo-markup-functions 3217An alist of style types to custom functions for that kind of text. 3218 3219For more on the structure of this list, 3220@xref{muse-publish-markup-functions}. 3221 3222@item muse-texinfo-markup-strings 3223Strings used for marking up text. 3224 3225These cover the most basic kinds of markup, the handling of which 3226differs little between the various styles. 3227 3228@item muse-texinfo-markup-specials 3229A table of characters which must be represented specially. 3230 3231@item muse-texinfo-markup-specials 3232A table of characters which must be represented specially. 3233These are applied to URLs. 3234 3235@end table 3236 3237@node XML, , Texinfo, Publishing Styles 3238@comment node-name, next, previous, up 3239@section Publish entries to XML 3240 3241Muse is capable of publishing XML documents, with the help of the 3242@file{muse-xml.el} module. 3243 3244A RelaxNG schema is available as part of the Muse distribution in the 3245@file{etc/muse.rnc} file. 3246 3247@subheading Styles provided 3248 3249@table @code 3250 3251@cindex publishing styles, xml 3252@item xml 3253Publish a file in XML form. 3254 3255@end table 3256 3257@subheading Options provided 3258 3259@table @code 3260 3261@cindex muse-xml-encoding-map 3262@item muse-xml-encoding-map 3263An alist mapping Emacs coding systems to appropriate XML charsets. 3264Use the base name of the coding system (i.e. without the -unix). 3265 3266@item muse-xml-markup-specials 3267A table of characters which must be represented specially in all 3268XML-like markup formats. 3269 3270@item muse-xml-markup-specials-url-extra 3271A table of characters which must be represented specially in all 3272XML-like markup formats. 3273 3274These are extra characters that are escaped within URLs. 3275 3276@item muse-xml-extension 3277Default file extension used for publishing XML files. 3278 3279@item muse-xml-header 3280Header used for publishing XML files. 3281 3282This may be text or a filename. 3283 3284@item muse-xml-footer 3285Footer used for publishing XML files. 3286 3287This may be text or a filename. 3288 3289@item muse-xml-markup-regexps 3290List of markup rules for publishing a Muse page to XML. 3291 3292For more on the structure of this list, 3293@xref{muse-publish-markup-regexps}. 3294 3295@item muse-xml-markup-functions 3296An alist of style types to custom functions for that kind of text. 3297 3298For more on the structure of this list, 3299@xref{muse-publish-markup-functions}. 3300 3301@item muse-xml-markup-strings 3302Strings used for marking up text. 3303 3304These cover the most basic kinds of markup, the handling of which 3305differs little between the various styles. 3306 3307@item muse-xml-encoding-default 3308The default Emacs buffer encoding to use in published files. 3309 3310This will be used if no special characters are found. 3311 3312@item muse-xml-charset-default 3313The default XML charset to use if no translation is found in 3314@code{muse-xml-encoding-map}. 3315 3316@end table 3317 3318 3319@node Extending Muse, Miscellaneous, Publishing Styles, Top 3320@comment node-name, next, previous, up 3321@chapter Making your own publishing styles 3322 3323@menu 3324* Markup Functions:: Specifying functions to mark up text. 3325* Markup Regexps:: Markup rules for publishing. 3326* Markup Strings:: Strings specific to a publishing style. 3327* Markup Tags:: Tag specifications for special markup. 3328* Style Elements:: Parameters used for defining styles. 3329* Deriving Styles:: Deriving a new style from an existing 3330 one. 3331@end menu 3332 3333@node Markup Functions, Markup Regexps, , Extending Muse 3334@comment node-name, next, previous, up 3335@section Specifying functions to mark up text 3336@cindex publishing, markup functions 3337 3338@anchor{muse-publish-markup-functions} 3339@code{muse-publish-markup-functions} 3340 3341An alist of style types to custom functions for that kind of text. 3342 3343This is used by publishing styles to attempt to minimize the amount of 3344custom regexps that each has to define. @file{muse-publish} provides 3345rules for the most common types of markup. 3346 3347Each member of the list is of the following form. 3348 3349@example 3350(SYMBOL FUNCTION) 3351@end example 3352 3353@itemize @bullet 3354@item SYMBOL 3355Describes the type of text to associate with this rule. 3356@code{muse-publish-markup-regexps} maps regexps to these symbols. 3357 3358@item FUNCTION 3359Function to use to mark up this kind of rule if no suitable function is 3360found through the @option{:functions} tag of the current style. 3361@end itemize 3362 3363@node Markup Regexps, Markup Strings, Markup Functions, Extending Muse 3364@comment node-name, next, previous, up 3365@section Markup rules for publishing 3366@cindex publishing, markup regexps 3367@cindex publishing, rules 3368 3369@anchor{muse-publish-markup-regexps} 3370@code{muse-publish-markup-regexps} 3371 3372List of markup rules for publishing a page with Muse. 3373 3374The rules given in this variable are invoked first, followed by whatever 3375rules are specified by the current style. 3376 3377Each member of the list is either a function, or a list of the following 3378form. 3379 3380@example 3381(REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL) 3382@end example 3383 3384@itemize @bullet 3385@item REGEXP 3386A regular expression, or symbol whose value is a regular expression, 3387which is searched for using `re-search-forward'. 3388 3389@item TEXT-BEGIN-GROUP 3390The matching group within that regexp which denotes the beginning of the 3391actual text to be marked up. 3392 3393@item REPLACEMENT-TEXT 3394A string that will be passed to `replace-match'. 3395 3396If it is not a string, but a function, it will be called to determine 3397what the replacement text should be (it must return a string). If it is 3398a symbol, the value of that symbol should be a string. 3399@end itemize 3400 3401The replacements are done in order, one rule at a time. Writing 3402the regular expressions can be a tricky business. Note that case 3403is never ignored. `case-fold-search' is always bound to nil 3404while processing the markup rules. 3405 3406@subheading Publishing order 3407 3408This is the order that the publishing rules are consulted, by default. 3409This may be changed by customizing @code{muse-publish-markup-regexps}. 3410 3411@table @code 3412 3413@item trailing and leading whitespace 3414Remove trailing and leading whitespace from a file. 3415 3416@item directive 3417@samp{#directive} 3418 3419This is only recognized at the beginning of a file. 3420 3421@item comment 3422@samp{; a commented line} 3423 3424@item tag 3425@samp{<tag>} 3426 3427@item comment 3428@samp{; comment} 3429 3430@item explicit links 3431Prevent emphasis characters in explicit links from being marked up. 3432 3433Don't actually publish them here, just add a special no-emphasis text 3434property. 3435 3436@item word 3437Whitespace-delimited word, possibly with emphasis characters 3438 3439This function is responsible for marking up emphasis and escaping some 3440specials. 3441 3442@item heading 3443@samp{** Heading} 3444 3445Outline-mode style headings. 3446 3447@item enddots 3448@samp{....} 3449 3450These are ellipses with a dot at end. 3451 3452@item dots 3453@samp{...} 3454 3455Ellipses. 3456 3457@item rule 3458@samp{----} 3459 3460Horizontal rule or section separator. 3461 3462@item no-break-space 3463@samp{~~} 3464 3465Prevent lines from being split before or after these characters. 3466 3467@item line-break 3468@samp{<br>} 3469 3470Break a line at point. 3471 3472@item fn-sep 3473@samp{Footnotes:} 3474 3475Beginning of footnotes section. 3476 3477@item footnote 3478@samp{[1]} 3479 3480Footnote definition or reference. If at beginning of line, it is a 3481definition. 3482 3483@item list 3484@itemize @bullet 3485@item 3486@samp{ 1. } 3487 3488@item 3489@samp{ - } 3490 3491@item 3492@samp{term :: } 3493@end itemize 3494 3495Numbered list, item list, or term definition list. 3496 3497@item table-el 3498 3499@file{table.el} style tables 3500 3501@item table 3502@samp{table | cells} 3503 3504Muse tables or orgtbl-mode style tables. 3505 3506@item quote 3507spaces before beginning of text 3508 3509Blockquotes. 3510 3511@item emdash 3512@samp{--} 3513 35142-wide dash 3515 3516@item verse 3517@samp{> verse text} 3518 3519@item anchor 3520@samp{#anchor} 3521 3522@item link 3523@samp{[[explicit][links]]} 3524 3525@item url 3526@samp{http://example.com/} 3527 3528@item email 3529@samp{bare-email@@example.com} 3530 3531@end table 3532 3533@node Markup Strings, Markup Tags, Markup Regexps, Extending Muse 3534@comment node-name, next, previous, up 3535@section Strings specific to a publishing style 3536@cindex publishing, markup strings 3537 3538@dfn{Markup strings} are strings used for marking up text for a 3539particular style. 3540 3541These cover the most basic kinds of markup, the handling of which 3542differs little between the various styles. 3543 3544@subheading Available markup strings 3545 3546@table @code 3547 3548@item image-with-desc 3549An image and a description. 3550 3551Argument 1: image without extension. Argument 2: image extension. 3552Argument 3: description. 3553 3554@item image 3555An inlined image. 3556 3557Argument 1: image without extension. Argument 2: image extension. 3558 3559@item image-link 3560An image with a link around it. 3561 3562Argument 1: link. Argument 2: image without extension. 3563Argument 3: image extension. 3564 3565@item anchor-ref 3566A reference to an anchor on the current page. 3567 3568Argument 1: anchor name. Argument 2: description if one exists, or the 3569original link otherwise. 3570 3571@item url 3572A URL without a description. 3573 3574Argument 1: URL. 3575 3576@item link 3577A link to a Muse page with a description. 3578 3579Argument 1: link. Argument 2: description if one exists, or the 3580original link otherwise. 3581 3582@item link-and-anchor 3583A link to a Muse page with an anchor, and a description. 3584 3585Argument 1: link. Argument 2: anchor name. 3586Argument 3: description if one exists, or the original link otherwise. 3587Argument 4: link without an extension. 3588 3589@item email-addr 3590A link to an email address. 3591 3592Argument 1: email address. Argument 2: email address. 3593 3594@item anchor 3595An anchor. 3596 3597Argument 1: name of anchor. 3598 3599@item emdash 3600A 2-length dash. 3601 3602Argument 1: Initial whitespace. Argument 2: Terminating whitespace. 3603 3604@item comment-begin 3605Beginning of a comment. 3606 3607@item comment-end 3608End of a comment. 3609 3610@item rule 3611A horizontal line or space. 3612 3613@item no-break-space 3614A space that separates two words which are not to be separated. 3615 3616@item footnote 3617Beginning of footnote. 3618 3619@item footnote-end 3620End of footnote. 3621 3622@item footnotemark 3623Mark a reference for the current footnote. 3624 3625Argument 1: number of this footnote. 3626 3627@item footnotemark-end 3628End of a reference for the current footnote. 3629 3630@item footnotetext 3631Indicate the text of the current footnote. 3632 3633Argument 1: number of this footnote. 3634 3635@item footnotetext-end 3636End of a footnote text line. 3637 3638@item fn-sep 3639Text used to replace ``Footnotes:'' line. 3640 3641@item dots 36423 dots. 3643 3644@item enddots 36454 dots. 3646 3647@item part 3648Beginning of a part indicator line. This is used by book publishing. 3649 3650@item part-end 3651End of a part indicator line. This is used by book publishing. 3652 3653@item chapter 3654Beginning of a chapter indicator line. This is used by book publishing. 3655 3656@item chapter-end 3657End of a chapter indicator line. This is used by book publishing. 3658 3659@item section 3660Beginning of level 1 section indicator line. 3661 3662Argument 1: level of section; always 1. 3663 3664@item section-end 3665End of level 1 section indicator line. 3666 3667Argument 1: level of section; always 1. 3668 3669@item subsection 3670Beginning of level 2 section indicator line. 3671 3672Argument 1: level of section; always 2. 3673 3674@item subsection-end 3675End of level 2 section indicator line. 3676 3677Argument 1: level of section; always 2. 3678 3679@item subsubsection 3680Beginning of level 3 section indicator line. 3681 3682Argument 1: level of section; always 3. 3683 3684@item subsubsection-end 3685End of level 3 section indicator line. 3686 3687Argument 1: level of section; always 3. 3688 3689@item section-other 3690Beginning of section indicator line, where level is greater than 3. 3691 3692Argument 1: level of section. 3693 3694@item section-other-end 3695End of section indicator line, where level is greater than 3. 3696 3697Argument 1: level of section. 3698 3699@item begin-underline 3700Beginning of underlined text. 3701 3702@item end-underline 3703End of underlined text. 3704 3705@item begin-literal 3706Beginning of verbatim text. This includes @verb{|<code>|} tags and 3707=teletype text=. 3708 3709@item end-literal 3710End of verbatim text. This includes @verb{|<code>|} tags and =teletype 3711text=. 3712 3713@item begin-emph 3714Beginning of the first level of emphasized text. 3715 3716@item end-emph 3717End of the first level of emphasized text. 3718 3719@item begin-more-emph 3720Beginning of the second level of emphasized text. 3721 3722@item end-more-emph 3723End of the second level of emphasized text. 3724 3725@item begin-most-emph 3726Beginning of the third (and final) level of emphasized text. 3727 3728@item end-most-emph 3729End of the third (and final) level of emphasized text. 3730 3731@item begin-verse 3732Beginning of verse text. 3733 3734@item verse-space 3735String used to each space that is further indented than the beginning of 3736the verse. 3737 3738@item begin-verse-line 3739Beginning of a line of verse. 3740 3741@item empty-verse-line 3742End of a line of verse. 3743 3744@item begin-last-stanza-line 3745Beginning of the last line of a verse stanza. 3746 3747@item end-last-stanza-line 3748End of the last line of a verse stanza. 3749 3750@item end-verse 3751End of verse text. 3752 3753@item begin-example 3754Beginning of an example region. To make use of this, an 3755@samp{<example>} tag is needed. 3756 3757@item end-example 3758End of an example region. To make use of this, an @samp{</example>} tag 3759is needed. 3760 3761@item begin-center 3762Begin a centered line. 3763 3764@item end-center 3765End a centered line. 3766 3767@item begin-quote 3768Begin a quoted region. 3769 3770@item end-quote 3771End a quoted region. 3772 3773@item begin-quote-item 3774Begin a quote paragraph. 3775 3776@item end-quote-item 3777End a quote paragraph. 3778 3779@item begin-uli 3780Begin an unordered list. 3781 3782@item end-uli 3783End an unordered list. 3784 3785@item begin-uli-item 3786Begin an unordered list item. 3787 3788@item end-uli-item 3789End an unordered list item. 3790 3791@item begin-oli 3792Begin an ordered list. 3793 3794@item end-oli 3795End an ordered list. 3796 3797@item begin-oli-item 3798Begin an ordered list item. 3799 3800@item end-oli-item 3801End an ordered list item. 3802 3803@item begin-dl 3804Begin a definition list. 3805 3806@item end-dl 3807End a definition list. 3808 3809@item begin-dl-item 3810Begin a definition list item. 3811 3812@item end-dl-item 3813End a definition list item. 3814 3815@item begin-ddt 3816Begin a definition list term. 3817 3818@item end-ddt 3819End a definition list term. 3820 3821@item begin-dde 3822Begin a definition list entry. 3823 3824@item end-dde 3825End a definition list entry. 3826 3827@item begin-table 3828Begin a table. 3829 3830@item end-table 3831End a table. 3832 3833@item begin-table-group 3834Begin a table grouping. 3835 3836@item end-table-group 3837End a table grouping. 3838 3839@item begin-table-row 3840Begin a table row. 3841 3842@item end-table-row 3843End a table row. 3844 3845@item begin-table-entry 3846Begin a table entry. 3847 3848@item end-table-entry 3849End a table entry. 3850 3851@end table 3852 3853@node Markup Tags, Style Elements, Markup Strings, Extending Muse 3854@comment node-name, next, previous, up 3855@section Tag specifications for special markup 3856@cindex publishing, markup tags 3857 3858@anchor{muse-publish-markup-tags} 3859@code{muse-publish-markup-tags} 3860 3861A list of tag specifications, for specially marking up text. 3862 3863XML-style tags are the best way to add custom markup to Muse. This is 3864easily accomplished by customizing this list of markup tags. 3865 3866For each entry, the name of the tag is given, whether it expects a 3867closing tag and/or an optional set of attributes, whether it is 3868nestable, and a function that performs whatever action is desired within 3869the delimited region. 3870 3871The tags themselves are deleted during publishing, before the function 3872is called. The function is called with three arguments, the beginning 3873and end of the region surrounded by the tags. If properties are 3874allowed, they are passed as a third argument in the form of an alist. 3875The `end' argument to the function is always a marker. 3876 3877Point is always at the beginning of the region within the tags, when the 3878function is called. Wherever point is when the function finishes is 3879where tag markup will resume. 3880 3881These tag rules are processed once at the beginning of markup, and once 3882at the end, to catch any tags which may have been inserted in-between. 3883 3884@node Style Elements, Deriving Styles, Markup Tags, Extending Muse 3885@comment node-name, next, previous, up 3886@section Parameters used for defining styles 3887@cindex publishing, style elements 3888 3889Style elements are tags that define a style. Use either 3890@code{muse-define-style} or @code{muse-derive-style} 3891(@pxref{Deriving Styles}) to create a new style. 3892 3893@defun muse-define-style name &rest elements 3894@end defun 3895 3896@subheading Usable elements 3897 3898@table @option 3899 3900@item :suffix 3901File extension to use for publishing files with this style. 3902 3903@item :link-suffix 3904File extension to use for publishing links to Muse files with this 3905style. 3906 3907@item :osuffix 3908File extension to use for publishing second-stage files with this style. 3909 3910For example, PDF publishing generates a LaTeX file first, then a PDF 3911from that LaTeX file. 3912 3913@item :regexps 3914List of markup rules for publishing a page with Muse. 3915@xref{muse-publish-markup-regexps}. 3916 3917@item :functions 3918An alist of style types to custom functions for that kind of text. 3919@xref{muse-publish-markup-functions}. 3920 3921@item :strings 3922Strings used for marking up text with this style. 3923 3924These cover the most basic kinds of markup, the handling of which 3925differs little between the various styles. 3926 3927@item :tags 3928A list of tag specifications, used for handling extra tags. 3929@xref{muse-publish-markup-tags}. 3930 3931@item :specials 3932A table of characters which must be represented specially. 3933 3934@item :before 3935A function that is to be executed on the newly-created publishing buffer 3936(or the current region) before any publishing occurs. 3937 3938This is used to set extra parameters that direct the publishing process. 3939 3940@item :before-end 3941A function that is to be executed on the publishing buffer (or the 3942current region) immediately after applying all of the markup regexps. 3943 3944This is used to fix the order of table elements (header, footer, body) 3945in XML-ish styles. 3946 3947@item :after 3948A function that is to be executed on the publishing buffer after 3949:before-end, and immediately after inserting the header and footer. 3950 3951This is used for generating the table of contents as well as setting the 3952file coding system. 3953 3954@item :final 3955A function that is to be executed after saving the published file, but 3956while still in its buffer. 3957 3958This is used for generating second-stage documents like PDF files from 3959just-published LaTeX files. 3960 3961The function must accept three arguments: the name of the muse source 3962file, the name of the just-published file, and the name of the 3963second-stage target file. The name of the second-stage target file is 3964the same as that of the just-published file if no second-stage 3965publishing is required. 3966 3967@item :header 3968Header used for publishing files of this style. 3969 3970This may be a variable, text, or a filename. It is inserted at the 3971beginning of a file, after evaluating the publishing markup. 3972 3973@item :footer 3974Footer used for publishing files of this style. 3975 3976This may be a variable, text, or a filename. It is inserted at the end 3977of a file, after evaluating the publishing markup. 3978 3979@item :style-sheet 3980Style sheet used for publishing files of this style. 3981 3982This may be a variable or text. It is used in the header of HTML and 3983XHTML based publishing styles. 3984 3985@item :browser 3986The function used to browse the published result of files of this style. 3987 3988@end table 3989 3990@node Deriving Styles, , Style Elements, Extending Muse 3991@comment node-name, next, previous, up 3992@section Deriving a new style from an existing one 3993@cindex publishing styles, deriving 3994 3995To create a new style from an existing one, use @code{muse-derive-style} 3996as follows. This is a good way to fix something you don't like about a 3997particular publishing style, or to personalize it. 3998 3999@defun muse-derive-style new-name base-name &rest elements 4000@end defun 4001 4002The derived name is a string defining the new style, such as "my-html". 4003The base name must identify an existing style, such as "html" -- if you 4004have loaded @file{muse-html}. The style parameters are the same as 4005those used to create a style, except that they override whatever 4006definitions exist in the base style. However, some definitions only 4007partially override. The following parameters support partial 4008overriding. 4009 4010@xref{Style Elements}, for a complete list of all parameters. 4011 4012@table @option 4013 4014@item :functions 4015If a markup function is not found in the derived style's function list, 4016the base style's function list will be queried. 4017 4018@item :regexps 4019All regexps in the current style and the base style(s) will be used. 4020 4021@item :strings 4022If a markup string is not found in the derived style's string list, the 4023base style's string list will be queried. 4024 4025@end table 4026 4027@node Miscellaneous, Getting Help and Reporting Bugs, Extending Muse, Top 4028@comment node-name, next, previous, up 4029@chapter Miscellaneous add-ons, like a minor mode 4030 4031@menu 4032* Muse List Edit Minor Mode:: Edit lists easily in other major modes. 4033@end menu 4034 4035@node Muse List Edit Minor Mode, , , Miscellaneous 4036@comment node-name, next, previous, up 4037@section Edit lists easily in other major modes 4038@cindex muse-list-edit-minor-mode 4039 4040@code{muse-list-edit-minor-mode} is meant to be used with other major 4041modes, such as Message (for composing email) and debian-changelog-mode 4042(for editing debian/changelog files). 4043 4044It implements practically perfect support for editing and filling lists. 4045It can even handle nested lists. In addition to Muse-specific list 4046items ("-", numbers, definition lists, footnotes), it can also handle 4047items that begin with "*" or "+". Filling list items behaves in the 4048same way that it does in Muse, regardless of whether filladapt is also 4049enabled, which is the primary reason to use this tool. 4050 4051@subheading Installation 4052 4053To use it, add ``(require 'muse-mode)'' to your Emacs customization file 4054and add the function @code{turn-on-muse-list-edit-minor-mode} to any 4055mode hooks where you wish to enable this minor mode. 4056 4057@subheading Keybindings 4058 4059@code{muse-list-edit-minor-mode} uses the following keybindings. 4060 4061@table @kbd 4062 4063@item M-RET (`muse-l-e-m-m-insert-list-item') 4064Insert a new list item at point, using the indentation level of the 4065current list item. 4066 4067@item C-< (`muse-l-e-m-m-decrease-list-item-indent') 4068Decrease indentation of the current list item. 4069 4070@item C-> (`muse-l-e-m-m-increase-list-item-indent') 4071Increase indentation of the current list item. 4072 4073@end table 4074 4075@subheading Functions 4076 4077@defun muse-list-edit-minor-mode 4078This is a global minor mode for editing files with lists. 4079It is meant to be used with other major modes, and not with Muse mode. 4080 4081Interactively, with no prefix argument, toggle the mode. 4082With universal prefix @var{arg} turn mode on. 4083With zero or negative @var{arg} turn mode off. 4084 4085This minor mode provides the Muse keybindings for editing lists, 4086and support for filling lists properly. 4087 4088It recognizes not only Muse-style lists, which use the "-" 4089character or numbers, but also lists that use asterisks or plus 4090signs. This should make the minor mode generally useful. 4091 4092Definition lists and footnotes are also recognized. 4093 4094Note that list items may omit leading spaces, for compatibility 4095with modes that set @code{left-margin}, such as 4096@code{debian-changelog-mode}. 4097@end defun 4098 4099@defun turn-on-muse-list-edit-minor-mode 4100Unconditionally turn on Muse list edit minor mode. 4101@end defun 4102 4103@defun turn-off-muse-list-edit-minor-mode 4104Unconditionally turn off Muse list edit minor mode. 4105@end defun 4106 4107@node Getting Help and Reporting Bugs, History, Miscellaneous, Top 4108@comment node-name, next, previous, up 4109@chapter Getting Help and Reporting Bugs 4110@cindex help, getting 4111@cindex bugs, reporting 4112 4113After you have read this guide, if you still have questions about 4114Muse, or if you have bugs to report, there are several places you can 4115go. 4116 4117@itemize @bullet 4118 4119@item 4120@uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsMuse} is the 4121emacswiki.org page, and anyone may add tips, hints, or bug descriptions 4122to it. 4123 4124@item 4125@uref{http://mwolson.org/projects/EmacsMuse.html} is the web page 4126that Michael Olson (the current maintainer) made for Muse. 4127 4128@item 4129Muse has several different mailing lists. 4130 4131@table @samp 4132 4133@item muse-el-announce 4134Low-traffic list for Muse-related announcements. 4135 4136You can join this mailing list (@email{muse-el-announce@@gna.org}) 4137using the subscription form at 4138@url{http://mail.gna.org/listinfo/muse-el-announce/}. This 4139mailing list is also available via Gmane (@url{http://gmane.org/}). The 4140group is called @samp{gmane.emacs.muse.announce}. 4141 4142@item muse-el-discuss 4143Discussion, bugfixes, suggestions, tips, and the like for Muse. 4144This mailing list also includes the content of muse-el-announce. 4145 4146You can join this mailing list (@email{muse-el-discuss@@gna.org}) 4147using the subscription form at 4148@url{http://mail.gna.org/listinfo/muse-el-discuss/}. This mailing 4149list is also available via Gmane with the identifier 4150@samp{gmane.emacs.muse.general}. 4151 4152@item muse-el-logs 4153Log messages for commits made to Muse. 4154 4155You can join this mailing list (@email{muse-el-logs@@gna.org}) using 4156the subscription form at 4157@url{http://mail.gna.org/listinfo/muse-el-logs/}. This mailing list 4158is also available via Gmane with the identifier 4159@samp{gmane.emacs.muse.scm}. 4160 4161@item muse-el-commits 4162Generated bug reports for Emacs Muse. If you use our bug-tracker at 4163@url{https://gna.org/bugs/?group=muse-el}, the bug reports will be 4164sent to this list automatically. 4165 4166You can join this mailing list (@email{muse-el-commits@@gna.org}) using 4167the subscription form at 4168@url{http://mail.gna.org/listinfo/muse-el-commits/}. This mailing list 4169is also available via Gmane with the identifier 4170@samp{gmane.emacs.muse.cvs}. 4171 4172@item muse-el-internationalization 4173Discussion of translation of the Muse website and documentation into 4174many languages. 4175 4176You can join this mailing list 4177(@email{muse-el-internationalization@@gna.org}) using the subscription 4178form at @url{http://mail.gna.org/listinfo/internationalization/}. This 4179mailing list is also available via Gmane with the identifier 4180@samp{gmane.emacs.muse.internationalization}. 4181 4182@end table 4183 4184@item 4185You can visit the IRC Freenode channel @samp{#emacs}. Many of the 4186contributors are frequently around and willing to answer your 4187questions. The @samp{#muse} channel is also available for 4188Muse-specific help, and its current maintainer hangs out there. 4189 4190@item 4191The maintainer of Emacs Muse, Michael Olson, may be contacted at 4192@email{mwolson@@gnu.org}. He can be rather slow at answering email, so 4193it is often better to use the muse-el-discuss mailing list. 4194 4195@end itemize 4196 4197@node History, Contributors, Getting Help and Reporting Bugs, Top 4198@comment node-name, next, previous, up 4199@chapter History of This Document 4200@cindex history, of Muse 4201 4202@itemize 4203@item 2004 4204John Wiegley started Muse upon realizing that EmacsWiki had some serious 4205limitations. Around February 2004, he started making "emacs-wiki version 42063.00 APLHA", which eventually became known as Muse. 4207 4208Most of those who frequent the emacs-wiki mailing list continued to use 4209emacs-wiki, mainly because Planner hasn't been ported over to it. 4210 4211As of 2004-12-01, Michael Olson became the maintainer of Muse, as per 4212John Wiegley's request. 4213 4214@item 2005 4215Michael Olson overhauled this document and added many new sections in 4216preparation for the first release of Muse (3.01). 4217 4218@end itemize 4219 4220@node Contributors, GNU Free Documentation License, History, Top 4221@comment node-name, next, previous, up 4222@chapter Contributors to This Documentation 4223@cindex contributors 4224 4225The first draft of this document was taken from the emacs-wiki texinfo 4226manual. Michael Olson adapted it for Muse and added most of its 4227content. 4228 4229John Sullivan did a majority of the work on the emacs-wiki texinfo 4230manual. 4231 4232While Sacha Chua maintained emacs-wiki, she worked quite a bit on the 4233emacs-wiki texinfo manual. 4234 4235 4236@node GNU Free Documentation License, Concept Index, Contributors, Top 4237@appendix GNU Free Documentation License 4238@include doclicense.texi 4239 4240 4241@node Concept Index, , GNU Free Documentation License, Top 4242@comment node-name, next, previous, up 4243@unnumbered Index 4244 4245@printindex cp 4246 4247@bye 4248