Emacs Wiki
Introduction
Emacs Wiki is an editing mode, which allows one to create collections of hyperlinked documents - a Website - in a very intuitive way.
It is also the base for Planner a component of a PIM for Emacs, visit PlannerEtAl to read about the big picture.
This document was produced with EmacsWiki and should be available in the followint formats:
- Overview
- Markup - how to make it look nice
- Tags - Escaping and enhancing Markup
- Startup
- Editing Tips and Pitfalls
- Wiki Markup Quick Start
Overview
EmacsWiki is a Emacs mode for maintaining a local Wiki database.
Wiki's are a used for creating knowledge collections about a certain area, look at http://www.wikipedia.org for an impressive example. If you are interested in what is a Wiki anyway you should start reading at http://c2.com/cgi/wiki?WikiWikiWeb.
A Wiki is a hypertext and a content management system: Users are encouraged to enhance the hypertext by editing and refactoring existing wikis and by adding more pages. This is made easy by the way of writing the wiki pages. It is not as complicated as a markup language such as HTML. The general idea is to write plain ASCII text when editing, which is then marked up, following intuitive rules.
Normally a wiki is implemented as a CGI-Script with a database of Wiki pages in plain ASCII files, or other form of text storage like RDBMS or the like. Emacs Wiki uses plain-ascii files hold in one or more directories as the Wiki database. The collection of Wiki pages in these directories is called an Emacs Wiki project.
Emacs Wiki however is somewhat different to other Wikis. While it is possible to run a Webserver inside Emacs and serve the Wiki pages direct from there, the Emacs Wiki mode provides you with direct markup and hyperlinking from inside your Emacs buffers. So you can create and use several Wiki's for your only personal use, without ever publishing them on the web.
Another feature of Emacs Wiki is, that you can dump all Wiki pages in html format. This is called "publishing" the Wiki. What is yielded is a static view of your Wiki, which can be copied to a Webservers document tree. This snapshot of your Wiki however is not modifiable by visitors on the Web.
- Emacs Wiki is an editing mode to create and maintain a collection of hyperlinked plain-ascii documents.
- Emacs Wiki can publish this collection in HTML.
- Emacs Wiki can serve the Wiki on the wire, allowing remote colaborators to edit the documents.
WikiNames
Words with mixed case such as ThisOne are WikiNames1.WikiNames are links you can follow. If a page with that name exists, you will be taken there. If such a page does not exist, following the link will create a new page for you to fill. WikiNames for non-existing pages are rendered as links with class "nonexistent", and are also displayed in a warning color so that you can see whether following the link will lead you anywhere or not.
Markup - how to make it look nice
Here is a description of the default markup rules.
A horizontal rule can be created by putting four or more hyphens at the start of a line.
----
yielding:
a nice rule.
A reference2, which is just a number in square brackets: [2],
constitutes a footnote reference.
Footnotes: [2] Footnotes are defined by the same number in brackets occurring at the beginning of a line. Use footnote-mode's C-c ! a command, to very easily insert footnotes while typing. Use C-x C-x to return to the point of insertion.
The "Footnotes:" word on a line by itself is converted into a horizontal line, indicating the start of the footnote list. You usually put it on the bottom of your Wiki page but we put it here to show it just next to the example code.
[1] the mixed case notation is also sometimes called CamelCase.
[2] Footnotes are defined by the same number in brackets occurring at the beginning of a line. Use footnote-mode's C-c ! a command, to very easily insert footnotes while typing. Use C-x C-x to return to the point of insertion.
Headings
Headings are created by putting one or more * on the beginning of a line, followed by a a space and the text of the heading.
* First level ** Second level *** Third level
Note that the first level is actually indicated using H2, so that it doesn't appear at the same level as the page heading (which conceptually titles the section of that Wiki page).
Emphasis
*emphasis* - **strong emphasis** - ***very strong emphasis*** - _underlined text_ =verbatim/monotyped=
yields:
emphasis - strong emphasis - very strong emphasis - underlined text
verbatim/monotyped
Preventing markup
by putting an equal sign `=' around a couple of letters they are displayed =*verbatim*=. As you can note, the emphasis markup `*' has been ignored.
For larger blocks of text the <verbatim> tag should be used:
<verbatim>
The <verbatim> tag should be used for larger blocks of
text
</verbatim>.
yields:
The <verbatim> tag should be used for larger blocks of text .
The <verbatim> tag is also necessary to prevent some inline markup which can not be accounted for with the `=' markup. Comparte the Emacs Wiki source of this section with it's html output to get some ideas about it.
Paragraphs, centering and quotation
One or more blank lines separates paragraphs.
A line that begins with six or more columns of whitespace (made up of
tabs or spaces) indicates a centered paragraph. It's expected you
will use M-s to center the line, which usually
adds a lot of whitespace before it.
If a line begins with some whitespace, but less than six columns, it indicates a quoted paragraph.
Poetry requires that whitespace be preserved, without resorting to the monospace typical of <pre>. For this, the following special markup exists, which is reminiscent of e-mail quotations:
> A line of Emacs verse; > forgive its being so terse.
which yields:
A line of Emacs verse;
forgive its being so terse.
You can also use the <verse> tag, if you prefer:
<verse>
A line of Emacs verse;
forgive its being so terse.
</verse>
Giving us the following example:
A line of Emacs verse;
forgive its being so terse.
However (at this moment) the verse tag does not respect if it is nested inside quoted and centered environments.
Use the HTML tags <pre></pre> to insert a
paragraph and preserve whitespace. If you're inserting a block of
code, you will almost always want to use
<verbatim><
<example> Some literal text or code here. < /example>
Note that we put a space between the < and the / so you can see the
example, because there is now way to show the closing example tag
inside an example environment. You will of course use </example> in
your Wiki pages.
Lists
- bullet list 1. Enumerated list Term :: A definition list
will result in:
- bullet list
- Enumerated list
- Term
- A definition list
Blank lines between list elements are optional, but required between members of a definition list.
The numbering of en enumerated list is "fixed" by the HTML-code, so you can write any number followed by a point on the beginning of a line to get a numbered list.
Tables
There are two forms of table markup supported. If Takaaki Ota's table.el package is available, then simply create your tables using his package, and they will be rendered into the appropriate HTML.
If table.el is not available, then only very simple table markup is supported. The attributes of the table are kept in `emacs-wiki-table-attributes'. The syntax is:
Double bars || Separate header fields Single bars | Separate body fields Here are more | body fields Triple bars ||| Separate footer fields
| Double bars | Separate header fields |
|---|---|
| Single bars | Separate body fields |
| Here are more | body fields |
| Triple bars | Separate footer fields |
You can make a table just with single vertical bars, it will be surrounded by a simple border then. If you just put a space and a vertical bar in front of a line, a single column table will be created:
| a line in a box |
Other paragraph markup applies to both styles, meaning that if six or more columns of whitespace precedes the first line of the table, it will be centered, and if any whitespace at all precedes first line, it will occur in a blockquote.
Anchors and tagged links
If you begin a line with "#anchor" -- where anchor can be any word that doesn't contain whitespace -- it defines an anchor at that point into the document. This anchor text is not displayed.
You can reference an anchored point in another page (or even in the current page) using WikiName#anchor. The #anchor will never be displayed in HTML, whether at the point of definition or reference, but it will cause browsers to jump to that point in the document.
When you want to make a link to an anchor visible use an extended link.
Redirecting to another page or URL
Sometimes you may wish to redirect someone to another page. To do this, put:
<redirect url="http://somewhereelse.com"/>
at the top of the page. If the <redirect> tag specifies content, this will be used as the redirection message, rather than the default.
The numbers of seconds to delay is defined by `emacs-wiki-redirect-delay', which defaults to 2 seconds. The page shown will also contain a link to click on, for browsing which do not support automatic refreshing.
URLs
A regular URL is given as a link. If it's an image URL, it will be inlined using an IMG tag.
Embedded lisp
<lisp>(concat "This form gets" "inserted")</lisp>
will result in This form getsinserted.
Special handling of WikiNames
If you need to add a plural at the end of a WikiName, separate it with
four single quotes (WikiName''''s) or make it an
explicit link: ([[WikiName]]s).
To prevent a link name (of any type) from being treated as such, surround it with =equals= (to display it in monotype), or prefix it with the tag <nop> to escape it from WikiName markup.
Special Wiki links
Besides the normal WikiName type links, emacs-wiki also supports extended links and explicit links:
[[link text]]
[[link text][optional link description]]
If the optional link description is omitted, the link text is converted into an explicit link. An extended or explicit link is always a link, no matter how it looks. This means you can use any file in your `emacs-wiki-directories' as a Wiki file. If you provide an optional description, that's what will be shown instead of the link text. This is very useful for providing textual description of URLs. We call this type of links extended links.
See the documentation to emacs-wiki-image-regexp for how to inline files and images.
InterWiki names
There are times when you will want to constantly reference pages on another website. Rather than repeating the URL ad nauseum, you can define an InterWiki name. This is a set of WikiNames to URL correlations, that support textual substitution using #anchor names (which are appended to the URL). For example, MeatballWiki is defined in the variable `emacs-wiki-interwiki-names'. It means you can reference the page "MeatBall" on MeatballWiki using this syntax:
MeatballWiki#MeatBall
Giving us: MeatballWiki:MeatBall.
In the resulting HTML, the link is simply shown as
"MeatballWiki:MeatBall".
To define new InterWiki names you have to customize the variable 'emacs-wiki-interwiki-names'. Here is an example setup:
(defcustom emacs-wiki-interwiki-names
'(("GnuEmacs" . "http://www.gnu.org/software/emacs/emacs.html")
("TheEmacsWiki" .
(lambda (tag)
(concat "http://www.emacswiki.org/cgi-bin/wiki.pl?"
(or tag "SiteMap"))))
("MeatballWiki" .
(lambda (tag)
(concat "http://www.usemod.com/cgi-bin/mb.pl?"
(or tag "MeatballWiki")))))
The format of this variable is an alist, or series of cons cells. Each cons cell must be of the form:
(WIKINAME . STRING-OR-FUNCTION)
The second part of the cons cell may either be a STRING, which in most cases should be a URL, or a FUNCTION. If a function, it will be called with one argument: the tag applied to the Interwiki name, or nil if no tag was used. If the cdr was a STRING and a tag is used, the tag is simply appended.
Here are some examples:
(\"JohnWiki\" . \"http://alice.dynodns.net/wiki?\")
Referring to [[JohnWiki#EmacsModules]] then really means:
http://alice.dynodns.net/wiki?EmacsModules
If a function is used for the replacement text, you can get creative depending on what the tag is. Tags may contain any alphabetic character, any number, % or _. If you need other special characters, use % to specify the hex code, as in %2E. All browsers should support this.
Tags - Escaping and enhancing Markup
Here is a summary of the default tags. This includes the dangerous tags listed in `emacs-wiki-dangerous-tags', which may not be used by outsiders.
- verbatim
- Protects against highlighting and wiki interpretation, and escapes any characters which have special meaning to the publishing format. For HTML, this means characters like '<' are escaped as HTML entities.
- example
- Like verbatim, but typesets in HTML using the <pre> tag, with class=example, so whitespace formatting is preserved.
- nowiki
- Inhibits wiki markup, but does not do any escaping to the underlying publishing medium. Useful for embedding HTML, PHP, etc.
- verse
- Typesets like a normal paragraph, but without word-wrapping. That is, whitespace is preserved.
- redirect
- Using the "url" attribute, you can specify that a page should redirect to another page. The remaining contents of the page will not be published. The optional "delay" attribute specifies how long to wait before redirecting.
- nop
- When placed before a WikiLink, it will prevent that WikiLink from being treated as such. Good for names like DocBook.
- contents
- Produces a compact table of contents for any section heading at the same level or lower than the next section header encountered. Optional "depth" attribute specifies how deep the table of contents should go.
- lisp
- Evaluate the region as a Lisp form, and displays the result. When highlighting, the `display' text property is used, preserving y the underlying text. Turn off font-lock mode if you wish to edit it.
- command
- Pass the region to a command interpretor and insert the result, guarding it from any further expansion. Optional "file" attribute specifies the shell or interpretor to use. If none is given, and `emacs-wiki-command-tag-file' has not been configured, Eshell is used.
- python, perl
- Pass the region to the Python or Perl language interpretor, and insert the result.
- c-source
- Markup the region as C or C++ source code, using the c2html program, if available. Optional boolean attribute "numbered" will cause source lines to be numbered.
- Note: If c2html is not available, the region will be converted to HTML friendly text (i.e., <> turns into <>), and placed in a <pre> block. In this case, line numbering is not available.
- bookmarks
- Insert bookmarks at the location of the tag from the given bookmarks file. Required attribute "file" specifies which file to read from, and the optional attribute "type" may be one of: adr (for Opera), lynx, msie, ns, xbel or xmlproc. The default type is "xbel". The optional attribute "folder" may be used to specify which folder (and its children) should be inserted.
- Note that xml-parse.el version 1.5 (available from my website) and the xbel-utils package (available at least to Debian users) is required for this feature to work.
Inserting images
A link matching the regexp in the variable emacs-wiki-image-regex
will be published inline as an image. Remember that it must be matched
as a link first - so use either CamelCase or include a
leading slash - [[./text]]. An example:
[[./emacs_logo.png][The Emacs Wiki Logo]]
If you omit the description, the alt tag of the resulting HTML will be the name of the file.
Startup
To begin using emacs-wiki, put this in your .emacs file:
(load "emacs-wiki")
Now you can type M-x emacs-wiki-find-file, give
it a WikiName (or just hit return) and start typing!
You should also type M-x customize-group, and give the name
"emacs-wiki". Change it to suite your preferences. Each of the
options has its own documentation.
Keystroke summary
Here is a summary of keystrokes available in every Wiki buffer:
| Keystroke | Description |
|---|---|
| C-c C-a | jump to an index of all the Wiki pages |
| C-c C-b | show all pages that reference this page |
| C-c C-s | search for a word in your Wiki pages |
| C-c C-f | jump to another Wiki page; prompts for the name |
| C-c C-l | highlight/refresh the current buffer |
| C-c C-p | publish any Wiki pages that have changed as HTML |
| C-c C-r | rename wiki link at point |
| C-c C-v | change wiki project |
| C-c C-D | delete wiki link at point (binding will only work on X) |
| C-c = | diff this page against the last backup version |
| TAB | move to the next Wiki reference |
| S-TAB | move to the previous Wiki reference |
Using pcomplete
If you have pcomplete loaded, you can type M-TAB to complete Wiki names. Hitting M-TAB twice or more time in succession, will cycle through all of the possibilities. You can download pcomplete from John Wigleys Website: http://www.newartisans.com/johnw/emacs.html, however it is yet included in Gnu Emacs.
ChangeLog support
If you use a ChangeLog (C-x 4 a) within one of your Wiki directories, it will be used for notifying visitors to your wiki of recent changes.
Changing title or stylesheet
For convenience, if you want to change the visible title, or the stylesheet, used by a certain Wiki page during HTML publishing, just put:
#title Hello there #style hello.css
at the top of the page.
<a name="sec24" id="sec24"></a><lisp> tricks
<lisp></lisp> tags can be used, not only to evaluate forms for insertion at that point, but to influence the publishing process in many ways. Here's another way to change a page's stylesheet:
<lisp>
(ignore
;; use special.css for this Wiki page
(set (make-variable-buffer-local 'emacs-wiki-style-sheet)
"<link rel=\"stylesheet\" type=\"text/css\" href=\"special.css\" />"))
</lisp>
The 'ignore' is needed so nothing is inserted where the <lisp> tag occurred. Also, there should be no blank lines before or after the tag (to avoid empty paragraphs from being created). The best place to put this would be at the very top or bottom of the page.
Sub-lists?
There is no inherent support for sub-lists, since I couldn't think of a simple way to do it. But if you really need them, here's a trick you can use:
- Hello <ul> <li>There <li>My friend </ul>
Editing Tips and Pitfalls
The first character on the line plays an important role. If you write a paragraph with 'special' characters like *- or with numbers do not put these on the beginning of the line to be sure they are not marked up. You always can put one (1) space before them.
To edit a WikiName you go to the end of it, and delete backwards. This kills the ] at the end which is either inserted automatically when you type a Word in CamelCase
Always leave a blank line after a list (numbered or item) or the following paragraph will form part of the last list item. This is valid also for a horizontal line
A quoted paragraph needs at least two consecutive lines. If it only needs one line, break the paragraph manually.
Put #anchors right before the spot where you want to jump to.
To enlarge a Term :: definition with a second third, etc. paragraph,
use an empty definition, to start these, i.e. put two spaces and
:: in front of the second, third, etc. paragraph. However this will
not put an empty line between the paragraphs.
Take care with loose underscores _ as they mess up with the rest of the markup.
Wiki Markup Quick Start
---- - horizontal line
*emphasis*: emphasis
**strong**: strong
***very strong***: very strong
- item list
- second item
- item list
- second item
0. numbered list
0. you don't need to do the numbering yourselves.
- numbered list
- you don't need to do the numbering yourselves.
Double Colon
:: creates a definition term
- Double Colon
- creates a definition term
Two spaces at the beginning of a paragraphs lines make it quoted.
six or more spaces at the begginning of a line make it a centered paragraph
> on the beginnig of your text
> preserves your linebreaks
>and does this
>also on quoted
> and centered
> pyaragraphs
http://example.domain: is converted into a link
http://example.domain
Image URL's are inlined: http://www.emacswiki.org/emacs_logo.pngImage URL's are inlined:
Local Images are published with their filename -
[[./images/emacs_logo.png][Emacs Wiki Logo]]:
