You are not logged in Log in Join
You are here: Home » Members » lemburg » psc-wiki » TextFormattingRules

Log in
Name

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: &#39;code&#39; => '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 : '&quot;Zope central&quot;: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 &#39; 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: &#39;code&#39; => '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 :

        '&quot;Zwiki central&quot;: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 &#39; 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...]