Log in
Forgot your password?
History for TextFormattingRules
??changed:- 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":#quickreference, for those already familiar with (or intuiting) the format. It has links into... - "A more thorough reference":#moredetails, with details and orientation for those first being exposed to the format. <a name=quickreference></a> Quick Reference Style Formatting - Emphasis: '*italic*' => *italic* - Bold: '**bold**' => **bold** - Code: 'code' => 'code' Making and Preventing Links Expressing Links - "Wiki refs":#wikirefs : 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":http://www.zope.org Preventing Links (and Other Processing) - "Bang":#exclamationpoint : Prefix the wiki word or '[]' square brackets with an exclamation point: '!!StructuredText', '!![meta comment]' - "Tick":#singlequote : Put the expression in ' single-quote code-fragment form: 'ZWiki' - "Example block":#exampleblock : 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":#sections : Adjacent sequences of paragraphs with the same indentation level. - "Subsections":#sections : Sections having greater indentation level than their immediately preceding section. - "Headers":#headers: Single-line paragraphs that do not end in punctuation, and that contain a new subsection. Lists - "Unordered Bulleted Lists":#unordered: Paragraphs beginning with a '-', '*', or 'o' - "Ordered Bulleted Lists":#ordered : Paragraphs beginning with a sequence of digits followed by a white-space character are treated as ordered list elements. - "Definition lists":#definition : Paragraphs with first line containing text followed by some white-space and '--' <a name=moredetails></a> 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. <a name=levels></a> 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":#sections for more details. Style Formatting - Emphasis: '*italic*' => *italic* - Bold: '**bold**' => **bold** - Code: 'code' => 'code' Making and Preventing Links Expressing Links <a name=wikirefs></a> - 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. <a name=squarebrackets></a> - ![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.-) <a name=spelledout></a> - 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":http://joyful.com/zwiki Preventing Links (and Other Processing) <a name=exclamationpoint></a> - Bang : Prefix the wiki word or '[]' square brackets with an exclamation point: '!!StructuredText', '!![meta comment]' <a name=singlequote></a> - 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. [93 more lines...]