Stx document tools distribution

What is this?

This software distribution is a bunch of tools to deal with structured text (Stx). Stx is a kind of plain text format with semantic markup. Stx is documented in:

• Stx quickie guide
• Stx markup reference

Of some interest may be also Accreditions of ideas behind structured text.

There are a homepage (currently in the author's wiki), and a distribution page at http://sange.fi/~atehwa/ for this project. You can contact the author at mailto:atehwa@sange.fi.

Included tools

The following tools are included:

stx2any

This is the main tool, an utility to convert Stx into other formats.

strip_stx

A simple literal programming tool for document-programs written in Stx.

gather_stx_titles

A utility for generating cross references between documents written in Stx.

extract_usage_from_stx

A utility for producing Usage: messages and manual pages from the same source.

html2stx

Conversion tool from HTML to Stx. This makes it easy to import documents written in other formats into Stx. Besides, you can tidy an HTML document by converting it first into Stx, then back into (X)HTML.

stx-mode.el

An emacs mode for writing Stx documents. Provides syntax highlighting, paragraph filling, and simple interfaces to stx2any for those who cannot use the command line.

Installation

A traditional make && make install will do. You can override the make variable PREFIX to install somewhere else than /usr. Other variables you might want to override include EMACSDIR and MANDIR. Take a look at the ./Makefile.

The installation process of stx2any normally uses w3m to produce usage messages from Stx. If you don't want to install w3m, you can give make the option BUILD_USAGE_WITH=plain to avoid using w3m. The only consequence is that usage messages (the output of stx2any --help, for instance) will look cruder.

If you have a debian box, you can build a debian package directly by saying fakeroot debian/rules binary and installing the resulting package with dpkg -i.

Implementation documentation

Parsing phase:

• emphasis syntax
• preformatted block and inline element syntax
• block level element syntax
• link abbreviation syntax

Output format independent m4 definitions:

• stx2any — common m4 facilities
• stx2any — low-level and common markup facilities

Output format specific m4 definitions:

• stx2any — definitions for HTML
• stx2any — definitions for troff with man macros
• stx2any — definitions for LaTeX
• stx2any — definitions for DocBook XML