TextFormattingRules

TextFormattingRules

(See HowDoIEdit for general information ZWiki editing info.)

ZWiki formatting conventions make it easy for everyone to create nice web pages without making it hard for anyone to read and edit other people's page source. This page is for helping both novice and experienced users understand the rules, where intuition doesn't suffice:

• A quick reference, for those already familiar with (or intuiting) the format. It has links into...
• A more thorough reference, with details and orientation for those first being exposed to the format.

Quick Reference

Style Formatting

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

Making and Preventing Links

Expressing Links

• Wiki refs : Squashed-together capitalized words, e.g. StructuredText, WikiWikiWeb, TextFormattingRules (numbers and the "~" tilde are also allowed).
• "[Square brackets]":#squarebrackets : (Discouraged!) Usually turn anything into a wiki ref.
• Spelled-out URLs : 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)

• Bang : Prefix the wiki word or '[] square brackets with an exclamation point: !StructuredText', '![meta comment]'
• Tick : Put the expression in ' single-quote code-fragment form: ZWiki
• Example block : Put the expression in an "::" example block:

            StructuredText, http://www.zope.org, <strong>nope!</strong>
            <dtml-var "1 + 1">, etc.
  

Sectional Structure

• Paragraphs : adjacent sequences of non-blank text lines. Indentation of the first line determines the level of the paragraph.
• Sections : Adjacent sequences of paragraphs with the same indentation level.
• Subsections : Sections having greater indentation level than their immediately preceding section.
• Headers Single-line paragraphs that do not end in punctuation, and that contain a new subsection.

Lists

• Unordered Bulleted Lists Paragraphs beginning with a '-', *, or o
• Ordered Bulleted Lists : Paragraphs beginning with a sequence of digits followed by a white-space character are treated as ordered list elements.
• Definition lists : Paragraphs with first line containing text followed by some white-space and --

Background and Elaboration

ZWiki's "structuredtext" format text is based on Zope's StructuredText, plus some WikiWikiWeb conventions. Both are concerned with the readability and intuitive obviousness of the raw text - to prevent formatting from getting in the way of editing. The ultimate aim is to support crafting of text that is readable and attractive in both the formatted and the raw form.

With ZWiki pages, you indicate everything, including the structure of a document - its sections and the nesting of subsections, its formatting, links, and stuff like that - using plain-text formatting conventions. (ZWiki text can include raw HTML, in case there's some elaborate HTML formatting you must do beyond what StructuredText text offers. The less HTML you use, the easier the job will be for editors - yourself included!)

The source of existing pages can provide good examples of the conventions - the text of this page, in particular, presents many central examples. Click the "Edit" or "View" in the page footer to see.

One formatting feature worth immediate attention is the way indentation level is used to distinguish 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 their first lines having the same indentation, ...
• and the subsections are paragraphs whose first lines have greater indentation than their immediately preceding, 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 peculiar, 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 use where capital letters would be, except at the beginning of the word, and ~ tildes can be used as lowercase letters.) 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

  See RemoteWikiLinks for a way to link to wiki pages in other Wikis.

• [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.-)

• Spelled-out URLs : 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 :

  "Zwiki central":http://joyful.com/zwiki => Zwiki central

Preventing Links (and Other Processing)

• Bang : Prefix the wiki word or '[] square brackets with an exclamation point: !StructuredText', '![meta comment]'

• Tick : Put the expression in ' single-quote code-fragment form.

  This is a good way to escape small portions of text from wiki processing:

  For instance, stuff like WikiNames, bare URLs - http://www.zope.org - etc., are not processed.

  It all needs to be within a single paragraph, and you can't include contractions because of the single quote.

• Example block : Put the expression in an "::" example block.

  This is the prime 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 literally, 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, and see the bit about indentation levels, above for more details.

• Paragraphs

  Paragraphs are adjacent sequences of non-blank text lines.

• Sections

  Paragraphs have section levels relative to each other, 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 preceding section are subsections of the preceding 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 interspersed - 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
  

See Also StructuredText and ZWikiWeb:TextFormattingRules