<!-- -*-Indented-text-*- -->
<!doctype document public "-//JFW//DTD Document//EN"[
<!ENTITY % remark "ignore" >
<!ENTITY % LaTeX "IGNORE" >
<![ %LaTeX [ <!ENTITY LaTeX SDATA "\LaTeX" >]]>
<!ENTITY LaTeX "LaTeX" >
<!ENTITY % f.text system "common.ent" > %f.text;
]>

<document
author="Jrg Wittenberger"
inst="TU Dresden"
date="5. 5. 1995"
face="2s 2c"
>Target formats of typeset

<index id=formating>

Typeset supports various "target formats" i.e., backends. All these
formats have some special properties, are supported to different
extent and are partially customizable. Here details are discussed.

<sect id="Target PS">PostScript
<index id=target sub=PostScript>

The PostScript output is generated by a special PostScript formatter.
Typeset generates only the input for this formatter and invokes it for
the PostScript output.

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 <ref id="Target Lout"/Lout section/. I
must also admit that &LaTeX; output looks a little better, but that is
a matter of taste. See <ref id="Target LaTeX"/&LaTeX; section/ how to
use its output.

<sect id="Target ASCII">ASCII
<index id=target sub=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 <ref id="Target Lout"/Lout section/ for discussion.

<sect id="Target Lout">Lout
<index id=target sub=Lout>

Lout is the default PostScript backend of typeset.

Even if not described in the standard values for the <code/-O/ Option
also <code/lout/ is a valid parameter to the <code/-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 <code/brief/ <index id=brief
sub=formating> it's the only target defined. See <ref 
id="Lout problems"// about the manpage document type.

<sect1 id="Lout face">The <code/face/ attribute
<index id=face sub=Lout>

The face attribute is a string of tokens delimited by spaces.

The following values of the <code/face/ attribute are recognized:

<desc

<dt/1S 2S/These change between one side and double side printing.

<dt/1C 2C/These switch between one column and two column for the main
text. Some text chunks are one column in any case (e.g.,the table of
contents, abstract, intro, preface) index text is two column in any
case.

<dt/nidx/This suppresses the generation of an index even though 
<code/&lt;index>/ tags are used in the document.

</desc>

By default simple documents use <code/face="1S 1C nidx"/, report use 
<code/face="1S 2C"/ and books <code/face="2S 1C"/.

<sect1 id="Lout notations">Notations with Lout

<index id=notations sub=Lout
<index id="temporary files" sub=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 <code/fig/ for figures drawn with 
<code/xfig/).

Notations which are converted into Encapsulated PostScript can't
really determine if the <code/.eps/ file is no longer necessary.
Therefore it is not deleted by typeset.

<note> It is always a good idea to move to an empty directory to
invoke typeset and supply the full file name to the source. This way
you will end up with your document and you can see with ease which
files are no longer needed.
</note>

<sect1 id="Lout problems">Problems
<index id=Lout sub=problems>

But the old Lout had also its drawbacks. Unfortunately typeset reveals
bugs and after all misfeatures all the time. Those keep me for
instance from a better table implementation.

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 &lt;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.

<sect1 id="Lout customization">Customization
<index id=customization
<index id=Lout sub=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 <code/layout.scm/ in the <code/include/ 
directory of the installation. The following options are customizable:


<desc

<dt/page size/Only the named page types of Lout are supported. These
are: Letter, Tabloid Ledger, Legal, Statment, Executive, A3, A4, A5,
B4, B5, Folio, Quarto and 10x14. Change the definition of
<code/lout-pagetype/ to the size you want.

<dt/page margins/The left and right margins of the document are set
from typeset due to the request of single or double page printing.

For single page printing both margins are set to the same value 
<code/lout-both-margin/, for double page printing the left side of odd
and the right side of even pages are the same <code/lout-inner-margin/ 
and the other are set to <code/lout-outer-margin/.

<dt/initial break/The initial break used by typeset is also open to
customization. But it's very unlikely that someone need to change it.

</desc>

Future versions will open the formating of paragraphs to customization.

<sect id="Target LaTeX">&LaTeX;
<index id=target sub=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
<code/bibtex/ or <code/makeindex/. Eventually you might adjust the
substyles used. See <ref id="LaTeX customization"/the customization
section/ how to prevent this.

<sect1 id="LaTeX face">The <code/face/ attribute
<index id=face sub=LaTeX>

The same values as for Lout are supported see <ref id="Lout face"// 
for description.

<sect1 id="LaTeX notations">Notations with &LaTeX;
<index id="temporary files" sub="LaTeX">

The following notations are supported with &LaTeX;:

<desc

<dt/eps/ encapsulated postscript. Note: a temporary eps file is copied into
the current directory and left there
<dt/fig/ xfig drawn pictures
<dt/latex/ Code unconditional passed to the backend
<dt/lout/ plain <code/lout/ code
<dt/lfig/ lout code using the @Fig package of Lout
<dt/roff/ roff code which will be converted into eps by <code/groff/.
<dt/tgif/ tgif drawn pictures

</desc>

<note>
As for some other target formats it is a good idea to format the
document in a empty directory allowing you to delete files left over
with ease.
</note>

<sect1 id="LaTeX problem">Problems
<index id=LaTeX sub=problems>

&LaTeX; is huge and most installations differ. The package aims to run
at most plain installations. Only the inclusion of EPS figures depends
on either the substyle <code/epsfig/ or the <code/graphics/package.

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 &lt; and > yield strange results in some
environments they are set using <code/{\tt >}/ respectively <code/{\tt
>}/ except within <code/&lt;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 &lt;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 &lt;verb> elements.

<sect1 id="LaTeX customization">Customization
<index id=Customization
<index id=LaTeX sub=customization>

To customize the &LaTeX; output you need to change the file 
<code>include/layout.scm</code>. The following variables are
available:

<desc

<dt/latex-latex-type/ Switch between &LaTeX; 2.09 or LaTeX2e style.

<dt/latex-styleoptions/ This is a list of strings. By default only 
<code/"epsfig"/ is included. For &LaTeX; 2.09 this seems to be a good
choice, for LaTeX2E it's probably the empty list.

<dt/latex-packages/ A list of packages to be included by 
<code/\usepackage/ into the &LaTeX; source. By default only 
<code/[dvips]{graphics}/ is in this list.

<dt/latex-preamble/ This is a list of strings which are put into the
preamble of the document just before the <code/\begin{document}/. By
default <code/latex-a4-preamble/ is included into this list.

</desc>

For German documents the substyle <code/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
<code>target/latex/preparse.scm</code>. If you do please drop me a note so
I can include the support.

<sect id="Target HTML">HTML
<index id=target sub=HTML>

<sect1 id="HTML face">The <code/face/ attribute
<index id=face sub=HTML>

Only one token is used from the face attribute: <code/nidx/. If it is
present the generation of an index is suppressed.

<sect1 id="HTML splitting">Splitting
<index id=book sub=formating>

Except for the book document type one document becomes one HTML file
(defined by the <code/-o/ option to typeset). For the document type 
<code/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 <code/-o/ option is extended by <code/-/<var/number/. E.g.,
given a command line of:

<verb>
typeset -O html -o doc doc.sgml
</verb>

And assumed the file doc.sgml contains three chapters, you will end up
with (at least) 6 files named <code/doc.html, doc-1.html, doc-2.html
... doc-6.html/. These contain the top level stuff in <code/doc.html/,
the single chapters -- one per file -- and also the index and
references get their own file.

<note>
If entities of other notations are used (e.g., figures) you will get
some more files following the same naming scheme (with different
extensions -- most likely ".gif"). Refer to <ref id="HTML notations"//.
</note>

<sect1 id="HTML notations">Notations with HTML
<index id=notations sub=HTML
<index id="temporary files" sub=HTML>

For the HTML target, notations are best converted into GIF files. To
do this conversion typeset will by default invoke ghostscript and the
pbm-tools for Encapsulated PostScript. The files are named after one
of two schemes. For external entities which already have a filename,
the basename of it is used (with extension ".gif"). If the notation is
used inline, a new "subfile" is created with the basename of the
target file (given to the <code/-o/ option) appended with a dash and a
running number. The extension is also ".gif". See <ref 
id="HTML splitting"/the splitting section/ for details.

<sect1 id="HTML problems">Problem

Because of the possible splitting the filenames of the file(s)
produced are compiled into the output. Therefor you can't rename them
after compilation anymore. You need to be aware of this and give a
filename <em/without/ any leading directory component to the <code/-o/.
option.

<sect1 id="HTML customization">Customization
<index id=customization
<index id=HTML sub=customization>

There is not too much to be customized for the HTML target. Only for
manpages: the file <code/manpage.scm/ in the <code/include/ directory
is to be changed. The procedure <code/html-make-man-ref/ receives a
string (the id given to a <code>&lt;ref t=m
id=<var/string/<code>//</code>  tag) and has to return a list of
string. The concatenation of these strings must form valid HTML code
(either a URL to some server providing man pages or text to be
included in the document.

<sect id="Target Info">Info
<index id=target sub=info>

Only the document types <code/document, report/ and <code/book/ have a
representation in the info format. Due to the limitation to plain text
some, tags like character formating are ignored.

The <code/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.

<index id=book sub=formating>
<!--
As for the HTML format, books are split at the chapter boundaries into
single files. The naming scheme for these files is the same as for the
<ref id="HTML splitting"/splitting for HTML/ except that no extension
is added to the filenames.
-->

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.

<!-- removed at the moment

As for HTML the file names based upon the name given to the <code/-o/ 
option are compiled into the resulting files. For the final document
which is supposed to be moved into the info path of a system you don't
want to give a name with a leading directory component to this option.
At the other hand you can have an advantage: if you store an info file
somewhere outside of the info path searched by emacs and open it via 
<code/C-u C-h i/ emacs will fail to find the subcomponents. If you
compile with a leading directory component emacs fill find it.

E.g.,
<verb>
typeset -O info -o ./test.info mydoc.sgml
</verb>

Will produce info files with the leading path <code>./</code> 
component in them.

-->

<sect id="Target man">man
<index id=target sub=man>

For the manpage target only the document type <code/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 <code/nroff/ command of your
system.

Only the notation <code/roff/ is supported with this target.

Customization

The file <code/manpage.scm/ in the <code/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.

<sect id="Target literate">Literate Programming
<index id="Target" sub="literate">

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.

<sect id="Target RTF">RTF
<index id=target sub=RTF>

The RTF target is the least supported one. Only the document types 
<code/document/ and <code/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.

<sect id="Target slide">Slide
<index id=target sub=slide>

The slide target works similar to the literate target. Only the parts
of the source enclosed by the <code/&lt;slide>/ tag are
extracted. These are formatted using the lout backend with it's
overhead transparencies support.