TextFormattingRules

ZWiki text is based on Zope's StructuredText, plus some WikiWikiWeb conventions. Both hold very highly the readabilty and intuitive obviousness of the raw text - it should be as readable as the formatted text, and the formatting cues should not get in the way of editing. A bit of attention to the following rules can provide you with one of the easiest and most versatile ways around to create web content.

With ZWiki pages, you indicate the structure of a document - its sections and the nesting of subsections, its formatting, links, and stuff like that - using plain-text formatting conventions. The conventions are niftily designed so that the formatting is uncluttered and obvious to the casual reader, even in the plain text version.

The raw source of existing pages can provide good clues about the formatting - the text of this page, in particular, presents many central examples. Click the "Edit" or "View" in the page footer to view it, and have the (not-so secret) secrets revealed!

One primary formatting feature worth immediate attention is use of indentation levels to determine what are sections and subsections:

It starts with paragraphs - adjacent, non-blank text lines in groups that are bounded above and below by blank lines.
Sections are sequences of these paragraphs with first lines having the same indentation, and also any intevening subsections, ...
and the subsections are paragraphs whose first lines have greater indentation than their immediately preceeding, containing sections.

This use of whitespace makes the sectional structure as obvious in the raw text as it is in the formatted result, without cluttering the raw text with arbitrary and distracting marks. See Sectional Structure for more details.

Style Formatting

Emphasis: *italic* => italic
Bold: **bold** => bold
Code: 'code' => code

Making and Preventing Links

Expressing Links

Wiki refs: the main way to link to pages in the same wiki, they're made of two or more run-together capitalized words naming the target pages. (In ZWiki, numbers can be used for all but the first capital letter.) When the target page is there, the wiki ref is rendered as a link to it. Easy!
Wiki refs also serve to create new pages - when the target page is absent, then the ref itself is not a link, but it has an appended question mark, which is a link to a page for creating authoring and creating the target.

Some examples: StructuredText, WikiWikiWeb, TextFormattingRules
[square brackets] turn anything into a wiki ref - but beware, spaces and other forced characters make for unobvious links, to be avoided! (I'm not offering an example, they're so yucky.-)
Any text recognizable as a URL: http://www.zope.org
RemoteWikiURL - a way to refer to pages in remote wikis, eg: ZWikiWeb:RemoteWikiURL
Linked text:
"Zope central":http://www.zope.org => Zope central

Preventing Links (and Other Processing)

Prefix the wiki word or '[]square brackets with an exclamation point:!StructuredText', '![meta comment]'
Put the expression in ' single-quote code-fragment form.
This is a good way to escape small portions of text (within a single line) from wiki name recognition:
```
          'ZWiki'
```
Put the expression in an "::" example block.
This is the primo way to escape blocks of text from formatting - no html flow or other processing is done, and dtml and other server-side includes are prevented:
```
          Escaping *all* web and wiki formatting::

            StructuredText isn't recognized (nor is http://www.zope.org,
            <strong>rendered litereally, ay?</strong>, <dtml-var "1 + 1">,
            etc!)
```
(What happens? The section is bracketed by <pre></pre>" preformatting directives, and any "<" less-than symbols in the section are turned into<' before the web server sees them. Thus the server doesn't specially process anything within the section. This paragraph is outside the example section, because it's at a lesser indentation - and so is once again subject to processing.)

Sectional Structure

See this page's source for examples.

Paragraphs
Paragraphs are adjacent sequences of non-blank text lines.
Sections
Paragraphs have section levels relative to eachother, according to the indentation of their first line. Adjacent sequences of paragraphs with the same indentation level (the indentation of the first line is what's significant) make up a single section. Sections at a deeper level - i.e., having greater indentation - than their preceeding section are subsections of the preceeding section.
Headers
Single-line paragraphs that do not end in punctuation, and that contain a new subsection - i.e., are immediately followed by paragraphs with greater indentation - take on the role of header lines for the subsection. The section header <h#> ... </h#> header level is determined by how deeply nested the subsection is within the top level section.

Lists

Unordered Bulleted Lists
Paragraphs beginning with a '-', *, or o are treated as unordered list elements:
```
       - And example unordered list element (unrendered, so you can
         see the formatting)
```
Ordered Bulleted Lists
Paragraphs beginning with a sequence of digits followed by a white-space character are treated as ordered list elements. (The sequence of digits could be a digits or letters with . periods interpsersed - e.g., A.B.C. or 1.1.3.):
```
       1.1. First ordered list element (unrendered)

       1.2. Second...
```
Definition lists
Paragraphs whose first line contains text followed by some white-space and -- is treated as a descriptive list element. The leading text is treated as the element title:
```
        Example definition list element -- unrendered for your
        viewing pleasure
```