<wmmeta name="Title" value="The Text::EtText Format Converter" />
<wmmeta name="Section" value="07-fmt_converters" />
<wmmeta name="Score" value="10" />
<wmmeta name="Abstract">
A simple plain-text format, easily converted to HTML (format: <em>text/et</em>)
</wmmeta>

This converter converts from Text::EtText, a simple plain-text format, to
HTML.  Like most simple text markup formats (POD, setext, etc.), EtText markup
handles the usual things: insertion of __&lt;P&gt;__ tags, header recognition
and markup. However it adds a powerful link markup system.

EtText is no longer included in WebMake; instead it must be downloaded
separately from http://ettext.taint.org/, where there is also a more
detailed set of documentation.  However, this page is retained in WebMake
for quick reference.

Basic Text Markup
~~~~~~~~~~~~~~~~~

If you leave blank lines between paragraphs, **&lt;p&gt;** and
**&lt;/p&gt;** tags will be inserted in the correct places.
EtText does quite a good job of this.

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.)

A paragraph consisting of a line of 10 or more consecutive - or _ signs will
be converted to a HR tag.

Sections of text between pairs of certain characters will be turned into
markup, as follows:

  <table>
  <tr><th width=30%>**EtText**</th>
  <th width=30%>**Tag Used**</th>
  <th width=30%>**Result**</th>
  </tr>
  <tr><td width=30%><code>&#42;&#42;text&#42;&#42;</code></td>
  <td width=30%>&lt;strong&gt;</td>
  <td width=30%>**text**</td>
  </tr>
  <tr><td width=30%><code>&#95;&#95;text&#95;&#95;</code></td>
  <td width=30%>&lt;em&gt;</td>
  <td width=30%>__text__</td>
  </tr>
  <tr><td width=30%><code>&#35;&#35;text&#35;&#35;</code></td>
  <td width=30%>&lt;code&gt;</td>
  <td width=30%>##text##</td>
  </tr>
  </table>

**&amp;** signs that have whitespace on either side will be converted
to **&amp;amp;** signs automatically.

Text indented from the left margin will be converted into a **&lt;P&gt;**
paragraph wrapped in a **&lt;blockquote&gt;** -- 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
**Lists** below.

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 &lt;pre&gt; tags.

If you find writing HTML tag-pairs manually annoying, EtText includes an idea
from Latte [latte]; balanced-tag generation.  Wrap the text to be tagged with
the name of the tag followed immediately by a { character on the left, and a }
character on the right.  In other words,

	code{strong&#123;text&#125;}
	
will be rendered as

	&lt;strong&gt;text&lt;/strong&gt;

or, in other words, **text** .  This can be nested, so code{strong&#123;text
with i&#123;italic&#125; bits&#125;} will be rendered as **text with i{italic}
bits**.

	Auto: [latte]: http://www.latte.org/

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:

	code{i.green&#123;foo&#125;}
	
will be rendered as

	&lt;i class="green&gt;foo&lt;/i&gt;

Lists
~~~~~

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 (**&lt;li&gt;** tag).

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 **&lt;ol&gt;**...**&lt;/ol&gt;** 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 [Wiki], it
looks better.)

	__(Compatibility note: previous versions of EtText required that the
	**&lt;ul&gt;** or **&lt;ol&gt;** tags be written manually. This is no
	longer the case.)__

Some text editors (such as __vim__) 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:

<pre>
	- this is a list item. We should make sure that
	  blah blah etc. etc.
</pre>

WebMake supports this.

Indented paragraphs that start with <code>**term**:</code>
__tab__ <code>**rest of paragraph**</code> will be converted
into definition lists (this is another StolenFromWikiIdea [Wiki]).  They
look like this:

	Foo:	Blah blah blah etc.

Sidebars and Side Images
~~~~~~~~~~~~~~~~~~~~~~~~

If you wish to display an image, or small sidebar, beside a paragraph of text,
use the **&lt;etleft&gt;** and **&lt;etright&gt;**
tags.  These are rendered as a one-row, two-column
**&lt;table&gt;** wrapping the paragraph and the sidebar, as
follows:

<pre>
&lt;etleft&gt;&lt;img src=bubba.png&gt;&lt;/etleft&gt;This is the main
paragraph body.  Foo bar baz blah blah blah etc.
</pre>

Is displayed as:

<etleft><img src=bubba.png></etleft>This is the main paragraph body.
Foo bar baz blah blah blah etc.

<pre>
&lt;etright&gt;&lt;img src=bubba.png&gt;&lt;/etright&gt;This is the
main paragraph body.  Foo bar baz blah blah blah etc.
</pre>

Is displayed as:

<etright><img src=bubba.png></etright>This is the main paragraph body.
Foo bar baz blah blah blah etc.

When HTML and EtText Collide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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
**&lt;!--etsafe--&gt;**...**&lt;!--/etsafe--&gt;**
tag pair; this will protect it.

Note that text blocks wrapped in **&lt;pre&gt;**,
**&lt;listing&gt;** and **&lt;xmp&gt;** tags are
automatically protected in this way; the **&lt;!--etsafe--&gt;**
tag pair is not required.

EtText adds two entities, &amp;etsqi; and &amp;etsqo;.  These represent
&etsqi; and &etsqo; respectively, and are used to protect a square-bracketed
piece of text from being interpreted as a link URL (see __Link Markup__
below).

EtText Links
~~~~~~~~~~~

As well as the standard **&lt;a href=url&gt;...&lt;/a&gt;** 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.

The basic concept is of a word or ''quoted set of words'' followed by a link
label in &etsqi;square brackets&etsqo;, like this: **''this is a link''
&etsqi;label&etsqo;**.

The href used in the link is then defined at another point in the document, as
an indented line like this:

	&etsqi;__label__&etsqo;: __http://url...__

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:

<safe>
  <img src="http://jmason.org/license_plate.jpg"
  	width="10" height="10" /> [homepage]
</safe>

Glossary Links
~~~~~~~~~~~~~~

EtText also supports a concept called __glossary links__; if you define a
link, the name of that link will automatically become a href if enclosed in
quotes. For example:

	&etsqi;Justin Mason&etsqo;: http://jmason.org/

will mean that any occurrence of the name **''Justin Mason''**, in quotes, in
__any__ EtText content chunk or file in the site, becomes a link to that
address.  These links are stored in the WebMake "cache file" [making].

	Auto: [making]: $(making)

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).

URLs, such as http://webmake.taint.org/ , and email addresses, such as
jm@nospam-jmason.org, are automatically converted into links to that same
address.

Blocking EtText Link Interpretation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To block interpretation as a link, replace square brackets with the HTML
entities **&amp;etsqi;** and **&amp;etsqo;**, which map to &etsqi; and &etsqo;
respectively; replace quote characters, **"**, with two apostrophes,
**&#39;&#39;**.  If that doesn't do the trick, wrap the entire section of text
with the **&lt;!--etsafe--&gt;**...**&lt;!--/etsafe--&gt;** tags.

Similar Systems
~~~~~~~~~~~~~~~

EtText-like plain-text-to-markup conversion systems have a long history.  The
first time I came across the concept was with Setext [setext], which was
included with Tony Sanders' __Plexus__ web server, back in September 1993.
Yes, 1993. Setext has been around for a while!

	Auto: [setext]: http://www.bsdi.com/setext/
	Auto: [Wiki]: http://c2.com/cgi/wiki?WikiWikiWeb

WikiWikiWeb [Wiki] is quite a recent, well-established system which uses
a similar markup style.

Userland's Frontier [frontier] includes a text-to-markup conversion
system as well.

	Auto: [frontier]: http://www.userland.com/

Some well-known sites that use their own converters to convert
plain-text to markup include http://www.blogger.com/, http://slashdot.org/
(for comments) and http://www.advogato.org/.

Jorn Barger maintains an impressive summary of etext formats at "his Robot
Wisdom site" [etextfaq]. Skip down to section 3, <em>Internet etext
standards</em>, for the directly-relevant stuff.

	[etextfaq]: http://www.robotwisdom.com/net/etextfaq.html

Zope and ZWiki use a format called "StructuredText", which again comes from
WikiLand. There's some interesting work going on there with the "STXDocument"
object, which is __a web-managable object that contains information marked up
in the structured text format__.

    Auto: [StructuredText]: http://dev.zope.org/Wikis/DevSite/Proposals/StructuredText
    Auto: [STXDocument]: http://www.zope.org/Members/jim/StructuredTextWiki/STXDocument
