<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"DTD/xhtml1-transitional.dtd">
<head>
<title>
WebMake: Documentation: The Text::EtText Format Converter
</title>
<meta name="generator" content="WebMake/1.2" />
<style>
body {
background-color: #ffffff;
color: #000000;
font-size: medium;
font-family: verdana,lucida,helvetica,sans-serif;
}
// OL,UL,P,BODY,TD,TR,TH,FORM {
// font-family: verdana,lucida,helvetica,sans-serif;
// font-size: medium;
// color: #000000;
}
code, samp, pre
{
font-family: monospace;
}
H1 { font-size: x-large; font-family: Garamond,Book Antiqua,Times,serif; background: #FFCC66; }
H2 { font-size: large; font-family: Garamond,Book Antiqua,Times,serif; background: #FFDD77; }
H3 { font-size: medium; font-family: Garamond,Book Antiqua,Times,serif; background: #FFEE88; }
H4 { font-size: small; font-family: Garamond,Book Antiqua,Times,serif; }
H5 { font-size: x-small; font-family: Garamond,Book Antiqua,Times,serif; }
H6 { font-size: xx-small; font-family: Garamond,Book Antiqua,Times,serif; }
A:link {
font-weight: bold;
color: #004000;
text-decoration: underline;
}
A:visited {
font-weight: normal;
color: #008000;
text-decoration: underline;
}
A:active {
font-weight: bold;
color: #800000;
text-decoration: underline;
}
</style>
</head>
<body bgcolor="#ffffff" text="#000000" link="#3300cc" vlink="#660066">
<font face="lucida,verdana,sans-serif">
<div align="center">
<img src="images/WebMakeTitle.png" width="500" height="122" />
</div>
<table width="100%">
<tr>
<td valign="top">
Documentation</strong> (version 1.2)
</td>
<td valign="top">
<div align="right">
[ <a href="index_07-fmt_converters.html">Back</a> | <a href="pod.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td bgcolor="#aaaaaa">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td bgcolor="#ffffff">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td>
<h1>The Text::EtText Format Converter</h1><p>
This converter converts from Text::EtText, a simple plain-text format, to
handles the usual things: insertion of <em><P></em> tags, header recognition
and markup. However it adds a powerful link markup system.
</p>
<p>
EtText is no longer included in WebMake; instead it must be downloaded
detailed set of documentation. However, this page is retained in WebMake
for quick reference.
</p>
<a name="Basic_Text_Markup"><h3>Basic Text Markup</h3></a> <p>
If you leave blank lines between paragraphs, <strong><p></strong> and
<strong></p></strong> tags will be inserted in the correct places.
EtText does quite a good job of this.
</p>
<p>
Words wrap and fill automatically, so there's no need to worry about wrapping
before 80 characters. (It's good form to do so anyway, in case other people
ever need to edit your text, though.)
</p>
<p>
A paragraph consisting of a line of 10 or more consecutive - or _ signs will
be converted to a HR tag.
</p>
<p>
Sections of text between pairs of certain characters will be turned into
markup, as follows:
</p>
<blockquote>
<p>
<table>
<tr>
<th width="30%">
<strong>EtText</strong>
</th>
<th width="30%">
<strong>Tag Used</strong>
</th>
<th width="30%">
<strong>Result</strong>
</th>
</tr>
<tr>
<td width="30%">
<code>**text**</code>
</td>
<td width="30%">
<strong>
</td>
<td width="30%">
<strong>text</strong>
</td>
</tr>
<tr>
<td width="30%">
<code>__text__</code>
</td>
<td width="30%">
<em>
</td>
<td width="30%">
<em>text</em>
</td>
</tr>
<tr>
<td width="30%">
<code>##text##</code>
</td>
<td width="30%">
<code>
</td>
<td width="30%">
<code>text</code>
</td>
</tr>
</table>
</p>
</blockquote>
<p>
<strong>&</strong> signs that have whitespace on either side will be converted
to <strong>&amp;</strong> signs automatically.
</p>
<p>
Text indented from the left margin will be converted into a <strong><P></strong>
paragraph wrapped in a <strong><blockquote></strong> -- unless it starts with a
<code>*</code>, <code>-</code>, <code>+</code> or <code>o</code> character
followed by whitespace, in which case it's interpreted as a list item; see
<strong>Lists</strong> below.
</p>
<p>
Another exception to the above rule is that text indented by only 1 space, or
on lines starting in the first column with two colon characters, will be
surrounded by <pre> tags.
</p>
<p>
If you find writing HTML tag-pairs manually annoying, EtText includes an idea
the name of the tag followed immediately by a { character on the left, and a }
character on the right. In other words,
</p>
<blockquote>
<p>
<code>strong{text}</code>
</p>
</blockquote>
<p>
will be rendered as
</p>
<blockquote>
<p>
<strong>text</strong>
</p>
</blockquote>
<p>
or, in other words, <strong>text</strong> . This can be nested, so <code>strong{text
with i{italic} bits}</code> will be rendered as <strong>text with <i>italic</i>
bits</strong>.
</p>
<p>
In addition, the balanced-tag support has a bonus feature, in that it supports
CSS classes; follow the name of the tag with a full stop and the class, and
it will use that class, like so:
</p>
<blockquote>
<p>
<code>i.green{foo}</code>
</p>
</blockquote>
<p>
will be rendered as
</p>
<blockquote>
<p>
<i class="green>foo</i>
</p>
</blockquote>
<a name="Lists"><h3>Lists</h3></a> <p>
A paragraph indented from the left margin (by either spaces or tabs, or both),
and starting with a <code>*</code>, <code>-</code>, <code>+</code> or
<code>o</code> character followed by whitespace, will be converted into a list
item (<strong><li></strong> tag).
</p>
<p>
The same goes for indented paragraphs that start with the string
<code>1.</code>, followed by whitespace. However the default list tag in this
case will be an <strong><ol></strong>...<strong></ol></strong> list. Any positive integer
followed immediately by a full stop and a space will do the trick. (BTW: I
used to use <code>#</code> to do this, but I preferred the WikiIdea, it
looks better.)
</p>
<blockquote>
<p>
<em>(Compatibility note: previous versions of EtText required that the
<strong><ul></strong> or <strong><ol></strong> tags be written manually. This is no
longer the case.)</em>
</p>
</blockquote>
<p>
Some text editors (such as <em>vim</em>) will reformat list items automatically,
assuming that you want the text to line up with the start of the text, instead
of the bullet-point character, on the previous line, like so:
</p>
<p>
<pre>
- this is a list item. We should make sure that
blah blah etc. etc.
</pre>
</p>
<p>
WebMake supports this.
</p>
<p>
Indented paragraphs that start with <code><strong>term</strong>:</code> <em>tab</em> <code><strong>rest of paragraph</strong></code> will be converted
into definition lists (this is another StolenFromWikiIdea). They
look like this:
</p>
<dl>
<dt>
Foo
</dt>
<dd>
<p>
Blah blah blah etc.
</p>
</dd>
</dl>
<a name="Sidebars_and_Side_Images"><h3>Sidebars and Side Images</h3></a> <p>
If you wish to display an image, or small sidebar, beside a paragraph of text,
use the <strong><etleft></strong> and <strong><etright></strong>
tags. These are rendered as a one-row, two-column
<strong><table></strong> wrapping the paragraph and the sidebar, as
follows:
</p>
<p>
<pre>
<etleft><img src=bubba.png></etleft>This is the main
paragraph body. Foo bar baz blah blah blah etc.
</pre>
</p>
<p>
Is displayed as:
</p>
<table>
<tr>
<td valign="top">
<img src="bubba.png" width="110" height="70" />
</td>
<td width="99%" valign="top">
<p>
This is the main paragraph body.
Foo bar baz blah blah blah etc.
</p>
</td>
</tr>
</table>
<p>
<pre>
<etright><img src=bubba.png></etright>This is the
main paragraph body. Foo bar baz blah blah blah etc.
</pre>
</p>
<p>
Is displayed as:
</p>
<table>
<tr>
<td width="99%" valign="top">
<p>
This is the main paragraph body.
Foo bar baz blah blah blah etc.
</p>
</td>
<td valign="top">
<img src="bubba.png" width="110" height="70" />
</td>
</tr>
</table>
<a name="When_HTML_and_EtText_Collide"><h3>When HTML and EtText Collide</h3></a> <p>
HTML tags can be used freely throughout an EtText document. However, in some
situations, you may wish to preserve whitespace, avoid paragraph tags being
added, etc.; to use your own HTML without meddling from EtText, wrap it in an
<strong><!--etsafe--></strong>...<strong><!--/etsafe--></strong>
tag pair; this will protect it.
</p>
<p>
Note that text blocks wrapped in <strong><pre></strong>,
<strong><listing></strong> and <strong><xmp></strong> tags are
automatically protected in this way; the <strong><!--etsafe--></strong>
tag pair is not required.
</p>
<p>
EtText adds two entities, &etsqi; and &etsqo;. These represent
[ and ] respectively, and are used to protect a square-bracketed
piece of text from being interpreted as a link URL (see <em>Link Markup</em>
below).
</p>
<a name="EtText_Links"><h3>EtText Links</h3></a> <p>
As well as the standard <strong><a href=url>...</a></strong> link
specification used in HTML, EtText will automatically add href tags for URLs
and email addresses that occur in the text. In addition, EtText supports its
own link format, as follows.
</p>
<p>
The basic concept is of a word or "quoted set of words" followed by a link
label in [square brackets], like this: <strong>"this is a link"
[label]</strong>.
</p>
<p>
The href used in the link is then defined at another point in the document, as
an indented line like this:
</p>
<blockquote>
<p>
</p>
</blockquote>
<p>
Text and markup can be enclosed in the quotes, everything quoted will become
part of the link text. Single words or HTML tags do not need to be quoted, so
this will work correctly:
</p>
<p>
<pre>
width="10" height="10" /> [homepage]
</pre>
</p>
<a name="Glossary_Links"><h3>Glossary Links</h3></a> <p>
EtText also supports a concept called <em>glossary links</em>; if you define a
link, the name of that link will automatically become a href if enclosed in
quotes. For example:
</p>
<blockquote>
<p>
</p>
</blockquote>
<p>
will mean that any occurrence of the name <strong>"Justin Mason"</strong>, in quotes, in
<em>any</em> EtText content chunk or file in the site, becomes a link to that
address. These links are stored in the WebMake <a href="making.html">cache file</a>.
</p>
<p>
Quoted bits of text that do not map to an entry in the glossary are not
converted to links (unless they're followed by a square-bracketed link-label
reference).
</p>
<p>
<a href="mailto:jm@nospam-jmason.org">jm@nospam-jmason.org</a>, are automatically converted into links to that same
address.
</p>
<a name="Blocking_EtText_Link_Interpretation"><h3>Blocking EtText Link Interpretation</h3></a> <p>
To block interpretation as a link, replace square brackets with the HTML
entities <strong>&etsqi;</strong> and <strong>&etsqo;</strong>, which map to [ and ]
respectively; replace quote characters, <strong>"</strong>, with two apostrophes,
<strong>''</strong>. If that doesn't do the trick, wrap the entire section of text
with the <strong><!--etsafe--></strong>...<strong><!--/etsafe--></strong> tags.
</p>
<a name="Similar_Systems"><h3>Similar Systems</h3></a> <p>
EtText-like plain-text-to-markup conversion systems have a long history. The
included with Tony Sanders' <em>Plexus</em> web server, back in September 1993.
Yes, 1993. Setext has been around for a while!
</p>
<p>
WikiWikiWeb is quite a recent, well-established system which uses
a similar markup style.
</p>
<p>
system as well.
</p>
<p>
Some well-known sites that use their own converters to convert
</p>
<p>
Wisdom site</a>. Skip down to section 3, <em>Internet etext
standards</em>, for the directly-relevant stuff.
</p>
<p>
object, which is <em>a web-managable object that contains information marked up
in the structured text format</em>.
</p>
<p>
</p>
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
</tr>
</table>
<table width="100%">
<tr>
<td valign="top">
Documentation</strong> (version 1.2)
</td>
<td valign="top">
<div align="right">
[ <a href="index_07-fmt_converters.html">Back</a> | <a href="pod.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<div align="right">
</div>
</font>
</body>
</html>
