THE BABLEX MARKUP LANGUAGE

To create a plain text file marked up in Bablex, you will need to choose a text editor to use.

Most importantly, it should be a text editor and not a word processor. It shouldn't have buttons or menu options to set text into bold or italics, and it should save files using a .txt suffix by default.

Almost any text editor will do, and as most computers are shipped with a text editor installed, you probably already have access to one.

There are a few settings, though, you should check before writing:

1. Word Wrap: Enable word wrap, so that as you type past the right-hand edge of your screen (or the right-hand border of your window) the text continues on the line below without you hitting the Enter key.
2. Tabs to Spaces: If your editor offers the choice, have it insert spaces when you hit the tab key, rather than actual tab characters. If not, it is probably best to avoid hitting tab, as tab characters will be displayed differently to every reader of your text file, depending on the software each uses. The Bablex translator converts tabs to groups of four spaces.
3. Encoding: The Bablex syntax itself is entirely drawn from the ASCII character set, and so any encoding which contains this as a subset is fine in principle, but as it needs to be supported by your web browser, we recommend Unicode set UTF-8. (Bablex assumes UTF-8, so if you choose something different, be sure to specify the appriopriate charset metadata in your text.)
4. Line Endings: The Bablex translator can handle lines divided by linefeeds (as generally saved by Unix and modern Mac software), or carriage returnlinefeed pairs (DOSWindows) - as almost all modern editors offer one or both of these, use whichever is most convenient for you.

If your editor doesn't allow the appropriate settings, or if you simply don't much care for it, you will find many excellent alternatives, for every platform, available for download from the web without charge. Try a few!

Having found and configured a text editor you like, write your document, adding markup as you go.

The section on Bablex Syntax below explains the language in detail, but once you have read through it, you can use the Bablex Cheatsheet to refresh your memory as you need.

Remember to hit Enter only where you wish to force a line break/which will also appear on the translated web page, and hit it twice, leaving a blank line, to start new paragraphs.

Once you have finished your document, save it as a text file named with a .txt, such as mydoc.txt.

To translate your documents into HTML, you will need a copy of the Bablex toolkit.

You can download this from this address:

http://mannyneira.com/bablex/bablex.zip

When you unzip bablex.zip, you will find the following fifteen files:

Open the Bablex translator bx2web.html in your web browser, and use the file selector at the top to load your .txt document.

NOTE: Your browser must support JavaScript, and allow JavaScript to run from your own computer, not just on remote websites.

Depending on how long your document is, it may take a little time to load, so you may need to wait briefly.

If a problem arises while translating your document, the attempt will be abandoned, and a message displayed explaining why.

Open your document in your text editor, make the necessary changes, and save it again.

Then refresh your browser to clear the contents, and reload your document.

NOTE: Be sure to refresh before reloading, or the translation may not run.

Repeat this until the translation finishes successfully, and your document is displayed as a web page. Scroll through it to check that it has been translated as you intended.

If you see anything which looks wrong, go back to your text editor, make any changes you feel may be necessary, and reload the document, once again repeating this process until you are happy with the displayed page.

In the top-right corner of the translator, you'll see the Bablex logo. Clicking this will hide the controls except for the logo itself, allowing the document to be read with a little less visual clutter.

To redisplay the controls, simply click the logo again.

The first button to the right of the file selector is labelled Bablex.

Click this to redisplay the original Bablex marked up text.

If your document is long, it might benefit from a contents listing at the top, both to let readers of the text version know in detail what subjects you cover, and to allow readers of the web version to click an item in the contents and jump directly to the section which interests them.

The translator could automatically add such a contents listing, but the disadvantage of this approach is that it only enhances the web version - the contents do not appear in the original text. (And, of course, it may not always be wanted even in the web version.)

So if you wish to add a contents listing to your document, load the document into the translator, and click the Contents button.

You will then see an automatically generated contents list, numbered and structured to reflect the headings in the body of the document.

Then click the Bablex logo at the top right of the translator window to hide the controls, select the text, copy it, and paste it back into the top of the original text file. (Clicking the logo to hide the controls prevents the button labels being accidentally selected and copied.)

If you edit the text document in the future and the headings change, you can simply reload the updated text into the translator, and click the contents button again. Then simply remove the old contents listing from the document, and paste in the newly generated contents.

Click the HTML button to display the HTML translated from the Bablex text.

If it interests you, spend a little time scrolling through the HTML to see how your original text has been translated. The HTML is shown in a series of blocks, each carrying the translation of a single paragraph of the original.

Open a new, empty, editing window using your editor, click the Bablex logo in the top right of the browser window to hide the controls, select all the HTML, and copy and paste it into the editor.

(As before, hiding the controls before selecting the HTML avoids the risk that the button labels will accidentally be copied with the text.)

Then save the copied text as a file with a .html suffix. Take a little care, as most editors will assume you wish to save files with a .txt suffix, and offer an optional way of overriding this which can be easily missed.

This new HTML file will contain the following line:

<link rel="stylesheet" href="bxstyle.css" type="text/css">

This links it to the stylesheet file bxstyle.css - one of the files you extracted from the bablex.zip archive - which controls the colors, fonts, spacing and so forth used to display the web page.

You will therefore need to make sure there is a copy of the bxstyle.css in the same folder as your HTML file, both on your own computer, and on any server to which you upload it.

If you wish to change the appearance of the page, make sure you edit a copy of the bxstyle.css file, rather than the original. See the appendix titled Bablex Stylesheet for more information.

As explained above (see Writing Bablex), to write a text document you plan to mark up using Bablex, you should use a text editor rather than a word processor, and ensure that word wrap is enabled.

Allow long sentences and paragraphs to wrap automatically at the right edge of your editor's window, and only hit return when the paragraph is finished.

Then leave a blank line before the next paragraph. For instance:

Please restrict your typing to the upper surface of the keyboard.

Because there's a difference between originality and just being silly.

Leave multiple blank lines to space out your document as you wish. Leaving a few blank lines before headings can make divisions clearer in the original text, though the additional blank lines will have no effect of the appearance of the resultant web page (where the spacing of elements will be controlled by the stylesheet).

Relax. If you've got 'em, smoke 'em.



Right. Back to work.

In text such as the verse of a poem, break a paragraph into lines.

Freedom is the freedom to say that two plus two make four.
If that is granted, all else follows.
//George Orwell, 1984//

Freedom is the freedom to say that two plus two make four.
If that is granted, all else follows.
George Orwell, 1984

You may be surprised, or even critical, on learning Bablex preserves line breaks.

In HTML line breaks are treated as if they were merely spaces. Breaking text into two lines does not cause it to be displayed as two lines by a browser. To force a line break, a <br> tag must be added.

And in HTML, this makes sense. Some web pages use a lot of tags, which are easier to read when broken onto separate lines than in long strings, but which couldn't be written that way if the line breaks between them appeared in the browser.

Also, the general reader will never see the HTML itself, only the web page is generates. It simply doesn't matter if the underlying markup is laid out differently to its appearance in a browser.

Other lightweight text markup languages such as Markdown and Creole were designed with eventual conversion to HTML very much in mind, and it is therefore natural that they would adopt HTML's view of line breaks, aside from being friendlier to users who will be used to HTML's treatment of whitespace.

Bablex is different simply because it has slightly different aims. It places relatively greater emphasis on creating text documents to be read in their original form, and therefore aims to keep the translated web page in line with that form. So where a line break appears in the text, it is inserted into the translated HTML.

Interestingly, early drafts of Creole also specified that line breaks should be preserved, but then switched to HTML's approach in version 1.0. And while Markdown also follows HTML, it allows a trailing space to be added to a line to prevent it being joined to the next. The designers of both were clearly aware that this was a tricky and rather marginal decision, and Bablex's different approach purely reflects its slightly different design priorities.

Use pairs of symbols either side of a word to denote its style:

Bold text is marked by *asterisks*.
Italic text is marked by /slashes/.
Underlined text is marked by _underscores_.
Tinted text is marked by ^carets^.

These styles can be combined:

You can combine */bold & italics/*,
or /^italics & tint^/,
or _/*^anything you like^*/_!

Doubling the symbols *, /, & _ adds a tint to their usual meaning:

This is /italic/, and this is //tinted italic//.
(You could write /^this^/ - it means the same.)

To protect a paragraph means to indicate that none of the symbols it contains should be interpreted as markup: they should be treated like any other character.

Simply begin a paragraph with a space to protect it.

Question 7. Solve x/4=x/8+4 (unprotected)

 Question 7. Solve x/4=x/8+4 (protected)

As described in the section about styles above, a pair of slashes are usually interpreted as markup for italic text. However, as this paragraph is protected, the slashes are simply left unchanged, and no text is italicised.

(x is 32, by the way.)

If you wish to protect only some of the symbols in a paragraph, while allowing the rest to be translated, the simplest way is to use spaces.

No symbol followed by a space can begin a style, and none preceded by one can end one. (A symbol with a space either side is, therefore, protected from being either.)

This is *bold*, but these are just * starry *.

As described under styles, Bablex styling is done using paired symbols, so if only one appears in a paragraph, it is automatically protected.

And even if there are two, it isn't always necessary to protect both, as unless a suitable pair can be found for a symbol, it is ignored.

One slash/symbol *won't* be translated, nor will ^these ^carets.

Later in this document, the creation and use of bookmarks, links, and embedded HTML are described. For the moment, however, it is simply worth noting that the chevrons, brackets, and braces surrounding these can be protected using spaces in the same way.

<Alpha> is a valid bookmark
...but <Alpha >, < Alpha>, & < Alpha > aren't.
[Alpha] is a valid link
...but [Alpha ], [ Alpha], & [ Alpha ] aren't.
{&alpha;} is valid embedded HTML
...but {&alpha; }, { &alpha;}, & { &alpha; } aren't.

If you wish to protect a phrase, and for some reason it isn't possible to insert spaces, you can instead put \ symbols around it:

The *stock number* is \A953*8633*6CD0\.

If the symbol you are protecting happens to be \, use \\.

The *other stock number* is \\6698\D995\5B55\\

You can even use \\\ to protect text including \\.

Pairs of backslashes look like this: \\\A\\B\\C\\\
Or without protection, like this: \A\\B\\C\

Text like the code in a computer program must not only be protected from styling, but also be shown complete with any leading or duplicated spaces (which are usually reduced to a single space by HTML), and in a monospaced font.

There are two ways to markup formatted text.

The first is to ensure that every line begins with four or more spaces. These will visibly indent the text and make it clearly distinct in the text version, and be taken as an instruction to translate it as formatted text (somewhat redundantly termed 'preformatted' text) in HTML.

    while (true)
    {
        // Give the CPU a work-out.
    }

while (true)
{
    // Give the CPU a work-out.
}

The second is to put the text between two lines, the first being backtick followed by one or more dashes, the second being one or more dashes followed by a backtick.

`---
<p> This is HTML!</p>
---`

<p> This is HTML!</p>

To protect only part of a paragraph in the same way, and show it in the same monospaced font, wrap it in backticks.

The box's capacity is `2m*3m*4m=24m3`.

You can also use them simply to indicate that text is of a type which is usually shown in formatted blocks, such as a command in a programming language.

The Basic `PRINT` command displays text.

Doubled backticks will protect single ones, and tripled backticks protect pairs.

The sequence ``1`2`3`` contains backticks.
Without double ticks, it looks like this: `1`2`3`.

Similar rules apply when combining backticks and backslashes: triples are processed before pairs, and pairs before singles.

Example *No. 1*
Example \*No. 2*\
Example `*No. 3*`
`Example \*No. 4*\`
\Example `*No. 5*`\
\Example ``*No. 6*``\

Your first heading must be an A-Heading, and your document must have at least one. It serves as a main heading - a heading for the document as a whole.

It need not be on the first line, though. Anything above the main heading becomes a 'header' block for the document, and might commonly include metadata, a contents list (see Generating Contents), or both, as this document's header does.

You may choose to make this the only A-Heading in your document, or you may use further A-Headings to introduce later sections. (To understand how these headings are mapped to valid HTML heading tag structures either way, see the HTML Tag Usage appendix description of the <h1> tag below.)

If the Bablex translator finds no headings, or the first it finds is not an A-Heading, it will report this as an error, and abandon translation.

Under each heading the Bablex translator will add a bar with up to four arrows:

1. Left: jump back to previous heading (except from the first heading)
2. Up: jump to the top of the document
3. Down: jump to the bottom of the document
4. Right: jump to the next heading (except from the last heading)

Use three or more asterisks in a row to create a dividing line or rule (sometimes called a horizontal rule).

That crosses the line.

**************************

That. See, told you.

After three asterisks, you may optionally add a space and text. This may in turn, also optionally, be followed by more asterisks.

*** This line divides the bit up there from the bit down here ***

A simple numbered list is written much as you might expect, each item being prefixed by a number and a dot.

1. Spam
2. Spam
3. Spam

You can create multilevel numbered lists by using multipart numbers to indicate the level of each item.

Lines after the first may optionally be indented to reinforce the hierarchy visually, providing that the first line is not indented.

1. ^Climate Change^
    1.1. Spelling Reform
    1.2. *Turnips*
        1.2.1. /Country & Western/
2. The Horsehead Nebula
    2.1. `QWERTY`
    2.2. //Winnie the Pooh//

They may have as many levels as you wish.

1. 1st level item - good start.
1.1. 2nd level - fair enough.
1.1.1. 3rd level ok.
1.1.1.1. This can go on as long as you like.
1.1.1.1.1. And then some.

But to be recognised as a list at all, they must start with a first level item.

1.1. Second Level item - this is wrong
2. First level item - too late.
2.1. This list won't work.

You may not skip a level in a list. If the Bablex translator encounters a list with a skipped level, it will report the error and abandon translation. The following list, for instance, would cause this:

1. Level 1
1.1.1. What happened to level 2?

You will sometimes see list items written like this:

**BAD LIST**

1. See the trailing dot?
1.1 It's gone!

Bbablex will not recognise this as a list.

The translator expects a trailing dot after all item numbers, regardless of level.

**FIXED LIST**

1. <- Trailing dot here...
1.1. <- .../and/ here.

Bbablex will not recognise this as a list. It expects all numeric prefixes to be treated consistently, with trailing dots.

When items are shown in a numbered list on a web page, they are numbered automatically.

The original prefixes still determine the level of each item, but not the actual numbers shown next to them. The following example illustrates the effect.

0. *First* main level item.
0. *Second* main level item.
0.0. First /second level/ item under second main level item.
0.0. Second /second level/ item under second main level item.
0. *Third* main level item.

A simple bulleted list just requires an asterisk at the beginning of each item.

* Spam
* Spam
* Spam

Multilevel bullet lists use asterisks before level 1, pluses before 2, and dashes before 3. They too must begin with an unindented first level item, though the following items may be indented.

* Oxygen
    + The Highest Prime Number
        - Thermostats
        - Turquoise
* Victoria Sponge Cake
    + Accountancy
    + MS-DOS

The first item in a list must begin with an asterisk and a space. If it doesn't, it will be translated as an ordinary paragraph.

+ First item, but second level? Won't work.
* First level item, but too late.

Note that the symbol prefixes - the asterisks, plus, and dashes - are not recorded in the translated HTML. Items are simply translated as first level, second level, and so forth, and when the page is displayed in the browser, the prefixes displayed for each level will be specified by the stylesheet.

As with numbered lists, levels may not be skipped in a bulleted list. If the Bablex translator encounters a list with a missing level, it will report the error and abandon the translation. The following list, for instance, would cause this:

* Level 1
- What happened to level 2?

You can mark up the text of list items as you might any other text, in numbered lists...

1. The **Good**
2. The //Bad//
3. The __Ugly__

...or bulleted lists.

* /Bread/
* *Ham & Pickle*
* /Bread/

Blank lines may be left between numbered list items, though if this is done, the items must be first level, and not indented.

1. This is a paragraph which appears as the /first item/ in a /numbered list/. It can be as long as you wish.

2. The second paragraph is clearly a new paragraph as it is separated from the first by a blank line.

Blank lines may also be left between bulleted list items, though these too must be first level, and not indented.

* Something.

* Everything /else/.

Use bars to delimit cells in a table.

| Row 1, Column 1 | Row 1, Column 2 |
| Row 1, Column 1 | Row 1, Column 2 |

If a cell's content has two or more spaces on both sides, it will be centred.

Otherwise, it will be justified to the side with fewer spaces.

If the sides are equal, it will be left justified.

For instance...

|LLLL| LLLL |  CCCC  |  RRRR | RRRR|
|LLL | LLL  |  CCC   |   RRR |  RRR|
|LL  | LL   |    CC  |    RR |   RR|
|L   | L    |    C   |     R |    R|

Add a row consisting only of bars and dashes to indicate that the row above contains table headers. Table headers need not appear at the top, and you may even have multiple header rows.

| ASCII CHARACTERS     |  COUNT |
|----------------------|--------|
|                      |        |
| Non-printing         |        |
|----------------------|--------|
| Control chararacters |     32 |
| Delete character     |      1 |
|                      |        |
| Printable            |        |
|----------------------|--------|
| Letters              |     52 |
| Digits               |     10 |
| Punctuation/symbols  |     33 |

Add a row consisting only of bars and dots above rows which offer summary data such as totals or averages.

| ASCII CHARACTERS     |  COUNT |
|----------------------|--------|
|                      |        |
| Non-printing         |        |
|----------------------|--------|
| Control chararacters |     32 |
| Delete character     |      1 |
|......................|........|
|                      |     33 |
|                      |        |
| Printable            |        |
|----------------------|--------|
| Letters              |     52 |
| Digits               |     10 |
| Punctuation/symbols  |     33 |
|......................|........|
|                      |     95 |
|                      |        |
|......................|........|
| TOTAL                |    128 |

Merge cells horizontally simply by missing out the bar between them.

Merge a cell vertically with the one above by replacing the bar to its left with a colon.

| Type       |    Letters     |  Number |
|------------|----------------|---------|
| Vowels     |     AEIOU      |       5 |
| Consonants |  *ABCDFGHJKLM  |      19 |
:            :   NPQRSTVXZ*   :         |
| Glides     |     /WY/       |       2 |
|............|................|.........|
| TOTAL                       |      26 |

Note that in the example above, the list of consonants is treated as a single string, even though part of it is in the middle of one line, and the other is in the middle of the line below. This is because it is within a single cell which happens to span two rows.

A freestanding image is one which can be understood by its caption alone, rather than being dependent for its meaning on being embedded in a paragraph explaining it.

To add such an image to your document, insert an image caption, a colon, a space, and the image's URL, between brackets - [caption: url] - and leave blank lines around it so that it is treated as a separate paragraph.

[The //Bablex// logo: bxlogo.gif]

Bablex insists on a caption because those reading the text version of your document need to know what it shows. Even those reading the web page may rely on the caption, as they may be blind and using a screen-reader, or browsing text-only because their net connection is slow, unreliable, or charges for bandwidth.

If the image is closely linked to the content of a particular paragraph, you can embed the same syntax at the beginning of the paragraph like this:

[//Bablex// logo: bxlogo.gif] The logo features the name //Bablex// and the optional .`bx` filename suffix, over a triangle representing the original /Tower of Babel/.

The image URL can be replaced by a bookmark, providing the bookmark referred to is followed by a link to the image (see Bookmarks and Links below), as follows:

[The //Bablex// logo: Logo]

<Logo> [bxlogo.gif]

Logo bxlogo.gif

In this way, you can build a reference list of some or all of the images used in your document. Though most commonly such lists are placed at the end of a document, these bookmark/image pairs can be placed anywhere, and need not appear together in a list at all.

If you wish to add terms and their descriptions to your document, list each as follows:

exists :: Things that used to be ists.

exists

Things that used to be ists.

As you can see, defining a term causes it to be given a dotted underline wherever it exists in the text. On the translated web page, you may click any term marked in this way to see its definition.

Note that only complete words will be highlighted. Define cat, and only a cat - and not a catfish - will be identified.

cat

A small mammal with an agenda entirely its own.

Terms defined using lower case will match all references regardless of case. Those in mixed or upper case are case sensitive. So Danger Mouse is a mouse, but coke is not a kind of Coke.

mouse

A wild creature, easily distinguished from the pointing device of the same name by its ability to function on all surfaces.

Coke

The real thing, apparently. The rest of the universe presumably being merely the shadows of quantum oscillations in a sea of primal black fizzy liquid.

If a term has an optional ending, show it in parentheses. For instance, the following will highlight references to both hat and hats.

hat(s)

A sock for the head. Sort of.

If the ending might be replaced with another of the same length, prefix the alternative with a slash. For instance, to define an axis, and also capture references to the plural axes...

axis(/es)

Notional lines, usually called X, Y, or Z, relative to which the position of your keys can be defined but not determined.

Or if there are multiple alternative endings replacing their own length in the original term, add them all. For instance, to capture references to Formula 1, Formula 2, Formula 3, and Formula 4 racing...

Formula 1(/2/3/4)

A class of racing car, furiously ignored by the US motorsports community.

If the alternative endings are of different lengths, don't include them in the basic term, but rather put them all in parentheses, and don't precede the list with a slash. The terms datum and data might both be captured thus...

dat(um/a)

What computers provide. Like information, but far more plentiful and less meaningful.

And if you wish to define multiple terms which have no common stem, simply use slashes between them. For instance, Microsoft, Google, and Apple might be defined...

Apple/Microsoft/Google

A company that loves you.

A paragraph may contain any number of metadata: and (optionally) extra spaces may be added if you wish to to line up the bars.

Whimsicality   | Variable
Swearing Level | Low

Language    | en
Title       | The Da Vinci Code
Charset     | UTF-8
Description | A formerly lovely tree.
Keywords    | twaddle, ludicrous, kindling
Author      | Dan Brown

These six metadata are all displayed much as are the other metadata examples shown above.

However, when a document is translated, these six properties will also define tags in the <head> of the resultant HTML.

1 The language must be taken from the IANA Language Subtag Registry which you can find at: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry

2 The charset must be taken from the IANA Character Sets Registry at: http://www.iana.org/assignments/character-sets/character-sets.xhtml

A block insert is a passage included in your document, but clearly distinguished from the main flow of the text. For instance, the examples given in this document of rendered markup have all been block inserts.

To create a block insert of one or more paragraphs, write a line above them beginning with a plus and one or more dashes, and one below with dashes followed by a plus.

+---
This space available for advertising.

**SPEAK TO THE GEEK-CHIC!**

/Apply to me@mannyneira.com./
-+

If the passage you are inserting is a quotation, use quotemarks in place of pluses...

"-----
Internet attributions are often unreliable.
//William Shakespeare//
-----"

Internet attributions are often unreliable.
William Shakespeare

Inserts can themselves contain inserts. These are called nested inserts.

+-
Sign seen today:
"---
**Don't read this quote.**

/by Order of the /Ministry of //Paradox///
---"
+-

You can nest inserts as deeply as you wish: though it can get a little overwhelming.

+----
Here we go...
+-
Level 2
+-
Level 3
+-
Level 4
+-
Level 5
+-
Level 6
End of level 6
-+
End of level 5
-+
End of level 4
-+
End of level 3
-+
End of level 2
-+
...and /relaaaaax./
----+

But take care to close each insert you open, in the right order, and using the appropriate type of closing.

The Bablex Translator will report an error, and abandon translation, if...

1. An insert is not closed by the end of the document.
2. Close insert markup (eg. -+) is encountered when no insert is open.
3. An insert is closed with markup which doesn't match its opening: for instance, if an insert opened by +- is closed by -".

To refer the reader to a heading within the same document, simply enclose the text of the heading within brackets.

--- Recursion

See under [Recursion].

The text within the link is not case sensitive.

To link to a point within the document other than a heading, first mark it with a bookmark. This is just a word or phrase between chevrons. You can then create a link to a bookmark exactly as you would to a heading.

Here is an <example of a bookmark>.

This is a link which takes you to an [example of a bookmark].

Bookmark names are not case sensitive.

The Bablex translator implicitly inserts a number of bookmarks automatically:

1. <top> at the top of the document
2. <heading-1>...<heading-n> where n is the number of headings in the document (excluding those in inserts)
3. <bottom> at the bottom of the document

You may therefore use links such as [top], [bottom], and [heading 7] (assuming you have at least 7 headings) in any Bablex document.

(Spaces in links are converted to dashes, so link [heading 7] will find bookmark <heading-7>.)

Go back to the [top] of this document.
Go to [heading 1].
Go to the [bottom] of this document.

You may not set up your own bookmarks with the same name as any automatic bookmark: if the Bablex translator finds one, it will report it as an error, and abandon the translation.

To create a footnote, put the footnote number between chevrons. To link to it, put the same number between brackets.

Marx [1] was a revolutionary and author of the //Communist Manifesto//.

<1> Karl, not Groucho.

Footnotes may not be duplicated within the main text. For instance, the footnote <99> may not appear twice. However, you may create as many links to a single footnote as you wish, so [99] may be repeated as often as you wish: 99, 99, 99.

99 And they all point here.

Nor need your footnotes be sequentially numbered: they may appear in any order, and their may be gaps in the number sequence. Naturally, it is normal practice to number footnotes in the order they first appear, but if this isn't done, the Bablex translator will not object, providing that no footnote number is used twice, and every link to a footnote corresponds to a footnote definition.

Inserts, however, are considered to be outside the main flow of the text, and so each insert may have its own sequence of footnotes, even if the numbers used have been used in other inserts, or in the main text. Footnote links within an insert can only refer to, and must be satisfied by, footnotes within the same insert.

To refer the reader to another document in the same folder, put the file name between brackets.

Please read Terms & Conditions: [T&C.txt]

If the document is local, but not in the same folder, include a relative path.

George Orwell, 1984 [authors/orwell.txt]

As you can see, when displayed on a web page, links to local files with the suffix .txt (and, in fact, .bx) are changed to refer to files ending .html. This allows the original plain text files to correctly reference each other by name, but also be converted into a set of HTML files which also correctly reference each other.

To reference a document on the web, put its URL between brackets.

Check out my website:
[http://mannyneira.com/index.html]

Note that absolute paths ending in suffixes .txt or .bx are not changed.

Some text file on the internet: [http://google.com/idontexist.txt]

Normally, when a link to another file is clicked, the top of the linked file is displayed.

However, you can link directly to points further down within another file.

To create a link to a heading or bookmark within another Bablex based file put the name of the heading or bookmark, followed by a semicolon and a space and then the path of the file, between brackets:

Bored? Why not check out [Yodelling; Pointless Activities.txt]

You will sometimes see links like this on the net:

https://en.m.wikipedia.org/wiki/Jorge_Luis_Borges#Philosophy

This is a link to the Wikipedia page about the writer Jorge Luis Borges, but note the way the link ends: #Philosophy.

This is a link to a point labelled 'Philosophy' - a fragment - within the page.

There are two ways to include links to fragments. You can use the link exactly as it appears, or you can take the fragment name, and put it before the file path, separated by a semicolon and space.

This can be a little more readable, and emphasise that you are linking to a particular subject within a page.

[https://en.m.wikipedia.org/wiki/Jorge_Luis_Borges#Philosophy]

[Philosophy; https://en.m.wikipedia.org/wiki/Jorge_Luis_Borges]

If a bookmark appears in a paragraph followed by a link (and nothing else), then a link to that bookmark is referred onwards to the link following it:

The world's biggest wiki is [Wikipedia].

<Wikipedia> [http://wikipedia.com]

This can save you embedding the same long URL many times, and, if you wish, allow you to collect URLs in a single "sources" or "references" style list at the end of the document.

If a link does not contain a . followed by a character other than a space (as you usually find at the end of filenames, such as .html), it is assumed to be an internal link - a link to a heading or bookmark within the same document.

If a corresponding bookmark or heading cannot be found, the Bablex translator will report this as an error, and abandon the translation.

However, external links - to other local files, or files on the net - are not checked for existence, as you may be creating a link to document you plan to create later.

Bablex does not offer a syntax for what might be called "hidden" links. The omission is deliberate, and requires a little explanation.

HTML provides a way to connect arbitrary text to a URL, without displaying the URL itself. This is what is meant here by a hidden link.

<p>Click <a href="https://google.com">search</a> to open a search page.</p>

This is extremely useful in the design of web pages, as it allows words or phrases to be linked to a source without displaying a long URL in the middle of a sentence.

Most text markup languages provide a syntax for hidden links. For instance, in Markdown this would be written:

Click [search](https://www.google.com) to open a search page.

When this Markdown is translated into HTML, the URL is hidden, though clicking "search" will still take you there.

Bablex doesn't offer a syntax which, when translated, will yield a hidden link. Its principles are that:

1. The source should be as readable as possible.
2. All the text in the source should appear in the HTML translation.

Unfortunately:

1. Putting a long URL in the middle of a sentence hurts readability.
2. Hiding the URL on the web page causes it to diverge from its source.

There are three work-rounds.

Recast the sentence so that it can be read easily with the address in-place:

Click here to open a search page: [https://www.google.com]

This is the generally recommended method.

Use bookmarked links:

Click [search] to open a search page.

(...then under the paragraph, or at the end of the document...)

<search> [https://www.google.com]

Bookmarked links are particularly useful if you wish to offer a single table of sources, or if the same URL is linked from many places in the document.

Use embedded HTML:

<p>Click {<a href="https://www.google.com">search</a>} to open a search page.</p>

Embedding hidden links is discouraged.

If you find yourself doing it often, Bablex may not be the best medium for the document you are working on. Markdown, amongst others, offers a closer match to such HTML constructs.

And I cannot emphasise enough that this difference in approach in no way implies any criticism of Markdown, which also provides an indirect link mechanism, the only difference being that it is optional.

Bablex deliberately avoids hidden links because it was designed to encourage the writing of text documents as readable, and as consistent with their web version, as possible, even at the cost of not providing support for all of HTML's features.

In short, different tools do different jobs :)

The { and } symbols may be protected - that is, not treated as embedded HTML markers - in all the same ways as other symbols: see Protected Text above.

Briefly, the text between { and } will only be treated as embedded HTML if they are both in the same paragraph, in the right order, and don't have spaces immediately inside either symbol.

However, these restrictions will not prevent you embedding multiline blocks of HTML. For instance:

{
<i>This is a block of embedded HTML.
<br>It has no blank lines between the braces.
<br>So it's all one paragraph.
<br>So it works.</i>
}

Use embedded HTML sparingly, and with care.

It cannot be validated, and incorrect HTML may disrupt the display of the entire translated page.

And while it is undoubtedly useful as an occasional convenience, a lot of embedded HTML rather undermines the idea of providing a simple, readable text document.

Consider writing directly in HTML if you use many features Bablex cannot provide. Cleanly written HTML may be preferable to a rich mixture of different markup systems.

/* PAGE & TEXT */

html { color: white; background: black;
font-family: serif; font-size: 16pt;
padding: 2rem; border: 0; margin: 0; }

body, header, main { clear: both;
padding: 0; border: 0; margin: 0; }

p { clear: none; overflow: visible;
margin: 1rem 0 1rem 0; }

<html> is the container or 'root' element element for the entire web page. It therefore acts not only as a big background box, but as a way to set default values for other elements.

Set the color `, `background, font-family, and font-size of the body text here: all other colors and fonts will be defined in the stylesheet below only where they differ from these defaults.

The font-size is particularly important as it defines the rem unit, which is used in all other size specifications - for fonts, line thickness, padding and so for.

Therefore, by changing the font-size from, say, 16pt to 20pt, you will make everything on the page 25% larger.

Note for <p> that 1rem defines the top/bottom margin for paragraphs, so it effectively sets the paragraph spacing.

/* STYLES */

b { font-weight: bold; }

i { font-style: italic; }

u { text-decoration: underline; }

mark { color: #FFFFA0; background: none; }

This block makes it explicit that <b> should be displayed as bold, <i> in italic, and <u> using underline.

Most browsers would do this by default even if these lines weren't there, but including them makes them easier to change.

It's not generally a good idea to change the basic meaning of these tags: preventing <b> from making text bold may cause confusion.

But there are ways of refining the type or degree of bolding, italics, or underline used: and if you wish to do this, this is the place to do it.

As always, if you're unsure, consult the CSS documentation linked above for more information about what is possible.

/* PREFORMATTED TEXT */

pre { clear: both; white-space: pre-wrap;
background: #082000; padding: 1rem; margin: 1rem; }

code { color: #40FF00; font-family: monospace; }

These properties specify the light green (#40FF00) monospace font applied to formatted text and the dark green (#082000) background behind for formatted blocks.

Both colours are hex #RRGGBB mixes: again, consult the CSS documentation if you aren't familiar with these.

/* HEADINGS */

h1, h2, h3, h4, h5, h6, th,
p.h2-in-insert, p.h3-in-insert,
p.h4-in-insert, p.h5-in-insert,
p.h6-in-insert { color: #FFA000;
font-family: sans-serif; font-weight: bold; }

h1, h2, h3, h4, h5, h6,
p.h2-in-insert, p.h3-in-insert,
p.h4-in-insert, p.h5-in-insert,
p.h6-in-insert { clear: both;
margin: 4rem 0 1rem 0; }

h1 { font-size: 1.8rem; background: #302001;
border-bottom: 0.2rem solid #FFA000;
border-top: 0.2rem solid #FFA000; }

h2, p.h2-in-insert { font-size: 1.8rem;
background: #302001;
border-top: 0.2rem solid #FFA000; }

h3, p.h3-in-insert { font-size: 1.4rem;
border-top: 0.4rem double #FFA000; }

h4, p.h4-in-insert { font-size: 1.2rem;
border-top: 0.2rem solid #FFA000; }

h5, p.h5-in-insert { font-size: 1.0rem;
border-top: 0.1rem dotted #FFA000; }

h6, p.h6-in-insert { font-size: 1.0rem; }

p.navigation-bar { text-align: right; }

p.navigation-bar a { color: white;
background: #800000;
font-family: sans-serif; font-size: 0.8rem;
padding: 0.2rem 1.0rem 0.0rem; }

These properties control the appearance of headings.

Two points are worth mentioning.

1. The border-top property is used to draw lines across the page above all the headings except <h6>.
2. For each level of heading, as well as a heading tag, a paragraph class is defined. For instance, defined alongside h3 is p.h3-in-insert.

As the name suggests, this class is used when headings are included in inserts. As inserts are not part of the main flow of the text, this mechanism allows you to add headings to inserts without disrupting the structure of your document as defined by the heading tags.

/* RULES */

hr, p.rule-with-text { clear: both;
border-top: 0.2rem solid #FFFFA0;
margin: 1rem 0; }

hr.rule-with-text { display: none; }

p.rule-with-text { color: #FFFFA0;
font-family: sans-serif; font-size: 1.2rem; }

These properties define the yellow colour of the rules (#FFFFA0) and their style and thickness (0.2rem solid #FFFFA0).

Note that rules with text (*** Hello! ***) make hr invisible, and instead use the border-top of the text's paragraph box p.rule-with-text to draw the rule.

/* LISTS */

ol, ul { list-style-type: none; clear: both;
padding: 0; border: 0; margin: 1rem 0; }

ol ol, ul ul { margin: 0 0 0 4rem; }

ol { counter-reset: item; }

ol li::before { content: counters(item,".") ". ";
counter-increment: item; color: #FFFFA0; }

ul li::before { content: "* ";
color: #FFFFA0; font-weight: bold; }

ul li li::before { content: "+ ";
color: #FFFFA0; font-weight: bold; }

ul li li li::before { content: "- ";
color: #FFFFA0; font-weight: bold; }

li.isolated-item { margin: 1rem 0; }

A little extra complexity here as various ol properties are used to calculate the numbers to show next to items in multi-level ordered lists.

Additionally, ul properties assign different "bullet point" characters to the three levels of nested unsorted lists.

The properties you are most likely to change are easily accessed though.

The light yellow colour #FFFFA0 appears four times. The first sets the colour of the numbers which appear before items in an ordered list, and the next three set the colour of the bullets before 1st level, 2nd level, and 3rd level unsorted items respectively.

These prefix colours are easily changed, and there is no reason you need use the same colour for them all.

Next to the three unsorted list item colours, you'll also find the strings used for the bullets themselves. These too are easily changed, and needn't correspond to the characters used to markup lists in Bablex.

/* TABLES */

table { clear: both; margin: 1rem 0; }

th, td { padding: 0.5rem; }

th { border: 2px solid #804000; }

td { border: 2px solid #808080; }

td.left-cell, th.left-cell { text-align: left; }

td.centre-cell, th.centre-cell { text-align: center; }

td.right-cell, th.right-cell { text-align: right; }

td.total-cell { color: #FFFFA0;
border: 2px solid #808040; }

The th and td definitions draw boxes around the table header cells (above --- lines) and ordinary cells respectively: allowing you to change their colour or line width.

td.total-cell does the same for cells under ... lines.

You can also modify these properties to replace cell boxes with a lined grid and so forth, but this is slightly more complicated, so consult CSS documentation to see what is possible.

/* IMAGES */

figure { clear: both;
padding: 0; border: 0; margin: 1rem 0; }

figure::after { content: "";
display: block; clear: both; }

p.paragraph-with-image { clear: both; }

span.image-frame { background: #800000;
display: inline-block; clear: left; float: left;
padding: 0.3rem; margin: 0 1rem 1rem 0; }

img { padding: 0; border: 0; margin: 0; }

Note the span.image-frame definition. This is a coloured rectangle, slightly larger than the displayed image, within which the image is centred. Only the edges are left visible as a frame.

0.3rem determines the width of this frame, and #800000 the colour. Simply find and change these to modify (or hide) the frame.

/* TERMS */

dl.term dt { display: inline;
color: #FFA0FF; font-variant: small-caps; }

dl.term dt::after { content: " ::"; color: #FFFFA0; }

dl.term dd { display: inline; color: #FF80C0;
padding: 0; margin: 0; }

a.term { font-family: inherit; font-weight: inherit;
color: inherit; text-decoration: underline dotted; }

These properties control the display of term definitions.

They specify three colours: #FFA0FF, #FFFFA0, and #FF80C0. These control the colors of - in turn - the term, the arrow between the term and the definition, and the definition itself.

The string " ::" - defines what is shown between term and definition. You may change this as you wish, and the string you choose need not correspond to the Bablex syntax for metadata as this default string does.

/* METADATA */

dl.metadata { color: #8080FF; font-family: monospace;
clear: both; margin: 1rem 0; }

dl.metadata dt { color: #4040FF; }

dl.metadata dd { font-weight: bold; }

The first colour #8080FF controls the metadata property names, and the second, #4040FF, the colour of their values.

/* INSERTS */

blockquote, div.insert { clear: both; overflow: auto;
padding: 0 1rem; border: 0; margin: 1rem; }

blockquote,
div.insert blockquote { background: #401000; }

div.insert,
blockquote div.insert { background: #003030; }

blockquote blockquote,
div.insert div.insert
{ background: rgba(255, 255, 255, 0.1); }

The first color #401000 sets the background of inserted quotes (using "--/--"), and the second, #003030, the colour of other inserts ("+--/--+").

The backgrounds are partially transparent, so against a black page they look darker than they are. Their opacity is controlled by the 0.1 right at the end of this section: they are 90% transparent.

The point of this is that when inserts are shown within inserts, the inner insert appears brighter, as the transparency through two backgrounds is reduced.

You can change the colours and the transparency to achieve the look you want, and even make the backgrounds opaque by changing 0.1 to 1.0, though if you do this, nested backgrounds will not be distinguishable unless you also add a border.

/* LINKS, BOOKMARKS & FOOTNOTES */

a { color: #FF2020; text-decoration: none;
font-family: serif; font-weight: bold; }

a.footnote { font-size: 0.5rem;
vertical-align: super; }

span.bookmark { color: #FFA000; }

span.footnote { color: #FFA000;
font-size: 0.5rem; vertical-align: super; }

The red colour #FF2020 controls clickable text, and the two occurrences of the orange #FFA000 control the colour of bookmark and footnote text respectively.

Two occurences of 0.5rem determine the size of footnote numbers compared to ordinary text: the first time where it appears in the main text, and the second where it appears next to the footnote itself.

/* ONLY FOR BX2WEB.HTML */

/* (Remaining properties not used by translations.) */

[CSS omitted]

The CSS below this point has no effect on the display of translated pages. It is used by the translator page itself, so we strongly recommend you do not change it.

The exception is when you are editing a copy of bxstyle.css to use with your own pages. In this case, by all means delete everything from this comment down. It does no harm, but you may not want the clutter.

The document type tag for HTML5 is blessedly simple, and inserted near the top of each translation.

<!DOCTYPE html>

The <a> tag is used to implement all Bablex links. Below are examples of links to the various destinations possible. See Links for more information about these.

Bablex

Headings: [HTML Tag Usage]
Bookmarks: [A Bookmark]
Automatic bookmarks: [top]
Footnotes: [90]
Files: [idontexist.txt]
Websites: [http://google.com]
Foreign bookmarks: [bookmark; foreign.txt]
Bookmarked Links: [Facebook]

<A Bookmark> - Nothing to see here.

<90> Welcome to footnote 90.

<Facebook> [http://facebook.com]

Web

HTML

<p>Headings: <a href="#html-tag-usage">HTML Tag Usage</a>
<br>Bookmarks: <a href="#a-bookmark">A Bookmark</a>
<br>Automatic bookmarks: <a href="#top">top</a>
<br>Footnotes: <a href="#insert-88-footnote-90" class="footnote">90</a>
<br>Files: <a href="idontexist.html">idontexist.html</a>
<br>Websites: <a href="http://google.com">http://google.com</a>
<br>Foreign bookmarks: <a href="foreign.html#bookmark">bookmark; foreign.html</a>
<br>Bookmarked Links: <a href="http://facebook.com">Facebook</a></p>

<p><span id="a-bookmark" class="bookmark">A Bookmark</span> - Nothing to see here.</p>

<p><span id="insert-88-footnote-90" class="footnote">90</span> Welcome to footnote 90.</p>

<p><span id="facebook" class="bookmark">Facebook</span> <a href="http://facebook.com">http://facebook.com</a></p>

A few points are worth noting:

1. <span> elements mark the position of bookmarks and footnotes: eg. <span id="a-bookmark" class="bookmark">A Bookmark</span>
2. Footnotes in inserts each have a prefixed id to ensure they don't clash with similarly numbered footnotes in the main text: eg. <span id="insert-88-footnote-90" class="footnote">90</span>. The insert-88- prefix before the id is also inserted before the href of footnote links in the same insert. The result is that footnotes and footnote links inside an insert may not be paired with anything outside that insert.
3. Links to local .txt (and in fact .bx) files in Bablex are translated to links to similarly named .html files in HTML: [idontexist.txt] became <a href="idontexist.html">idontexist.html</a>. See File Links for more information.
4. The link [Facebook] was not linked to bookmark <Facebook>, but to the destination of the link after it, [http://facebook.com], by translation <a href="http://facebook.com">Facebook</a>. See Bookmarked Links.

The basic styles *bold*, /italic/, and _underlined_ are translated using <b>, <i>, and <u>. See Styles.

Bablex

*bold* /italic/ _underlined_

Web

HTML

<p><b>bold</b> <i>italic</i> <u>underlined</u></p>

The use of these tags is worth commenting on as, for most of HTML's history prior to HTML5, they were officially deprecated.

In early HTML, these tags were defined as simply bold, italic, and underlined.

Later, CSS was developed to encourage the separation of form and content. HTML tags would mark only types or uses of text, rules controlling the display of these types being moved to CSS files.

Tags like <b>, <i>, and <u>, which control presentation directly from HTML, were therefore deprecated.

New tags appeared, such as <strong> for important text, and <em> for emphasised text. In principle, therefore, these tags didn't tell a browser how to display text, only what it meant. But by default, <strong> and <em> were displayed as bold and italic, and to most HTML writers - let's be honest - they became simply replacements for <b> and <i>.

In HTML5, <b>, <i>, and <u> were redefined: no longer presentational tags meaning bold, italic, and underlined but marking types of text.

<b> marks "a span of text to which attention is being drawn for utilitarian purposes without conveying any extra importance and with no implication of an alternate voice or mood."

<i> marks "a span of text in an alternate voice or mood, or otherwise offset from the normal prose in a manner indicating a different quality of text."

<u> marks "a span of text with an unarticulated, though explicitly rendered, non-textual annotation."

Realistically, though, by default, almost all browsers still render <b> as bold, <i> as italic, and <u> as underlined, exactly as they have always done.

And so, when it came to translating Bablex markup for *bold*, /italic/, and _underlined_, these tags were the obvious choices.

While these tags are no longer deprecated, the wider issue remains that Bablex is mapping essentially presentational tags onto semantic ones.

Unfortunately, this is unavoidable, as a Bablex text file is a single document, and so cannot separate form and content as web pages do between .html and .css files. Both here, and in all the translations below, an attempt has been made to choose tags which have both suitable definitions, and an appropriate default rendering when viewed through a browser.

<blockquote> is used to translate Quote Inserts.

Bablex

"---
Covfefe! /Donald Trump/
---"

Web

Covfefe! Donald Trump

HTML

<!-- insert 90 begins -->
<blockquote>

<p>Covfefe! <i>Donald Trump</i></p>

<!-- insert 90 ends -->
</blockquote>

Note that inserts (Block Inserts and Quote Inserts) are numbered, and the numbers shown in comments at the beginning of the insert in HTML...

<!-- insert 90 begins -->

...and at the end...

<!-- insert 90 ends -->

This makes <blockquote> and </blockquote> (or <div> and </div>) pairs easier to match should you choose to read the HTML, particularly if inserts are long, or nested.

See: <main>

See: <p>

See: <pre>

See: <dl>

<div> is used to translate Block Inserts.

Bablex

+---
This insert is secret.
---+

Web

HTML

<!-- insert 91 begins -->
<div class="insert">

<p>This insert is secret.</p>

<!-- insert 91 ends -->
</div>

The <dl> construct is used to translate both Metadata and Terms.

The translation of metadata is fairly straightforward:

Bablex

refcode | X-2349-F322
version | 2.7

Web

HTML

<dl class="metadata">
<dt>refcode</dt>
<dd>X-2349-F322</dd>
<dt>version</dt>
<dd>2.7</dd>
</dl>

Terms translate similarly.

Bablex

trolley :: A bit like a troll.

Don't be trolley.

Web

HTML

<dl id="trolley-term" class="term">
<dt>trolley</dt>
<dd>A bit like a troll.</dd>
</dl>

<p>Don't be <a class="term" href="#trolley-term">trolley</a>.</p>

In addition to the <dl> construct above, the translator also inserts <a> links to the term definition wherever the term itself appears in the document.

Note the id="trolley-term" attribute marking the term definition, and the corresponding href="#trolley-term" attribute specified in the link around the occurrence of 'trolley'.

The label trolley-term is created simply by adding the suffix -term to the defined word. Terms with multiple endings are slightly more complex.

Bablex

misnomer(s) :: The most beautiful woman in Nomer.

post(man/woman/cat) :: Postal workers with varying degrees of fur.

vowel/consonant/circular :: A type of letter.

The postcat delivered several circulars, a vowel, and some misnomers dressed for the beachwear round.

Web

HTML

<dl id="misnomer-s-term" class="term">
<dt>misnomer(s)</dt>
<dd>The most beautiful woman in Nomer.</dd>
</dl>

<dl id="post-man-woman-cat-term" class="term">
<dt>post(man/woman/cat)</dt>
<dd>Postal workers with varying degrees of fur.</dd>
</dl>

<dl id="vowel-consonant-circular-term" class="term">
<dt>vowel/consonant/circular</dt>
<dd>A type of letter.</dd>
</dl>

<p>The <a class="term" href="#post-man-woman-cat-term">postcat</a> delivered several circulars, a <a class="term" href="#vowel-consonant-circular-term">vowel</a>, and some <a class="term" href="#misnomer-s-term">misnomers</a> dressed for the beachwear round.</p>

The id and href attributes for terms with multiple endings is derived from the term as follows:

1. Convert the non-alphanumeric characters in the term to dashes.
2. Remove any dashes from the ends.
3. Reduce groups of dashes to a single dash.

In the examples above, the results are:

See: <dl>

See: <img>

See: <img>

<h1> only appears once in each html translation, translated from the first, and therefore main, heading in the Bablex document.

However, it has much in common with the other heading tags, and forms part of a common structure with then, so they are all discussed under this heading.

Bablex

### SAMPLE MAIN HEADING

### Sample A Heading

=== Sample B Heading

Web

HTML

<h1 id="heading-1"><span id="sample-main-heading">SAMPLE MAIN HEADING</span></h1>

<h2 id="heading-2">Sample A Heading</h2>

<h3 id="heading-3">Sample B Heading</h3>

Headings as Bookmarks

Note the id="heading-1" attribute within each <h1> tag. This allows the link [Heading 1] to be used anywhere in the document. All heading tags carry the same attribute: you will see it in the <h2> and <h3> tags above.

The text inside <h1> is further wrapped in a <span>, which carries the attribute id="sample-main-heading". This allows the main heading to be linked by name using [Sample Main Heading]. (See <span>.)

The other headings may also be linked by name, but the corresponding id attributed are in their corresponding <header> tags. (See <header>.)

Mapping Bablex to HTML Headings

Bablex headings are assigned letters, from A-Heading to E-Heading.

They are lettered because, while they are translated using tags <h1> to <h6>, the mapping between them is not fixed. Which HTML tag is used for each heading depends on which headings you use.

For instance, if your document contains only an A-Heading, a C-Heading, and an E-Heading, then these are translated using <h1>, <h2>, and <h3> respectively, so that there are no gaps in the series of heading levels used.

Also, W3C recommends that a page should only have one <h1> heading, so if you have several A-Headings, the first is translated using <h1>, and the remainder using <h2>. This means that if this document also has any B-Headings, they will be pushed down to <h3>, and C-Headings to <h4>, and so on.

This is why Bablex has five headings: if multiple A-Headings are used, and B-Headings to E-Headings are each used at least once, the resultant mapping will run as follows:

Headings in Inserts

Headings in inserts are not considered part of the main flow of the text, so headings inside them are not translated using HTML heading tags. For instance, while a Heading-B in the main text might be translated using <h2>...</h2> tags, in an insert the tags used will be <p class="h2-in-insert">...</p>.

In bxstyle.css, these special classes are styled to resemble the heading tags to which they correspond.

Note that headings in inserts will not set the document title, create <section>...</section> blocks, or have navigation bars.

See: <h1>

See: <h1>

See: <h1>

See: <h1>

See: <h1>

Below is the <head> added by the translator to its translation of this file - bablex.txt.

<head>
<title>The Bablex Markup Language</title>
<meta charset="UTF-8">
<meta name="description" content="An introduction to the Bablex markup language">
<meta name="keywords" content="Bablex, lightweight, text, markup, language">
<meta name="author" content="Manny Neira">
<meta name="generator" content="Bablex 1.0">
<link rel="stylesheet" href="bxstyle.css" type="text/css">
</head>

It is very simple, and varies little from translation to translation. Each <head> contains the following:

1. The page <title>.
2. Various pieces of <meta> data.
3. A <link> to the bxstyle.css stylesheet.

W3C describe a header as 'introductory content for its nearest ancestor sectioning content or sectioning root element'.

Bablex therefore creates <header> elements inside <main>, and inside each <section>.

The first <header> opens on the line after the <main> tag, and contains three parts:

1. Everything above the main heading.
2. The main heading or <h1> element.
3. The <nav> immediately after <h1>

The remaining section <header> elements open on the lines under the <section> tags, and only contain two parts:

1. The section heading <h2>-<h6> element.
2. The <nav> immediately after the heading.

Note that the <header> tags for all the headings after the main heading carry an id attribute allowing the associated heading tags to be linked by name. For instance...

<header id="all-about-hamsters">
<h3 id="heading-23">All About Hamsters</h3>

This can be linked using [All About Hamsters].

The equivalent id for the main heading is within a special <span> tag. (See <h1>.)

A typical header, with its heading and its navigation bar, appears like this in the translation:

<header id="introduction">
<h3 id="heading-2">INTRODUCTION</h3>
<nav>
<p class="navigation-bar">
<a href="#heading-1">&lt; LAST</a>
<a href="#top">^ TOP</a>
<a href="#bottom">v BOTTOM</a>
<a href="#heading-3">NEXT &gt;</a>
</p>
</nav>
</header>

<hr> is used to translate Bablex rules.

Bablex

 There follows a rule.

 ***

 There follows a rule with embedded text.

 *** I Am A Rule ***

 That's it for rules.

Web

HTML

<p>There follows a rule.</p>

<hr>

<p>There follows a rule with embedded text.</p>

<hr class="rule-with-text">
<p class="rule-with-text">I Am A Rule</p>

<p>That's it for rules.</p>

Rules with text are translated by the same <hr> tag, plus a <p> paragraph element containing the text.

Both tags representing rules with text are assigned the class rule-with-text to allow them to be styled specifically.

By default, the translator creates the following <html> tag.

<html lang="en">

This defines the page language as English.

However, you can change this by specifying language metadata:

language | de

In addition to this being displayed within the <body> of the page (see <dl>), the value updates the <html> tag:

<html language="de">

Note that while metadata in inserts will be displayed in the usual way, they will not cause any updates to the document <head>.

See: <b>

HTML5 provides a <figure> tag to markup content which, while related to the text flowing around it, does not rely on its exact position in the text for its relevance.

The syntax for all images is the same, so to determine whether an image is position independent in this way, Bablex simply looks at the text around it.

If it is in a paragraph by itself, it is considered a "freestanding image", and wrapped in a <figure> tag (and given a <figcaption>) on translation.

Bablex

[Freestanding image: bxlogo.gif]

Web

HTML

<figure><span class="image-frame"><a href="bxlogo.gif"><img src="bxlogo.gif" alt="IMAGE_RX: Freestanding image"></a></span><figcaption>Freestanding image<br><a href="bxlogo.gif">bxlogo.gif</a></figcaption></figure>

If the image has been inserted at the beginning of a text paragraph, it is an "embedded image".

Bablex

[Embedded image: bxlogo.gif] This image belongs with this text, hence "embedded".

Web

Embedded image

This image belongs with this text, hence "embedded".

HTML

<p class="paragraph-with-image"><span class="image-frame"><a href="bxlogo.gif"><img src="bxlogo.gif" alt="IMAGE_RX: Embedded image"></a><br>Embedded image</span></p>
<p>This image belongs with this text, hence "embedded".</p>

Note that both image styles are wrapped in <a> tags, which simply link directly to the raw images. The effect is that if (say) the image is reduced in size by the stylesheet, clicking on the image opens it directly in the browser window at full size.

The translation of lists contained in a single paragraph is very simple.

Bablex

1. Item A
    1.1. Item B
    1.2. Item C
        1.2.1. Item D
2. Item E
    2.1. Item F
    2.2. Item G

Web

HTML

<ol>
<li>Item A
<ol>
<li>Item B</li>
<li>Item C
<ol>
<li>Item D</li>
</ol>
</li>
</ol>
</li>
<li>Item E
<ol>
<li>Item F</li>
<li>Item G</li>
</ol>
</li>
</ol>

<ol>...</ol> establishes an ordered list, within which ordinary items are wrapped in <li>...</li>.

Sublists are the same. Their <ol>...</ol> wrapper is simply dropped in just before the closing </li> tag of the item above them in the main list.

Note that the numbering for the original list is not retained in the HTML translation. The numbers shown in a browser are calculated by the Bablex stylesheet.

Isolated lists - lists in which each item is a separate paragraph - are translated similarly.

Bablex

1. One

2. Two

Web

HTML

<ol><li class="isolated-item">One</li>

<li class="isolated-item">Two</li></ol>

The only difference is the each <li> tag is classed isolated-item, allowing the stylesheet to selectively style them with greater vertical separation.

Both these examples are ordered lists, but unordered lists simply substitute <ul>...</ul> for <ol>...</ol>, and are otherwise identical.

This tag appears once within the <head> of every translated HTML page, and always takes the same form.

<link rel="stylesheet" href="bxstyle.css" type="text/css">

This links the page to the bxstyle.css CSS file, which you can read with accompanying notes in the appendix on the Bablex Stylesheet.

W3C describes the <main> part of a document as 'content that is unique to that document and excludes content that is repeated across a set of documents such as site navigation links, copyright information, site logos and banners and search forms (unless the document or applications main function is that of a search form)'.

As the original plain text file is unlikely to contain the kind of website dressing that they seek to exclude, Bablex inserts <main> and </main> tags immediately inside the <body> and </body> tags, enclosing the entire document.

HTML5 defines <mark> as "a part of the document that has been highlighted due to its likely relevance to the user's current activity."

By default, <mark> is generally rendered as a yellow background to text, reminiscent of the use of a highlighter pen on printed documents.

The Bablex translator uses it to translate ^tint^ markers.

Bablex

You can ^tint^ text.

Web

HTML

<p>You can <mark>tint</mark> text.</p>

The translator will automatically add two <meta> tags to the HTML <head> element.

<meta charset="UTF-8">
<meta name="generator" content="Bablex 1.0">

You can specify a different character set by setting charset metadata.

charset | US-ASCII

This will both appear in the translated HTML <body> (see <dl>), and update the corresponding <meta>.

<meta charset="US-ASCII">

Three other metadata will cause the translator to add further <meta> tags:

description | Popular cat names
keywords    | pet, cat, names, list
author      | Kat Lover

The added tags run:

<meta name="description" content="Popular cat names">
<meta name="keywords" content="pet, cat, names, list">
<meta name="author" content="Kat Lover">

Note that metadata in inserts will still appear in the <body> of the document, but will not create or change <meta> tags.

HTML5 offers these tags to mark up navigation blocks: that is, any block primarily designed to contain links to take you to different parts of the document.

Bablex wraps <nav> tags around the four linked arrows in the navigation bars immediately following each heading: see <header>

See: <li>

The translator treats blank lines as paragraph separators, and preserves line breaks

Bablex

Line breaks in text
are preserved in HTML

Paragraphs are separated by blank lines.

Web

HTML

<p>Line breaks in text
<br>are preserved in HTML</p>

<p>Paragraphs are separated by blank lines.</p>

The translator uses <pre> to preserve the whitespace in formatted text, and <code> to apply a monospace typeface.

while(preformatted_code)
{
    intend_by_4_spaces(TRUE);
}

The translation runs:

<pre><code>while(preformatted_code)
{
    intend_by_4_spaces(TRUE);
}</code></pre>

Monospaced text within a paragraph is implemented using the <code> tag.

Bablex

The `PRINT` statement displays text.

Web

HTML

<p>The <code>PRINT</code> statement displays text.</p>

W3C define a <section> as 'a thematic grouping of content, typically with a heading'.

Bablex therefore creates a section for each heading after the first (which acts as a heading for the <main> block, enclosing the entire page).

The opening <section> tag goes on the line before the heading, and the closing </section> tag before the next heading at the same or higher level.

This means that if you have used headings of different levels, sections may contain (sub)sections to reflect this.

Each <section> tag in the document is given a class to indicate its level, which is the same as the level of the heading which begins it.

For instance, if your document contains B-Headings which have been translated as <h2> headings, the corresponding sections will begin with the tag <section class="level-2">. You can therefore use the CSS selector section.level-2 to control the appearance of these sections.

The translator uses <span> tags in three ways:

1. To create a coloured frame around each image: see <img>
2. To mark the main heading as the destination for the automatic bookmark heading-1: see <h1>
3. To mark the position of bookmarks and footnotes so that links can be created to them.

Bablex

Click to go [there]. [12]

<there> Here!

<12> With your mouse. Don't just sit there making clicking noises.

Web

HTML

<p>Click to go <a href="#there">there</a>. <a href="#insert-102-footnote-12" class="footnote">12</a></p>

<p><span id="there" class="bookmark">there</span> Here!</p>

<p><span id="insert-102-footnote-12" class="footnote">12</span> With your mouse. Don't just sit there making clicking noises.</p>

Note the <span> elements wrapped round both the bookmark and footnote destinations, using the id property to mark their positions.

Naturally enough, the translator uses <table> to translate tables in the original text.

Bablex

| Type       |    Letters     |  Number |
|------------|----------------|---------|
| Vowels     |     AEIOU      |       5 |
| Consonants |  *ABCDFGHJKLM  |      19 |
:            :   NPQRSTVXZ*   :         |
| Glides     |     /WY/       |       2 |
|............|................|.........|
| TOTAL                       |      26 |

Web

HTML

<table>
<tr>
<th class="left-cell">Type</th>
<th class="centre-cell">Letters</th>
<th class="right-cell">Number</th>
</tr>
<tr>
<td class="left-cell">Vowels</td>
<td class="centre-cell">AEIOU</td>
<td class="right-cell">5</td>
</tr>
<tr>
<td class="left-cell">Consonants<br></td>
<td class="centre-cell"><b>ABCDFGHJKLM<br>NPQRSTVXZ</b></td>
<td class="right-cell">19<br></td>
</tr>
<tr>
<td class="left-cell">Glides</td>
<td class="centre-cell"><i>WY</i></td>
<td class="right-cell">2</td>
</tr>
<tr>
<td class="left-cell total-cell" colspan=2>TOTAL</td>
<td class="right-cell total-cell">26</td>
</tr>
</table>

Note particularly the use of classes. left-cell, centre-cell, and right-cell determine the alignment of cell contents, and total-cell styles cells under a dotted line in the original text. Cells above a dashed line act as headers, and are therefore translated using the <th> tag.

See: <table>

See: <table>

The translator uses <dl> to translate all Bablex metadata into the <body> of an HTML document. (For more information about this, see <dl> above.)

However, if the property name is title, (regardless of case), it also updates the title specified using the <title> tag in the document <head>.

Title | The Da Vinci Cod, And Other Italian Fish

The resultant HTML is:

<title>The Da Vinci Cod, And Other Italian Fish</title>

W3C specifies that to be valid HTML, a document must contain a <title>.

So if you don't specify title metadata, the translator will use the text of the first heading in the document: see <h1>

Note that while metadata in inserts will be displayed in the usual way, they will not cause any updates to the document <head>.

See: <table>

See: <b>

See: <li>