Oberon/ETH Oberon/Tutorial/Tutorials

These tutorial pages were written by André Fischer (afi) with editorial assistance of Hannes Marais, were hosted at the ETHZ and remain under the ETH license. Related content is found in the system via Book.Tool. Extended content is also available on paper. Some tutorial pages are in the WayBack archive.

HTML tutorial developer guide

[ Text | Contents | Index | Master index]

Objective

Learn the rules for creating a document that can be mechanically converted to a HTML document that will serve as on-line Oberon tutorial.

Estimated time: < 10 minutes.

Rationale for a converter

In principle, a conventional text editor, even a very simple one, is all you need to edit an HTML page in standard ASCII format. But if you want somewhat more comfort or if you want to re-use already existing texts, you have to look for another solution. The answer to the first wish already exists in the form of numerous commercial and free HTML editors. Such an editor is, at the moment, not available in Oberon. The answer to the second wish is less costly to develop and is offered here. The raw material for a converter is a presentable, roughly formatted text having the appearance of the final document. It is the duty of the converter to implement the HTML tags which describe the complete document (<HTML>, <HEAD>, <TITLE>, etc.) and text structuring tags such as <Hn>, <P> and <BR>. The raw text may also be decorated with any of the many HTML tags.

With the provision of special tags the converter offers in addition the automatic construction of a table of contents and of an index.

Tutorial authoring commands

Authoring commands are of the form:

\command[option]"{"argument 1"}" ... "{"argument n"}"

Some commands have no [option] part.

There are different types of arguments:

docuname: any legal file name

label: Letter {Letter | Digit}

title, string: any text without }, use "\}" to have a } within a string

For a well-formed document text follow these rules:

- The first command must be "\Book".
- In a document labels must be unique.

\Book{docuname}{title}

docuname: Document filename (only characters allowed in a filename). The extension ".html" is appended automatically.
title: Document title. It will appear twice in the final HTML document, that is, once in the document header as title: <TITLE> title </TITLE> and once more in the document body as <H1> title </H1>. According to the rules of HTML, title may not contain embedded tags. Further, several systems analyze the title of Web documents automatically for creating indices. Therefore, a title should be expressive and rather short (a maximum length of 64 characters is recommendable).

The first command in any document specification must be "\Book".

Examples:

\Book{Sample}{My first document}

This command will produce a file named "Sample.html". The title will be "My first document".

\Chapter[option]{title}

option: the default is [0]

Absolute numbering of chapter level

0: chapter

1: subchapter

...

Relative numbering of chapter level

=: same level as current chapter

+: current chapter level + 1

-: current chapter level - 1

title: chapter title

Start a new chapter. A table of contents will be constructed using the information provided by the \Chapter commands appearing in the document.

Examples:

Absolute numbering

\Book{Sample}{My first Document}

\Chapter[0]{About}

\Chapter[1]{About A}

\Chapter[2]{About AA}

\Chapter[1]{About B}

Relative numbering

\Book{Sample}{My first Document}

\Chapter{About}

\Chapter[+]{About A}

\Chapter[+]{About AA}

\Chapter[-]{About B}

\Label{label}

label: Label for later reference to this point in the text. In a document, labels must be unique.

Example: \Label{label1}

\Link{docuname.label}{string}

label: Label used in a Link{Label}{\Label} command to which to refer now. To refer to a label defined in another document prefix the label with that document's name.
string: String (blue) to display in the document text.

Examples:
Assume that a label "thispoint" is defined in a document "DocumentXY". Note the difference of behaviour of

\Link{thispoint}{sensitive text} and

\Link{DocumentXY.thispoint}{sensitive text}

In the first example you will stay in DocumentXY. In the second example, DocumentXY is opened again. [Back] can be used to backtrack.

\Index[-]{string}

- : when this option is present the string is inserted in the index but does not show in the document - Used to place an anchor which is offset with respect to where the string appears in the text.

string: String to add to the index. An index will be constructed using the information provided by the command. The index is a hypertext document containing links to the anchor points which are substituted for the \Index commands.

Examples:

\Index{this is in the index and in the text}

\Index[-]{this is in the index only}

\Call{string1} ... {stringN}

string1 ... stringN-1: Sequence of Oberon commands stringN: String to display in the document text

If a single string is specified it is used both as command and as text. Clicking on the text colored in red executes the Oberon command sequence.

Examples:

\Call{System.Time}

\Call{Backup.ReadFiles My.Tool}{Edit.Open My.Tool}{Read "My.Tool" from diskette and open it.}

\\

The backslash character "\" is used by the compiler as an escape character to recognize the start of a command as in \Chapter ... . To generate a single "\" in the book, write a double one "\\" in the text.

Example: \\Label - will produce: \Label

HTML tags

HTML tags may be interspersed in the text according to the standard HTML syntax rules. A "\" must precede each tag.

Compiling a document - Text2HTML.Compile

Text2HTML.Compile [\I=indexName] [\M=modelName] ( {fileName}~ | * ) converts the tagged text files named in the list to HTML documents. For each source text file the compiler creates:

a main HTML document
a GIF file for each visual gadget floating in the source text
a public library in which all the visual gadgets are collected
a table of contents HTML document
an index HTML document (including a quick index at the beginning)

If the option \I is used, a master index HTML document is also created. It encompasses all documents processed in the same compilation.

Finally, an FTP tool FTPCommands.Tool is created that contains a collection of FTPTool commands for uploading these files to the Web server. Except when the marked text is compiled, a file transfer command for uploading (backing up) the source text file is included. The tool also contains System commands for deleting the GIF files from the local PC. The transfer of a large number of files can then be initiated by executing the single command: Configuration.Do FTPCommands.Tool ~

All these files are stored in the current directory. Existing files with the same names are overwritten.

Assuming that Sample is the document name (assigned with \Book{Sample}), the HTML file will be named Sample.html. The table of contents is constructed automatically using the information provided in the chapter headings \Chapter{...}. The file will be named Sample.Contents.html. Also the index is automatically constructed using the information provided by the \Index{...} commands. It is stored in a file named Sample.Index.html.

Index

H

HTML tag

T

Text2HTML.Compile
tutorial authoring commands

\

\Book
\Call
\Chapter
\Index
\Label
\Link
\\

Revised, afi 02 Dec 1996
Installed on 30 05 1997