Subdirectories: NewFeatures.
2005-06-08
A brief sketch of the Dwiki processing model
The core of DWiki is a template expansion engine and a collection of (text) renderers; DWiki displays pages by figuring out what template to use and then rendering it out.
Renderers generate text based on the current context, such as the page that is being displayed. The most important (and largest) renderer is the wikitext renderer, which takes page content in DWiki's wiki text format and turns it into HTML.
Other renderers create things like the navigation 'breadcrumbs' up at the top of this page and and the page tools and last-modified lines at the bottom. Renderers generally create only the essential pieces of that information; surrounding text is created through template expansion. Renderers are hardcoded parts of DWiki and are thus written in Python.
Templates are text files; they get expanded by the template engine through a recursive process of applying template 'macros' to their text. Template macros can insert other (expanded) templates, insert text taken from context variables, and insert the results of renderers. A typical template might look like:
<html><head><title>${|wikititle|wikiname} :: ${page}</title></head> <body> @{breadcrumbs} <br/> @{wikitext} <hr> #{footer.tmpl} #{site-sig.tmpl} </body> </html>(the actual templates that render this DWiki are somewhat more complicated than that, but this shows the flavour.)
DWiki produces all pages this way. Displaying different types of pages (regular pages versus directories) and different views of the same page (such as the history view) is done by selecting a different starting template; the template (presumably) uses different renderers that the normal view.
Errors are also rendered using templates (if an appropriate template exists). This allows some error pages to reuse renderers as appropriate; for example, the no-such-page error template includes breadcrumbs just as regular pages do, as you can see at NoSuchPage.
Wart: the view source display is not done by a template: it just barfs the content out straight as plain text. One current limitation of renderers and templates is that they can't control the content-type, which is set in the HTML view core.
Wart: the mapping of view + file attributes to templates is currently hard-coded.
The frontend versus the core
DWiki is divided into two components: the front end and the core. The front end receives raw HTTP requests, figures out if they are proper requests, and then passes them to the core to go through the core's processing. If the front end can detect that a HTTP request is not something that the core can handle, it rejects it immediately with a terse error.
Similarly, if the core encounters a processing error it throws an exception up to the front end, which logs it and generates another terse error.
It is the front end that can optionally serve static files; the core is not involved in that process.
2005-06-06
Directories can now have Readme files, called __readme. Readme
files are injected into pages via the new renderer inject::readme
(probably the first of several injectors).
The current templates don't inject __readme in normal directory
views, but do inject them for blog and blogdir views (as you may see
from this directory). Blog and blogdir views now drop all files
starting with __, taking out __readme and __access and any
future special magic files.
DWiki features
DWiki's job is to be a good way to display version controlled wiki-text pages that you write in a real editor.
The important DWiki features:
- simple but reasonably powerful text rendering (based on WikiText).
- natural support for arbitrarily-named links: you don't have to follow some magic page naming standard that doesn't fit well with the natural names for things.
- pages are normal, simple files, and you edit them directly in Unix.
- support for putting pages in RCS, with strong disincentives to hand-edit files without checking them out (they stop displaying).
- directories can display like changelogs: pages inline, most recent first.
- can generate Atom syndication feeds for recently changed things.
The inevitable feature list:
In no particular order:
- simple WikiText-like text rendering. (Chris wrote pages in GNU Emacs and relentlessly smushed anything that got in the way of how GNU Emacs wanted to autoformat things.)
- The text rendering choices are designed to make it easy to write about Unix systems.
- full support for directly editing wiki pages.
- does not force a flat page namespace; uses straightforward Unix files and directories to organize the DWiki page space. (Thereby keeping the Unix view of DWiki's pages simple.)
- supports a blog-like view of a directory that inlines pages there, most recent first.
- in-filesystem page redirects make it trivial to support plurals, moved/renamed pages, etc.
- text-based page templates control how all pages appear, making it easy to control various bits of a DWiki's appearance.
- pages can be put in RCS for version control and multi-person editing access. RCS files can live in either the page directory hierarchy (for simplicity) or another parallel directory tree (for neatness).
- forces people not to edit RCS-controlled files without locking them by refusing to display inconsistent unlocked files.
- generates Atom syndication feeds for recently changed pages and recent comments, for the entire DWiki or any subtree thereof.
- written in Python.
- simple-ish yet powerful enough (I hope) user authentication system, with an equally simple yet powerful way of restricting who can read DWiki pages.
- supports the option of letting people (possibly including the world) comment on some or all of the pages.
- takes some pride in properly generating and handling Last-Modified: and ETag: headers in HTTP responses.
- wikitext to HTML generates fully HTML 4.01 Transitional compliant HTML provided only that you don't jump multiple indent levels in at once in lists (thus Formatting doesn't validate).
- can run as a CGI-BIN or standalone, and support for additional environments (SCGI, WSGI, whatever) should be easy to add if it is needed. Disclaimer: standalone does not use a production-quality webserver implementation; it uses Python's
BaseHTTPServerwith a hack to use threading.Missing DWiki features
Also in no particular order:
- you can't edit DWiki pages from the web, but see WhyNotWebEditing.
- no user authentication.
- therefor, no access restrictions on who can read what.
- searching is primitive at best.
A necessary acknowledgement:
A number of DWiki's features and design decisions are shamelessly inspired by C.J. Silverio's as yet (22 May 2005) unfinished Snippy. Note that Snippy is much more powerful than DWiki probably ever will be, plus if it had been finished when I was writing DWiki I probably wouldn't have.
2005-06-05
DWiki can now generate Atom feeds for recently changed pages and recently made comments, either for the entire DWiki or for some subtree of it. For comments, this can be down to an individual article.
At the moment, pages in the Atom feed are rendered without macros
except for CutShort, for efficiency reasons. All of the links
are turned into absolute links (with http:// et al), since this is
basically required. Nulled-out macros produce a small message to that
effect in the generated content, so that people reading the Atom feed
can tell that something is going on.
2005-06-03
The primary way of getting nested lists is now to indent the nested list entries relative to the parent list (entry). This looks visually better in plain ASCII for cases when there is a decent amount of text.
Although ChrisSiebenmann thought he wasn't going to, the old style of
nesting lists (multiple list start characters, eg ***) still
works. It turns out the GNU Emacs will properly autoindent for these
lists but not for real indented lists, plus sometimes they actually
look visually better.
The amount of old-style nesting is ignored in an indented context; it's treated as just a new level.
2005-06-02
You can now use LinkAbbrevs by name (not by URL) without a |; ie,
instead of writing [[<text>|]], you can just write [[<text>]].
This only happens if <text> wouldn't result in a link to a real page
or an external URL if there was no abbreviation.
Thus, one can write [[Google http://www.google.com/]] in the
page once, and later write [[Google]], and have it work out.
DWiki now lets you use spaces to separate things in [[....]] links
instead of |. If you do this, the last word is taken as the link
URL or page, and the rest are the link name. (| has priority over
this; DWiki tries space-separation only if there is no |.)
Thus [[Google Rules The Web http://www.google.com/]] turns into
Google Rules The Web.
You can use either side as an abbeviation later, for example: Google Rules The Web, Google Rules The Web. (See View Source.)
LinkAbbrevs done this way don't have to use |, as long as there is a
space in the value: [[Google Rules The Web]] still turns into
Google Rules The Web.
This allows somewhat more aesthetic long link name things.
Note that the opening [[ and the closing ]] have to be on the
same line in the wikitext.
2005-06-01
Page Names That DWiki Won't Serve
There are some paths and page names that DWiki categorically refuses to serve, even if they seem to resolve to real files. Because they're enforced by both low-level code and high-level code, they apply to DWiki pages, static files being served by DWiki, and even templates. (Technically they apply to comments too, but comments can't generate file names that violate these rules.)
What gets rejected:
Any path that includes a path component that starts with a
., ends with,vor a~, or isRCS.Any non-relative path that includes
..,., or a sequence//; usually this might appear in the URL of an incoming request. (Incoming requests are not supposed to include things like that. But ChrisSiebenmann declines to believe that everyone sending DWiki requests is going to do what they're supposed to.)DWiki will reject REDIRECT files that either have too many '..' entries (so that they are trying to escape the root of the page directory) or that fail these checks after they've potentially been converted from relative path names to absolute inside-DWiki paths.
When DWiki rejects bad paths, generally it says that there is no page by that name. Sometimes it rejects the request entirely in huge flames.