1#author John Wiegley and Michael Olson 2#title The Emacs Muse 3 4Emacs Muse is an authoring and publishing environment for Emacs. It 5simplifies the process of writing documents and publishing them to 6various output formats. 7 8Muse consists of two main parts: an enhanced text-mode for authoring 9documents and navigating within Muse projects, and a set of publishing 10styles for generating different kinds of output. 11 12<contents> 13 14* About this document 15 16This document provides an example of Muse markup and also functions as 17a quickstart for Muse. 18 19To see what it looks like when published, type =make examples=. You 20will then get an Info document, an HTML document, and a PDF document 21(provided you have an implementation of LaTeX installed with the 22necessary fonts). 23 24* Getting Started 25 26To use Muse, add the directory containing its files to your 27=load-path= variable, in your =.emacs= file. Then, load in the 28authoring mode, and the styles you wish to publish to. For example: 29 30<example> 31(add-to-list 'load-path "<path to Muse>") 32 33(require 'muse-mode) ; load authoring mode 34 35(require 'muse-html) ; load publishing styles I use 36(require 'muse-latex) 37(require 'muse-texinfo) 38(require 'muse-docbook) 39 40(require 'muse-project) ; publish files in projects 41</example> 42 43Once loaded, the command =M-x muse-publish-this-file= will publish an 44input document to any available style. If you enable =muse-mode= 45within a buffer, by typing =M-x muse-mode=, this command will be bound 46to =C-c C-t=. 47 48* Creating a Muse project 49 50Often you will want to publish all the files within a directory to a 51particular set of output styles automatically. To support, Muse 52allows for the creations of "projects". Here is a sample project, to 53be defined in your =.emacs= file: 54 55<example> 56(setq muse-project-alist 57 '(("website" ("~/Pages" :default "index") 58 (:base "html" :path "~/public_html") 59 (:base "pdf" :path "~/public_html/pdf")))) 60</example> 61 62The above defines a project named "website", whose files are located 63in the directory =~/Pages=. The default page to visit is =index=. 64When this project is published, each page will be output as HTML to 65the directory =~/public_html=, and as PDF to the directory 66=~/public_html/pdf=. Within any project page, you may create a link 67to other pages using the syntax =[[pagename]]=. 68 69* Markup rules 70 71A Muse document uses special, contextual markup rules to determine how 72to format the output result. For example, if a paragraph is indented, 73Muse assumes it should be quoted. 74 75There are not too many markup rules, and all of them strive to be as 76simple as possible so that you can focus on document creation, rather 77than formatting. 78 79** Paragraphs 80 81Separate paragraphs in Muse must be separate by a blank line. 82 83For example, the input text used for this section is: 84 85<example> 86Separate paragraphs in Muse must be separate by a blank line. 87 88For example, the input text used for this section is: 89</example> 90 91** Centered paragraphs and quotations 92 93A line that begins with six or more columns of whitespace (either tabs 94or spaces) indicates a centered paragraph. 95 96 This is centered 97 98 But if a line begins with whitespace, though less than six columns, 99 it indicates a quoted paragraph. 100 101** Headings 102 103A heading becomes a chapter or section in printed output -- depending 104on the style. To indicate a heading, start a new paragraph with one 105to three asterices, followed by a space and the heading title. Then 106begin another paragraph to enter the text for that section. 107 108<example> 109* First level 110 111** Second level 112 113*** Third level 114</example> 115 116** Horizontal rules 117 118Four or more dashes indicate a horizontal rule. Be sure to put blank 119lines around it, or it will be considered part of the proceeding or 120following paragraph! 121 122---- 123 124The separator above was produced by typing: 125 126<example> 127---- 128</example> 129 130** Emphasizing text 131 132To emphasize text, surround it with certain specially recognized 133characters: 134 135<example> 136*emphasis* 137**strong emphasis** 138***very strong emphasis*** 139_underlined_ 140=verbatim and monospace= 141</example> 142 143The above list renders as: 144 145<verse> 146*emphasis* 147**strong emphasis** 148***very strong emphasis*** 149_underlined_ 150=verbatim and monospace= 151</verse> 152 153** Adding footnotes 154 155A footnote reference is simply a number in square 156brackets<verbatim>[1]</verbatim>.[1] To define the footnote, place 157this definition at the bottom of your file. =footnote-mode= can be 158used to greatly facilitate the creation of these kinds of footnotes. 159 160<example> 161 Footnotes: 162 [1] Footnotes are defined by the same number in brackets 163 occurring at the beginning of a line. Use footnote-mode's 164 C-c ! a command, to very easily insert footnotes while 165 typing. Use C-x C-x to return to the point of insertion. 166</example> 167 168** Verse 169 170Poetry requires that whitespace be preserved, but without resorting to 171monospace. To indicate this, use the following markup, reminiscent of 172e-mail quotations: 173 174<example> 175> A line of Emacs verse; 176> forgive its being so terse. 177</example> 178 179The above is rendered as: 180 181> A line of Emacs verse; 182> forgive its being so terse. 183 184You can also use the =<literal><verse></literal>= tag, if you prefer: 185 186<example> 187<verse> 188A line of Emacs verse; 189 forgive its being so terse. 190</verse> 191</example> 192 193** Literal paragraphs 194 195The =<literal><example></literal>= tag is used for examples, where 196whitespace should be preserved, the text rendered in monospace, and 197any characters special to the output style escaped. 198 199There is also the =<literal><literal></literal>= tag, which causes a 200marked block to be entirely left alone. This can be used for 201inserting a hand-coded HTML blocks into HTML output, for example. 202 203If you want some text to only be inserted when publishing to a 204particular format, use the =style= attribute for the 205=<literal><literal></literal>= tag. Some examples follow. 206 207<example> 208You are reading the 209<literal style="html">HTML</literal> 210<literal style="pdf">PDF</literal> 211<literal style="info">Info</literal> 212version of this document. 213</example> 214 215Produces: 216 217You are reading the 218<literal style="html">HTML</literal> 219<literal style="pdf">PDF</literal> 220<literal style="info">Info</literal> 221version of this document. 222 223<example> 224<literal style="latex"> 225LaTeX was used in the publishing of this document. 226</literal> 227</example> 228 229Produces: 230 231<literal style="latex"> 232LaTeX was used in the publishing of this document. 233</literal> 234 235** Lists 236 237Lists are given using special characters at the beginning of a line. 238Whitespace must occur before bullets or numbered items, to distinguish 239from the possibility of those characters occurring in a real sentence. 240 241The supported kinds of lists are: 242 243<example> 244 - bullet item one 245 - bullet item two 246 247 1. Enumerated item one 248 2. Enumerated item two 249 250Term1 :: A definition one 251 252Term2 :: A definition two 253</example> 254 255These are rendered as a bullet list: 256 257 - bullet item one 258 - bullet item two 259 260An enumerated list: 261 262 1. Enum item one 263 2. Enum item two 264 265And a definition list: 266 267Term1 :: 268 This is a first definition 269 And it has two lines; 270 no, make that three. 271 272Term2 :: 273 This is a second definition 274 275Lists may be nested inside of one another. The level of nesting is 276determined by the amount of leading whitespace. 277 278<example> 279 - Level 1, bullet item one 280 1. Level 2, enum item one 281 2. Level 2, enum item two 282 - Level 1, bullet item two 283</example> 284 285This is rendered as: 286 287 - Level 1, bullet item one 288 1. Level 2, enum item one 289 2. Level 2, enum item two 290 - Level 1, bullet item two 291 292** Tables 293 294Simple tables are supported. The syntax is: 295 296<example> 297 Double bars || Separate header fields 298 299 Single bars | Separate body fields 300 Here are more | body fields 301 302 Triple bars ||| Separate footer fields 303</example> 304 305The above is rendered as: 306 307Double bars || Separate header fields 308 309Single bars | Separate body fields 310Here are more | body fields 311 312Triple bars ||| Separate footer fields 313 314<comment> 315Double bars || Separate header fields 316 317Single bars | Separate body fields 318Here are more | body fields 319 320Triple bars ||| Separate footer fields 321</comment> 322 323It is also possible to make tables that look like: 324 325<example> 326| Single bars | Separate body fields | 327| Here are more | body fields | 328</example> 329 330This publishes as: 331 332| Single bars | Separate body fields | 333| Here are more | body fields | 334 335If you are familiar with Org-mode style tables, simple variants (no 336column groups or autogenerated formulas) will publish fine. Also, 337table.el style tables will be published, provided that the output 338format is something that table.el supports. 339 340** Anchors and tagged links 341 342#example If you begin a line with "#anchor" -- where "anchor" can be 343any word that doesn't contain whitespace -- it defines an anchor at 344that point into the document. This point can be referenced using 345"page#anchor" as the target in a Muse link (see below). 346 347Click [[#example][here]] to go back to the previous paragraph. 348 349** URLs and E-mail addresses 350 351A URL or e-mail address encountered in the input text is published as 352a hyperlink if the output style supports it. For example, the latest 353Muse source can be downloaded at http://download.gna.org/muse-el and 354mail may be sent to mwolson@gnu.org. 355 356** Images 357 358If a URL has an extension of a known image format, it will be inlined 359if possible. To create a link to an image, rather than inlining it, 360put the text "URL:" immediately in front of the link. 361 362This is an inlined image example: 363 364<example> 365Made with [[muse-made-with.png]] Emacs Muse. 366</example> 367 368This publishes as: 369 370Made with [[muse-made-with.png]] Emacs Muse. 371 372Here is an example of a captioned image: 373 374<example> 375[[emacs-muse.png][Emacs Muse, the publishing choice of (a subset of) Great Thinkers]] 376</example> 377 378This publishes as: 379 380[[emacs-muse.png][Emacs Muse, the publishing choice of (a subset of) Great Thinkers]] 381 382The following will be published as a link only. 383 384<example> 385The Muse logo: [[URL:http://mwolson.org/static/logos/emacs-muse.png]]. 386</example> 387 388The Muse logo: [[URL:http://mwolson.org/static/logos/emacs-muse.png]]. 389 390** Links 391 392A hyperlink can reference a URL, or another page within a Muse 393project. In addition, descriptive text can be specified, which should 394be displayed rather than the link text in output styles that supports 395link descriptions. The syntax is: 396 397<example> 398[[link target][link description]] 399[[link target without description]] 400</example> 401 402Thus, the text: 403 404<example> 405Muse can be downloaded [[http://download.gna.org/muse-el/][here]], or at 406[[http://download.gna.org/muse-el/]]. 407</example> 408 409Publishes as: 410 411Muse can be downloaded [[http://download.gna.org/muse-el/][here]], or at 412[[http://download.gna.org/muse-el/]]. 413 414** Source code 415 416If you have htmlize.el version 1.34 or later installed, you can 417publish colorized HTML for source code in any major mode that Emacs 418supports by using the =<literal><src></literal>= tag. If not publishing 419to HTML, the text between the tags will be treated like an 420=<literal><example></literal>= tag. 421 422Here is some example C code. Muse takes the =lang= element and appends 423="-mode"= to it in order to determine which major mode to use when 424colorizing the code. 425 426<example> 427<src lang="c"> 428#include <stdlib.h> 429 430char *unused; 431 432int main (int argc, char *argv[]) 433{ 434 puts("Hello, world!\n"); 435} 436</src> 437</example> 438 439Here is the colorized output. This may look different if you have 440customized some faces. Also, it may look different depending on 441whether you are publishing from Emacs on the console, or Emacs on X -- 442what you see when viewing (in this case) a C file is what you get. 443 444<src lang="c"> 445#include <stdlib.h> 446 447char *unused; 448 449int main (int argc, char *argv[]) 450{ 451 puts("Hello, world!\n"); 452} 453</src> 454 455** Embedded Lisp, Perl, Ruby, Python, or Shell 456 457Arbitrary kinds of markup can be achieved using the 458=<literal><lisp></literal>= tag, which is the only Muse tag supported 459in a style's header and footer text. With the 460=<literal><lisp></literal>= tag, you may generated whatever output 461text you wish. The inserted output will get marked up, if the 462=<literal><lisp></literal>= tag appears within the main text of the 463document. 464 465<example> 466<lisp>(concat "This form gets " "inserted")</lisp> 467</example> 468 469The above renders as: <lisp>(concat "This form gets " "inserted")</lisp>. 470 471It is also possible to treat the output as if it were surrounded by 472the =<literal><example></literal>=, =<literal><src></literal>=, or 473=<literal><verse></literal>= tags, by specifying ="example"=, ="src"=, or 474="verse"= as the =markup= attribute of the tag. 475 476For example: 477 478<example> 479<lisp markup="example"> 480(concat "Insert" " me") 481</lisp> 482</example> 483 484The output is: 485 486<lisp markup="example"> 487(concat "Insert" " me") 488</lisp> 489 490This =markup= attribute can also be passed to the 491=<literal><perl></literal>=, =<literal><ruby></literal>=, 492=<literal><python></literal>=, and =<literal><command></literal>= tags, 493which interpret Perl, Ruby, Python, and Shell code, respectively. 494 495* Publishing styles 496 497One of the principle features of Muse is the ability to publish a 498simple input text to a variety of different output styles. Muse also 499makes it easy to create new styles, or derive from an existing style. 500 501** Deriving from an existing style 502 503To create a new style from an existing one, use =muse-derive-style=: 504 505<example> 506(muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS) 507</example> 508 509The derived name is a string defining the new style, such as 510"my-html". The base name must identify an existing style, such as 511"html" -- if you have loaded =muse-html=. The style parameters are the 512same as those used to create a style, except that they override 513whatever definitions exist in the base style. 514 515Most often, this will come in handy for using a custom header, footer, 516and/or stylesheet for a project. Here is one such example. 517 518<example> 519(setq my-different-style-sheet 520 (concat "<link rel=\"stylesheet\" type=\"text/css\"" 521 " charset=\"utf-8\" media=\"all\"" 522 " href=\"/different.css\" />")) 523 524(muse-derive-style "my-xhtml" "xhtml" 525 :header "~/.emacs.d/muse/different-header.html" 526 :footer "~/.emacs.d/muse/different-footer.html" 527 :style-sheet my-different-style-sheet) 528</example> 529 530Many parameters support being partially overridden. As an example: 531with =:functions=, if a markup function is not found in the derived 532style's function list, the base style's function list will be queried. 533 534If a parameter takes the name of a function, then returning non-nil 535from that function causes no further processing to be done. If the 536function returns nil, any other functions in the base style will be 537called. 538 539** Creating a new style 540 541To create a new style, use =muse-define-style=: 542 543<example> 544(muse-define-style NAME STYLE-PARAMETERS) 545</example> 546 547If you want to create a new style, it is best to examine the source 548code for other styles first, to get an idea of what needs to be done. 549Each output format should have its own file, containing all styles 550based on it. For example. the =latex=, =latex-slides=, and =pdf= styles are 551all contained in =muse-latex.el=. 552 553If you are willing to sign copyright papers for the Free Software 554Foundation (we will help you with this step), the Muse authors may be 555interested in including your work in future versions of Muse. 556 557* License 558 559This QuickStart document may be redistributed and/or modified under 560the terms of the GNU General Public License as published by the Free 561Software Foundation; either version 3, or (at your option) any later 562version. 563 564 565Footnotes: 566[1] This is a footnote. 567 568[2] Another footnote, this one unreferenced. 569