« back to all changes in this revision
Viewing changes to muse.texi
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Michael W. Olson (GNU address)
- Date: 2005-12-17 12:11:27 UTC
- Revision ID: james.westby@ubuntu.com-20051217121127-b4yfr70a7hnrexdg
Tags: upstream-3.02.5
Import upstream version 3.02.5
- files added:
- contrib
- contrib/pyblosxom
- examples
- examples/johnw
- examples/mwolson
- examples/mwolson/stylesheets
- examples/mwolson/templates
- experimental
- lisp
- scripts
added
removed
muse.texi
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
15
This manual is for the Emacs Muse version 3.02.5.
16
17
Copyright (C) 2004, 2005 Free Software Foundation, Inc.
18
19
@quotation
20
Permission is granted to copy, distribute and/or modify this document
21
under the terms of the GNU General Public License.
22
@end quotation
23
@end copying
24
25
@titlepage
26
@title Muse manual
27
@subtitle an authoring and publishing environment
28
@subtitle for GNU Emacs and XEmacs
29
30
@c The following two commands
31
@c start the copyright page.
32
@page
33
@vskip 0pt plus 1filll
34
@insertcopying
35
@end titlepage
36
37
@c So the toc is printed at the start
38
@contents
39
40
@ifnottex
41
@node Top, Preface, (dir), (dir)
42
@comment node-name, next, previous, up
43
@top Muse
44
45
@insertcopying
46
@end ifnottex
47
48
@menu
49
* Preface:: About the documentation.
50
* Introduction:: What is Muse?
51
* Obtaining Muse:: How to get Muse releases and development
52
changes.
53
* Installation:: Compiling and installing Muse.
54
* Getting Started:: Settings for Muse.
55
* Projects:: Creating and managing Muse projects.
56
* Keystroke Summary:: Keys used in Muse mode.
57
* Markup Rules:: Rules for using markup.
58
* Publishing Styles:: Publishing various types of documents.
59
* Getting Help and Reporting Bugs::
60
* History:: History of this document.
61
* Contributors:: Contributors to this documentation.
62
* GNU General Public License:: The license for this manual and Muse.
63
* Concept Index:: Search for terms.
64
65
@detailmenu
66
--- The Detailed Node Listing ---
67
68
How to Get Muse Releases and Development Changes
69
70
* Releases:: Released versions of Muse.
71
* Development:: Latest unreleased development changes.
72
73
Rules for Using Markup
74
75
* Paragraphs:: Paragraphs: centering and quoting.
76
* Headings:: Levels of headings.
77
* Directives:: Directives at the beginning of a
78
document.
79
* Emphasizing Text:: Bold, italicized, and underlined text.
80
* Footnotes:: Making notes to be shown at the end.
81
* Verse:: Indicating poetic stanzas.
82
* Lists:: Lists of items.
83
* Tables:: Generation of data tables.
84
* Explicit Links:: Hyperlinks and email addresses with
85
descriptions.
86
* Implicit Links:: Bare URLs, WikiNames, and InterWiki
87
links.
88
* Images:: Publishing and displaying images.
89
* Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
90
* Embedded Lisp:: Evaluating Emacs Lisp code in documents
91
for extensibility.
92
* Comments:: Lines to omit from published output.
93
94
Publishing Various Types of Documents
95
96
* Blosxom:: Integrating Muse and pyblosxom.cgi.
97
* Book:: Publishing entries into a compilation.
98
* DocBook:: Publishing in DocBook XML form.
99
* HTML:: Publishing in HTML or XHTML form.
100
* Journal:: Keeping a journal or blog.
101
* LaTeX:: Publishing LaTeX documents.
102
* Poem:: Publish a poem to LaTex or PDF.
103
* Texinfo:: Publish entries to Texinfo format or PDF.
104
* Common Elements:: Common functionality shared by styles.
105
* Deriving Styles:: Deriving a new style from an existing
106
one.
107
108
Integrating Muse and pyblosxom.cgi
109
110
* Blosxom Requirements:: Other tools needed to the Blosxom style.
111
* Blosxom Entries:: Format of a Blosxom entry and automation.
112
* Blosxom Options:: Blosxom styles and options provided.
113
114
Common functionality shared by styles
115
116
* Markup Functions:: Specifying functions to marking up text.
117
* Markup Regexps:: Markup rules for publishing.
118
* Markup Strings:: Strings specific to a publishing style.
119
* Markup Tags:: Tag specifications for special markup.
120
* Style Elements:: Parameters used for defining styles.
121
122
@end detailmenu
123
@end menu
124
125
@node Preface, Introduction, Top, Top
126
@comment node-name, next, previous, up
127
@chapter About the documentation
128
129
This document describes Muse, which was written by John Wiegley
130
and is now maintained by Michael Olson. Several versions of it are
131
available on-line.
132
133
@itemize @bullet
134
@item PDF: http://www.mwolson.org/static/doc/muse.pdf
135
@item HTML (single file): http://www.mwolson.org/static/doc/muse.html
136
@item HTML (multiple files): http://www.mwolson.org/static/doc/muse/
137
@end itemize
138
139
@node Introduction, Obtaining Muse, Preface, Top
140
@comment node-name, next, previous, up
141
@chapter What is Muse?
142
143
Emacs Muse is an authoring and publishing environment for Emacs. It
144
simplifies the process of writing documents and publishing them to
145
various output formats.
146
147
Muse consists of two main parts: an enhanced text-mode for authoring
148
documents and navigating within Muse projects, and a set of publishing
149
styles for generating different kinds of output.
150
151
This idea is not in any way new. Numerous systems exist -- even one
152
other for Emacs itself (Bhl Mode). What Muse adds to the picture is a
153
more modular environment, with a rather simple core, in which "styles"
154
are derived from to create new styles. Much of Muse's overall
155
functionality is optional. For example, you can use the publisher
156
without the major-mode, or the mode without doing any publishing; or if
157
you don't load the Texinfo or LaTeX modules, those styles won't be
158
available.
159
160
The Muse codebase is a departure from emacs-wiki.el version 2.44. The
161
code has been restructured and rewritten, especially its publishing
162
functions. The focus in this revision is on the authoring and publishing
163
aspects, and the "wikiness" has been removed as a default behavior (to
164
be offered again as an optional module). CamelCase words are no longer
165
special by default.
166
167
@node Obtaining Muse, Installation, Introduction, Top
168
@comment node-name, next, previous, up
169
@chapter How to Get Muse Releases and Development Changes
170
171
@menu
172
* Releases:: Released versions of Muse.
173
* Development:: Latest unreleased development changes.
174
@end menu
175
176
@node Releases, Development, Obtaining Muse, Obtaining Muse
177
@comment node-name, next, previous, up
178
@section Released versions of Muse
179
180
Choose to install a release if you want to minimize risk.
181
182
Errors are corrected in development first. User-visible changes will be
183
announced on the @email{emacs-wiki-discuss@@nongnu.org} mailing list.
184
This mailing list also provides support for @command{Planner} and
185
@command{emacs-wiki}, which is the predecessor of Muse.
186
@pxref{Getting Help and Reporting Bugs}.
187
188
@cindex releases, Debian package
189
@cindex Debian package for Muse
190
Debian users can get Muse via apt-get. The @file{muse-el} package is
191
available both at Michael Olson's Debian repository and the official
192
Debian repository. To make use of the former, add the following line to
193
your @file{/etc/apt/sources.list} file and run @code{apt-get install
194
muse}.
195
196
@example
197
deb http://www.mwolson.org/debian/ ./
198
@end example
199
200
@cindex releases, from source
201
Alternatively, you can download the latest release from
202
@uref{http://www.mwolson.org/static/dist/muse/} .
203
204
@node Development, , Releases, Obtaining Muse
205
@comment node-name, next, previous, up
206
@section Latest unreleased development changes
207
@cindex development
208
209
Choose the development version if you want to live on the bleeding edge
210
of Muse development or try out new features before release.
211
212
@cindex arch revision control system, using
213
The Arch revision control system allows you to retrieve previous
214
versions and select specific features and bug fixes. If you would like
215
to contribute to Muse development, it is highly recommended that you use
216
Arch, but this is not a requirement.
217
218
If you are new to Arch, you might find this tutorial helpful:
219
@uref{http://www.mwolson.org/projects/ArchTutorial.html}.
220
221
Downloading the Muse module with Arch and staying up-to-date involves
222
the following steps.
223
224
@enumerate
225
@item Install arch
226
227
@itemize @bullet
228
@item Debian: @kbd{apt-get install tla}.
229
@item Other distributions: see @uref{http://regexps.srparish.net/www/}.
230
@end itemize
231
232
@item Register the archive.
233
@example
234
tla register-archive -f http://www.mwolson.org/archives/2005
235
@end example
236
237
@item Download the Muse package.
238
@example
239
# Download Muse into the @file{muse} directory.
240
tla get mwolson@@gnu.org--2005/muse--main--1.0 muse
241
@end example
242
243
@item List upstream changes that are missing from your local copy.
244
Do this whenever you want to see whether new changes have been committed
245
to Muse.
246
247
@example
248
# Change to the source directory you are interested in.
249
cd muse/
250
251
# Display the summary of changes
252
tla missing --summary
253
@end example
254
255
@cindex updating Muse with Arch
256
@item Update to the latest version by replaying missing changes.
257
@example
258
cd muse
259
tla replay
260
@end example
261
262
@end enumerate
263
264
There are other ways to interact with the Muse archive.
265
266
@itemize
267
@item Browse arch repository: @uref{http://www.mwolson.org/archives/}
268
@item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/muse-latest.tar.gz}
269
@end itemize
270
271
The latest development snapshot will be kept up-to-date since it is
272
updated at the same time as the Arch repository.
273
274
@node Installation, Getting Started, Obtaining Muse, Top
275
@comment node-name, next, previous, up
276
@chapter Compiling and Installing Muse
277
278
Muse may be compiled and installed on your machine.
279
280
@subsubheading Compilation
281
282
This is an optional step, since Emacs Lisp source code does not
283
necessarily have to be byte-compiled. It will yield a speed increase,
284
though.
285
286
A working copy of Emacs or XEmacs is needed in order to compile the
287
Emacs Muse. By default, the program that is installed with the name
288
@command{emacs} will be used.
289
290
If you want to use the @command{xemacs} binary to perform the
291
compilation, you would need to edit @file{Makefile.defs} in the
292
top-level directory as follows. You can put either a full path to an
293
Emacs or XEmacs binary or just the command name, as long as it is in the
294
@env{PATH}.
295
296
@example
297
EMACS = xemacs
298
SITEFLAG = -no-site-file
299
@end example
300
301
Running @code{make} should compile the Muse source files in the
302
@file{lisp} directory.
303
304
@subsubheading Installation
305
306
Muse may be installed into your file hierarchy by doing the following.
307
308
Edit the @file{Makefile.defs} file so that @env{ELISPDIR} points to
309
where you want the source and compiled Muse files to be installed and
310
@env{INFODIR} indicates where to put the Muse manual. Of course, you
311
will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
312
Compilation section if you are using XEmacs.
313
314
If you are installing Muse on a Debian system, you might want to change
315
the value of @env{INSTALLINFO} as specified in @file{Makefile.defs}.
316
317
If you wish to install Muse to different locations than the defaults
318
specify, edit @file{Makefile.defs} accordingly.
319
320
Run @code{make} as a normal user.
321
322
Run @code{make install} as the root user if you have chosen installation
323
locations that require this.
324
325
326
@node Getting Started, Projects, Installation, Top
327
@comment node-name, next, previous, up
328
@chapter Getting Started
329
@cindex settings
330
331
To use Muse, add the directory containing its files to your
332
@code{load-path} variable, in your @file{.emacs} file. Then, load in
333
the authoring mode, and the styles you wish to publish to. An example
334
follows.
335
336
@lisp
337
(add-to-list 'load-path "<path to Muse>")
338
339
(require 'muse-mode) ; load authoring mode
340
341
(require 'muse-html) ; load publishing styles I use
342
(require 'muse-latex)
343
(require 'muse-texinfo)
344
(require 'muse-docbook)
345
@end lisp
346
347
Once loaded, the command @kbd{M-x muse-publish-this-file} will publish
348
an input document to any available style. If you enable
349
@file{muse-mode} within a buffer, by typing @kbd{M-x muse-mode}, this
350
command will be bound to @kbd{C-c C-t}.
351
352
If the currently opened file is part of a defined project in
353
@code{muse-project-alist}, it may be published using @kbd{C-c C-p}.
354
355
You should also type @kbd{M-x customize-group}, and give the name
356
@samp{muse}. Each of the options has its own documentation.
357
358
359
@node Projects, Keystroke Summary, Getting Started, Top
360
@comment node-name, next, previous, up
361
@chapter Creating and Managing Muse Projects
362
@cindex projects
363
364
Often you will want to publish all the files within a directory to a
365
particular set of output styles automatically. To support, Muse
366
allows for the creations of "projects". Here is a sample project, to
367
be defined in your @file{.emacs} file.
368
369
@lisp
370
(require 'muse-project)
371
372
(setq muse-project-alist
373
'(("website" ; my various writings
374
("~/Pages" :default "index")
375
(:base "html" :path "~/public_html")
376
(:base "pdf" :path "~/public_html/pdf"))))
377
@end lisp
378
379
The above defines a project named "website", whose files are located
380
in the directory @file{~/Pages}. The default page to visit is
381
@file{index}. When this project is published, each page will be
382
output as HTML to the directory @file{~/public_html}, and as PDF to
383
the directory @file{~/public_html/pdf}. Within any project page, you
384
may create a link to other pages using the syntax @samp{[[pagename]]}.
385
386
@c PRE3_03: Give more examples
387
@c PRE3_03: Describe :set and other options fully
388
389
@node Keystroke Summary, Markup Rules, Projects, Top
390
@comment node-name, next, previous, up
391
@chapter Keys Used in Muse Mode
392
@cindex keystrokes
393
394
This is a summary of keystrokes available in every Muse buffer.
395
396
@table @kbd
397
398
@item C-c C-a (`muse-index')
399
Display an index of all known Muse pages.
400
401
@item C-c C-b (`muse-browse-result')
402
Show the published result of this page.
403
404
@item C-c C-e (`muse-edit-link-at-point')
405
Edit link at point.
406
407
@item C-c C-f (`muse-project-find-file'), also C-c C-v
408
Open another Muse page. Prompt for the name.
409
410
@item C-c C-l (`font-lock-mode')
411
Highlight/refresh the current buffer.
412
413
@item C-c C-p (`muse-project-publish')
414
Publish any Muse pages that have changed.
415
416
@item C-c C-v (`muse-project-find-file'), also C-c C-f
417
Open another Muse page. Prompt for the name.
418
419
@item C-c = (`muse-what-changed')
420
Diff this page against the last backup version.
421
422
@item C-c TAB (`muse-insert-tag')
423
Insert a tag interactively.
424
425
@item TAB
426
Move to the next Wiki reference.
427
428
@item S-TAB
429
Move to the previous Wiki reference.
430
431
@end table
432
433
434
@node Markup Rules, Publishing Styles, Keystroke Summary, Top
435
@comment node-name, next, previous, up
436
@chapter Rules for Using Markup
437
@cindex markup
438
439
A Muse document uses special, contextual markup rules to determine how
440
to format the output result. For example, if a paragraph is indented,
441
Muse assumes it should be quoted.
442
443
There are not too many markup rules, and all of them strive to be as
444
simple as possible so that you can focus on document creation, rather
445
than formatting.
446
447
@menu
448
* Paragraphs:: Paragraphs: centering and quoting.
449
* Headings:: Levels of headings.
450
* Directives:: Directives at the beginning of a
451
document.
452
* Emphasizing Text:: Bold, italicized, and underlined text.
453
* Footnotes:: Making notes to be shown at the end.
454
* Verse:: Indicating poetic stanzas.
455
* Lists:: Lists of items.
456
* Tables:: Generation of data tables.
457
* Explicit Links:: Hyperlinks and email addresses with
458
descriptions.
459
* Implicit Links:: Bare URLs, WikiNames, and InterWiki
460
links.
461
* Images:: Publishing and displaying images.
462
* Horizontal Rules and Anchors:: Inserting a horizontal line or anchor.
463
* Embedded Lisp:: Evaluating Emacs Lisp code in documents
464
for extensibility.
465
* Comments:: Lines to omit from published output.
466
@end menu
467
468
@node Paragraphs, Headings, Markup Rules, Markup Rules
469
@comment node-name, next, previous, up
470
@section Paragraphs: centering and quoting
471
@cindex paragraphs
472
473
Paragraphs in Muse must be separated by a blank line.
474
475
@cindex paragraphs, centered
476
@strong{Centered paragraphs and quotations}
477
478
A line that begins with six or more columns of whitespace (either tabs
479
or spaces) indicates a centered paragraph.
480
481
@cindex paragraphs, quoted
482
@cindex quotations
483
But if a line begins with whitespace, though less than six columns, it
484
indicates a quoted paragraph.
485
486
@cindex examples
487
@cindex monospace, rendering blocks
488
@cindex HTML, rendering blocks in monospace
489
@strong{Literal paragraphs}
490
491
The @verb{|<example>|} tag is used for examples, where whitespace should
492
be preserved, the text rendered in monospace, and any characters special
493
to the output style escaped.
494
495
@cindex literal text
496
@cindex HTML, inserting a raw block
497
There is also the @verb{|<literal>|} tag, which causes a marked block to
498
be entirely left alone. This can be used for inserting a hand-coded
499
HTML blocks into HTML output, for example.
500
501
@node Headings, Directives, Paragraphs, Markup Rules
502
@comment node-name, next, previous, up
503
@section Levels of headings
504
@cindex headings
505
506
A heading becomes a chapter or section in printed output -- depending on
507
the style. To indicate a heading, start a new paragraph with one or
508
more asterices, followed by a space and the heading title. Then begin
509
another paragraph to enter the text for that section.
510
511
All levels of headings will be published. Most publishing styles only
512
distinguish the between the first 4 levels, however.
513
514
@example
515
* First level
516
517
** Second level
518
519
*** Third level
520
521
**** Fourth level
522
@end example
523
524
@node Directives, Emphasizing Text, Headings, Markup Rules
525
@comment node-name, next, previous, up
526
@section Directives at the beginning of a document
527
@cindex directives
528
529
Directives are lines beginning with the @samp{#} character that come
530
before any paragraphs or sections in the document. Directives are of
531
the form ``#directive content of directive''. You can use any
532
combination of uppercase and lowercase letters for directives, even if
533
the directive is not in the list below.
534
535
The @code{muse-publishing-directive} function may be used in header and
536
footer text to access directives. For example, to access the
537
@samp{#title} directive, use @code{(muse-publishing-directive "title")}.
538
539
The following is a list of directives that Muse uses.
540
541
@table @code
542
@cindex #author
543
@item #author
544
The author of this document.
545
546
If this is not specified, Muse will attempt to figure it out from the
547
@code{user-full-name} variable.
548
549
@cindex #date
550
@item #date
551
The date that the document was last modified.
552
553
This is used by publishing styles that are able to embed the date
554
information.
555
556
@cindex #desc
557
@item #desc
558
A short description of this document.
559
560
This is used by the @code{journal} publishing style to embed information
561
inside of an RSS/RDF feed.
562
563
@cindex #title
564
@item #title
565
The title of this document.
566
567
If this is not specified, the name of the file is used.
568
569
@end table
570
571
@node Emphasizing Text, Footnotes, Directives, Markup Rules
572
@comment node-name, next, previous, up
573
@section Bold, italicized, and underlined text
574
@cindex emphasizing text
575
@cindex underlining text
576
@cindex italicizing text
577
@cindex verbatim text
578
@cindex monospace, rendering words
579
580
To emphasize text, surround it with certain specially recognized
581
characters.
582
583
@example
584
*emphasis*
585
**strong emphasis**
586
***very strong emphasis***
587
_underlined_
588
=verbatim and monospace=
589
@end example
590
591
@cindex WYSIWYG
592
While editing a Muse document in Muse mode, these forms of emphasis will
593
be highlighted in a WYSIWYG manner. Each of these forms may span
594
multiple lines.
595
596
Verbatim text will be colored as gray by default. To change this,
597
customize @code{muse-verbatim-face}.
598
599
@node Footnotes, Verse, Emphasizing Text, Markup Rules
600
@comment node-name, next, previous, up
601
@section Making notes to be shown at the end
602
@cindex footnotes
603
604
A footnote reference is simply a number in square brackets. To define
605
the footnote, place this definition at the bottom of your file.
606
@samp{footnote-mode} can be used to greatly facilitate the creation of
607
these kinds of footnotes.
608
609
Footnotes are defined by the same number in brackets occurring at the
610
beginning of a line. Use footnote-mode's @kbd{C-c ! a} command, to very
611
easily insert footnotes while typing. Use @kbd{C-x C-x} to return to
612
the point of insertion.
613
614
@node Verse, Lists, Footnotes, Markup Rules
615
@comment node-name, next, previous, up
616
@section Indicating poetic stanzas
617
@cindex verses
618
@cindex poetry
619
620
Poetry requires that whitespace be preserved, but without resorting to
621
monospace. To indicate this, use the following markup, reminiscent of
622
email quotations.
623
624
@example
625
> A line of Emacs verse;
626
> forgive its being so terse.
627
@end example
628
629
You can also use the @verb{|<verse>|} tag, if you prefer.
630
631
@example
632
<verse>
633
A line of Emacs verse;
634
forgive its being so terse.
635
</verse>
636
@end example
637
638
@cindex verses, multiple stanzas
639
Multiple stanzas may be included in one set of @verb{|<verse>|} tags, as
640
follows.
641
642
@example
643
<verse>
644
A line of Emacs verse;
645
forgive its being so terse.
646
647
In terms of terse verse,
648
you could do worse.
649
</verse>
650
@end example
651
652
@node Lists, Tables, Verse, Markup Rules
653
@comment node-name, next, previous, up
654
@section Lists of items
655
@cindex lists
656
657
Lists are given using special characters at the beginning of a line.
658
Whitespace must occur before bullets or numbered items, to distinguish
659
from the possibility of those characters occurring in a real sentence.
660
661
@cindex lists, bullets
662
These are rendered as a bullet list.
663
664
@example
665
- bullet item one
666
- bullet item two
667
@end example
668
669
@cindex lists, enumerated
670
An enumerated list follows.
671
672
@example
673
1. Enum item one
674
2. Enum item two
675
@end example
676
677
@cindex lists, definitions
678
Here is a definition list.
679
680
@example
681
Term1 ::
682
This is a first definition
683
And it has two lines;
684
no, make that three.
685
686
Term2 ::
687
This is a second definition
688
@end example
689
690
@node Tables, Explicit Links, Lists, Markup Rules
691
@comment node-name, next, previous, up
692
@section Generation of data tables
693
@cindex tables
694
695
@cindex tables, simple
696
Only very simple tables are supported. The syntax is as follows.
697
698
@example
699
Double bars || Separate header fields
700
701
Single bars | Separate body fields
702
Here are more | body fields
703
704
Triple bars ||| Separate footer fields
705
@end example
706
707
Some publishing styles require header fields to come first, then footer
708
fields, and then the body fields. You can use any order for these
709
sections that you like, and Muse will re-order them for you at
710
publish-time.
711
712
@node Explicit Links, Implicit Links, Tables, Markup Rules
713
@comment node-name, next, previous, up
714
@section Hyperlinks and email addresses with descriptions
715
@cindex links, explicit
716
717
A hyperlink can reference a URL, or another page within a Muse
718
project. In addition, descriptive text can be specified, which should
719
be displayed rather than the link text in output styles that supports
720
link descriptions. The syntax is as follows.
721
722
@example
723
[[link target][link description]]
724
[[link target without description]]
725
@end example
726
727
Thus, the current maintainer's homepage for Muse can be found
728
@samp{[[http://www.mwolson.org/projects/MuseMode.html][here]]},
729
or at @samp{[[http://www.mwolson.org/projects/MuseMode.html]]}.
730
731
@node Implicit Links, Images, Explicit Links, Markup Rules
732
@comment node-name, next, previous, up
733
@section Bare URLs, WikiNames, and InterWiki links
734
@cindex links, implicit
735
@cindex links, raw
736
@cindex URLs
737
@cindex Email addresses
738
739
A URL or email address encountered in the input text is published as a
740
hyperlink. These kind of links are called @dfn{implicit links} because
741
they are not separated from the rest of the Muse document in any way.
742
743
@cindex WikiNames
744
If the @command{muse-wiki} module is loaded, another form of implicit
745
link will be made available. WikiNames, which are typed in camelcase,
746
will be highlighted and published as links, provided that the file they
747
refer to exists.
748
749
@cindex InterWiki links
750
@cindex inter-project links
751
The @command{muse-wiki} module also allows for InterWiki links. These
752
are similar to WikiWords, but they specify both the project and page of
753
a file. The names of your project entries in @code{muse-project-alist}
754
will be used as InterWiki names by default. Several examples follow.
755
756
@example
757
Blog::DocumentingMuse
758
Projects#MuseMode
759
Website
760
@end example
761
762
In the first case, the interwiki delimiter is @samp{::}, @samp{Blog} is
763
the project name, and @samp{DocumentingMuse} is the page name. In the
764
second example, @samp{#} is the interwiki delimiter. If the name of a
765
project occurs by itself in text, like the third case, it will be
766
colorized and published as a link to the default page of the given
767
project.
768
769
Customization of interwiki links may be accomplished by editing the
770
@code{muse-wiki-interwiki-alist} option.
771
772
@node Images, Horizontal Rules and Anchors, Implicit Links, Markup Rules
773
@comment node-name, next, previous, up
774
@section Publishing and displaying images
775
@cindex images
776
@cindex links, with images
777
@strong{Image links}
778
779
Links to images may be used in either the target or the description, or
780
both. Thus, the following code will publish as a clickable image that
781
points to @url{http://www.mwolson.org/}.
782
783
@example
784
[[http://www.mwolson.org/][http://www.mwolson.org/static/logos/site-logo.png]]
785
@end example
786
787
@cindex images, displaying
788
@cindex images, inlined
789
@cindex images, local
790
If a link to a locally-available image is encountered in the link
791
description, Muse mode will attempt to display it if your version of
792
Emacs permits this. The following example will display correctly and
793
publish correctly if a @acronym{PNG} file called @file{TestLogo.png}
794
exists in the @file{../pics/} directory.
795
796
@example
797
[[TestPage][../pics/TestLogo.png]]
798
@end example
799
800
@cindex images, without a description
801
An image link is not required to have a description. The link
802
@samp{[[../myimage.png]]} will display and publish as expected.
803
804
@node Horizontal Rules and Anchors, Embedded Lisp, Images, Markup Rules
805
@comment node-name, next, previous, up
806
@section Inserting a horizontal line or anchor
807
808
@cindex horizontal rules
809
@cindex dashes
810
@strong{Horizontal Rules}
811
812
Four or more dashes indicate a horizontal rule. Be sure to put blank
813
lines around it, or it will be considered part of the proceeding or
814
following paragraph!
815
816
@cindex anchors
817
@cindex links, with target on same page
818
@strong{Anchors}
819
820
If you begin a line with "#anchor" -- where "anchor" can be any word
821
that doesn't contain whitespace -- it defines an anchor at that point
822
into the document. This point can be referenced using "page#anchor" as
823
the target in a Muse link.
824
825
@node Embedded Lisp, Comments, Horizontal Rules and Anchors, Markup Rules
826
@comment node-name, next, previous, up
827
@section Evaluating Emacs Lisp code in documents for extensibility
828
@cindex lisp, embedded
829
830
Arbitrary kinds of markup can be achieved using the @verb{|<lisp>|} tag,
831
which is the only Muse tag supported in a style's header and footer
832
text. With the @verb{|<lisp>|} tag, you may generated whatever output
833
text you wish. The inserted output will get marked up, if the
834
@verb{|<lisp>|} tag appears within the main text of the document.
835
836
@example
837
<lisp>(concat "This form gets " "inserted")</lisp>
838
@end example
839
840
@cindex lisp, and insert command
841
Note that you should not use the @code{insert} command within a set of
842
@verb{|<lisp>|} tags, since the return value from the @verb{|<lisp>|}
843
tags will be automatically inserted into the document.
844
845
@node Comments, , Embedded Lisp, Markup Rules
846
@comment node-name, next, previous, up
847
@section Lines to omit from published output
848
@cindex comments
849
@cindex publishing, omitting lines
850
851
Use the following syntax to indicate a comment. Comments will not be
852
published.
853
854
@example
855
; Comment text goes here.
856
@end example
857
858
That is, only a semi-colon at the beginning of a line, followed by a
859
literal space, will cause that line to be treated as a comment.
860
861
@node Publishing Styles, Getting Help and Reporting Bugs, Markup Rules, Top
862
@comment node-name, next, previous, up
863
@chapter Publishing Various Types of Documents
864
@cindex publishing styles
865
866
One of the principle features of Muse is the ability to publish a simple
867
input text to a variety of different output styles. Muse also makes it
868
easy to create new styles, or derive from an existing style.
869
870
@menu
871
* Blosxom:: Integrating Muse and pyblosxom.cgi.
872
* Book:: Publishing entries into a compilation.
873
* DocBook:: Publishing in DocBook XML form.
874
* HTML:: Publishing in HTML or XHTML form.
875
* Journal:: Keeping a journal or blog.
876
* LaTeX:: Publishing LaTeX documents.
877
* Poem:: Publish a poem to LaTex or PDF.
878
* Texinfo:: Publish entries to Texinfo format or PDF.
879
* Common Elements:: Common functionality shared by styles.
880
* Deriving Styles:: Deriving a new style from an existing
881
one.
882
@end menu
883
884
@node Blosxom, Book, Publishing Styles, Publishing Styles
885
@comment node-name, next, previous, up
886
@section Integrating Muse and pyblosxom.cgi
887
@cindex blog, one-file-per-entry style
888
889
The Blosxom publishing style publishes a tree of categorised files to a
890
mirrored tree of stories to be served by blosxom.cgi or pyblosxom.cgi.
891
In other words, each blog entry corresponds with one file.
892
893
@menu
894
* Blosxom Requirements:: Other tools needed to the Blosxom style.
895
* Blosxom Entries:: Format of a Blosxom entry and automation.
896
* Blosxom Options:: Blosxom styles and options provided.
897
@end menu
898
899
@node Blosxom Requirements, Blosxom Entries, Blosxom, Blosxom
900
@comment node-name, next, previous, up
901
@subsection Other tools needed to the Blosxom style
902
903
You will need to have @command{pyblosxom.cgi} or @command{blosxom.cgi}
904
installed on a machine that you have upload access to.
905
906
The following additional components are required in order to make the
907
date of blog entries display as something sensible.
908
909
@enumerate
910
@item
911
A script to gather date directives from the entire blog tree into a
912
single file. The file must associate a blog entry with a date.
913
914
@item
915
A plugin for (py)blosxom that reads this file.
916
@end enumerate
917
918
These 2 things are provided for @command{pyblosxom.cgi} in the
919
@file{contrib/pyblosxom} subdirectory. @file{getstamps.py} provides the
920
former service, while @file{hardcodedates.py} provides the latter
921
service. Eventually it is hoped that a @command{blosxom.cgi} plugin and
922
script will be found/written.
923
924
Here is a sample listing from my @file{timestamps} file, which maps
925
each file to a date. This can really be in any format, as long as your
926
date-gathering script and your plugin can both understand it.
927
928
@example
929
2005-04-01-14-16 personal/paper_cranes
930
2005-03-21 personal/spring_break_over
931
2004-10-24 personal/finished_free_culture
932
@end example
933
934
@node Blosxom Entries, Blosxom Options, Blosxom Requirements, Blosxom
935
@comment node-name, next, previous, up
936
@subsection Format of a Blosxom entry and automation
937
938
Each Blosxom file must include `#date yyyy-mm-dd', or optionally the
939
longer `#date yyyy-mm-dd-hh-mm', a title (using the #title directive),
940
plus whatever normal content is desired.
941
942
The date directive is not used directly by @command{pyblosxom.cgi} or
943
this program. You need to have the two additional items from the former
944
section to make use of this feature.
945
946
There is a function called @code{muse-blosxom-new-entry} that will
947
automate the process of making a new blog entry. To make use of it, do
948
the following.
949
950
@itemize @bullet
951
@item
952
Customize @code{muse-blosxom-base-directory} to the location that your
953
blog entries are stored.
954
955
@item
956
Assign the @code{muse-blosxom-new-entry} function to a key sequence. I
957
use the following code to assign this function to @kbd{C-c p l'}.
958
959
@example
960
(global-set-key "\C-cpl" 'muse-blosxom-new-entry)
961
@end example
962
963
@item
964
You should create your directory structure ahead of time under your base
965
directory. These directories, which correspond with category names, may
966
be nested.
967
968
@item
969
When you enter this key sequence, you will be prompted for the category
970
of your entry and its title. Upon entering this information, a new file
971
will be created that corresponds with the title, but in lowercase
972
letters and having special characters converted to underscores. The
973
title and date directives will be inserted automatically.
974
@end itemize
975
976
@node Blosxom Options, , Blosxom Entries, Blosxom
977
@comment node-name, next, previous, up
978
@subsection Blosxom styles and options provided
979
980
The following styles and options are available in the Blosxom publishing
981
style.
982
983
@subsubheading Styles provided
984
985
@table @code
986
987
@cindex publishing styles, blosxom-html
988
@item blosxom-html
989
Publish Blosxom entries in HTML form.
990
991
@cindex publishing styles, blosxom-xhtml
992
@item blosxom-xhtml
993
Publish Blosxom entries in XHTML form.
994
995
@end table
996
997
@subsubheading Options provided
998
999
@table @code
1000
1001
@item muse-blosxom-extension
1002
Default file extension for publishing Blosxom files.
1003
1004
@item muse-blosxom-header
1005
Header used for publishing Blosxom files.
1006
1007
This may be text or a filename.
1008
1009
@item muse-blosxom-footer
1010
Footer used for publishing Blosxom files.
1011
1012
This may be text or a filename.
1013
1014
@item muse-blosxom-base-directory
1015
Base directory of blog entries, used by @code{muse-blosxom-new-entry}.
1016
1017
This is the top-level directory where your blog entries may be found
1018
locally.
1019
1020
@end table
1021
1022
@node Book, DocBook, Blosxom, Publishing Styles
1023
@comment node-name, next, previous, up
1024
@section Publishing entries into a compilation
1025
1026
This publishing style is used to output ``books'' in LaTeX or PDF
1027
format.
1028
1029
Each page will become a separate chapter in the book, unless the style
1030
keyword @option{:nochapters} is used, in which case they are all run
1031
together as if one giant chapter.
1032
1033
You will need to call the @code{muse-book-publish-project} function in
1034
order to publish this style. An example of this may be found in John
1035
Wiegley's configuration file at @file{examples/johnw/muse-johnw.el}.
1036
1037
@subsubheading Styles provided
1038
1039
@table @code
1040
1041
@cindex publishing styles, book-latex
1042
@item book-latex
1043
Publish a book in LaTeX form. The header and footer are different than
1044
the normal LaTeX publishing mode.
1045
1046
@cindex publishing styles, book-pdf
1047
@item book-pdf
1048
Publish a book in PDF form. The header and footer are different than
1049
the normal PDF publishing mode.
1050
1051
@end table
1052
1053
@subsubheading Options provided
1054
1055
@table @code
1056
1057
@item muse-book-before-publish-hook
1058
A hook run in the book buffer before it is marked up.
1059
1060
@item muse-book-after-publish-hook
1061
A hook run in the book buffer after it is marked up.
1062
1063
@item muse-book-latex-header
1064
Header used for publishing books to LaTeX.
1065
1066
This may be text or a filename.
1067
1068
@item muse-book-latex-footer
1069
Footer used for publishing books to LaTeX.
1070
1071
This may be text or a filename.
1072
1073
@end table
1074
1075
@node DocBook, HTML, Book, Publishing Styles
1076
@comment node-name, next, previous, up
1077
@section Publishing in DocBook XML form
1078
1079
This publishing style is used to generate DocBook XML files.
1080
1081
@subsubheading Styles provided
1082
1083
@table @code
1084
1085
@cindex publishing styles, docbook
1086
@item docbook
1087
1088
@end table
1089
1090
@subsubheading Options provided
1091
1092
@table @code
1093
1094
@item muse-docbook-extension
1095
Default file extension for publishing DocBook XML files.
1096
1097
@item muse-docbook-header
1098
Header used for publishing DocBook XML files.
1099
1100
This may be text or a filename.
1101
1102
@item muse-docbook-footer
1103
Footer used for publishing DocBook XML files.
1104
1105
This may be text or a filename.
1106
1107
@item muse-docbook-markup-regexps
1108
List of markup rules for publishing a Muse page to DocBook XML.
1109
1110
@item muse-docbook-markup-functions
1111
An alist of style types to custom functions for that kind of text.
1112
1113
@item muse-docbook-markup-strings
1114
Strings used for marking up text.
1115
1116
These cover the most basic kinds of markup, the handling of which
1117
differs little between the various styles.
1118
1119
@item muse-docbook-markup-specials
1120
A table of characters which must be represented specially.
1121
1122
@item muse-docbook-encoding-default
1123
The default Emacs buffer encoding to use in published files.
1124
This will be used if no special characters are found.
1125
1126
@item muse-docbook-charset-default
1127
The default DocBook XML charset to use if no translation is
1128
found in @code{muse-docbook-encoding-map}.
1129
1130
@item muse-docbook-encoding-map
1131
An alist mapping emacs coding systems to appropriate DocBook charsets.
1132
Use the base name of the coding system (i.e. without the -unix).
1133
1134
@end table
1135
1136
@node HTML, Journal, DocBook, Publishing Styles
1137
@comment node-name, next, previous, up
1138
@section Publishing in HTML or XHTML form
1139
1140
This publishing style is capable of producing HTML or XHTML documents.
1141
1142
@subsubheading Styles provided
1143
1144
@table @code
1145
1146
@cindex publishing styles, html
1147
@item html
1148
Supports publishing to HTML 4.0 and HTML 4.01, Strict or Transitional.
1149
1150
@item xhtml
1151
Supports publishing to XHTML 1.0 and XHTML 1.1, Strict or Transitional.
1152
1153
@end table
1154
1155
@subsubheading Options provided
1156
1157
If an HTML option does not have a corresponding XHTML option, it will
1158
be used for both of these publishing styles.
1159
1160
@table @code
1161
1162
@item muse-html-extension
1163
Default file extension for publishing HTML files.
1164
1165
@item muse-xhtml-extension
1166
Default file extension for publishing XHTML files.
1167
1168
@item muse-html-style-sheet
1169
Store your stylesheet definitions here.
1170
1171
This is used in @code{muse-html-header}. You can put raw CSS in here or
1172
a @verb{|<link>|} tag to an external stylesheet. This text may contain
1173
@verb{|<lisp>|} markup tags.
1174
1175
If you are using XHTML, make sure to close the @verb{|<link>|} tag
1176
properly.
1177
1178
@item muse-html-header
1179
Header used for publishing HTML files.
1180
1181
This may be text or a filename.
1182
1183
@item muse-html-footer
1184
Footer used for publishing HTML files.
1185
1186
This may be text or a filename.
1187
1188
@item muse-xhtml-header
1189
Header used for publishing XHTML files.
1190
1191
This may be text or a filename.
1192
1193
@item muse-xhtml-footer
1194
Footer used for publishing XHTML files.
1195
1196
This may be text or a filename.
1197
1198
@item muse-html-anchor-on-word
1199
When true, anchors surround the closest word.
1200
1201
This allows you to select them in a browser (i.e. for pasting), but has
1202
the side-effect of marking up headers in multiple colors if your header
1203
style is different from your link style.
1204
1205
@item muse-html-table-attributes
1206
The attribute to be used with HTML @verb{|<table>|} tags.
1207
1208
Note that since Muse supports direct insertion of HTML tags, you can
1209
easily create any kind of table you want, as long as each line begins at
1210
column 0 (to prevent it from being blockquoted).
1211
1212
@item muse-html-markup-regexps
1213
List of markup rules for publishing a Muse page to HTML.
1214
1215
@item muse-html-markup-functions
1216
An alist of style types to custom functions for that kind of text.
1217
1218
@item muse-html-markup-strings
1219
Strings used for marking up text as HTML.
1220
1221
These cover the most basic kinds of markup, the handling of which
1222
differs little between the various styles.
1223
1224
@item muse-xhtml-markup-strings
1225
Strings used for marking up text as XHTML.
1226
1227
These cover the most basic kinds of markup, the handling of which
1228
differs little between the various styles.
1229
1230
@item muse-html-markup-tags
1231
A list of tag specifications, for specially marking up HTML.
1232
@xref{muse-publish-markup-tags}, for more information.
1233
1234
@item muse-html-markup-specials
1235
A table of characters which must be represented specially. By default,
1236
this includes @samp{"}, @samp{<}, @samp{>}, and @samp{&}.
1237
1238
@item muse-html-meta-http-equiv
1239
The http-equiv attribute used for the HTML @verb{|<meta>|} tag.
1240
1241
@item muse-html-meta-content-type
1242
The content type used for the HTML @verb{|<meta>|} tag.
1243
1244
If you are striving for XHTML 1.1 compliance, you may want to change
1245
this to ``application/xhtml+xml''.
1246
1247
@item muse-html-meta-content-encoding
1248
The charset to append to the HTML @verb{|<meta>|} tag.
1249
1250
If set to the symbol 'detect, use @code{muse-html-encoding-map} to try
1251
and determine the HTML charset from emacs's coding. If set to a string,
1252
this string will be used to force a particular charset.
1253
1254
@item muse-html-charset-default
1255
The default HTML meta charset to use if no translation is found in
1256
@code{muse-html-encoding-map}.
1257
1258
@item muse-html-encoding-default
1259
The default Emacs buffer encoding to use in published files.
1260
This will be used if no special characters are found.
1261
1262
@item muse-html-encoding-map
1263
An alist mapping emacs coding systems to appropriate HTML charsets.
1264
Use the base name of the coding system (i.e. without the -unix).
1265
1266
@end table
1267
1268
@node Journal, LaTeX, HTML, Publishing Styles
1269
@comment node-name, next, previous, up
1270
@section Keeping a journal or blog
1271
@cindex journal
1272
@cindex blog, journal style
1273
1274
The module facilitates the keeping and publication of a journal. When
1275
publishing to HTML, it assumes the form of a web log, or blog.
1276
1277
The input format for each entry is as follows.
1278
1279
@example
1280
* 20040317: Title of entry
1281
1282
text for the entry.
1283
1284
<qotd>
1285
"You know who you are. It comes down to a simple gut check: You
1286
either love what you do or you don't. Period." -- P. Bronson
1287
</qotd>
1288
@end example
1289
1290
The "qotd", or Quote of the Day, is entirely optional. When generated
1291
to HTML, this entry is rendered as the following.
1292
1293
@example
1294
<div class="entry">
1295
<div class="entry-qotd">
1296
<h3>Quote of the Day:</h3>
1297
<p>"You know who you are. It comes down to a simple gut
1298
check: You either love what you do or you don't. Period."
1299
-- P. Bronson</p>
1300
</div>
1301
<div class="entry-body">
1302
<div class="entry-head">
1303
<div class="entry-date">
1304
<span class="date">March 17, 2004</span>
1305
</div>
1306
<div class="entry-title">
1307
<h2>Title of entry</h2>
1308
</div>
1309
</div>
1310
<div class="entry-text">
1311
<p>Text for the entry.</p>
1312
</div>
1313
</div>
1314
</div>
1315
@end example
1316
1317
The plurality of "div" tags makes it possible to display the entries in
1318
any form you wish, using a CSS style.
1319
1320
Also, an .RDF file can be generated from your journal by publishing it
1321
with the "rdf" style. It uses the first two sentences of the first
1322
paragraph of each entry as its "description", and auto-generates tags
1323
for linking to the various entries.
1324
1325
@subsubheading Styles provided
1326
1327
@table @code
1328
1329
@cindex publishing styles, journal-html
1330
@item journal-html
1331
Publish journal entries as an HTML document.
1332
1333
@cindex publishing styles, journal-xhtml
1334
@item journal-xhtml
1335
Publish journal entries as an XHTML document.
1336
1337
@cindex publishing styles, journal-latex
1338
@item journal-latex
1339
Publish journal entries as a LaTeX document.
1340
1341
@cindex publishing styles, journal-pdf
1342
@item journal-pdf
1343
Publish journal entries as a PDF document.
1344
1345
@cindex publishing styles, journal-book-latex
1346
@item journal-book-latex
1347
Publish journal entries as a LaTeX book.
1348
1349
@cindex publishing styles, journal-book-pdf
1350
@item journal-book-pdf
1351
Publish journal entries as a PDF book.
1352
1353
@cindex publishing styles, journal-rdf
1354
@cindex publishing styles, RSS 1.0
1355
@item journal-rdf
1356
Publish journal entries as an RDF file (RSS 1.0).
1357
1358
@cindex publishing styles, journal-rss
1359
@cindex publishing styles, RSS 2.0
1360
@item journal-rss
1361
Publish journal entries as an RSS file (RSS 2.0).
1362
1363
@end table
1364
1365
@subsubheading Options provided
1366
1367
@table @code
1368
1369
@item muse-journal-heading-regexp
1370
A regexp that matches a journal heading.
1371
1372
Paren group 1 is the ISO date, group 2 is the optional category, and
1373
group 3 is the optional heading for the entry.
1374
1375
@item muse-journal-date-format
1376
Date format to use for journal entries.
1377
1378
@item muse-journal-html-heading-regexp
1379
A regexp that matches a journal heading from an HTML document.
1380
1381
Paren group 1 is the ISO date, group 2 is the optional category, and
1382
group 3 is the optional heading for the entry.
1383
1384
@item muse-journal-html-entry-template
1385
Template used to publish individual journal entries as HTML.
1386
1387
@item muse-journal-latex-section
1388
Template used to publish a LaTeX section.
1389
1390
@item muse-journal-latex-subsection
1391
Template used to publish a LaTeX subsection.
1392
1393
@item muse-journal-latex-markup-tags
1394
A list of tag specifications, for specially marking up LaTeX.
1395
1396
@xref{muse-publish-markup-tags}, for more information.
1397
1398
@item muse-journal-rdf-extension
1399
Default file extension for publishing RDF (RSS 1.0) files.
1400
1401
@item muse-journal-rdf-base-url
1402
The base URL of the website referenced by the RDF file.
1403
1404
@item muse-journal-rdf-header
1405
Header used for publishing RDF (RSS 1.0) files.
1406
1407
This may be text or a filename.
1408
1409
@item muse-journal-rdf-footer
1410
Footer used for publishing RDF (RSS 1.0) files.
1411
1412
This may be text or a filename.
1413
1414
@item muse-journal-rdf-date-format
1415
Date format to use for RDF entries.
1416
1417
@item muse-journal-rdf-entry-template
1418
Template used to publish individual journal entries as RDF.
1419
1420
@item muse-journal-rdf-summarize-entries
1421
If non-nil, include only summaries in the RDF file, not the full data.
1422
1423
@item muse-journal-rss-extension
1424
Default file extension for publishing RSS 2.0 files.
1425
1426
@item muse-journal-rss-base-url
1427
The base URL of the website referenced by the RSS file.
1428
1429
@item muse-journal-rss-header
1430
Header used for publishing RSS 2.0 files.
1431
1432
This may be text or a filename.
1433
1434
@item muse-journal-rss-footer
1435
Footer used for publishing RSS 2.0 files.
1436
1437
This may be text or a filename.
1438
1439
@item muse-journal-rss-date-format
1440
Date format to use for RSS 2.0 entries.
1441
1442
@item muse-journal-rss-entry-template
1443
Template used to publish individual journal entries as RSS 2.0.
1444
1445
@item muse-journal-rss-enclosure-types-alist
1446
File types that are accepted as RSS enclosures.
1447
1448
This is an alist that maps file extension to content type.
1449
1450
Useful for podcasting.
1451
1452
@item muse-journal-rss-summarize-entries
1453
If non-nil, include only summaries in the RSS file, not the full data.
1454
1455
Many RSS subscribers find this annoying.
1456
1457
@item muse-journal-rss-markup-regexps
1458
List of markup rules for publishing a Muse journal page to RSS.
1459
1460
For more information on the structure of this list,
1461
@xref{muse-publish-markup-regexps}.
1462
1463
@item muse-journal-rss-markup-functions
1464
An alist of style types to custom functions for that kind of text.
1465
1466
For more on the structure of this list,
1467
@xref{muse-publish-markup-functions}.
1468
1469
@end table
1470
1471
@node LaTeX, Poem, Journal, Publishing Styles
1472
@comment node-name, next, previous, up
1473
@section Publishing LaTeX documents
1474
1475
This publishing style is capable of producing LaTeX or PDF documents.
1476
1477
If you wish to publish PDF documents, you will need to have a good TeX
1478
installation. For Debian, this can be accomplished by installing the
1479
``tetex-bin'' and ``tetex-extra'' packages. TeX fonts are also a must.
1480
1481
@subsubheading Styles provided
1482
1483
@table @code
1484
1485
@cindex publishing styles, latex
1486
@item latex
1487
Publish a LaTeX document.
1488
1489
@cindex publishing styles, pdf
1490
@item pdf
1491
Publish a PDF document, using an external LaTeX document conversion
1492
tool.
1493
1494
@cindex publishing styles, latexcjk
1495
@item latexcjk
1496
Publish a LaTeX document with CJK (Chinese) encodings.
1497
1498
@cindex publishing styles, pdfcjk
1499
@item pdfcjk
1500
Publish a PDF document with CJK (Chinese) encodings, using an external
1501
LaTeX document conversion tool.
1502
1503
@end table
1504
1505
@subsubheading Options provided
1506
1507
@table @code
1508
1509
@item muse-latex-extension
1510
Default file extension for publishing LaTeX files.
1511
1512
@item muse-latex-pdf-extension
1513
Default file extension for publishing LaTeX files to PDF.
1514
1515
@item muse-latex-header
1516
Header used for publishing LaTeX files.
1517
1518
This may be text or a filename.
1519
1520
@item muse-latex-footer
1521
Footer used for publishing LaTeX files.
1522
1523
This may be text or a filename.
1524
1525
@item muse-latexcjk-header
1526
Header used for publishing LaTeX files (CJK).
1527
1528
This may be text or a filename.
1529
1530
@item muse-latexcjk-footer
1531
Footer used for publishing LaTeX files (CJK).
1532
1533
This may be text or a filename.
1534
1535
@item muse-latex-markup-regexps
1536
List of markup regexps for identifying regions in a Muse page.
1537
1538
For more on the structure of this list,
1539
@xref{muse-publish-markup-regexps}.
1540
1541
@item muse-latex-markup-functions
1542
An alist of style types to custom functions for that kind of text.
1543
1544
For more on the structure of this list,
1545
@xref{muse-publish-markup-functions}.
1546
1547
@item muse-latex-markup-strings
1548
Strings used for marking up text.
1549
1550
These cover the most basic kinds of markup, the handling of which
1551
differs little between the various styles.
1552
1553
@item muse-latexcjk-encoding-map
1554
An alist mapping emacs coding systems to appropriate CJK codings.
1555
Use the base name of the coding system (ie, without the -unix).
1556
1557
@item muse-latexcjk-encoding-default
1558
The default Emacs buffer encoding to use in published files.
1559
1560
This will be used if no special characters are found.
1561
1562
@item muse-latex-markup-specials
1563
A table of characters which must be represented specially.
1564
1565
@end table
1566
1567
@node Poem, Texinfo, LaTeX, Publishing Styles
1568
@comment node-name, next, previous, up
1569
@section Publish a poem to LaTex or PDF
1570
1571
The @code{muse-poem} module makes it easy to attractively publish and
1572
reference poems in the following format, using the "memoir" module for
1573
LaTeX publishing. It will also markup poems for every other output
1574
style, though none are nearly as pretty.
1575
1576
@example
1577
Title
1578
1579
1580
Body of poem
1581
1582
1583
Annotations, history, notes, etc.
1584
@end example
1585
1586
Once a poem is written in this format, just publish it to PDF using the
1587
@code{poem-pdf} style. To make an inlined reference to a poem that
1588
you've written -- for example, from a blog page -- there is a "poem" tag
1589
defined by this module.
1590
1591
@example
1592
<poem title="name.of.poem.page">
1593
@end example
1594
1595
Let's assume the template above was called @file{name.of.poem.page};
1596
then the above tag would result in this inclusion.
1597
1598
@example
1599
** Title
1600
1601
> Body of poem
1602
@end example
1603
1604
John Wiegley uses this module for publishing all of the poems on his
1605
website, which are at
1606
@uref{http://www.newartisans.com/johnw/poems.html}.
1607
1608
@subsubheading Styles provided
1609
1610
@table @code
1611
1612
@cindex publishing styles, poem-latex
1613
@item poem-latex
1614
Publish a poem in LaTeX form.
1615
1616
@cindex publishing styles, poem-pdf
1617
@item poem-pdf
1618
Publish a poem to a PDF document.
1619
1620
@cindex publishing styles, chapbook-latex
1621
@item chapbook-latex
1622
Publish a book of poems in LaTeX form.
1623
1624
@cindex publishing styles, chapbook-pdf
1625
@item chapbook-pdf
1626
Publish a book of poems to a PDF document.
1627
1628
@end table
1629
1630
@subsubheading Options provided
1631
1632
@table @code
1633
1634
@item muse-poem-latex-header
1635
Header used for publishing LaTeX poems.
1636
1637
This may be text or a filename.
1638
1639
@item muse-poem-latex-footer
1640
Footer used for publishing LaTeX files.
1641
1642
This may be text or a filename.
1643
1644
@item muse-poem-markup-strings
1645
Strings used for marking up poems.
1646
1647
These cover the most basic kinds of markup, the handling of which
1648
differs little between the various styles.
1649
1650
@item muse-chapbook-latex-header
1651
Header used for publishing a book of poems in LaTeX form.
1652
1653
This may be text or a filename.
1654
1655
@item muse-chapbook-latex-footer
1656
Footer used for publishing a book of poems in LaTeX form.
1657
1658
This may be text or a filename.
1659
1660
@item muse-poem-chapbook-strings
1661
Strings used for marking up books of poems.
1662
1663
These cover the most basic kinds of markup, the handling of which
1664
differs little between the various styles.
1665
1666
@end table
1667
1668
@node Texinfo, Common Elements, Poem, Publishing Styles
1669
@comment node-name, next, previous, up
1670
@section Publish entries to Texinfo format or PDF
1671
1672
Rules for publishing a Muse file as a Texinfo article.
1673
1674
@subsubheading Styles provided
1675
1676
@table @code
1677
1678
@cindex publishing styles, texi
1679
@item texi
1680
Publish a file in Texinfo form.
1681
1682
@cindex publishing styles, texi
1683
@item info
1684
Generate an Info file from a Muse file.
1685
1686
@cindex publishing styles, info-pdf
1687
@item info-pdf
1688
Publish a file in PDF form.
1689
1690
@end table
1691
1692
@subsubheading Options provided
1693
1694
@table @code
1695
1696
@item muse-texinfo-process-natively
1697
If non-nil, use the Emacs `texinfmt' module to make Info files.
1698
1699
@item muse-texinfo-extension
1700
Default file extension for publishing Texinfo files.
1701
1702
@item muse-texinfo-info-extension
1703
Default file extension for publishing Info files.
1704
1705
@item muse-texinfo-pdf-extension
1706
Default file extension for publishing PDF files.
1707
1708
@item muse-texinfo-header
1709
Text to prepend to a Muse page being published as Texinfo.
1710
1711
This may be text or a filename.
1712
It may contain @verb{|<lisp>|} markup tags.
1713
1714
@item muse-texinfo-footer
1715
Text to append to a Muse page being published as Texinfo.
1716
1717
This may be text or a filename.
1718
It may contain @verb{|<lisp>|} markup tags.
1719
1720
@item muse-texinfo-markup-regexps
1721
List of markup rules for publishing a Muse page to Texinfo.
1722
1723
For more on the structure of this list,
1724
@xref{muse-publish-markup-regexps}.
1725
1726
@item muse-texinfo-markup-functions
1727
An alist of style types to custom functions for that kind of text.
1728
1729
For more on the structure of this list, see
1730
@xref{muse-publish-markup-functions}.
1731
1732
@item muse-texinfo-markup-strings
1733
Strings used for marking up text.
1734
1735
These cover the most basic kinds of markup, the handling of which
1736
differs little between the various styles.
1737
1738
@item muse-texinfo-markup-specials
1739
A table of characters which must be represented specially.
1740
1741
@end table
1742
1743
@node Common Elements, Deriving Styles, Texinfo, Publishing Styles
1744
@comment node-name, next, previous, up
1745
@section Common functionality shared by styles
1746
@cindex publishing styles, common
1747
1748
@menu
1749
* Markup Functions:: Specifying functions to marking up text.
1750
* Markup Regexps:: Markup rules for publishing.
1751
* Markup Strings:: Strings specific to a publishing style.
1752
* Markup Tags:: Tag specifications for special markup.
1753
* Style Elements:: Parameters used for defining styles.
1754
@end menu
1755
1756
@node Markup Functions, Markup Regexps, , Common Elements
1757
@comment node-name, next, previous, up
1758
@subsection Specifying functions to mark up text
1759
@cindex publishing, markup functions
1760
1761
@anchor{muse-publish-markup-functions}
1762
@code{muse-publish-markup-functions}
1763
1764
An alist of style types to custom functions for that kind of text.
1765
1766
This is used by publishing styles to attempt to minimize the amount of
1767
custom regexps that each has to define. @file{muse-publish} provides
1768
rules for the most common types of markup.
1769
1770
Each member of the list is of the following form.
1771
1772
@example
1773
(SYMBOL FUNCTION)
1774
@end example
1775
1776
@itemize @bullet
1777
@item SYMBOL
1778
Describes the type of text to associate with this rule.
1779
@code{muse-publish-markup-regexps} maps regexps to these symbols.
1780
1781
@item FUNCTION
1782
Function to use to mark up this kind of rule if no suitable function is
1783
found through the @option{:functions} tag of the current style.
1784
@end itemize
1785
1786
@node Markup Regexps, Markup Strings, Markup Functions, Common Elements
1787
@comment node-name, next, previous, up
1788
@subsection Markup rules for publishing
1789
@cindex publishing, markup regexps
1790
@cindex publishing, rules
1791
1792
@anchor{muse-publish-markup-regexps}
1793
@code{muse-publish-markup-regexps}
1794
1795
List of markup rules for publishing a page with Muse.
1796
1797
The rules given in this variable are invoked first, followed by whatever
1798
rules are specified by the current style.
1799
1800
Each member of the list is either a function, or a list of the following
1801
form.
1802
1803
@example
1804
(REGEXP/SYMBOL TEXT-BEGIN-GROUP REPLACEMENT-TEXT/FUNCTION/SYMBOL)
1805
@end example
1806
1807
@itemize @bullet
1808
@item REGEXP
1809
A regular expression, or symbol whose value is a regular expression,
1810
which is searched for using `re-search-forward'.
1811
1812
@item TEXT-BEGIN-GROUP
1813
The matching group within that regexp which denotes the beginning of the
1814
actual text to be marked up.
1815
1816
@item REPLACEMENT-TEXT
1817
A string that will be passed to `replace-match'.
1818
1819
If it is not a string, but a function, it will be called to determine
1820
what the replacement text should be (it must return a string). If it is
1821
a symbol, the value of that symbol should be a string.
1822
@end itemize
1823
1824
The replacements are done in order, one rule at a time. Writing
1825
the regular expressions can be a tricky business. Note that case
1826
is never ignored. `case-fold-search' is always bound to nil
1827
while processing the markup rules.
1828
1829
@subsubheading Publishing order
1830
1831
This is the order that the publishing rules are consulted, by default.
1832
This may be changed by customizing @code{muse-publish-markup-regexps}.
1833
1834
@table @code
1835
1836
@item trailing and leading whitespace
1837
Remove trailing and leading whitespace from a file.
1838
1839
@item directive
1840
@samp{#directive}
1841
1842
This is only recognized at the beginning of a file.
1843
1844
@item tag
1845
@samp{<tag>}
1846
1847
@item comment
1848
@samp{; comment}
1849
1850
@item anchor
1851
@samp{#anchor}
1852
1853
@item explicit links
1854
Prevent emphasis characters in explicit links from being marked up.
1855
1856
Don't actually publish them here, just add a special no-emphasis text
1857
property.
1858
1859
@item word
1860
Whitespace-delimited word, possibly with emphasis characters
1861
1862
This function is responsible for marking up emphasis and escaping some
1863
specials.
1864
1865
@item emdash
1866
@samp{--}
1867
1868
2-wide dash
1869
1870
@item heading
1871
@samp{** Heading}
1872
1873
Outline-mode style headings.
1874
1875
@item enddots
1876
@samp{....}
1877
1878
These are ellipses with a dot at end.
1879
1880
@item dots
1881
@samp{...}
1882
1883
Ellipses.
1884
1885
@item rule
1886
@samp{----}
1887
1888
Horizontal rule or section separator.
1889
1890
@item fn-sep
1891
@samp{Footnotes:}
1892
1893
beginning of footnotes section
1894
1895
@item footnote
1896
@samp{[1]}
1897
1898
Footnote definition or reference. If at beginning of line, it is a
1899
definition.
1900
1901
@item list
1902
@itemize @bullet
1903
@item
1904
@samp{ 1. }
1905
1906
@item
1907
@samp{ - }
1908
1909
@item
1910
@samp{term :: }
1911
@end itemize
1912
1913
Numbered list, item list, or term definition list.
1914
1915
@item quote
1916
spaces before beginning of text
1917
1918
Blockquotes.
1919
1920
@item verse
1921
@samp{> verse text}
1922
1923
@item table
1924
@samp{table | cells}
1925
1926
@item link
1927
@samp{[[explicit][links]]}
1928
1929
@item url
1930
@samp{http://example.com/}
1931
1932
@item email
1933
@samp{bare-email@@example.com}
1934
1935
@end table
1936
1937
@node Markup Strings, Markup Tags, Markup Regexps, Common Elements
1938
@comment node-name, next, previous, up
1939
@subsection Strings specific to a publishing style
1940
@cindex publishing, markup strings
1941
1942
@dfn{Markup strings} are strings used for marking up text for a
1943
particular style.
1944
1945
These cover the most basic kinds of markup, the handling of which
1946
differs little between the various styles.
1947
1948
@subsubheading Available markup strings
1949
1950
@table @code
1951
1952
@item image-with-desc
1953
An image and a description.
1954
1955
Argument 1: image. Argument 2: description.
1956
1957
@item image-link
1958
A link to an image.
1959
1960
Argument 1: image link.
1961
1962
@item url-with-image
1963
A URL with an image.
1964
1965
Argument 1: link. Argument 2: image.
1966
1967
@item url-link
1968
A link with a description.
1969
1970
Argument 1: link. Argument 2: description if one exists, or the
1971
original link otherwise.
1972
1973
@item internal-link
1974
A link that refers to an internal anchor.
1975
1976
Argument 1: internal link. Argument 2: description if one exists, or
1977
the original link otherwise.
1978
1979
@item email-addr
1980
A link to an email address.
1981
1982
Argument 1: email address. Argument 2: email address.
1983
1984
@item emdash
1985
A 2-length dash.
1986
1987
@item rule
1988
A horizontal line or space.
1989
1990
@item footnote
1991
Beginning of footnote.
1992
1993
@item footnote-end
1994
End of footnote.
1995
1996
@item footnotemark
1997
Mark a reference for the current footnote.
1998
1999
Argument 1: number of this footnote.
2000
2001
@item footnotetext
2002
Indicate the text of the current footnote.
2003
2004
Argument 1: number of this footnote.
2005
2006
@item footnotetext-end
2007
End of a footnote text line.
2008
2009
@item fn-sep
2010
Text used to replace ``Footnotes:'' line.
2011
2012
@item enddots
2013
4 dots.
2014
2015
@item dots
2016
3 dots.
2017
2018
@item part
2019
Beginning of a part indicator line. This is used by book publishing.
2020
2021
@item part-end
2022
End of a part indicator line. This is used by book publishing.
2023
2024
@item chapter
2025
Beginning of a chapter indicator line. This is used by book publishing.
2026
2027
@item chapter-end
2028
End of a chapter indicator line. This is used by book publishing.
2029
2030
@item section
2031
Beginning of level 1 section indicator line.
2032
2033
Argument 1: level of section; always 1.
2034
2035
@item section-end
2036
End of level 1 section indicator line.
2037
2038
Argument 1: level of section; always 1.
2039
2040
@item subsection
2041
Beginning of level 2 section indicator line.
2042
2043
Argument 1: level of section; always 2.
2044
2045
@item subsection-end
2046
End of level 2 section indicator line.
2047
2048
Argument 1: level of section; always 2.
2049
2050
@item subsubsection
2051
Beginning of level 3 section indicator line.
2052
2053
Argument 1: level of section; always 3.
2054
2055
@item subsubsection-end
2056
End of level 3 section indicator line.
2057
2058
Argument 1: level of section; always 3.
2059
2060
@item section-other
2061
Beginning of section indicator line, where level is greater than 3.
2062
2063
Argument 1: level of section.
2064
2065
@item section-other-end
2066
Beginning of section indicator line, where level is greater than 3.
2067
2068
Argument 1: level of section.
2069
2070
@item begin-underline
2071
Beginning of underlined text.
2072
2073
@item end-underline
2074
End of underlined text.
2075
2076
@item begin-literal
2077
Beginning of verbatim text. This includes @verb{|<code>|} tags and
2078
=teletype text=.
2079
2080
@item end-literal
2081
End of verbatim text. This includes @verb{|<code>|} tags and =teletype
2082
text=.
2083
2084
@item begin-emph
2085
Beginning of the first level of emphasized text.
2086
2087
@item end-emph
2088
End of the first level of emphasized text.
2089
2090
@item begin-more-emph
2091
Beginning of the second level of emphasized text.
2092
2093
@item end-more-emph
2094
End of the second level of emphasized text.
2095
2096
@item begin-most-emph
2097
Beginning of the third (and final) level of emphasized text.
2098
2099
@item end-most-emph
2100
End of the third (and final) level of emphasized text.
2101
2102
@item begin-verse
2103
Beginning of verse text.
2104
2105
@item verse-space
2106
String used to each space that is further indented than the beginning of
2107
the verse.
2108
2109
@item begin-verse-line
2110
Beginning of a line of verse.
2111
2112
@item empty-verse-line
2113
End of a line of verse.
2114
2115
@item begin-last-stanza-line
2116
Beginning of the last line of a verse stanza.
2117
2118
@item end-last-stanza-line
2119
End of the last line of a verse stanza.
2120
2121
@item end-verse
2122
End of verse text.
2123
2124
@item begin-example
2125
Beginning of an example region. To make use of this, an
2126
@samp{<example>} tag is needed.
2127
2128
@item end-example
2129
End of an example region. To make use of this, an @samp{</example>} tag
2130
is needed.
2131
2132
@item begin-center
2133
Begin a centered line.
2134
2135
@item end-center
2136
End a centered line.
2137
2138
@item begin-quote
2139
Begin a quoted region.
2140
2141
@item end-quote
2142
End a quoted region.
2143
2144
@item begin-uli
2145
Begin an unordered list.
2146
2147
@item end-uli
2148
End an unordered list.
2149
2150
@item begin-oli
2151
Begin an ordered list.
2152
2153
@item end-oli
2154
End an ordered list.
2155
2156
@item begin-ddt
2157
Begin a definition list.
2158
2159
@item start-dde
2160
Begin a term in a definition list.
2161
2162
@item end-ddt
2163
End a definition list.
2164
2165
@end table
2166
2167
@node Markup Tags, Style Elements, Markup Strings, Common Elements
2168
@comment node-name, next, previous, up
2169
@subsection Tag specifications for special markup
2170
@cindex publishing, markup tags
2171
2172
@anchor{muse-publish-markup-tags}
2173
@code{muse-publish-markup-tags}
2174
2175
A list of tag specifications, for specially marking up text.
2176
2177
XML-style tags are the best way to add custom markup to Muse. This is
2178
easily accomplished by customizing this list of markup tags.
2179
2180
For each entry, the name of the tag is given, whether it expects a
2181
closing tag and/or an optional set of attributes, and a function that
2182
performs whatever action is desired within the delimited region.
2183
2184
The tags themselves are deleted during publishing, before the function
2185
is called. The function is called with three arguments, the beginning
2186
and end of the region surrounded by the tags. If properties are
2187
allowed, they are passed as a third argument in the form of an alist.
2188
The `end' argument to the function is always a marker.
2189
2190
Point is always at the beginning of the region within the tags, when the
2191
function is called. Wherever point is when the function finishes is
2192
where tag markup will resume.
2193
2194
These tag rules are processed once at the beginning of markup, and once
2195
at the end, to catch any tags which may have been inserted in-between.
2196
2197
@node Style Elements, , Markup Tags, Common Elements
2198
@comment node-name, next, previous, up
2199
@subsection Parameters used for defining styles
2200
@cindex publishing, style elements
2201
2202
Style elements are tags that define a style. Use
2203
@code{muse-define-style} to create a new style.
2204
2205
@example
2206
(muse-define-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2207
@end example
2208
2209
@subsubheading Usable elements
2210
2211
@table @option
2212
2213
@item :suffix
2214
File extension to use for publishing files with this style.
2215
2216
@item :link-suffix
2217
File extension to use for publishing links to Muse files with this
2218
style.
2219
2220
@item :osuffix
2221
File extension to use for publishing second-stage files with this style.
2222
2223
For example, PDF publishing generates a LaTeX file first, then a PDF
2224
from that LaTeX file.
2225
2226
@item :regexps
2227
List of markup rules for publishing a page with Muse.
2228
@xref{muse-publish-markup-regexps}.
2229
2230
@item :functions
2231
An alist of style types to custom functions for that kind of text.
2232
@xref{muse-publish-markup-functions}.
2233
2234
@item :strings
2235
Strings used for marking up text with this style.
2236
2237
These cover the most basic kinds of markup, the handling of which
2238
differs little between the various styles.
2239
2240
@item :tags
2241
A list of tag specifications, used for handling extra tags.
2242
@xref{muse-publish-markup-tags}.
2243
2244
@item :specials
2245
A table of characters which must be represented specially.
2246
2247
@item :before
2248
A function that is to be executed on the newly-created publishing buffer
2249
(or the current region) before any publishing occurs.
2250
2251
This is used to set extra parameters that direct the publishing process.
2252
2253
@item :before-end
2254
A function that is to be executed on the publishing buffer (or the
2255
current region) immediately after applying all of the markup regexps.
2256
2257
This is used to fix the order of table elements (header, footer, body)
2258
in XML-ish styles.
2259
2260
@item :after
2261
A function that is to be executed on the publishing buffer after
2262
:before-end, and immediately after inserting the header and footer.
2263
2264
This is used for generating the table of contents as well as setting the
2265
file coding system.
2266
2267
@item :final
2268
A function that is to be executed after saving the published file, but
2269
while still in its buffer.
2270
2271
This is used for generating second-stage documents like PDF files from
2272
just-published LaTeX files.
2273
2274
@item :header
2275
Header used for publishing files of this style.
2276
2277
This may be text or a filename. It is inserted at the beginning of a
2278
file, after evaluating the publishing markup.
2279
2280
@item :footer
2281
Footer used for publishing files of this style.
2282
2283
This may be text or a filename. It is inserted at the end of a file,
2284
after evaluating the publishing markup.
2285
2286
@item :browser
2287
The function used to browse the published result of files of this style.
2288
2289
@end table
2290
2291
@node Deriving Styles, , Common Elements, Publishing Styles
2292
@comment node-name, next, previous, up
2293
@section Deriving a new style from an existing one
2294
@cindex publishing styles, deriving
2295
2296
To create a new style from an existing one, use @code{muse-derive-style}
2297
as follows. This is a good way to fix something you don't like about a
2298
particular publishing style, or to personalize it.
2299
2300
@example
2301
(muse-derive-style DERIVED-NAME BASE-NAME STYLE-PARAMETERS)
2302
@end example
2303
2304
The derived name is a string defining the new style, such as "my-html".
2305
The base name must identify an existing style, such as "html" -- if you
2306
have loaded @file{muse-html}. The style parameters are the same as
2307
those used to create a style, except that they override whatever
2308
definitions exist in the base style. However, some definitions only
2309
partially override. The following parameters support partial
2310
overriding.
2311
2312
@xref{Style Elements}, for a complete list of all parameters.
2313
2314
@table @option
2315
2316
@item :functions
2317
If a markup function is not found in the derived style's function list,
2318
the base style's function list will be queried.
2319
2320
@item :regexps
2321
All regexps in the current style and the base style(s) will be used.
2322
2323
@item :strings
2324
If a markup string is not found in the derived style's string list, the
2325
base style's string list will be queried.
2326
2327
@end table
2328
2329
2330
@node Getting Help and Reporting Bugs, History, Publishing Styles, Top
2331
@comment node-name, next, previous, up
2332
@chapter Getting Help and Reporting Bugs
2333
@cindex help, getting
2334
@cindex bugs, reporting
2335
2336
After you have read this guide, if you still have questions about
2337
Muse, or if you have bugs to report, there are several places you can
2338
go.
2339
2340
@itemize @bullet
2341
2342
@item
2343
@uref{http://www.emacswiki.org/cgi-bin/wiki/MuseMode} is the
2344
emacswiki.org page, and anyone may add tips, hints, or bug descriptions
2345
to it.
2346
2347
@item
2348
@uref{http://www.mwolson.org/projects/MuseMode.html} is the web page
2349
that Michael Olson (the current maintainer) made for Muse.
2350
2351
@item
2352
You can join the mailing list at @email{emacs-wiki-discuss@@nongnu.org}
2353
using the subscription form at
2354
@uref{http://mail.nongnu.org/mailman/listinfo/ emacs-wiki-discuss}.
2355
This mailing list provides support for Muse, @command{Planner} and
2356
@command{emacs-wiki}, which is the predecessor of Muse.
2357
2358
There are additional methods for accessing the mailing list, adding
2359
content to it, and searching it. Consult
2360
@uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsWikiMailingList} for
2361
more information.
2362
2363
@item
2364
You can visit the IRC Freenode channel @samp{#emacs}. Many of the
2365
contributors are frequently around and willing to answer your
2366
questions. The @samp{#muse} channel is also available for
2367
Muse-specific help, and its current maintainer hangs out there.
2368
2369
@item
2370
The maintainer of MuseMode, Michael Olson, may be contacted at
2371
@email{mwolson@@gnu.org}.
2372
2373
@end itemize
2374
2375
@node History, Contributors, Getting Help and Reporting Bugs, Top
2376
@comment node-name, next, previous, up
2377
@chapter History of This Document
2378
@cindex history, of Muse
2379
2380
@itemize
2381
@item 2004
2382
John Wiegley started Muse upon realizing that EmacsWiki had some serious
2383
limitations. Around February 2004, he started making "emacs-wiki version
2384
3.00 APLHA", which eventually became known as Muse.
2385
2386
Most of those who frequent the emacs-wiki mailing list continued to use
2387
emacs-wiki, mainly because Planner hasn't been ported over to it.
2388
2389
As of 2004-12-01, Michael Olson became the maintainer of Muse, as per
2390
John Wiegley's request.
2391
2392
@item 2005
2393
Michael Olson overhauled this document and added many new sections in
2394
preparation for the first release of Muse (3.01).
2395
2396
@end itemize
2397
2398
@node Contributors, GNU General Public License, History, Top
2399
@comment node-name, next, previous, up
2400
@chapter Contributors to This Documentation
2401
@cindex contributors
2402
2403
The first draft of this document was taken from the emacs-wiki texinfo
2404
manual. Michael Olson adapted it for Muse and added most of its
2405
content.
2406
2407
John Sullivan did a majority of the work on the emacs-wiki texinfo
2408
manual.
2409
2410
While Sacha Chua maintained emacs-wiki, she worked quite a bit on the
2411
emacs-wiki texinfo manual.
2412
2413
@node GNU General Public License, Concept Index, Contributors, Top
2414
@comment node-name, next, previous, up
2415
@appendix GNU GENERAL PUBLIC LICENSE
2416
@center Version 2, June 1991
2417
@cindex GPL
2418
@cindex GNU General Public License
2419
2420
@c This file is intended to be included in another file.
2421
2422
@display
2423
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
2424
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2425
2426
Everyone is permitted to copy and distribute verbatim copies
2427
of this license document, but changing it is not allowed.
2428
@end display
2429
2430
@appendixsec Preamble
2431
2432
The licenses for most software are designed to take away your
2433
freedom to share and change it. By contrast, the GNU General Public
2434
License is intended to guarantee your freedom to share and change free
2435
software---to make sure the software is free for all its users. This
2436
General Public License applies to most of the Free Software
2437
Foundation's software and to any other program whose authors commit to
2438
using it. (Some other Free Software Foundation software is covered by
2439
the GNU Library General Public License instead.) You can apply it to
2440
your programs, too.
2441
2442
When we speak of free software, we are referring to freedom, not
2443
price. Our General Public Licenses are designed to make sure that you
2444
have the freedom to distribute copies of free software (and charge for
2445
this service if you wish), that you receive source code or can get it
2446
if you want it, that you can change the software or use pieces of it
2447
in new free programs; and that you know you can do these things.
2448
2449
To protect your rights, we need to make restrictions that forbid
2450
anyone to deny you these rights or to ask you to surrender the rights.
2451
These restrictions translate to certain responsibilities for you if you
2452
distribute copies of the software, or if you modify it.
2453
2454
For example, if you distribute copies of such a program, whether
2455
gratis or for a fee, you must give the recipients all the rights that
2456
you have. You must make sure that they, too, receive or can get the
2457
source code. And you must show them these terms so they know their
2458
rights.
2459
2460
We protect your rights with two steps: (1) copyright the software, and
2461
(2) offer you this license which gives you legal permission to copy,
2462
distribute and/or modify the software.
2463
2464
Also, for each author's protection and ours, we want to make certain
2465
that everyone understands that there is no warranty for this free
2466
software. If the software is modified by someone else and passed on, we
2467
want its recipients to know that what they have is not the original, so
2468
that any problems introduced by others will not reflect on the original
2469
authors' reputations.
2470
2471
Finally, any free program is threatened constantly by software
2472
patents. We wish to avoid the danger that redistributors of a free
2473
program will individually obtain patent licenses, in effect making the
2474
program proprietary. To prevent this, we have made it clear that any
2475
patent must be licensed for everyone's free use or not licensed at all.
2476
2477
The precise terms and conditions for copying, distribution and
2478
modification follow.
2479
2480
@iftex
2481
@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2482
@end iftex
2483
@ifinfo
2484
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2485
@end ifinfo
2486
2487
@enumerate 0
2488
@item
2489
This License applies to any program or other work which contains
2490
a notice placed by the copyright holder saying it may be distributed
2491
under the terms of this General Public License. The ``Program'', below,
2492
refers to any such program or work, and a ``work based on the Program''
2493
means either the Program or any derivative work under copyright law:
2494
that is to say, a work containing the Program or a portion of it,
2495
either verbatim or with modifications and/or translated into another
2496
language. (Hereinafter, translation is included without limitation in
2497
the term ``modification''.) Each licensee is addressed as ``you''.
2498
2499
Activities other than copying, distribution and modification are not
2500
covered by this License; they are outside its scope. The act of
2501
running the Program is not restricted, and the output from the Program
2502
is covered only if its contents constitute a work based on the
2503
Program (independent of having been made by running the Program).
2504
Whether that is true depends on what the Program does.
2505
2506
@item
2507
You may copy and distribute verbatim copies of the Program's
2508
source code as you receive it, in any medium, provided that you
2509
conspicuously and appropriately publish on each copy an appropriate
2510
copyright notice and disclaimer of warranty; keep intact all the
2511
notices that refer to this License and to the absence of any warranty;
2512
and give any other recipients of the Program a copy of this License
2513
along with the Program.
2514
2515
You may charge a fee for the physical act of transferring a copy, and
2516
you may at your option offer warranty protection in exchange for a fee.
2517
2518
@item
2519
You may modify your copy or copies of the Program or any portion
2520
of it, thus forming a work based on the Program, and copy and
2521
distribute such modifications or work under the terms of Section 1
2522
above, provided that you also meet all of these conditions:
2523
2524
@enumerate a
2525
@item
2526
You must cause the modified files to carry prominent notices
2527
stating that you changed the files and the date of any change.
2528
2529
@item
2530
You must cause any work that you distribute or publish, that in
2531
whole or in part contains or is derived from the Program or any
2532
part thereof, to be licensed as a whole at no charge to all third
2533
parties under the terms of this License.
2534
2535
@item
2536
If the modified program normally reads commands interactively
2537
when run, you must cause it, when started running for such
2538
interactive use in the most ordinary way, to print or display an
2539
announcement including an appropriate copyright notice and a
2540
notice that there is no warranty (or else, saying that you provide
2541
a warranty) and that users may redistribute the program under
2542
these conditions, and telling the user how to view a copy of this
2543
License. (Exception: if the Program itself is interactive but
2544
does not normally print such an announcement, your work based on
2545
the Program is not required to print an announcement.)
2546
@end enumerate
2547
2548
These requirements apply to the modified work as a whole. If
2549
identifiable sections of that work are not derived from the Program,
2550
and can be reasonably considered independent and separate works in
2551
themselves, then this License, and its terms, do not apply to those
2552
sections when you distribute them as separate works. But when you
2553
distribute the same sections as part of a whole which is a work based
2554
on the Program, the distribution of the whole must be on the terms of
2555
this License, whose permissions for other licensees extend to the
2556
entire whole, and thus to each and every part regardless of who wrote it.
2557
2558
Thus, it is not the intent of this section to claim rights or contest
2559
your rights to work written entirely by you; rather, the intent is to
2560
exercise the right to control the distribution of derivative or
2561
collective works based on the Program.
2562
2563
In addition, mere aggregation of another work not based on the Program
2564
with the Program (or with a work based on the Program) on a volume of
2565
a storage or distribution medium does not bring the other work under
2566
the scope of this License.
2567
2568
@item
2569
You may copy and distribute the Program (or a work based on it,
2570
under Section 2) in object code or executable form under the terms of
2571
Sections 1 and 2 above provided that you also do one of the following:
2572
2573
@enumerate a
2574
@item
2575
Accompany it with the complete corresponding machine-readable
2576
source code, which must be distributed under the terms of Sections
2577
1 and 2 above on a medium customarily used for software interchange; or,
2578
2579
@item
2580
Accompany it with a written offer, valid for at least three
2581
years, to give any third party, for a charge no more than your
2582
cost of physically performing source distribution, a complete
2583
machine-readable copy of the corresponding source code, to be
2584
distributed under the terms of Sections 1 and 2 above on a medium
2585
customarily used for software interchange; or,
2586
2587
@item
2588
Accompany it with the information you received as to the offer
2589
to distribute corresponding source code. (This alternative is
2590
allowed only for noncommercial distribution and only if you
2591
received the program in object code or executable form with such
2592
an offer, in accord with Subsection b above.)
2593
@end enumerate
2594
2595
The source code for a work means the preferred form of the work for
2596
making modifications to it. For an executable work, complete source
2597
code means all the source code for all modules it contains, plus any
2598
associated interface definition files, plus the scripts used to
2599
control compilation and installation of the executable. However, as a
2600
special exception, the source code distributed need not include
2601
anything that is normally distributed (in either source or binary
2602
form) with the major components (compiler, kernel, and so on) of the
2603
operating system on which the executable runs, unless that component
2604
itself accompanies the executable.
2605
2606
If distribution of executable or object code is made by offering
2607
access to copy from a designated place, then offering equivalent
2608
access to copy the source code from the same place counts as
2609
distribution of the source code, even though third parties are not
2610
compelled to copy the source along with the object code.
2611
2612
@item
2613
You may not copy, modify, sublicense, or distribute the Program
2614
except as expressly provided under this License. Any attempt
2615
otherwise to copy, modify, sublicense or distribute the Program is
2616
void, and will automatically terminate your rights under this License.
2617
However, parties who have received copies, or rights, from you under
2618
this License will not have their licenses terminated so long as such
2619
parties remain in full compliance.
2620
2621
@item
2622
You are not required to accept this License, since you have not
2623
signed it. However, nothing else grants you permission to modify or
2624
distribute the Program or its derivative works. These actions are
2625
prohibited by law if you do not accept this License. Therefore, by
2626
modifying or distributing the Program (or any work based on the
2627
Program), you indicate your acceptance of this License to do so, and
2628
all its terms and conditions for copying, distributing or modifying
2629
the Program or works based on it.
2630
2631
@item
2632
Each time you redistribute the Program (or any work based on the
2633
Program), the recipient automatically receives a license from the
2634
original licensor to copy, distribute or modify the Program subject to
2635
these terms and conditions. You may not impose any further
2636
restrictions on the recipients' exercise of the rights granted herein.
2637
You are not responsible for enforcing compliance by third parties to
2638
this License.
2639
2640
@item
2641
If, as a consequence of a court judgment or allegation of patent
2642
infringement or for any other reason (not limited to patent issues),
2643
conditions are imposed on you (whether by court order, agreement or
2644
otherwise) that contradict the conditions of this License, they do not
2645
excuse you from the conditions of this License. If you cannot
2646
distribute so as to satisfy simultaneously your obligations under this
2647
License and any other pertinent obligations, then as a consequence you
2648
may not distribute the Program at all. For example, if a patent
2649
license would not permit royalty-free redistribution of the Program by
2650
all those who receive copies directly or indirectly through you, then
2651
the only way you could satisfy both it and this License would be to
2652
refrain entirely from distribution of the Program.
2653
2654
If any portion of this section is held invalid or unenforceable under
2655
any particular circumstance, the balance of the section is intended to
2656
apply and the section as a whole is intended to apply in other
2657
circumstances.
2658
2659
It is not the purpose of this section to induce you to infringe any
2660
patents or other property right claims or to contest validity of any
2661
such claims; this section has the sole purpose of protecting the
2662
integrity of the free software distribution system, which is
2663
implemented by public license practices. Many people have made
2664
generous contributions to the wide range of software distributed
2665
through that system in reliance on consistent application of that
2666
system; it is up to the author/donor to decide if he or she is willing
2667
to distribute software through any other system and a licensee cannot
2668
impose that choice.
2669
2670
This section is intended to make thoroughly clear what is believed to
2671
be a consequence of the rest of this License.
2672
2673
@item
2674
If the distribution and/or use of the Program is restricted in
2675
certain countries either by patents or by copyrighted interfaces, the
2676
original copyright holder who places the Program under this License
2677
may add an explicit geographical distribution limitation excluding
2678
those countries, so that distribution is permitted only in or among
2679
countries not thus excluded. In such case, this License incorporates
2680
the limitation as if written in the body of this License.
2681
2682
@item
2683
The Free Software Foundation may publish revised and/or new versions
2684
of the General Public License from time to time. Such new versions will
2685
be similar in spirit to the present version, but may differ in detail to
2686
address new problems or concerns.
2687
2688
Each version is given a distinguishing version number. If the Program
2689
specifies a version number of this License which applies to it and ``any
2690
later version'', you have the option of following the terms and conditions
2691
either of that version or of any later version published by the Free
2692
Software Foundation. If the Program does not specify a version number of
2693
this License, you may choose any version ever published by the Free Software
2694
Foundation.
2695
2696
@item
2697
If you wish to incorporate parts of the Program into other free
2698
programs whose distribution conditions are different, write to the author
2699
to ask for permission. For software which is copyrighted by the Free
2700
Software Foundation, write to the Free Software Foundation; we sometimes
2701
make exceptions for this. Our decision will be guided by the two goals
2702
of preserving the free status of all derivatives of our free software and
2703
of promoting the sharing and reuse of software generally.
2704
2705
@iftex
2706
@heading NO WARRANTY
2707
@end iftex
2708
@ifinfo
2709
@center NO WARRANTY
2710
@end ifinfo
2711
2712
@item
2713
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2714
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2715
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2716
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2717
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2718
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
2719
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2720
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2721
REPAIR OR CORRECTION.
2722
2723
@item
2724
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2725
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2726
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2727
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2728
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2729
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2730
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2731
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2732
POSSIBILITY OF SUCH DAMAGES.
2733
@end enumerate
2734
2735
@iftex
2736
@heading END OF TERMS AND CONDITIONS
2737
@end iftex
2738
@ifinfo
2739
@center END OF TERMS AND CONDITIONS
2740
@end ifinfo
2741
2742
@page
2743
@appendixsec Appendix: How to Apply These Terms to Your New Programs
2744
2745
If you develop a new program, and you want it to be of the greatest
2746
possible use to the public, the best way to achieve this is to make it
2747
free software which everyone can redistribute and change under these terms.
2748
2749
To do so, attach the following notices to the program. It is safest
2750
to attach them to the start of each source file to most effectively
2751
convey the exclusion of warranty; and each file should have at least
2752
the ``copyright'' line and a pointer to where the full notice is found.
2753
2754
@smallexample
2755
@var{one line to give the program's name and a brief idea of what it does.}
2756
Copyright (C) @var{yyyy} @var{name of author}
2757
2758
This program is free software; you can redistribute it and/or modify
2759
it under the terms of the GNU General Public License as published by
2760
the Free Software Foundation; either version 2 of the License, or
2761
(at your option) any later version.
2762
2763
This program is distributed in the hope that it will be useful,
2764
but WITHOUT ANY WARRANTY; without even the implied warranty of
2765
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2766
GNU General Public License for more details.
2767
2768
You should have received a copy of the GNU General Public License along
2769
with this program; if not, write to the Free Software Foundation, Inc.,
2770
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2771
@end smallexample
2772
2773
Also add information on how to contact you by electronic and paper mail.
2774
2775
If the program is interactive, make it output a short notice like this
2776
when it starts in an interactive mode:
2777
2778
@smallexample
2779
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2780
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2781
This is free software, and you are welcome to redistribute it
2782
under certain conditions; type `show c' for details.
2783
@end smallexample
2784
2785
The hypothetical commands @samp{show w} and @samp{show c} should show
2786
the appropriate parts of the General Public License. Of course, the
2787
commands you use may be called something other than @samp{show w} and
2788
@samp{show c}; they could even be mouse-clicks or menu items---whatever
2789
suits your program.
2790
2791
You should also get your employer (if you work as a programmer) or your
2792
school, if any, to sign a ``copyright disclaimer'' for the program, if
2793
necessary. Here is a sample; alter the names:
2794
2795
@example
2796
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2797
`Gnomovision' (which makes passes at compilers) written by James Hacker.
2798
2799
@var{signature of Ty Coon}, 1 April 1989
2800
Ty Coon, President of Vice
2801
@end example
2802
2803
This General Public License does not permit incorporating your program into
2804
proprietary programs. If your program is a subroutine library, you may
2805
consider it more useful to permit linking proprietary applications with the
2806
library. If this is what you want to do, use the GNU Library General
2807
Public License instead of this License.
2808
2809
2810
@node Concept Index, , GNU General Public License, Top
2811
@comment node-name, next, previous, up
2812
@unnumbered Index
2813
2814
@printindex cp
2815
2816
@bye
2817
2818
@c Local Variables:
2819
@c ispell-local-pdict: "ispell-dict"
2820
@c End:
Loggerhead is a web-based interface for Breezy
Version: 2.0.1