There is support to choose the backend formatter in principle, but currently only Lout and LaTeX is supported. Future versions will at least support LaTeX + dvips.
Why is Lout the default? Just because it's the one simple enough that
I learned a bit how to program it. And it supports most of the
features someone needs to produce neat documents. Unfortunately it has
some drawbacks discussed in the Lout section (3.3). I
must also admit that LaTeX output looks a little better, but that is
a matter of taste. See LaTeX section (3.4) how to
use its output.
3.2 ASCII
For the ASCII target applies the same as for PostScript. The default
formatter is also Lout. Maybe some day there will be support for roff.
See Lout section (3.3) for discussion.
3.3 Lout
Lout is the default PostScript backend of typeset.
Even if not described in the standard values for the -O Option also lout is a valid parameter to the -O option. It's not described among the standard values because it's not considered to be a final target.
The most important features of Lout are it's easy to learn programming language, it's capability to denote equations, pictures, graphs and even ``special effects'' (like rotated text) without much hassle and the fact that it's relatively small on the disk.
All the document types which come with typeset have a representation
in the Lout target. For the brief it's the only target defined. See (3.3.3) about the manpage document type.
3.3.1 The face attribute
The face attribute is a string of tokens delimited by spaces.
The following values of the face attribute are recognized:
By default simple documents use face=``1S 1C nidx'', report use
face=``1S 2C'' and books face=``2S 1C''.
3.3.2 Notations with Lout
For all notations suitable to be used in conjunction with the Lout
target there must be a way to convert the code either into Lout code
or into Encapsulated PostScript.
Typeset as it comes has these conversion defined for a couple of notations (e.g., notation fig for figures drawn with xfig).
Notations which are converted into Encapsulated PostScript can't really determine if the .eps file is no longer necessary. Therefore it is not deleted by typeset.
The old version of Lout were unable to break indented chunks of text over columns and pages. This is solved by the new release, but typeset revealed a bug in that code. Thus there is a chance left to get bitten by this bug. If it appears, long junks will not be broken. Moreover the spacing between the paragraphs behaves very funny in this case. It is likely to happen only when you have nested <desc> elements and more than one paragraph in the inner description list. If this appears to you please send me a test file.
An finally there is the problem with Lout, that it may fail sometimes
to resolve cross references on heavy loaded machines or if disk space
is ``tight''. (Where tight could be a couple of Megabytes.) This should
be circumvented now because most cross referencing is done without the
lout (only page references are left to lout). But I can't test it.
3.3.4 Customization
Lout has its own way for extensive customization. This includes all
sort of things like hyphenation exceptions, definitions of new
symbols, page background and so on. This is not the place to discuss
them. See the documentation of Lout for details.
Typeset supports the widely necessary customizations. To change these options go to the file layout.scm in the include directory of the installation. The following options are customizable:
For single page printing both margins are set to the same value lout-both-margin, for double page printing the left side of odd and the right side of even pages are the same lout-inner-margin and the other are set to lout-outer-margin.
Future versions will open the formating of paragraphs to customization.
3.4 LaTeX
You can produce LaTeX files from typeset. To produce DVI file you need
to run LaTeX on the result by hand. For PostScript output through
LaTeX you also need to run dvips.
Currently only the DTD's book, report and document are supported for LaTeX.
The file is usually ready to be feed to LaTeX. There is no need for
bibtex or makeindex. Eventually you might adjust the
substyles used. See the customization
section (3.4.4) how to prevent this.
3.4.1 The face attribute
The same values as for Lout are supported see (3.3.1)
for description.
3.4.2 Notations with LaTeX
The following notations are supported with LaTeX:
Which one is used has to be defined in the installation process.
Also to be defined in the installation process is whether LaTeX version 2.09 or LaTeX2e code is generated.
Typeset aims to be a ``don't worry application'' for the author. Regarding LaTeX this implies that some characters are set in a save way regardless whether or not this is necessary in a certain case. E.g., because the characters < and > yield strange results in some environments they are set using {\tt >} respectively {\tt >} except within <math> elements.
Also LaTeX offers an extensive set of symbols to write math formulas. Unfortunately it is quite hard to generate them proper for what typeset already offers. So better use sdc's way only for simple formulas and <inline latex> for complicated formulas which are written in native LaTeX notation then.
I've also got a report about a version which discard the
leading (or all?) blanks in <verb> elements.
3.4.4 Customization
To customize the LaTeX output you need to change the file
include/layout.scm. The following variables are
available:
For German documents the substyle german will be included into
the list of substyles. For further customization (e.g., other
languages) you'll need to go into the code of
target/latex/preparse.scm. If you do please drop me a note so
I can include the support.
3.5 HTML
3.5.1 The face attribute
Only one token is used from the face attribute: nidx. If it is
present the generation of an index is suppressed.
3.5.2 Splitting
Except for the book document type one document becomes one HTML file
(defined by the -o option to typeset). For the document type
book the document is split at the chapter boundaries into
single files. For the names of these files the base name of name given
to the -o option is extended by -number. E.g.,
given a command line of:
typeset -O html -o doc doc.sgml
And assumed the file doc.sgml contains three chapters, you will end up with (at least) 6 files named doc.html, doc-1.html, doc-2.html ... doc-6.html. These contain the top level stuff in doc.html, the single chapters -- one per file -- and also the index and references get their own file.
The face attribute is completely ignored.
For each division of text (i.e., the whole document/ report/ book, chapters, section and subsections) a node, is generated with a menu containing each division of the next level.
Other than the preceding version, the Info output is no longer spread into different files. Todays computers are usually powerful enough not to need this, and it would blow up the code too much.
Only notations which have a plain text representation can be used with
the info target.
3.7 man
For the manpage target only the document type manpage is really
supported. The intention of this target is not to print everything
from the man command but to produce pages suitable to be stored in the
online manual of Unix systems.
To produce a printed version of manpages you should use the manpage produced by typeset and feed it into the nroff command of your system.
Only the notation roff is supported with this target.
Customization
The file manpage.scm in the include hold a translation
table from the symbolic short name of the section into the numbers and
the long names. Some systems use a different order (numbering). Adapt
it to reflect your system.
3.8 Literate Programming
For literate programming the filenames written are part of the program
hence determined within the document. Only if no file name is given
for a part of literate program it's written to the standard output.
There is nothing to be customized for this target.
3.9 RTF
The RTF target is the least supported one. Only the document types
document and report are supported by now and even these
not to the full extend.
The RTF target is indented to open a way to use parts of a document with the widespread MS tools. Unfortunately it's pretty hard to support this format. Even page size and font information is stored in and to make it worse the ``reference application'' (guess which) treats it different than the definition published by Microsoft.
But for the restrictions word processors carry, RTF formated text is not
supposed to look as professional as others anyway.
3.10 Slide
The slide target works similar to the literate target. Only the parts
of the source enclosed by the <slide> tag are
extracted. These are formatted using the lout backend with it's
overhead transparencies support.