< The STML command languageLists >

Title, author, headlines, subheaders, text and paragraphs

Titles, author and headlines are put into the text by one-line commands. Those STML structures consist always of a command at the line begin, prepended by a colon (“<tt>:</tt>”) and followed by one or more parameters. For title and headlines, the command names are more or less directly derived from the correspondant HTML tags: “:title”, “:author”, “:h1”, “:h2”, “:h3”, and “:h4”. Each STML document must have a “:title” and it must be the first command issued in the text.

Note

:h1 text is exactly of the same size as the :title of the page. It is therefore no bad idea to use :h2 and :h3 heading commands for subsections in the document :h1 should only be used for logical parts on the same level as the actual documents of the help set.

To get a real document, one should put one bit or the other of “normal” text between the headlines. Such text is typed just as it is. It is possible to make parts of the text **bold** or //italic// by inserting special marks: “**” at the begin and end of bold text, “//” left and right from italic text. Bold and italic can also be combined, of course. However, none of them can cross paragraph boundaries and the closing marks must always appear in reverse order as the opening marks did. If the closing mark is forgotten or order is wrong, any bold or italic text is ended automatically at the end of the current paragraph.

It also possible to print parts of the paragraph as typewriter text by putting it between double colons, “<tt>::</tt>”. Typewriting, bold and italic can also be mixed in any fashion, as long as the output renderer allows it.

Note

Ending the text decoration at the end of the paragraph is a guaranteed feature of STML. If you want to have a complete paragraph bold, it is save to put the bold marker (“**”) at the beginning of the paragraph only and leave them out at the end.

Paragraphs are simply seperated from each other by one or more blank lines. A paragraph itself consists of one or more lines following each other directly. So, it is possible to work on STML files with editors keeping each paragraph in one long logical line or with editors inserting line feeds in the paragraph itself.

Within a paragraph, explicit line breaks can be inserted by a double tilde, “~~”. Note that this does not suppress normal line breaking at the line end. Line breaks can happen at every space character. To prevent this, use a non-breakable space character which is written as an underscore, “_”. Note that you must not have any normal space characters around the non-breakable space.

Note

Text markup for bold, italic or typewriter text, “~~” line breaks and “_” non-breakable spaces are also understood in header command parameters (:h1-4) and links. They must not be placed in :title command parameters, however.

Using these basic markup elements, one can begin to produce structured text:

Example

:title Documentation - A Deeper Look
:author Dirk Hillbrecht

Documentation is important. This is an introductional paragraph written directly below the main document title, which you can read just above. It is good practice to put the real content of the document below separate titles.

Sometimes, however, an additional reminder is needed for even such a simple truth. So, read my lips again: //You should use headlines and subtitles in your document//. It helps you and the reader. Believe me!

:h1 The Beginning

Ah! So, we are finally in that new section of our document. The title says we should take a look into the beginning of a documentation. Well, it should be clear that each document should begin at the begin. In former times, one could have said that you should start at the top of the otherwise blank sheet of paper, but for electronic documents, sheets of paper are a rather unusual environment.

If you have an editor opened, the cursor being up left on the screen, the document otherwise empty, you are not totally wrong. It is save to define this as the beginning of your document.

:h1 Structure

As important as the beginning of the document is its structure. Therefore, the section title is of the same level and size as the one before.

:h2 Sections

A part of structuring is defining the text sections. We have now just begun such a new section and as it is only a part of the structuring section itself, its title is smaller and its logical position is not next to but below the bigger one.

:h2 Paragraphes

Having subsections normally only makes sense if you have more than one of them. Here, we have another subsection as structuring is not finished at the stage of sections and subsections.

Quite a number of authors sometimes forget that separating the text itself into handleable chunks, the so-called **paragraphes**, is critical for the text to be understandable as a whole. A reader must have a chance to order the text and split it into pieces. Best way to do this is to look at the same pieces the author did when he was writing the text. So, the author should give clear indication about what he thinks the sensible chunks are. Exactly for this purpose, he should use paragraphs in his document.


Documentation - A Deeper Look

Documentation is important. This is an introductional paragraph written directly below the main document title, which you can read just above. It is good practice to put the real content of the document below separate titles.

Sometimes, however, an additional reminder is needed for even such a simple truth. So, read my lips again: You should use headlines and subtitles in your document. It helps you and the reader. Believe me!

The Beginning

Ah! So, we are finally in that new section of our document. The title says we should take a look into the beginning of a documentation. Well, it should be clear that each document should begin at the begin. In former times, one could have said that you should start at the top of the otherwise blank sheet of paper, but for electronic documents, sheets of paper are a rather unusual environment.

If you have an editor opened, the cursor being up left on the screen, the document otherwise empty, you are not totally wrong. It is save to define this as the beginning of your document.

Structure

As important as the beginning of the document is its structure. Therefore, the section title is of the same level and size as the one before.

Sections

A part of structuring is defining the text sections. We have now just begun such a new section and as it is only a part of the structuring section itself, its title is smaller and its logical position is not next to but below the bigger one.

Paragraphes

Having subsections normally only makes sense if you have more than one of them. Here, we have another subsection as structuring is not finished at the stage of sections and subsections.

Quite a number of authors sometimes forget that separating the text itself into handleable chunks, the so-called paragraphes, is critical for the text to be understandable as a whole. A reader must have a chance to order the text and split it into pieces. Best way to do this is to look at the same pieces the author did when he was writing the text. So, the author should give clear indication about what he thinks the sensible chunks are. Exactly for this purpose, he should use paragraphs in his document.

< The STML command languageLists >