title: Stx quickie guide doc_id: stxdoc 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 [stxref]), 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.