Blocks of text in this application are mainly plain text. That means that newline characters will be faithfully represented when rendered into an output format. There are also several tags supported that allow you to build commonly used constructions, like ordered and unordered lists, preformatted blocks, quoted blocks and more.

These tags look like HTML and often share a name with a similar HTML element, but are not actually HTML tags. The content you write is transformed to HTML when displayed in a web page, but can also be transformed to plain text - e.g. when generating a plain text email.

Single-line vs. Multi-line

Some fields, like object titles, are explicitly single-line and support only a limited number of tags. In particular, block and image tags are not applied and are instead inserted as if they were just text. Only the <b>, <i> and <code> tags are supported in single-line mode. If attributes are specified, the tag will be rendered as text (this behavior may change in future revisions).

Newline handling

If you are just writing unformatted text, you may treat newlines as you normally would; both the HTML and plain text formatter will honor the spacing you've chosen. In some cases, HTML forces extra spacing that cannot be avoided - e.g. if you separate a normal text run from a preformatted text run with a single newline, HTML will render this with a double newline because the blocks are separated by a margin. In these cases, it makes no difference if you use zero, one or two newlines -- there are always two newlines rendered. The plain text formatter has been written to emulate this behavior, so that the plain text representation is as close as possible to the 'main' HTML output format.

Special Characters

Certain characters will be automatically replaced if they appear anywhere in regular text. You can disable this replacement for whole regions by using the <macro> tag.

Additionally, the following character pairs are automatically converted to their ligature equivalents. Some browsers don't especially like these characters, so this conversion is off, by default. You can enable this replacement for whole regions using the <macro> tag.

Paths/resources

As you'll see below, you can add images and links to your text really easily. You don't have to use absolute urls though. You can base your url on a path defined in the WebCore application by specifying a base 'location' at the start of your url, like this:

{icons}file_types/file_32px

If you leave off the extension when referring to an icon file, the default application icon extension is applied, so you get:

If, at some point, you move your icons, your reference to the icons folder won't be broken. This works for other stuff as well, like attachments. You can refer to an attachment file like this:

{att_link}my_file.zip

The path to the attachments folder for the current object will be prepended for you. If the attachment is an image, you can use that path as the 'src' attribute of an image and it will show up in the page. Or you can use {att_thumb} to show only the thumbnail for it.

Supported locations (you can also add your own) are:

• application: Root url for the current application.
• icons: Location of the application icons folder.
• styles: Location of the application styles folder.
• scripts: Location of the application scripts folder.
• att_link: Location of attachments for the current object.
• att_thumb: Converts the given attachment file to thumbnail name.
• pic_image: Location of images for the current album. Accepts a picture ID or file name. Only available in earthli Albums.
• pic_thumb: Same as "pic_image", but converts to the thumbnail name. Only available in earthli Albums.

Controlling the formatter

As discussed in special characters, you can control which types of character replacement occur within a block of text. The <macro> tag applies options, which apply for the rest of the text or until they are changed by a subsequent macro.

The following properties are supported:

convert

Pass in a comma-delimited list of converters, which should be active. Use a plus (+) sign to enable a converter and a minus (-) sign to disable it. If no sign is present, it is assumed to be enabling the converter. The converters in the list are applied in order and can overwrite one another. Choose from the following converters:

• punctuation: If enabled, punctuation marks are replaced with their fancier HTML equivalents. enabled by default
• ligature: If enabled, ligatures are replaced with their fancier HTML equivalents. disabled by default
• tags: If enabled, special html characters are converted to avoid being interpreted as HTML. The keyword "all" does not apply to this converter; you must explicitly toggle it if you want to change the setting. enabled by default
• highlight: If enabled, keywords from a search are highlighted within the text. enabled by default
• all: Applies to all converters except for "tags".

The following examples turn on ligatures:

<macro convert="ligature"> or <macro convert="+ligature">

The following examples turn off everything but highlighting:

<macro convert="-ligature,-punctuation"> or <macro convert="-all;+highlight">

The following example makes sure that all converters are turned on:

<macro convert="+all">

Tags

Tags are the same format as HTML tags (e.g. <tag attr="value">). The tokenizer recognizes as a tag any grouping of text that starts with <, has a letter or number as the next letter, then ends with >. This is discussed in more detail in Using < as text. If a tag is not recognized, it will be rendered as text. The list of recognized tags follow and are recognized by both the HTML and plain text formatters. When a tag is recognized, that means that it will not be rendered as text by the formatter, but will either be used directly, transformed to another tag or construct or discarded, depending on the output format.

Unknown tags are rendered as text, by default.

Literal characters

In this version, you may type anything you like; there is no longer a need to specifically escape characters as HTML. The input language is no longer HTML, so escaping characters has been limited to the single case of the < character, discussed next.

Using < as text

Since the content can be delimited by tags, the < character must necessarily be escaped in certain circumstances. These situations have been limited so that you will only very rarely have to use the escaped character. The only time you may need to escape the < character is if the character immediately following it is a letter or number. To escape the <, use <<.

Examples

If you want to write:

x < y and 5 < 8

you do not need to escape anything. Simply write it as shown above and the formatter detects that the < characters in the text cannot be parts of tags.

If you want to write:

If the text in the input box is still <default>, then you have to...

you still don't have to escape the bracket, since the formatter simply renders unknown tags as text anyway. In the next example, we see where we must include an escaped < character.

If you want to write:

<pre> to specify a backlink, use <linkname. </pre>

The problem here is that the tokenizer will recognize '<linkname. </pre>' as a tag, which will cause the </pre> end tag to be ignored, with unpredictable results. The text will still be output, but the preformatted region will not be properly rendered. To avoid this, use the escaped version of the < character:

<pre> to specify a backlink, use <<linkname. </pre>

Preformatted text and source code

Whitespace is interpreted differently by different output formats, so the <pre> tag can be used to force the formatter to use the exact whitespace you have specified. This is very useful for displaying code samples. For specifying that a block of text is source code, you may use the <code> tag. This will alter the display in the HTML formatter, but is stripped when rendered as plain text. For inline code examples, use the <c> tag. Text is still generally formatted the same as with the code tag, except that it doesn't force block formatting.

Tag attributes, if specified, are retained.

Headings

Headings are written with the <h> tag. Use headings to delineate new sections in longer text flows. The default heading is slightly larger than regular text and bold. Plain text mode will maintain proper spacing for headings even if you don't specify it. The following attributes are allowed.

level

Heading level, analogous to the HTML heading level. The default is 3. Since headings are usually just used to distinguish between sections, you shouldn't often need to control the heading level.

Example

<h>earthli WebCore</h>

HTML result

earthli WebCore

Plain text result

[earthli WebCore]

Links

Links are written with the <a> tag. The following attributes are allowed.

title

The title of the link. Can be a longer description of the resource to which the link goes.

class

This will assign the specified CSS class to the link itself.

href

The url to which the link goes.

format

This is used only in the plain-text renderer. The default value is 'all'.

• url: Show only the url.
• all: Show the url and title.
• none: Skip this link.

Example

<a href="http://www.earthli.com/software/webcore/" title="Try out the earthli WebCore!">earthli WebCore</a>

HTML result

earthli WebCore

Plain text result

earthli WebCore <http://www.earthli.com/software/webcore/> (Try out the earthli WebCore!)

Images

Images are inserted with the <img> tag. The following list of tags are supported.

The image must already exist as a URL. Inserting an image link does not magically upload a file for you.

src

The url for the image itself. Use path/resource syntax or an absolute URL.

href

If this is non-empty, a link is automatically wrapped around the image with this url. Use path/resource syntax or an absolute URL.

attachment

If this is non-empty, both "src" and "href" are ignored. Instead, both properties are automatically generated from the attachment file name given. It's up to the user to make sure the attachment is exists and is accessible.

title

Longer description of the linked image. If this is not given, then the value for 'alt' is used.

alt

Alternate description of the image. Should be concise. Put longer description in 'title', if needed. If this is not given, then the value for 'title' is used.

align

The default value is 'none'. This parameter is ignored in the plain-text renderer.

• left: Float the image to the left, with text wrapped around to the right.
• right: Float the image to the right, with text wrapped around to the left.
• center: Image is centered in its own block. Text is split, with the flow continuing after the image.
• none: Image is formatted inline with the text

class

This will assign the specified CSS class to the image itself. This parameter is ignored in the plain-text renderer.

format

This is used only in the plain-text renderer. The default value is 'all'. If 'alt' is not specified, 'title' is used for the text. If a url is included, 'href' is always used before 'src'.

• basic: Show only the 'alt' or 'title'.
• url: Show a url and 'alt', but no title.
• all: Show a url, 'alt' and the title (if different than 'alt' and 'alt' is non-empty).
• none: Skip this image.

Example

<img src="{icons}/file_types/file_50px" align="right" alt="WebCore File Icon" format="basic">This is purely sample text to illustrate that the text immediately following an image tag will be formatted around the image if it has an 'align' value of 'left' or 'right'. If it has an alignment of 'center', the image is placed in its own block, separating the text flow. If it is 'none', the image is simply rendered inline with the text. The image below is formatted differently.

<img href="http://data.earthli.com/albums/oz/images/im000185.jpg" src="http://www.earthli.com/users/oz/images/IM000185_tn.jpg" align="center" title="Ozzie in the garden">

HTML result

This is purely sample text to illustrate that the text immediately following an image tag will be formatted around the image if it has an 'align' value of 'left' or 'right'. If it has an alignment of 'center', the image is placed in its own block, separating the text flow. If it is 'none', the image is simply rendered inline with the text.

Plain text result

[WebCore Logo] This is purely sample text to illustrate that the text immediately following an image tag will be formatted around the image if it has an 'align' value of 'left' or 'right'. If it has an alignment of 'center', the image is placed in its own block, separating the text flow. If it is 'none', the image is simply rendered inline with the text.

[Ozzie in the garden] <http://www.earthli.com/users/oz/images/IM000185.jpg>

Videos

Videos can be embedded just as easily as images with the <img> tag. In fact, almost all of the properties documented for image handling work exactly the same for videos. You can reference local videos using the "attachment" property or remote videos using a full url in the "src" property. The "href" property is not used for videos.

Font formatting

There are two font formatting tags, <i> and <b>. In the HTML formatter, these translate to 'em' and 'strong'. They are ignored in the plain-text formatter.

Generic formatting

You may also use <span> and <div> tags. In the HTML formatter, they are copied in as tags and will have whatever functionality the browser gives them. They are ignored in the plain-text formatter.

Lists

Unordered, ordered and definition lists are supported. Use a <ul> tag to wrap text in an unordered list, an <ol> tag to create an ordered one and a <dl> tag to create a definition list. A new list item is created for each newline encountered in the list. The first and last newlines in a list are always ignored and are assumed to be for tag formatting. Lists and other tags can be freely mixed and nested. Plain text formatting will maintain vertical margins even if none are specified in the source text.

Tag attributes, if specified, are retained.

Examples

This is the way you would normally write lists, with indenting and newlines handled as expected. The indenting is not necessary here, but is used to make the source text clearer.

<ul>
One
<ol>
  1.25
  1.50
  1.75
</ol>
Two
Three
</ul>

It is possible to fully nest a list within an item, so that the item's text can continue after the list. The first item in the outer list is now formatted that way, so that 'Two' is no longer it's own list item. The only difference here is that there is no new line after 'One' in the text; this indicates that the item should continue after the embedded list.

<ul>
One<ol>
  1.25
  1.50
  1.75
</ol>
Two
Three
</ul>

Inserting blank lines will generate blank list items.

<ul>

One
<ol>
  1.25
  1.50
  1.75
</ol>
Two
Three
More...



</ul>

Definition lists generate alternating terms and definitions for each newline between the start and end tags. Two attributes are supported: dt_class and dd_class, which define the CSS class for definition terms and definitions, respectively.

<dl dt_class="field" dd_class="notes">
First Term
Definition.
Second Term
Definition.
</dl>

Quoting

Often, you pull information from other sites. You can indicate this with the <iq> (inline quote) and <bq> (block quote) tags. The inline-quote just applies formatting and coloring. The block quote will put the text in a separate block and indent it slightly, while also providing theme-specific coloring and formatting.

Tag attributes, if specified, are discarded.

Inline Quote Example

As Mark Twain once said, <iq>A banker is a fellow who lends you his umbrella when the sun is shining, but wants it back the minute it begins to rain.</iq>.

Result

As Mark Twain once said, "A banker is a fellow who lends you his umbrella when the sun is shining, but wants it back the minute it begins to rain."

Block Quote Example

As Mark Twain once said, <bq>A banker is a fellow who lends you his umbrella when the sun is shining, but wants it back the minute it begins to rain.</bq>

Result

As Mark Twain once said,

Notes

Another useful tag is the <n> tag. This uses a smaller font and is generally in italics to indicate that the text is supplemental or tangential. In the HTML formatter, this translates to the 'notes' CSS style. It is ignored in the plain-text formatter.

Notes Example

This is the main flow of text. Here is where I mention that you may look below* for more information. The normal flow continues until the paragraph ends.

<n>*This is the tangential extra information I referenced above.</n>

Result

This is the main flow of text. Here is where I mention that you may look below* for more information. The normal flow continues until the paragraph ends.

*This is the tangential extra information I referenced above.

Boxes

When formatting code or larger quoted samples, it's nice to be able box the content out. Use the <box> tag for this, with the following (optional) attributes:

title

The title of the box. This is usually formatted as a title bar on the box itself.

align

left, center, right or none. The default is none. Right and left float the box to the right or left and center leaves it centered.

width

If you specify a left or right alignment, you will probably want to specify a width as well. This attribute accepts all CSS values.

class

This will assign the specified CSS class to the innermost generated container (affecting the box's content).

All other attributes, if specified, are discarded.

Example

<box title="Listing One" align="right" width="35%">
<pre><code>function add_parsed (&$data)
{
$data = trim ($data);
if ($data)
  // if there is any data being added
{
  $this->_parse_unparsed_buffer ();
  if (! $this->_parsing_started)
  {
    // parsed buffer has not
  }
    // been initialized yet
  {
    $this->_open_buffer ();
    $this->_parsing_started = true;
  }
  $this->_parsed_buffer .= $data;
}
}
</code></pre>
</box>

This is a piece of code from the MUNGER class in the WebCore library. This text here is just to show how the box looks when it is floated next to content. I'm just going to write as much as I need to in order to make the paragraph as long as the box itself. Here's a chunk of text quoted from another article:

<bq style="margin-right: 25em">To Microsoft's credit, they are being quite aggressive about solving this particular hole. Even to the point of coming up with the embarassing solution of saying that they can't be trusted. So, perhaps they do mean it when they say they are now a security company and start babbling about Palladium and DRM. They just mean they care about telling people about security holes, but don't actually intend to write decent software.</bq>

There, that should make it long enough.

Result

function add_parsed ($data)
{
$data = trim ($data);
if ($data)
  // if there is any
  //data being added
{
  $this->_parse_unparsed_buffer ();
  if (! $this->_parsing_started)
  {
    // parsed buffer has
  }
    // not been initialized yet
  {
    $this->_open_buffer ();
    $this->_parsing_started = true;
  }
  $this->_parsed_buffer .= $data;
}
}

This is a piece of code from the MUNGER class in the WebCore library. This text here is just to show how the box looks when it is floated next to content. I'm just going to write as much as I need to in order to make the paragraph as long as the box itself. Here's a chunk of text quoted from another article:

There, that should make it long enough.

The width is not specified because the <pre> tag is used and that will size the box correctly in most browsers. If you just have flowing text, you should use a width or the box will simply take up the width of the window and won't really be floating. Note also how the block-quote has a right margin to prevent it from flowing behind the floating box. This addresses a limitation in CSS2; CSS3 should provide a style which honors margins with respect to floating elements as well.