This is, naturally, a test of how all of our formatting actually looks. (It has turned into sort of documenting things, too. You probably want to view the source, using the toolbar at the bottom.)
I'm not going to try to explain lists. Once you follow View Source, it should be obvious. The only tricky bit is that a list line that is continued on following lines must be indented; a flush-left line will be taken as returning to the paragraph (or starting one). List demo:
And back to the land of happy paragraphs. We've also got the third type of list on hand:
Definition lists don't come out quite as they're written in ASCII, but it's closer than some of the other choices. Definition lists nest with more leading characters, like the other lists.
The primary way of writing nested lists is to actually indent the nested lists in the wikitext, as you can see in the 'View Source' for this page. Sometimes this is awkward; in that case, you can use more than one of the list-start characters, like this:
Note that if you continue such a nested list on a new line, the new line's indentation must be deeper than the start characters for the list.
| left | right | |
| up | 10 | 20 |
| down | 30 | 40 |
Tables are extremely low-rent. Chris figures that this pretty much matches what he wants.
The downside is that more complicated tables may render, how shall we say, a little less than optimally. You're best off sticking to tables that have something in all of the cells and that are always the same shape.
'Horizontal' tables, where the only border lines are horizontal and
fainter, are created by starting a table with |_. instead of |:
| Code | Meaning | Look at body? |
| 200 | Successful page fetch | Yes (if GET) |
| 301 | (Permanent) redirect | No |
| 304 | Not modified | No |
| 404 | Access denied (don't retry) | Only for error text |
FIXME: I need to do more work on styling tables well. At the moment they are barely better than just sticking ASCII blocks in. I can steal ideas from other WikiText implementations.
Link formats:
http:// links, or absolute
local URLs if they're written with < and > around
them, eg [[</>]].|| instead of just |, you can use either to
separate the label and the link.The preferred link format for internal wiki links is the explicit wiki link [[....]], because that allows a wider variety of useful names than CamelCase. (eg, I do not want to have to CamelCase the names of all of the machines I want to write about.)
The DWiki path '/' is the wiki root, in an analogy to Unix and
URI 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 is not a link.
Thus all of the CamelCase DWiki's in this paragraph actually refer to the root /DWiki. The wiki link DWiki refers to the current directory one, /dwiki/DWiki. (This is unfortunately obscured by DWiki's new habit of rewriting CamelCase links that point to redirects to the redirection target, but trust Chris, this is what's actually happening.)
[Actually these days DWiki retargets all links that point to redirects, which may or may not be the right thing to do but does make it much harder to see this.]
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). Eg, Chris Siebenmann.
You can write [[<text>]] without the |. This is always taken to
be a name abbreviation, and only if there are spaces in <text> or
<text> isn't an absolute URL (http:// or with < and > around it) or
a real DWiki page.
Running text (in paragraphs, lists, tables, and in general all containers) is styled with fonts, links, macros, and magic line breaks.
A ' \\' (space backslash backslash) at the end of a line, and only
at the end of a line, produces a <br/>.
Bold, type writer text, and italic. Note that if we don't
close one, like say ~~bold here, that it dies at the end of the
paragraph.
No stray formatting putting 2/3rds of your text into italic, nosirree. I like my formatting self-contained.
There is one other font style: code style, which produces things
like 'char *dp_null;'. Code style is monospace with no further
font interpretation, and is done by a ((...)) construct. It exists
because ChrisSiebenmann keeps doing it by other, hackier means.
I could have used / for italics, but one major usage of dwiki
is going to be documenting our Unix systems. When doing this I
will be writing a lot more file paths than italics. Similarly,
monospace gets used more often than italics (or underline).
NOTE: the font styles are applied with heuristics. See DWikiText for the full details.
The ST macro is written {{ST:<style>:text ...}}, and formats
the enclosed text in the given HTML font style, which must be one
of big, small, strike, sub, sup, or u.
The C macro is used to insert a HTML character entity as either a
decimal number, a hexadecimal number starting with x, or a named
character entity from the list in CharacterEntities. Note that not all
of them are sensible entities, and some of the more exotic of these
may not render in the browser of your choice, although all of them are
valid HTML 4.01 transitional.
Some examples: И, the Cyrillic capital letter "I"; 水, the Chinese character for water. Certain sorts of cuteness are ruthlessly exterminated, like {{C:funky}}, {{C:10}} or {{C:x1F}}.
Having numeric character entities be valid in your DWiki's chosen character set is up to you. (Of course, the only really sensible character set these days is utf-8.)
HTML <abbr> elements are written {{AB:<abbreviation>[:text ...]}}.
Once an abbreviation has been used once its expansion is remembered, so
you can write API once and then
thereafter use just {{AB:API}} to get API. An abbreviation
without an available expansion is considered an invalid macro, so that
you notice.
(AB torture test: SWD.)
Unlike most macros, these can be used in comments.
A line of dashes will produce a horizontal cut, like:
this. You need at least four. These can come pretty much anywhere.
If you don't like really big horizontal lines, there's also the three-stars separator style, like so:
* * *
This is written as '* * *' without line indentation (although
you can put more whitespace between the stars if you want).
Like so. This is literal preformatted text and is going to stay that way. (I suppose you can do ASCII tables if you're so inclined.)
Notice that that was all one <pre> block. Also notice that that HTML markup was quoted, just like this '&' will be.
You need at least one whitespace character on the line. More than one whitespace character produces real in-<pre> whitespace out of the rest, like so:
Left. Indented one more space, with & and <pre> thrown in as a bonus. Back left.
I don't quite know what to call this, but you can quote things just
like you would in email: put '> ' at the start of the quote lines.
Like so.
This is a new quoted paragraph.Quotes nest, too.
You can put anything in a quote that you could put in normal text, and it will all work out right. For example:
- lists.
- and everything nests.
Even if you go back one level.
Quotes disappear when you stop putting the quotes in. Despite what the semantic markup people may tell you, feel free to use quotes to produce indentation if it works for you.
{{...}} is a macro. Macros are used to do special magic expansion. Macros can take parameters, separated with :'s. 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.
You can put a ! in front of http://foobar, [[..]], or {{..}} to escape their special meaning. Technically this just escapes the meaning of the special leadin, leaving everything else to get styled stylishly.
If you write [[<text>|]], ie you supply no link name/URL, the text
is produced un-DWikiText-ified. (This is different from the case where
there is a link, in which the text will be DWikiTexted for fonts (but
not links or macros).) This is the only genera way to escape font
styling (as ((...)) is not exactly general).
Testing: Google. Yep, that text is styled.
Pragmas have to be the very first line in the page. There are two:
#pragma pre (or #pragma plaintext) forces the rest of the page
to be treated as plaintext, not wikitext.#pragma search DIR1 [...] adds any listed directories to where
DWiki searches for relative links, after all of the hard-coded
searches.The search pragma is handy when drafting pages somewhere other than their final directory.
At least until ChrisSiebenmann starts adding more.
Disclaimer: not entirely guaranteed to be complete and
comprehensive. See wikirend.py in the source code.