Introduction

The best way to learn is through examples. The rest of this document presents examples showing how to markup text in an EsTexte format.

Learn by example

This documentation was generated with EsTexte. With the distribution, go into the doc/text folder and peruse the contents of the files. Then read and understand the following command that generates the HTML documentation from the text documentation:

java -cp "EsTexte.jar" estexte.EsTexte -indir doc/text -outdir doc/html -template ../template.txt

Titles

You mainly structure you text with titles. ExTexte offers 3 levels of header structure, corresponding to h1, h2 and h3 tags, respectively.

Title 1
=======

Title 2
-------

Title 3
.......

Links

Links and images are brought about through two different, complentary mechanisms: reference and command. the reference format is basically markup up a reference word by dollar signs. The actual target that the document will link to is enabled with a command.

Say you want to put a link to the w3c site. you write:

this is a link to \$w3c\$

w3c := link http://www.w3.org "The W3C"

...which will produce: this is a link to The W3C

Why separate into two different lines? First, because web links and images require more than a single word of info to mark up, making a one-stop syntax difficult to produce without resorting to some HTML-like structure. Secondly, and foremost, separating reference from the command that produces the link code will enable the writer to maintain all of the site links in a single page, included in all pages with an include command.

Lists

Lists come in two (2) flavors: unordered and ordered. This translates into non-numbered and numbered lists. List items in the unordered format are prefixed with asterisks (

\* a list of items
    \* lists are hierarchal and any
      item can contain sub items
    \* such as this one.

# Numbered lists
    # are much like
    # non-numbered, 
    # lists.

Bold and Italic text

Bold text is text surrounded by *asterisks*. Italic text is text surrounded by _underscores_. You can mix both types of text.

Images

Images work much the same way as links, except that the command verb is "image", not "link". If I wanted to include the W3C logo on my page. I would write :

\$w3c.logo\$
w3c.logo := image http://www.w3.org/Icons/w3c\_main

and obtain:

Line separators

You can include a line separator by writing

\* \* \*

gives:

Escaping

If you need to include in the final document a character used for markup, prefix it with a backslash (\). If you need to include a backslash, prefix it with another (more powerful) backslash.

What do I need to escape?

You need to escape any of the characters used for markup. They are listed in the following table

Templates

If you use the software as is, chances are the pages you generate don't contain HTML headers and encapsulating body tags. Use templates for this: basically write an empty HTML file and put a @content@ tag in the middle of it. Templates are used with a special command-line switch that is described in the usage section.

Includes

Your nifty new website generator wouldn't be much of anything if it couldn't include other files. To include a file, write << on a line with the file to include following. The file must be given relative to the current file being processed.

Example:

<< header.txt

includes the header file into the current file. Note that the file being included will be processed as well.This enables you to put all your link commands in the same file. All in one place, easy to use, easy to keep up with.

A special kind of text: the inline box

Some text needs special printing. This is text that you really need to stand out from the rest of the text, so you require it to be boxed in, or highlighted, or marked all capitals. Whatever your need may be, all you need to do is indent your text inwards, with either one tab or four spaces.

There's a catch, however, in using inline boxes. There's no direct HTML equivalent to the inline box, so the box will map to an HTML paragraph <p> with a class style attribute of "note":

<p class="note"> Some text needs special printing... </p>

Mixing in HTML code

In many circumstances, the EsTexte syntax will come up short for formatting your text for the web. In such cases, you should either supercharge you css stylesheet to take control in such cases or add in actual HTML code. The EsTexte processor will not prevent you from doing that - quite the opposite.

For example, when including an image, you may want to center it:

<center>\$my.image\$</center>

René Ghosh. last update: 03/07/2006