Stx quickie guide

(You may want to look at the source of this file.)

You can set various document metadata at the beginning of the file. The most important items can be seen above.

Usually, you will want to give your text some structure with headings. The lines beginning with exclamation points are headings. The number of exclamation points determines the level of the heading: one means top-level heading, two means subheading, three means sub-subheading and so on.

Paragraphs and whitespace

Basic paragraphs

For most part, you can use whitespace (spaces, tabs, and line breaks) the way you want to. There are two notable exceptions:

1. an empty line marks a paragraph break.
2. the amount of indentation of a line affects Stx's idea of where the line belongs. The text of every line in a paragraph should be indented to the same column.

Because Stx doesn't generally care about the way you use whitespace, if you want to preserve the formatting of the source, you need to request it separately.

Preformatted text

Three open curly braces ({{{) begin a preformatted text block, and three close curly braces (}}}) end it:

         This
   is                 preformatted
 text.

Line breaks

To force a line break at a certain point in text,
end a line with double-slash //. This will begin
a new line
immediately.

Inline markup

Inline markup is what you put in your document to cause textual effects.

Emphasis

There are two kinds of emphasis, normal and strong. Normal emphasis is achieved by bracketing the phrase with underscores _ or slashes / — the choice is free.[1] Strong emphasis is given by bracketing with asterisks *.

[1] Actually, underscores are meant for semantic emphasis (marking a phrase especially noteworthy) whereas slashes are meant for technical emphasis (first occurrences of terms, titles of cited works, text that is not to be taken literally).

Additionally, there is a special kind of emphasis that typesets the text in teletype font.

Footnotes

You can add footnotes[2] to the text by putting the footnote into double brackets ([[ and ]]). The footnote text must be separated from the brackets with a space ( ) or a dash (-).

[2] A footnote is a short comment to the text.

Special characters

Enclose quotations in quotation marks " to produce the right formatting. An upper- or lowercase c in parentheses (c) produces a copyright sign, and ™ produces a trademark sign.

Two dashes in a row -- produce long dashes.

Links

If you enable link abbreviations (see Stx markup reference), many expressions with brackets become links. Link data can be written right into the link, or placed indirectly into a link data block[3]. Another example. You can also point to sectional units, such as Sectioning.

[3] This is link data for the indirect link reference fn1. Because it does not look like anything link-like, it will be made into a footnote.

Block-level markup

Sectioning

A horizontal line can be achieved by putting two or more dashes -- on a line by themselves:

Lists

Lists give a document structure. Overuse of lists (demonstrated below) makes a document seem technical and reference-like. There are three kinds of lists:

1. enumerated (such as this one)
2. itemized (the same, only with bullets instead of numeric labels)
3. term-definition lists (such as the following one)

What are they good for and how do you write them?

Itemized lists

Very basic, general-purpose construct. You can often make notes by writing an ad-hoc itemised list. Subpoints can be added by making a sublist (lists can be nested within one another by indentation):

• note 1.
• note 2.
  • subnote 2.1

    By the way, list items can have many paragraphs, too. As well as all other kinds of constructs, as long as you indent them relative to the list.

• another point. If the item is very long and you add a line break, the lines must be indented properly.

In itemised lists, you can use the dash (-) or the asterisk (*) as a list marker, but not within the same list.

Term-definition lists

These are good for producing e.g.

• list-like descriptions of different things
• word lists and the like
• link menus with comments
• short textual blurbs which are naturally divided by subject

Term-definition lists are a very versatile construct, and underused by many. If your list items are short and/or stand by themselves, you can use ordinary lists, but if you want to attach comments to the items, you are usually better off using term-definition lists.

For term-definition lists, the double-colon (::) at the end of a line is the magic marker that causes a line to turn into a term. A definition is anything that follows a term, indented.

Enumerated lists

1. look somehow very official and precise.
2. written similarly to itemised lists, with a hash sign (#) as the list marker.
3. handy if the items of the list have some kind of preference or timeline order.
4. not good for giving lists to whose items you can refer:
   • adding items into the middle of the list changes the numbering of the rest of the items.
   • you can't know anyway how your list gets numbered in different output formats with different styles.

Quotes

An indented paragraph is taken to be a citation block. Citations, too, can be nested within one another and lists.

Those were the days, my friend,
I hope they'd never end..

Citation blocks are also good for indenting things that should stand out, such as mathematical formulae, examples, and noteboxes.