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 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.)
Sometimes you want to force a line break in the text. To do this, just
end a line with ' \\' (space backslash backslash).
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.)
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.
The final wrinkle is how DWiki should behave for something like:
Consider 'Dict *a, *b;' to be *an example*.
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.
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.
The C macro allows the direct insertion of HTML character entities,
either as a decimal number, a hexadecimal number prefixed with x, or
by name, like copy for ©, the copyright symbol. The available
character entity names are listed in CharacterEntities.
The AB macro allows you to insert HTML <abbr> elements. Unfortunately, Internet Explorer 6 and under
doesn't support <abbr> elements. (IE7 may.)
For more details about all of these, see the Macros section. Unlike other macros, all of these can be used in comments.
There are several formats for links in DWiki text.
[[<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.
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.)
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.
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.
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.
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 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>.
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.
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.
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:
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.
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 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
{{...}} 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 ...}}, where the height
should normally be 'auto', which set the image so that it will
automatically scale down for the browser width in modern CSS
environments. If the location is not absolute (http:, https:,
or starts with a /) it is taken as a location relative to the
DWiki staticurl 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). The title text is what browsers
show when you hover over the image.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.MatchingPagesUnder: List all pages under a particular directory if their page
name contains a word in the provided word list. Usage is
{{MatchingPagesUnder:directory:match ....:option ...:exclude ...}};
the third and fourth arguments are optional and may be blank or
omitted.
Page names are shown relative to the directory (eg 'fred'
instead of 'blog/fred' if blog is the directory). By default,
pages are shown in reverse chronological order. The optional
third argument sets various options, and may include 'c[hron]'
for the default reverse chronological order, '+c[hron]' for
forward chronological order, 'a[lpha]' for alpbahetical order
based on the page name, 't[able]' for a table display similar
to what TitleIndex shows, and 'u[tilstoo]' to include utility
pages in the results. Without the 't' option, this may be
used with PTitles or Striped, although use with PTitles
doesn't change the alphabetical sort to use the titles; it is
still based on page names.
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.
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.
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.
Unlike Restricted, by default no one can comment on pages.
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.
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.
DWiki accepts '#pragma plaintext' as a synonym.