Links in EtText

As well as the standard <a href=url>...</a> 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.

To use labelled links, you surround the link text with double-square-brackets, and (optionally) use a single open-square-bracket on the right-hand side with the link label.

Here's an example:

  WebMake's home page is [[at this website [WebMake]].

Alternatively, if the link text matches the link label, the link label is optional.

  Here's an example: [[WebMake]].

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

	[WebMake]: http://webmake.taint.org/

Even simpler: if the link label has been set as an Auto link, you can omit the square brackets altogether:

  Here's an example: WebMake.

Text and markup can be enclosed in the double-square-brackets, everything quoted will become part of the link text. Unlike the older form of EtText links (see below), even single words need to be enclosed in brackets to become links. This protects against accidentally interpreting normal text as a broken link.

The following text describes the old style for EtText links. Since it was way too easy to produce links this way where they were not intended to be, it has now been obsoleted by the method described above. However, support for it will remain on by default for a few revisions.

To turn off this backwards compatibility, set the EtTextOldLinkStyle option to 0, either using WebMake's <option> tag, or from your code.

The basic concept is of a word or "quoted set of words" followed by an optional link label in [square brackets], like this: "this is a link" [label].

The href used in the link is then defined at another point in the document, as above.

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

  <img src="/license_plate.jpg" width="10" height="10"> [homepage]

will work correctly.

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 double-square-brackets or quotes. For example:

  [Justin Mason]: http://jmason.org/

will mean that any occurrence of [[Justin Mason]], or "Justin Mason", 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, if WebMake is being used. If you use EtText in a standalone mode, without WebMake, you can provide an implementation of the Text::EtText::LinkGlossary interface to store defined links so that they can be used in other EtText files.

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

In addition, if the link definition is preceded with Auto:, the quotes are not required, and any occurrence of the link label -- with or without quotes or double-square-brackets -- will become a link.

  Auto: [WebMake]: http://webmake.taint.org/
  Auto: [any occurrence of the words]: http://webmake.taint.org/

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.

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