[Zope-CMF] Re: [Plone-users] Structured Text reference

J C Lawrence claw@kanga.nu
Thu, 06 Feb 2003 20:53:45 -0800


Ahh, I should have crossposted this to the zope-cmf list originally as
its not Plone specific.  Apologies.

On Thu, 6 Feb 2003 16:25:58 -0500
Geoff Davis <geoff@geoffdavis.net> wrote:

> I have put together a simple, visual Structured Text reference at
> http://plone.org/Members/geoff/structured_text

> Feel free to use this with clients, etc.

I've extended for shared use between StructuredText and ZWiki's
extensions as well as a few more markup types.  I've also more clearly
deliniated the example renderings from the mainline text.  Depending on
your CSS this may not come out as intended.

--<cut>--
The ultimate aim is to support crafting of text that is readable and
attractive in both the formatted *and* the raw form.

With StructuredText 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.  (Structured 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.  If you are logged in, click the "Edit" or "View"
tab on the page to see.

  Style Formatting

    - Emphasis: '*italic*' => *italic*

    - Bold: '**bold**' => **bold**

    - Underlined: '+underlined_' => _underlined_

    - Code: &#39;code&#39; => 'code'

  Headers and paragraphs

    **Paragraphs**

      Leave a blank line between paragraphs::

        This is some text in
        paragraph one.

        This is different
        text in paragraph two.

      Will be rendered
      as:

       <table><tr><td bgcolor="lightgray" border=1>

        This is some text in
        paragraph one.

        This is different
        text in paragraph two.

        </td></tr></table>

    **Text headers**

      Enter this::

         My header

           If you enter a single line paragraph (e.g. like the
           one above and then indent the first line of the next
           paragraph, the text in the one-line paragraph will be
           transformed into a header.

           Note that the second paragraph in the section also has
           its first line indented.  Note that you don't have to
           indent the whole paragraph (as is done here for clarity),
           just the first line of the parapgraph.

           Be sure to leave a blank line between paragraphs.
           This paragraph is indented, too.

           Subheading 1

             Use additional indentation to generate subheaders.
             Notice that the subheading's level of indenting is
             the same as the level for the previous paragraph,
             but that *this* paragraph is further indented.
             It's the extra indenting of *this* paragraph that
             creates the subheading.

             Subheading 2

               Get smaller subheadings by indenting even more.

               Subheading 3

                 Get even smaller subheadings by indenting even more.

      To get
      this:

<table><tr><td bgcolor="lightgray" border=1>

My header

  If you enter a single line paragraph (e.g. like the one
  above and then indent the first line of the next
  paragraph, the text in the one-line paragraph will be
  transformed into a header.

  Note that the second paragraph in the section also has
  its first line indented.  Note that you don't have to
  indent the whole paragraph (as is done here for clarity),
  just the first line of the parapgraph.

  Be sure to leave a blank line between paragraphs.  This
  paragraph's first line is indented, too.

  Subheading 1

    Use additional indentation to generate subheaders.
    Notice that the subheading's level of indenting is the
    same as the level for the previous paragraph, but that
    *this* paragraph is further indented.  It's the extra
    indenting of *this* paragraph that creates the
    subheading.

    Subheading 2

      Get smaller subheadings by indenting even more.

      Subheading 3

        Get even smaller subheadings by indenting even more.

</td></tr></table>

  Preformatted Text

    **Block of preformatted text**

      Enter this::

        The next block of text will be formatted exactly the way I
        have typed it::

           This is all preformatted.

              Your formatting will be used until...
                 ... you stop indenting text.
              None of the *structured text* **commands** _work_ here.

           This is still indented.

        This is no longer preformatted.

      To get
      this:

       <table><tr><td bgcolor="lightgray" border=1>

       The next block of text will be formatted exactly the way I
       have typed it::

         This is all preformatted.

           Your formatting will be used until...
              ... you stop indenting text.
           None of the *structured text* **commands** _work_ here.

         This is still indented.

      This is no longer preformatted.

      Note: You can also use the HTML &lt;pre&gt; and &lt;/pre&gt;
      tags to achieve the same effect.  Similarly paragraphs which
      end in either the word, 'example' or 'examples' will cause the
      next section to be treated as an unformatted block.

      </td></tr></table>

    **Inlined preformatted text**

      Enter this::

        Some ordinary text here.  Some 'preformatted text here'.
        More ordinary text.

      to get
      this:

        <table><tr><td bgcolor="lightgray" border=1>

        Some ordinary text here.  Some 'preformatted text here'.
        More ordinary text.

        </td></tr></table>

  Lists

    **Bulleted lists**

      Enter this::

        - First item

        - Second item.  Note that there is a blank line between each
        list item.

          - Make lists within lists by using extra indentation

          - Second indented item.

        - Third item in the main list.

      to get
      this:

        <table><tr><td bgcolor="lightgray" border=1>

        - First item

        - Second item.  Note that there is a blank line between
        each list item.

          - Make lists within lists by using extra indentation

          - Second indented item.

        - Third item in the main list.

        </td></tr></table>

      You can use any either '*' or '-' or 'o' for the marker for
      your
      bulleted list items.

    **Numbered lists**

      Enter this::

         1 First item

         1 Second item.  Again, note that there is a blank line
         between each list item.

         1 Third item in the main list.

      to get
      this:

        <table><tr><td bgcolor="lightgray" border=1>

        1 First item

        1 Second item.  Again, note that there is a blank line
        between each list item.

        1 Third item in the main list.

        </td></tr></table>

      Note that numbered lists cannot be embedded in bulleted lists.

    **Definition lists**

      Enter this::

         First item -- More information about the first item.

         Second item -- More information about the second item.

         Third item -- More information about the third item.

      to get
      this:

        <table><tr><td bgcolor="lightgray" border=1>

        First item -- More information about the first item.

        Second item -- More information about the second item.

        Third item -- More information about the third item.

        </td></tr></table>

  Links

    **Making Links**

      - **Links**

        Enter this::

           "A link to CNN":http://www.cnn.com

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          "A link to CNN":http://www.cnn.com

          </td></tr></table>

        Another form::

          "mail me", mailto:address@example.org

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          "mail me", mailto:address@example.org

          </td></tr></table>

      - **!URLs**

        Anything that's obviously a URL will be made into a link.  For
        example::

          http://www.zope.org/

        will
        produce:

          <table><tr><td bgcolor="lightgray" border=1>

          http://www.zope.org/

          </td></tr></table>

      - **Email addresses**

        Enter this::

           "address@example.com":mailto:address@example.com

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          "address@example.com":mailto:address@example.com

          </td></tr></table>

      - **!WikiWord** (Wiki specific)

        Wiki links are made of two or more run-together capitalized
        words naming the target page.  (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 WikiWord 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, StructuredTextRules

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          StructuredText, WikiWikiWeb, StructuredTextRules

          </td></tr></table>

      - <strong>![Square brackets]</strong> (Wiki specific)

        Use square brackets to turn pretty much anything into a wiki
        link - but beware, spaces and other forced characters make
        for unobvious links.  Use sparingly - its wise to avoid
        this technique where possible.

        Example::

          [a linked page]

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          [a linked page]

          </td></tr></table>

      - **!RemoteWikiURL** (Wiki specific)

        Enter this::

          ZWiki:RemoteWikiURL

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          ZWiki:RemoteWikiURL

          </td></tr></table>

        !RemoteWikiURLs require another page in the local wiki
        describing the remote wiki server.  The page must contain
        the RemoteWikiURL keyword followed by the URL on the same
        line.

      - **References**

        Enter this::

           I am going to refer to a footnote here [1].

           Later in the text I will have a footnotes
           section.

           ..[1] My footnote.  Note that its two periods at the
           start of a line, '..', followed by a space and then link
           in square brackets.

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>

          I am going to refer to a footnote here [1].

          Later in the text I will have a footnotes
          section.

          .. [1] My footnote.  Note that its two periods, '..', followed
          by a space and then link in square brackets.

          </td></tr></table>

    **Preventing Links**

      - Put the expression in &#39; single-quote code-fragment form:
      'ZWiki'

      - Put the expression in an "::" example block::

            StructuredText, http://www.zope.org, <strong>nope!</strong>

      - Prefix the WikiWord or '[]' square brackets with an
        exclamation point::

            !!StructuredText, !![meta comment]

        to get
        this:

          <table><tr><td bgcolor="lightgray" border=1>
          !StructuredText, ![meta comment]
          </td></tr></table>

  Images

    **Images**

      Enter this::

         "Text shown when the browser does not load the
         image":img:logo.jpg

      to get
      this:

        <table><tr><td bgcolor="lightgray" border=1>

        "Text shown when the browser does not load the
        image":img:logo.jpg

        </td></tr></table>

      You can use an arbitrary URL for the image, e.g.::

         "Plone logo":img:http://www.plone.org/logo.jpg

      <table><tr><td bgcolor="lightgray" border=1>

      "Plone logo":img:http://www.plone.org/logo.jpg

      </td></tr></table>

      Note that ZWiki differs from StructuredText documents here as
      ZWiki will render the text and not the image, and a
      StructuredText document will render the image.  If you really
      need a graphic in a ZWiki page, use an HTML 'img' link.

  Tables

    **Tables**

      Enter this::

        |------------------------------------|
        | Fruit     | Nut        | Mammal    |
        |====================================|
        | Apple     | Peanut     | Squirrel  |
        |------------------------------------|
        | Orange    | Macadamia  | Woodchuck |
        |------------------------------------|
        | Banana    | Walnut     | Dolphin   |
        |------------------------------------|
        | This spans 2 columns!  | Cat       |
        |------------------------------------|
        | Pear      | This spans 2 columns!  |
        |------------------------------------|
        | This spans 3 columns!              |
        |------------------------------------|

     to get
     this:

       <table><tr><td bgcolor="lightgray" border=1>

       |------------------------------------|
       | Fruit     | Nut        | Mammal    |
       |====================================|
       | Apple     | Peanut     | Squirrel  |
       |------------------------------------|
       | Orange    | Macadamia  | Woodchuck |
       |------------------------------------|
       | Banana    | Walnut     | Dolphin   |
       |------------------------------------|
       | This spans 2 columns!  | Cat       |
       |------------------------------------|
       | Pear      | This spans 2 columns!  |
       |------------------------------------|
       | This spans 3 columns!              |
       |------------------------------------|

       </td></tr></table>

    Be careful about numbers in cells being interpreted as list
    items!  Each cell will be treated as if it started a new line.

SeeAlso: StructuredTextFormattingSurprises, StructuredTextProblems
--<cut>--