title: Stx quickie guide
author: Panu Kalliokoski
date: 25.1.2006
language: english

(You may want to look at the source[./Stx-doc.txt] 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:

 # an empty line marks a paragraph break.
 # 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.[[ 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). ]]
*Strong emphasis* is given by bracketing with asterisks ''*''.

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

!! Footnotes

You can add footnotes[[ A footnote is a short comment to the text. ]] 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 (-).

!! 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 ''(tm)'' produces a trademark sign.

Two dashes in a row ''--'' produce "long dashes".

!! Links

If you enable link abbreviations (see [Stx-ref.html]), many expressions
with brackets become links.  Link data can be written right into the
link[http://example.com/like-this/], or placed indirectly into a
[link data block][fn1].  Another example[ln1].  You can also point to
sectional units, such as [Sectioning].

[fn1] 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.
[ln1] http://example.com/indirect-link/

! Block-level markup

!! Sectioning

A horizontal line can be achieved by putting two or more dashes ''--''
on a line by themselves:
---
But most of the time, you will only want to use headings for sectioning.

!! 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:

# enumerated (such as this one)
# itemized (the same, only with bullets instead of numeric labels)
# 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::
  # look somehow very official and precise.
  # written similarly to itemised lists, with a hash sign (''#'') as the
    list marker.
  # handy if the items of the list have some kind of preference or
    timeline order.
  # 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 w_beg(comment) or is it "thought"? w_end(comment) they'd never end..

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

