Ubuntu Manpage: stx2any - converter from structured text to multiple formats

NAME

       stx2any - converter from structured text to multiple formats

SYNOPSIS

       stx2any [ -T format ] [ stx and m4 options ] [ file  file ... ]

DESCRIPTION

stx2any converts files in structured text (Stx) format into other formats. Formats
currently implemented are HTML, man, raw text, PostScript, LaTeX, XHTML and DocBook XML.

The source format, structured text, is a kind of plain text format with standard markup
for representing headings, lists, emphasis etc. The markup is both quicker to write and
easier to remember than conventional tag-based markup languages, and is beautifully
legible also in source form. Stx markup is better explained in Stx quickie guide, which
is available in the examples directory.

Most of the conversion happens in m4, and you can define your own macros and other stuff
for giving structure to your documents. stx2any provides a LaTeX-like extensible
environment system and a diversion system for rearranging input. (Tårta på tårta, as they
say in Swedish.)

Because stx2any doesn't perform any kind of quoting on the input, markup that isn't
available can be written directly in the destination language (losing convertibility to
multiple languages). This way, if you are only interested in one output format (eg.
LaTeX), you can use Stx as an abbreviation format for the most common constructs.

Some formatting is not available as abbreviations, but by calling m4 macros. You need
macros relatively rarely: for example, floats (material that can “float” around in the
document) are created by macros.

OPTIONS

stx2any accepts all command line options of m4, passing them directly on. Of these, the
-D argument is important enough to mention here separately.

-DNAME=VALUE
Define macro NAME to have the expansion VALUE. This allows you to pass
information into the document from the command line.

-T format
Sets the output format. Default format is html. format should be one of:

html produces basic HTML (hypertext markup language) output.

man produces man macro output. This output is usable as a man page directly
(although see WRITING MAN PAGES below), or can be fed to troff / groff for
formatting to e.g. postscript.

latex produces LaTeX document preparation language output. You can run latex on
the result to produce e.g. high quality pdf's.

text produces raw text output by postprocessing HTML output with w3m. The
resulting output is very basic, like stripping away most Stx markup; if you
want more formatted output, consider piping man output to nroff -man.

ps produces simple postscript output by postprocessing man output with groff.
If you want to do real publishing, consider the LaTeX format instead.

xhtml produces XHTML output by postprocessing HTML output with W3C tidy. By the
way, check http://hixie.ch/advocacy/xhtml for discussion about HTML and
XHTML.

docbook-xml
produces rudimentary DocBook XML output. See BUGS below for more discussion
about this.

--link-abbrevs
Take link abbreviation syntax into use. Note that because link abbreviation
processing occurs in two phases, it doesn't work totally when the input comes
from standard input (for example, if you use stx2any as a middle part of a
pipeline).

--quote
Request quoting of characters (other than underscores and dollar signs) that are
somehow magical in the requested output format. This will make it quite
difficult to put markup in the output format directly in your document, but will
greatly increase the possibility that your document will be correct (ie. does
not have syntax errors) in the output format.

--quote-me-harder
Request quoting of underscores and dollar signs. This might make some LaTeX
documents work but might break some documents where underscores are used in
macro names or dollar signs in macro definitions.

--numbering { on | off }
Request numbering of section headings. The default varies by output format:
section numbering is by default off for HTML, DocBook XML and man, on for LaTeX.

--table-of-contents { on | off }
Request producing a table of contents from the headings. The default is to
produce a TOC when numbering is on. Not implemented for DocBook XML.

--make-title { on | off }
Request a “title page”. The default is “on”. This setting does not have any
effect in some formats. In HTML, it produces a big heading at the beginning of
the document. In LaTeX, it produces the canonical maketitle.

--no-template
Do not produce a document template at all, only the formatted input text. You
probably need this if your document will be included as a part of a bigger
document. If that bigger document is written totally in Stx, however, it will
be cleaner to give all the source files directly as arguments to stx2any rather
than combine the results afterwards.

--symmetric-crossrefs
In document formats that support linking (HTML, DocBook), produce reverse links
from labels to referrers as well as links from referrers to labels.

--latex-params params
Set the document class parameters for LaTeX documents. The default is affected
by system paper size; for example, on a European system it is typically
a4paper,notitlepage. (See “ENVIRONMENT” below.)

--html-params params
Set the body tag parameters for HTML documents. The default is no parameters.

--picture-suffix suffix
Inline images will refer to files with suffix suffix. The default is png for
HTML and DocBook, eps for LaTeX and man.

--no-emdash-separate
In the output, don't separate em dashes from adjacent text with spaces. This is
in accordance to traditional English typography (if I understand correctly), but
is not standard in many other languages — including Finnish, my mother tongue.

--more-secure
Disable some insecure features of m4 and check some command line arguments that
are passed to shell for problematic characters. This might be desirable if
you've received the document from somewhere else and want to make sure it won't
do anything malicious when converted. Currently this denies execution of shell
escapes.

Note that clearly no implementation of m4 has been designed with security in
mind. As a consequence, this option cannot prevent every potentially harmful
thing. Things not prevented which I'm aware of are including contents of
arbitrary files in the output and writing busy loops (so that the conversion
will use all processor time it can get, until terminated).

--sed-preprocessor scriptname
Run the sed script scriptname for all input. This allows you to add custom
abbreviation markups. It is almost the same as preprocessing input with sed,
then piping it into stx2any, but interacts better with --link-abbrevs (see its
explanation for details).

--version, -V
Just show version information and exit.

--help, -?
Just show a short help message and exit.

WRITING MAN PAGES

       Basically,  man  pages  are simply files in the man macro format.  However, there are some
       programs (first and foremost mandb) that require parts of man pages to be  in  a  specific
       format, and man pages should generally adhere to the standard sectioning and form (see man
       (1) and lexgrog (1) for details).

       When  writing  a  man  page,  the  title   (w_title)   of   the   page   should   be   the
       program/file/format/utility  name, and you should define the section (w_section).  To make
       the page suitable for mandb parsing, you should start the page with one or more  calls  to
       w_man_desc.   This will create a proper “NAME” section for you.  (Although you could write
       one by yourself.)

DIAGNOSTICS

stx2any may give any error message that m4 may give, e.g. on malformatted input (a macro
call with missing closing parenthesis etc). In addition, it has the following own error
messages:

unknown output format: “X”
You requested unsupported output format X with the -T option.

unknown macro “X” called
stx2any encountered a macro beginning with w_, but knows no definition for it.
This is a warning, not an error — the offending macro and its arguments are
stripped from the output.

environment “X” closed by “Y” in layer N
Environments in stx2any must be properly nested. stx2any encountered w_end(Y)
when it was expecting w_end(X). Often this is a sign of a forgotten w_end(X).

If N (the layer) is something other than 0, then the problem is probably in your
environment definitions, not at the point that stx2any was processing when it
encountered the error.

unknown environment “X”
There was an attempt to begin an environment whose name is unknown to stx2any,
i.e. no such environment has been defined.

diversion “X” closed by “Y”

unknown diversion “X”
Same as above, but for diversions (w_begdiv and w_enddiv).

attempt to use “X” in secure environment
You requested secure processing with --more-secure and the document contained an
“insecure” macro. This is a warning message, not an error — the causing macro
is left in the text verbatim.

unknown cross link to “X”
There was a cross link to document X, but stx2any does not know about such a
document. Probably you didn't gather /X/'s data with gather_stx_titles or you
misspelled the document reference. This is a warning, not an error — the
reference is left in the output verbatim, without any kind of link.

The return value of stx2any is zero on success, one if there was some problem.

ENVIRONMENT

          PAPERCONF

          PAPERSIZE
                 used for determining the default paper size for LaTeX documents.

FILES

          /etc/papersize
                 used for determining the default paper size for LaTeX documents.

          /usr/share/stx2any/common
                 directory for the definitions shared by all formats

          /usr/share/stx2any/{html,man,latex,docbook-xml}
                 directory for output format specific definitions

BUGS

The structured text format is not yet fully standardised. There are some corner cases
where it is unclear what the result of the formatting should be. In these cases, the
output of stx2any is authoritative, so it cannot have bugs :)

Some old GNU libc's seem to be abysmally slow on some instances of the emphasis regexps.
It would be possible to make the regexps faster and less correct, but as newer GNU libc's
and BSD libc seem to work OK in these cases, I guess it's not worth it.

The --more-secure switch is not really very secure for reasons explained above.

The support for DocBook XML sucks. It is only included because someone will show up
anyway and ask, “hey, does it support DocBook XML?” Partly this sucking is due to my
laziness, but partly it is because of the nature of DocBook. For instance, stx2any will
transform literal formatting into DocBook Literal elements, but the point of using DocBook
is to convey more information than that — whether it is some ComputerOutput, UserInput,
EnVar, or Application, or... and the result is still very abstract, not actually meant for
humans to read but rather for computers to process into something readable. Now the truth
is that I doubt you will ever come up with a DSSSL stylesheet whose output outperforms
LaTeX (for publishing on paper) or direct conversion to HTML (for publishing on the web).

The only sensible reasons I can think of for using Stx as a DocBook frontend are:

1. the ability to use both DocBook constructs and Stx abbreviations

2. if you have to write DocBook for some interesting reason (your boss told you so)
but don't want to learn it

3. you happen to already have infrastructure for processing DocBook documents, and
you want to take advantage of it

AUTHOR

       This page is written by Panu A. Kalliokoski.