/usr/share/doc/stx2any/stx2any.html is in stx2any 1.56-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>stx2any</title>
<meta name="author" content="Panu A. Kalliokoski">
<meta name="generator" content="stx2any">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>
<body>
<h1>stx2any</h1>
<em>converter from structured text to multiple formats</em><br>
<h2>SYNOPSIS</h2>
<p><tt>stx2any</tt> [ -T <var>format</var> ] [ <var>stx and m4 options</var> ] [ <var>file</var> <var>file</var> … ]
<h2>DESCRIPTION</h2>
<p><tt>stx2any</tt> converts files in structured text (Stx) format into other
formats. Formats currently implemented are HTML, man, raw text,
PostScript, LaTeX, XHTML and DocBook XML.
<p>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 <em>Stx quickie guide</em>, which is
available in the <tt>examples</tt> directory.
<p>Most of the conversion happens in <tt>m4</tt>, and you can define your own
macros and other stuff for giving structure to your documents.
<tt>stx2any</tt> provides a LaTeX-like extensible environment system and a
diversion system for rearranging input. (Tårta på tårta, as they say in
Swedish.)
<p>Because <tt>stx2any</tt> 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.
<p>Some formatting is not available as abbreviations, but by calling m4
macros. You need macros relatively rarely: for example, floats
(material that can <q>float</q> around in the document) are created by
macros.
<h2>OPTIONS</h2>
<p><tt>stx2any</tt> accepts all command line options of <tt>m4</tt>, passing them
directly on. Of these, the <tt>-D</tt> argument is important enough to
mention here separately.
<dl><dt><tt>-DNAME=VALUE</tt></dt>
<dd>Define macro NAME to have the expansion VALUE. This allows you
to pass information into the document from the command line.
</dd><dt><tt>-T <var>format</var></tt></dt>
<dd>Sets the output format. Default format is <tt>html</tt>. <var>format</var>
should be one of:
<dl><dt>html</dt>
<dd>produces basic HTML (hypertext markup language) output.
</dd><dt>man</dt>
<dd>produces man macro output. This output is usable as a
man page directly (although see WRITING MAN PAGES below), or
can be fed to <tt>troff</tt> / <tt>groff</tt> for formatting to e.g.
postscript.
</dd><dt>latex</dt>
<dd>produces LaTeX document preparation language output.
You can run <tt>latex</tt> on the result to produce e.g. high
quality pdf's.
</dd><dt>text</dt>
<dd>produces raw text output by postprocessing HTML output
with <tt>w3m</tt>. The resulting output is very basic, like
stripping away most Stx markup; if you want more
formatted output, consider piping man output to <tt>nroff
-man</tt>.
</dd><dt>ps</dt>
<dd>produces simple postscript output by postprocessing man
output with <tt>groff</tt>. If you want to do real
publishing, consider the LaTeX format instead.
</dd><dt>xhtml</dt>
<dd>produces XHTML output by postprocessing HTML output with
W3C <tt>tidy</tt>. By the way, check
<a href="http://hixie.ch/advocacy/xhtml">http://hixie.ch/advocacy/xhtml</a> for discussion
about HTML and XHTML.
</dd><dt>docbook-xml</dt>
<dd>produces rudimentary DocBook XML output. See BUGS below
for more discussion about this.
</dd></dl></dd><dt><tt>--link-abbrevs</tt></dt>
<dd>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 <tt>stx2any</tt> as a middle part of a pipeline).
</dd><dt><tt>--quote</tt></dt>
<dd>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.
</dd><dt><tt>--quote-me-harder</tt></dt>
<dd>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.
</dd><dt><tt>--numbering { on | off }</tt></dt>
<dd>Request numbering of section headings. The default varies by
output format: section numbering is by default <tt>off</tt> for HTML,
DocBook XML and man, <tt>on</tt> for LaTeX.
</dd><dt><tt>--table-of-contents { on | off }</tt></dt>
<dd>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.
</dd><dt><tt>--make-title { on | off }</tt></dt>
<dd>Request a <q>title page</q>. The default is <q>on</q>. 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.
</dd><dt><tt>--no-template</tt></dt>
<dd>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
<tt>stx2any</tt> rather than combine the results afterwards.
</dd><dt><tt>--symmetric-crossrefs</tt></dt>
<dd>In document formats that support linking (HTML, DocBook),
produce reverse links from labels to referrers as well as links
from referrers to labels.
</dd><dt><tt>--latex-params <var>params</var></tt></dt>
<dd>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 <tt>a4paper,notitlepage</tt>. (See
<q>ENVIRONMENT</q> below.)
</dd><dt><tt>--html-params <var>params</var></tt></dt>
<dd>Set the body tag parameters for HTML documents. The default is
no parameters.
</dd><dt><tt>--picture-suffix <var>suffix</var></tt></dt>
<dd>Inline images will refer to files with suffix <var>suffix</var>. The
default is <tt>png</tt> for HTML and DocBook, <tt>eps</tt> for LaTeX and
man.
</dd><dt><tt>--no-emdash-separate</tt></dt>
<dd>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.
</dd><dt><tt>--more-secure</tt></dt>
<dd>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.
<p>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).
</dd><dt><tt>--sed-preprocessor <var>scriptname</var></tt></dt>
<dd>Run the sed script <var>scriptname</var> for all input. This allows you
to add custom abbreviation markups. It is almost the same as
preprocessing input with <tt>sed</tt>, then piping it into
<tt>stx2any</tt>, but interacts better with <tt>--link-abbrevs</tt> (see
its explanation for details).
</dd><dt><tt>--version</tt>, <tt>-V</tt></dt>
<dd>Just show version information and exit.
</dd><dt><tt>--help</tt>, <tt>-?</tt></dt>
<dd>Just show a short help message and exit.
</dd></dl><h2>WRITING MAN PAGES</h2>
<p>Basically, man pages are simply files in the man macro format. However,
there are some programs (first and foremost <tt>mandb</tt>) 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 <tt>man</tt> (1)
and <tt>lexgrog</tt> (1) for details).
<p>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 <tt>mandb</tt> parsing, you
should start the page with one or more calls to w_man_desc. This will
create a proper <q>NAME</q> section for you. (Although you could write one
by yourself.)
<h2>DIAGNOSTICS</h2>
<p><tt>stx2any</tt> may give any error message that <tt>m4</tt> may give, e.g. on
malformatted input (a macro call with missing closing parenthesis etc).
In addition, it has the following own error messages:
<dl><dt>unknown output format: <q>X</q></dt>
<dd>You requested unsupported output format <var>X</var> with the <tt>-T</tt>
option.
</dd><dt>unknown macro <q>X</q> called</dt>
<dd><tt>stx2any</tt> encountered a macro beginning with <tt>w_</tt>, but knows
no definition for it. This is a warning, not an error — the
offending macro and its arguments are stripped from the output.
</dd><dt>environment <q>X</q> closed by <q>Y</q> in layer N</dt>
<dd>Environments in <tt>stx2any</tt> must be properly nested.
<tt>stx2any</tt> encountered w_end(<var>Y</var>) when it was expecting
w_end(<var>X</var>). Often this is a sign of a forgotten w_end(<var>X</var>).
<p>If <var>N</var> (the layer) is something other than 0, then the problem
is probably in your environment definitions, not at the point
that <tt>stx2any</tt> was processing when it encountered the error.
</dd><dt>unknown environment <q>X</q></dt>
<dd>There was an attempt to begin an environment whose name is
unknown to <tt>stx2any</tt>, i.e. no such environment has been
defined.
</dd><dt>diversion <q>X</q> closed by <q>Y</q></dt>
<dt>unknown diversion <q>X</q></dt>
<dd>Same as above, but for diversions (w_begdiv and w_enddiv).
</dd><dt>attempt to use <q>X</q> in secure environment</dt>
<dd>You requested secure processing with <tt>--more-secure</tt> and the
document contained an <q>insecure</q> macro. This is a warning
message, not an error — the causing macro is left in the text
verbatim.
</dd><dt>unknown cross link to <q>X</q></dt>
<dd>There was a cross link to document <var>X</var>, but <tt>stx2any</tt> does not
know about such a document. Probably you didn't gather /X/'s
data with <tt>gather_stx_titles</tt> 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.
</dd></dl><p>The return value of <tt>stx2any</tt> is zero on success, one if there was
some problem.
<h2>ENVIRONMENT</h2>
<dl><dt>PAPERCONF</dt>
<dt>PAPERSIZE</dt>
<dd>used for determining the default paper size for LaTeX documents.
</dd></dl><h2>FILES</h2>
<dl><dt><tt>/etc/papersize</tt></dt>
<dd>used for determining the default paper size for LaTeX documents.
</dd><dt><tt>PREFIX/share/stx2any/common</tt></dt>
<dd>directory for the definitions shared by all formats
</dd><dt><tt>PREFIX/share/stx2any/{html,man,latex,docbook-xml}</tt></dt>
<dd>directory for output format specific definitions
</dd></dl><h2>SEE ALSO</h2>
<p><tt>m4</tt> (1), <tt>latex</tt> (1), <tt>groff</tt> (1), <tt>lexgrog</tt> (1), <tt>w3m</tt> (1),
<tt>strip_stx</tt> (1), <tt>gather_stx_titles</tt> (1), <tt>html2stx</tt> (1),
<tt>extract_usage_from_stx</tt> (1) <br>
<em>Stx quickie guide</em> (<tt>PREFIX/share/doc/stx2any/Stx-doc.txt</tt>) <br>
<em>Stx markup reference</em> (<tt>PREFIX/share/doc/stx2any/Stx-ref.txt</tt>)
<h2>BUGS</h2>
<p>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 <tt>stx2any</tt> is authoritative,
so it <var>cannot</var> have bugs :)
<p>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.
<p>The <tt>--more-secure</tt> switch is not really very secure for reasons
explained above.
<p>The support for DocBook XML sucks. It is only included because someone
will show up anyway and ask, <q>hey, does it support <strong>DocBook XML</strong>?</q>
Partly this sucking is due to my laziness, but partly it is because of
the nature of DocBook. For instance, <tt>stx2any</tt> will transform literal
formatting into DocBook Literal elements, but the <em>point</em> 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).
<p>The only sensible reasons I can think of for using Stx as a DocBook
frontend are:
<ol><li>the ability to use both DocBook constructs and Stx abbreviations
<li>if you have to write DocBook for some interesting reason (your boss
told you so) but don't want to learn it
<li>you happen to already have infrastructure for processing DocBook
documents, and you want to take advantage of it
</ol><h2>AUTHOR</h2>
<p>This page is written by Panu A. Kalliokoski.
</body>
</html>
|