Please note that reading this document is not the proper way to learn Stx. You should never spend time learning tools you don't have to learn. Just start to write Stx (probably with the help of Stx quickie guide), and check this document if/when the need to do something complicated arises.
This document is arranged roughly by how frequently the material is of use for people. More frequently useful things come first, less frequently useful come after.
These are documented on the manual page of stx2any.
technicalemphasis, underscores (_)
semanticemphasis.
transition). The number (of dashes) determines the
strengthof the section break.
More indentation causes lists to become nested. If a paragraph is indented without being on the top level of a list item, it is made into a citation block.
Link abbreviations are discussed in a separate section.
At the beginning of file (before the first empty line in the document), you can give document metadata by writing lines of the form metadata_type: value. For example, put the following lines at the beginning of a file:
title: Very important document author: me language: english
All metadata is available for setting in this way. Different kinds of metadata are given in the section Macros for document metadata. You just leave the w_ prefix away.
You can use link abbreviations if you request them separately.[1] If you enable them, almost all brackets become special. Link abbreviations require two-pass processing for indirect link references and automatic labeling, so they are not well suited for using stx2any as part of a pipeline. However, stx2any will do what it can if it gets link abbreviations from the standard input.
[1] stx2any has a command line switch to activate link
abbreviations.
There are also indirect link references, which are gathered in separate link data blocks. Link data blocks do not affect the rendering of your document in any way except by providing information for linking. You can group them e.g. at the beginning of your document, at the end, or after every paragraph (which I think looks the neatest).
When link abbreviations are enabled, headings also produce labels automatically.
nameless linkto link-id. The text for the link is the label text for labels, the foreign document title (or filename) for cross links, the URL itself for URL's, and an empty string for the alternative text of inline images.
link data blocks), lines like these make indirect link references, declaring link-id to be equal to another link-id.
For every link-id, different interpretations are tried in order until an appropriate one is found. This is the order:
linkwas. But the footnote text has to originate from an indirect link reference. This is to protect a miswritten URL, cross reference or link tag from becoming a footnote by accident.
All Stx macros begin with a prefix w_. Normal m4 macros are also available, with the exception of GNU m4 format, which is too common a word to be left as a macro.
The included file is not subject to Stx abbreviations, but goes through m4 processing. These are a good way for adding templates to your HTML pages (just dump some HTML markup into the diversions frontmatter and backmatter), sharing some content between documents, or inserting long sections of content where abbreviation processing is not to take place. If you want to concatenate many Stx documents, it's better to give them all as arguments to stx2any — that way they go through abbreviation processing.
NAMEsections for man. The calls should be at the beginning of your man page, one by a line. name defaults to w_title, and on most pages, you need only one w_man_desc.
[2] This has
been changed; the default was latin1 up to and including
stx2any 1.57.
The optional parameter long-charset-name can be used to make documents in character sets that are not natively supported. The charset is used for LaTeX (and possibly internally); long-charset-name is used for HTML and DocBook.
dateof a document is a somewhat ambiguous; as a consequence, Stx doesn't try to guess what you use it for.
These macros have shorthands in Link abbreviations.
The text in the second parameter is always displayed alternatively, never in addition to, the image.
If the second argument is present, its text will be used as the link text instead of the destination document's title / filename.
index) as well as at the current point in document. The current point is cross referenced from the index. This command is useful for creating lists-of-tables and such stuff, but is not very well thought out yet. The text of marker, if given, is put into the index but not made part of the link.
Environments must be properly nested, i.e. w_beg(foo) must be closed by w_end(foo). Moreover, these abbreviated constructs are internally environments and must therefore be properly nested with explicit environments:
type; for example, w_beg(admonition, Note). Special admonition types supported by DocBook XML are
Note,
Tip,
Warning,
Caution, and
Important.
The environment takes two parameters, as in: w_beg(float, pos, caption). The first parameter pos determines the placement of the float and is composed of one-character placement hints, in order of preference of the placement of the float. (First character tells the most preferred placement and so on.) Some placements may not be available in some formats. The meanings of the characters are as follows:
near, for example after the paragraph or on the same page.
far. It may be e.g. several pages away.
The second parameter, caption, tells the caption text of the float, if any.
For example, the following only puts the included text in when producing a LaTeX document: w_beg(ifeq, w_outputfmt, latex) text… w_end(ifeq)
For HTML, the result is a S5 slide show, about which you can read more at http://www.meyerweb.com/eric/tools/s5/. You need to fetch the style sheets and javascript file yourself. You can define w_s5url to specify the directory where S5 files reside (default is ui/default/).
For man and DocBook XML, the slides simply suck.
Column types are given as parameters to the table environment, as in: w_beg(table, r, p). The meanings of column types are as follows:
All macros beginning with a w_ (or @w_) prefix are reserved for stx2any. You can redefine them, of course, if you want to change the operation of stx2any. For your own macros, you can choose your own prefix or use macros without a prefix at all. Environments, diversions and counters have their own namespaces under @w_, and you should not worry about them.
Calls to w_newcounter and w_delcounter can be nested for a counter. w_newcounter resets the counter to zero and w_delcounter returns the counter to the value it had before w_newcounter.
The following macros are good candidates for temporary redefinition.
The following environments are good
candidates for temporary
redefinition.
Warning: don't read this section unless you really need to or you want your head to explode. You have been warned.
Quoting
means the act of making literal text from something that
would have been considered markup ordinarily. For instance, if
you need a word surrounded by *asterisks* not to be converted
to strong emphasis, you need some kind of quoting.
Simple rule of quoting: don't quote unless you have to. stx2any has been built so that most of the time it gets the writer's intention correct. When it doesn't, you might have to resort to quoting.
stx2any has four types of quoting:
The reason for having so many is partly the implementation of stx2any, partly its philosophy, and partly the design of m4.
stx2any uses the native m4 quoting mechanism for its ordinary quoting job. The m4 quoting mechanism is actually quite elegant: quoted text begins from a backquote (`) and ends in an apostrophe ('). Quotes can be nested, so if you need literal quotes `like this', all you have to do is write ``like this''. With m4 quoting, you can quote macro calls, as in `w_paragraph'.
Abbreviations (the heart of Stx) are more problematic, because they are processed before the m4 processing phase takes place. But all abbreviations are defined to be highly contextual: for instance, the begin emphasis markup is required to have a left separator (space, open parenthesis, …) on its left side and a nonblank character on its right side. Because the backquote (`) is not considered to be a left separator, you can quote emphasis markup as if quoting m4 macro calls, and get e.g. /usr by writing `/'usr. All emphasis constructs also put quotes around the emphasised text, so literal /usr works without any quoting. Alternately, you can put markup out of context: for example, writing // in the middle of the line does not cause a line break.
Link abbreviations can be quoted by quoting the last square bracket in them.
When you have a quoting mechanism, you have to have a quote-quoting mechanism: otherwise, you have no way to include a literal quote in your text. Simple instances of quote quoting are handled by the nesting of quotes: whenever you write quotes inside quotes, the inner quotes are preserved.
Unmatched quotes are more problematic. Especially the apostrophe (i.e. m4 closing quote) is a common character. stx2any strives for keeping your apostrophes from interfering with its m4 machinery (which makes heavy use of quoting) by quoting them into calls to w_apo, which are eventually converted back into apostrophes. But there is the problem that sometimes your apostrophes are meant to be m4 quotes. stx2any takes this into account by applying the w_apo rule only to those apostrophes that do not have a matching backquote (i.e. m4 opening quote). This, in turn, means that if you need an unmatched apostrophe within quotes, you have no option but to write w_apo there yourself.
A whole another problem is the lone open quote, for which there is no way of writing without changing m4 quoting rules. If there is an unmatched backquote in the source, stx2any reports this as an error. The macro w_bq temporarily changes m4 quotes and puts a literal backquote in the output. So if you need a backquote (`) in the output, write w_bq (or `'w_bq`' if there are adjacent words) instead. And thank god[3] that you don't need backquotes all that often.
[3] or Gaea, destiny, what have
you
To enable easy mixing of direct output format code and stx2any markup, stx2any by default does not perform any quoting whatsoever for constructs in the output language. There is a command line option, --quote, which will quote all characters that are somehow magical in the output format so that they will appear literally in the output.
The magical constructs are, by output format:
The --quote option works by converting these special characters [4] into macro calls, which eventually get converted back to the literal representation of that character in the requested output format. Often this is just the character itself, if it happens not to be magical in that output format.
[4] except underscores and dollar signs, which are quoted by the separate
option --quote-me-harder.
If you decide not to use automatic output format quoting, you can call these macros yourself every time you need some character that might be magical. The macros are:
--quote-me-harder is a separate option because underscores and dollar signs are especially problematic. An underscore is a valid character in a macro name, and blindly quoting underscores will break your markup seriously. At the moment, w_ macro calls are protected against underscore quoting. Dollar signs are also sometimes used in macro definitions, and quoting them will break the macro definition.
As every creator has high hopes for his thought-child, I, too, would like to see Stx taken into widespread use and implemented many times.[5] There is, however, the problem that because stx2any allows (in fact, encourages) extending the vocabulary with your own m4 definitions, correctly reimplementing Stx would require you to build a m4 interpreter in the process, and if you did that, there would seem to be little point to reimplement Stx.[6]
[5] The chances of this actually happening are quite small, because
there are many competing formats out there, and everybody seems to have
own personal preferences about what the syntax of structured text should
be like.
[6] A similar situation
applies for LaTeX, whose proper reimplementation will require
reimplementing at least part of TeX, to allow for user-defined commands,
environments and the like.
Because of this, I suggest compatibility levels, which describe the
degree to which a particular implementation supports Stx. They're meant
to make a progression from more important things to less important ones.
I would deem implementation on the first level (abbrev level
) to be
quite sufficient for, for example, wiki markup, and the second level
(markup level
) sufficient for most purposes. On the fourth level, the
syntax supported is mostly equivalent to that of stx2any.
Support for Link abbreviations is orthogonal to these compatibility levels and regarded as an optional extension to them.
This level has support for abbreviation-based markup: paragraphs, different kinds of emphasis, headings, different kinds of lists, preformatted blocks, hard linebreaks, section breaks, and metadata headers (but support for footnotes and special characters such as long dashes, ellipses or copyright signs is not required).
Emphasis constructs should only be recognised when there is an opening and closing emphasis mark. Emphasis should not be allowed to span paragraph boundaries. An emphasis marker (asterisk, slash, double-apostrophe, etc) is recognised as an opening mark when preceded by a left separator and followed by a non-blank character; and as a closing mark when preceded by a non-blank character and followed by a right separator.[7] Emphasis must not be empty but can be only one character long.
[7] Separators include blanks, dashes, apostrophes and
quotation marks, in addition to which different kinds of opening
parentheses are left separators, and punctuation marks and
different kinds of closing parentheses are right separators.
This level has support for (almost) all non-extension-oriented
markup: all the contructs on abbrev level, plus footnotes,
everything in the sections environments
and macro-based
markup
except w_crosslink, w_index and
w_indexword. Support for m4 quoting is required,
though only one level (that is, no need to implement nested
quotes), as well as w_apo, w_bq and the
rest of special characters described in the section output
format quoting
.
When (part of) something is m4 quoted, it should not be considered for macro expansion or other kinds of processing.
This level is meant to support users using their own extensions,
as long as they don't do anything complicated. All the
constructs on markup level are supported, plus proper m4
(nestable) quoting and everything in the section extension
markup
. In short, everything described in this document, with
the exception of w_crosslink, w_index,
w_indexword and some esoteric subtleties of
abbreviation quoting should be supported.
Implementing w_define_env, define and friends will require at least some kind of macro processing capability. On this level, you don't have to implement arguments to macros; that's on the next level.
All m4 constructs not already mentioned should be supported, in addition to the stuff in extension level. This includes a lot of stuff, and means you ended up reimplementing m4 after all.