[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: 'code' => '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 <pre> and </pre>
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 ' 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>--