DWiki pages are written in DWikiText, a simple way to add some
formatting information to the sort of ordinary text that you'd write
in a plain text email message. Indeed, DWikiText tries to understand a
lot of the obvious things that people put in plain text files and do
the right thing with them.

DWikiText is a sort of WikiText, the family of text formatting systems
used on Wikis in general; if you already know how wikis format text,
you're most of the way to understanding DWikiText.

If you want to see the raw DWikiText for any particular DWiki page,
you can use the 'View Source' link that's part of the Page Tools menu
at the bottom of most pages. (Directories don't have page source, and
you can't see the page source of a page that you can't access.)

Because it starts out as plain text, HTML and HTML characters in
DWikiText have no effect. You can include &'s and <'s and >'s and so
on without having to think about it. (This does mean that you can't
include your own HTML markup; the only way of formatting DWiki pages
is with DWikiText.)

Paragraphs

Paragraphs are the basic thing in DWikiText, and they're done the same
way as in plain text: lines of text, one after the other. The one
important thing is that the start of paragraphs are not indented at
all (this is common in plain text email, although not universal).

Paragraphs are separated from each other with blank lines. (In fact,
any time you want to be sure that you've ended something in DWikiText,
stick in a blank line.)

Forcing a line break

Sometimes you want to force a line break in the text. To do this, just
end a line with ' \\' (space backslash backslash).

Emphasis and Fonts

There are several ways to add different emphasis and fonts to text
by surrounding the text you want font-ized with special characters.
*Emphasis* produces emphasis; _typewriter_ produces
typewriter; ~~strong~~ produces strong. You can nest one
style inside another to produce, for example, monospaced strong
(although not all combinations come out in browsers). Doubled versions
are left untouched, instead of producing nothing, so '**' is **.

There are two additional special text styles: the code style
((...)) and the quoting style [[....|]]. The code style
produces typewriter text that takes the text literally (no other
fonts, no anything); it was used to write most of these examples. The
quoting style just writes the text literally without applying any
styling at all; it's what you need to use to get, for example, a
non-typewriter text '*'.

There is a small ambiguity with the quoting style, which will be
mentioned later.

Fonts end at the end of paragraphs, and in fact pretty much anywhere
where the type of thing in the page changes. This keeps an unclosed
font style from having a global document effect.
Global document effects are generally bad; no one wants one accident
to turn the rest of the page into italics. (ChrisSiebenmann has seen
it happen, and it's not pretty.)

Font heuristics

That was the simple version of the font rules. The reality is a bit more
complicated.

To save people from accidents, DWiki tries to be reasonably smart about
when emphasis and fonts start. The basic idea is that emphasis should
always have both an opening and a closing, and, apart from '_',
it surrounds words, so any apparent start of emphasis that is followed
by whitespace isn't actually one, and when DWiki looks ahead to make
sure the closing emphasis is there it ignores a closing character that
has whitespace in front of it.

In this case DWiki follows a rule Chris calls minimal span. The only
proper closing * is the last one, so the italics run from it
backwards to the '*an', the closest opening. The result is:

Consider 'Dict *a, *b;' to be an example.

Because DWiki looks ahead at the raw text, these heuristics can
be fooled if the *, ~~, or _ is inside a ((...)) or
a [[...]] and so on.

Once an emphasis has actually started it's ended by the first matching
emphasis character DWiki runs into, no matter whether it is preceded by
whitespace or not.

Because monospace is often used for very literal things, all that DWiki
asks is that the '_'s be paired up. Monospace runs do not have to
start or end next to words, and so there is no minimal span stuff.

Additional font styles through macros

There are three additional special things that you can do to text.
Because DWikiText has run out of good escape characters and they're
expected to be uncommon, they're done through macros (which are
discussed in more length later).

The ST macro allows the insertion of big text,
small text, strikethrough text,
superscripts, subscripts, or
underlined text. Because the text to be formatted is placed
inside the macro, only plain font styling can really be done to it.

Links

Straight URLs, written as text: http://www.google.com/; these are
always to some absolute place, for the obvious reason.

CamelCase words, which make links to other pages in the DWikiif
the pages exist.

Explicit links, written as [[<link>]], or [[<text>|<link>]],
or [[<text ...> <link>]], or even [[|<link>]].

For explicitly specified links [[...]] in general, the link can be
to some website, done with http:// as you'd expect, to some URL on the
website hosting the DWiki, done by putting < and > around the URL,
or to some other page on the DWiki (the default).

If it's not given explicit text, the name (the visible text) of a link
to a DWiki page is always the filename of the DWiki page (the last
component in the path), not its full path or the literal value of the
link. This keeps such names short and non-annoying, while still
useful. The exception is [[|<link>]], which uses the full text of the
link.

Explicitly given link text is run through DWiki's normal font styling
process; [[*Google*|http://www.google.com/]] will thus turn into
Google.

For links to other DWiki pages, ChrisSiebenmann tends to use CamelCase
words if that works out right (because they're very convenient) and
[[...]] if the right name for the target page isn't a CamelCase word,
or if it's in another directory and he doesn't feel like making a
global alias for it.

Interpreting wiki links

The DWiki path '/' is the wiki root, in an analogy to Unix and
URI/URL roots. An absolute wiki link starts with / and always refers to
that absolute DWiki page.

[[...]] links are considered relative by default (and can include
'..' and so on as desired), except that if there's no page by the
relative name and there is a page if we consider it an absolute link,
DWiki does so. (This keeps me from having to write / at the start of
all my absolute links in [[...]]'s.)

CamelCase links are considered absolute by default, but if the
absolute version isn't found and a relative version is, that gets
used. If neither is found, DWiki tries an alias directory if that's
configured, and if that fails the CamelCase word is not a link.

When generating the HTML for pages, DWiki transparently rewrites the
target of most links that point to DWiki redirection files to the
target of the redirection. (See RedirectFile for details on
what a redirection file is.)

Extending the link search path

If you make the text '#pragma search DIR DIR2 ...' the very first line
in a page, then links that can't be found through the normal searching
process will also be tried as if they were in DIR, DIR2, and so on.
The directories cannot be relative paths.

This is primarily handy for drafts of pages, which may be written in a
different directory from their final home; add a #pragma search
directive pointing to the final home, and any relative links should
still come up right.

Link abbreviations

Every time you give a [[...]] link both text and a link (with either
[[...|...]] or [[... ... ...]]), DWiki remembers the pairing of
the text and the link. Afterwards, you can use either as a link
abbreviation; it will expand to the full pair.

The (almost) unambiguous form is to use | at the start or the end of
the [[...]]: at the end to use the name of the link, at the end to
use the URL of the link (whichever is shorter).

Ambiguity: If you write [[<text>|]], and the <text> is a valid
name abbreviation, you get that, not the result of <text> with no
text styling at all.

You can write [[<text>]] without the |. This has to be a name
abbreviation, and only works if there are spaces in <text>, or
<text> isn't an absolute URL (http:// or with < and > around it)
and also isn't a real DWiki page.

Escaping things

The special handling of [[...]], ((...)), and http://foobar can all
be turned off by putting a ! in front of them. (Technically this
just escapes the start of the thing, leaving the rest of the text to
be styled normally.)

The only way to escape font styling is either ((...)) or [[...|]].

Macros (which look like {{....}} and will be discussed later) can
also be escaped this way.

Preformatted text

If you have a lot of completely preformatted text (perhaps a code
example), you just put a space in front of it. The result looks like
this:

If you have a lot of completely preformatted text (perhaps a code
example), you just put a space in front of it. The result looks like
this:

Relative indentation in the preformatted text is usually preserved.
(ChrisSiebenmann will figure out how to make this 'all the time'
sometime. The technical answer is 'everything past the first
whitespace character is preserved', and the problem there is tabs,
which count as one whitespace character.)

Headers

Headers are created by starting a line with between one or more =
characters; that line becomes a header. The more = characters, the
smaller a header it is: = is a HTML <h1>, while ====== is a <h6>.

Separator lines

Four or more dashes on a line, like so:

----

produce a horizontal cut line, like so:

If you don't like horizontal cut lines as separators, you can use the
alternate separator '* * *'. If you put this (possibly with more
white space between the *s) on a line by itself, you get this:

* * *

Some people like this as a less abrupt separator.

Quoting things

You can 'quote' wikitext like you would in email: stick '> ' in
front of everything you want to quote. Quotes nest. The usual visual
result in common browsers is that everything is shown indented:

Like this. Despite what the semantic markup people may tell you
about keeping HTML pure, feel free to use this deliberately to get
indentation. This effect can be used for other purposes, for example
really short horizontal cut lines:

Quoting stops when you stop putting the '> ' at the start of
lines.

Lists:

There are three sorts of lists: ordinary, numbered, and what HTML
calls 'definition lists' (created with <dl>, <dd>, and <dt>). They are
written as:

* an ordinary list entry.
0 A numbered list entry. Ordinary number lists can start with any
single digit.
# Also a numbered list entry.
- a definition list: please note that the colon is
*required*. Everything before the colon is the term; everything
afterwards is the definition. (The colon vanishes.)

These come out looking like:

an ordinary list entry.

A numbered list entry. Ordinary number lists can start with any
single digit.

Also a numbered list entry.

a definition list

please note that the colon is
required. Everything before the colon is the term; everything
afterwards is the definition. (The colon vanishes.)

List entries can continue across multiple lines; the rule for this is
that you must indent following lines, generally to at least the level
of the text on the first line.

Nested lists

The primary way of nesting lists is just to indent the nested lists in
the wikitest, like so:

* A list.
* a nested list.
* a more nested list.

If this is inconvenient to write, the nesting level of a list can also
be set by using more than one *, #, 0, or - character
at the start of the line (this doesn't work on indented nested
lists, where it will be taken as just a single level of nesting).

DWiki does the right thing if you change what type of list you're
using in the middle of nesting, or abruptly jump back several nesting
levels.

Tables

Tables are created by starting to write table rows. Table rows are
created by starting a line with a '| '; table cells are separated
from each other with ' | '. A table row is ended explicitly by
ending a line with ' |', or just implicitly by starting another
table row. To continue a table row on another line, just indent the
line (any amount will do).

If all of that sounds complicated, let's just look at an example:

| | left
| right |
| up | 10 | 20 |
| down | 30 | 40 |

Turns into:

left

right

up

10

20

down

30

40

A second type of tables is 'horizontal' tables, intended for situations
where the most of the commonality and comparison is within a row.
Horizontal tables are created by starting the first row with
'|_. ' instead of the regular '| '. Thus the same table as
above, started with a horizontal table start, turns into:

left

right

up

10

20

down

30

40

Macros

{{...}} is a macro. Macros are used to do special magic expansion
that doesn't fit within normal DWikiText processing. Macros can take
arguments, separated with :'s, as in {{DocAll:macros}}. Available
macros currently are:

AB: Generate an inline HTML <abbr> element. The first argument is
the abbreviation and the following arguments are the expansion.
Once the abbreviation has been used once, the expansion is optional.

AllPages: List all pages. Arguments are prefixes of page paths and page
names to restrict the list to. If you simply want to list all
pages under a particular directory, you should use AllPagesUnder
instead; it is more efficient (and more aesthetic).

AllPagesUnder: List all pages under a particular directory, in alphabetical
order. Page names are shown relative to this directory (eg 'fred'
instead of 'blog/fred' if blog is the directory). If there is no
argument, the directory is the current directory of this page; if
there is a single argument, it is the directory.

C: Insert a character entity. The character entity may be given as
a decimal number or as a HTML 4.01 character entity name. See the
ShowCharEnts macro for how to display the list of known character
entity names.

CanComment: Allow authenticated users to comment on a page. Arguments are
users to allow or deny access to, as with the Restricted macro.
A DWiki without authentication disallows comments, as no one is
authenticated.

CutShort: Cut off rendering a page right at that point in some
contexts. Optional arguments restrict this effect to the
specified view(s); it's generally not useful to do this, but
if you want to some values are blog, blogdir, or
atom. Rendering as a full page can never be cut off. An
important note: CutShort is not really a macro. You must put
it at the start of a non-indented, non-nested line; it doesn't
work anywhere else in text.

DocAll: Enumerate all of the first argument (must be 'macros',
'processnotes', 'renderers', or 'textmacros') with their
documentation, if any, as a real HTML list. (In other words,
you're reading its output.)

EnumerateAll: Enumerate all of the first argument, which must be
'macros', 'processnotes' 'renderers', or 'textmacros' as a
comma-separated list. The short form version of DocAll.

IMG: Generate an inline image. Usage is
{{IMG:<loc> width height alt text ...}}. If the location is not
absolute (http:, https:, or starts with a /) it is taken as a
location relative to the DWikistaticurl directory. The location
cannot include spaces; % encode them if necessary. After the first
time you use an image, specifying the width, height, and alt text
is optional; if not specified, they default to the last values.
If the alt text contains ' ||| ', it is split there to be alt
text (before) and title text (afterwards).

ListDir: List what's in the current directory. An argument restricts it
to either files ('files') or subdirectories ('directory').

ListRefs: List pages with references to one of the arguments, or where
one of the arguments is a word in the page name. This is an
expensive operation in a DWiki of any decent size, since it must
search through all pages.

PTitles: Make another macro generate lists of pages using the titles
of the pages (if possible), instead of the names of the pages.
Invoked as {{PTitles:<macro>[:arg:arg...]}}.

RecentChanges: List recently changed pages. First argument is how many to cut
the list at, default 50; 0 means no limit, showing everything.
Additional arguments are which directories to include or (with a dash
at the start) to exclude from the list; you can use '.' to mean
the current directory. To preserve the default limit, use a
value for the first argument that is not a number.
If we're Striped, list pages under their name not their full path.

RecentCommentedPages: List pages with recent comments. Arguments are the same as for
RecentChanges.

RecentComments: List recent comments. Arguments are the same as for
RecentChanges. Use with Striped is somewhat dubious.

Restricted: Restrict a page to authenticated users. Arguments are which users
or groups to allow access to or, with a dash at the front, to deny
access to. If both allow and deny arguments are given, the viewing
user must pass both tests. Restricted has no effect if the DWiki
has no authentication configured.

ST: Style text with a particular HTML font style. The first argument
is the HTML font style; the remainder are the text to be in that
style. Valid styles are big, del, ins, small, strike,
sub, sup, and u.

ShowCfgVar: Insert the value of a DWiki configuration variable. The
argument is which variable to insert. Only a few variables may
be displayed, currently wikiname, wikititle,
server-name, pagedir, and charset.

ShowCharEnts: Show all the known character entities accepted by the C macro
as a real HTML list. Takes no arguments.

Striped: Make another macro generate lists of pages as a comma-separated
line, instead of the real list it would normally use. Invoked as
{{Striped:<macro>[:arg:arg...]}}.

TitleIndex: Insert a table of dates and entry titles (or relative paths
for entries without titles), linking to entries and to the day
pages. The table is in reverse chronological order. The single
argument is the page hierarchy to do this for; if it is not
specified, it is done for the current directory. The actual
rendering is done by the blog::titleindex renderer.

This list is generated by the same code that finds macros when turning
DWikiText into HTML, so it's guaranteed to be complete. The
documentation is hopefully complete, but ChrisSiebenmann
may have forgotten to update (or provide) it when he changed the code.

Macros that generate lists of pages generate them as links to the
pages in question, which is what you want.

Access restrictions

By default, pages are visible to everyone. If the DWiki has been set
up with authentication, it's possible to restriction who can read a
page. To do so, invoke the Restricted macro (with appropriate
arguments, if any) on the page.

The whole issue of DWiki authentication is discussed in more detail at
the Authentication page.

Comments

Similarly, if the DWiki is configured for it it's possible to allow
authenticated users, or only some authenticated users, to comment on
DWiki pages. You do this by invoking the CanComment macro somewhere
on the page with appropriate arguments.

The CutShort macro will tell DWiki that in certain contexts (for
example, in a 'blogdir' view of a directory, or in an Atom syndication
feed) that the display of the page can stop there. This generates a
note that to see the full content they should follow the link.

Forced plaintext

By putting the line '#pragma pre' (and nothing else) as the very
first line of a DWiki page, the rest of the page is forced to render
as one giant <pre> block, exactly as if everything had a space in
front of it. Since you don't actually have to put the space in front
of every line, this is a much easier and more maintainable way of
including plain text files in a DWiki.