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, pre-formatted 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.

Text

Single-line vs. Multi-line

Some fields, like object titles, are explicitly single-line and support only a limited number of nested tags. If block or image tags are included, they are instead inserted as if they were just text. Only the <b>, <i> and <c> tags are supported in single-line mode.

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 vertical 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 pre-formatted 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. Most browsers don't especially like these characters[1], so this conversion is off, by default. You can enable this replacement for whole regions using the <macro> tag.

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.

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.

Using < as text

Since the content can be delimited by tags, the < character must 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 <<.

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 -matted region will not be properly rendered. To avoid this, use the escaped version of the < character:

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

Basic

Standard attributes

All other attributes, unless otherwise specified below, are discarded.

All tags

The following attributes are recognized for all tags:

All blocks

The following attributes apply to all blocks:

Block captions

These attributes also apply to all blocks and are used to construct the caption for a block.

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 stripped by the plain-text formatter.

Character formatting

There are several character-formatting tags, aligned more or less with the common HTML tags. These are all stripped by the plain-text formatter.

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 additional attributes are allowed.

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.

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.

Inserting blank lines will generate blank list items.

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. Use a <div> tag to include more complex formatting in the definition, as shown in the example below, which has multiple paragraphs.

Links

Links

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

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.

Videos

Videos can be embedded just as easily as images with the <media> tag. 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 for videos refers to the page from which the video is being retrieved and is used to format the caption, as described in standard attributes for all blocks.

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:

Special

Pre-formatted text

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.

    <pre>Some text
         just
             needs
    to be
       formatted
                just...
                       ...so.</pre>
              

    Some text
         just
             needs
    to be
       formatted
                just...
                       ...so.
              

Source code

Use the <code> tag to highlight source code. This tag acts much like the pre tag but applies other styles. 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.

function _process($input, $tokenizer)
    {
      $tokenizer->set_input($input);
      while ($tokenizer->available())
      {
        $tokenizer->read_next();
        $token = $tokenizer->current();
        $this->_process($token);
      }
    }

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.

The following attributes apply to <bq> tags.

Notes

The <n> tag 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.

Abstract

Use the <abstract> tag at the beginning of longer articles to provide a synopsis or a tl;dr. In the HTML formatter, this translates to the 'abstract' CSS style. It is ignored in the plain-text formatter.

The <quote-style> attribute (see quoting above) applies this tag as well, but the default value is none.

Pull quotes

Use the <pullquote> tag throughout longer articles to highlight . In the HTML formatter, this translates to the 'abstract' CSS style. It is ignored in the plain-text formatter.

The <quote-style> attribute (see quoting above) applies to this tag as well, but the default value is none.

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:

function _process($input, $tokenizer)
    {
      $tokenizer->set_input($input);
      while ($tokenizer->available())
      {
        $tokenizer->read_next();
        $token = $tokenizer->current();
        $this->_process($token);
      }
    }

Messages

Use the <info>, <warning> or <error> tag to show a message box with some content.

Footnotes

Longer texts can include footnotes and end-notes by placing markers with the <fn> tag. These are replaced with integer markers (e.g. 1, 2, 3, etc.). Use the <ft> tag to create a block that forms the body of the footnote. These are also numbered incrementally. Footnotes can be placed anywhere in the text, but are commonly included at the end, separated by a horizontal rule, as shown in the example below.

Clearing floats

Use a <clear> tag to clear any floating element in the preceding text. You can also use the attribute clear="both" on any block to do the same thing, but this tag lets you avoid surrounding a paragraph with <div> tags, as shown in the example below.

Anchors

Use an <anchor> tag to provide an invisible anchor in the text to which you can link with an <a> tag. You can also use the attribute id on any other tag to do the same thing, but this tag lets you avoid adding unnecessary begin/end tags, as shown in the example below.

Rules

Use an <hr> tag to introduce a break in the text.

Advanced

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:

The following examples enable ligatures:

The following examples turn off everything but highlighting:

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