@c $Id: typesetting.texinfo,v 1.47 2002/01/09 17:01:30 m Exp m $
@node Typesetting, Fonts, Searching Text, Text
@comment  node-name,  next,  previous,  up
@chapter Typesetting and Word Processing
@cindex typesetting and word processing
@cindex word processing
@cindex Browne, Christopher B.
@pindex cat

@noindent
If you're coming to Linux with a Microsoft Windows or Apple MacOS
background, or from some other non-Unix computing environment, you are
likely used to one approach to ``word processing.'' In these
environments, most writing is done in word processors---large programs
that offer a vast array of formatting options and that store their
output in proprietary file formats. Most people use word processors no
matter where the intended output will go (even if it's just your diary).

Word processors, from complete suites like StarOffice to commercial
favorites like WordPerfect, are available for Linux---and have been for
years. However, the standard personal-computing paradigm known as ``word
processing'' has never really taken off on Linux---or, for that matter,
on Unix-like operating systems in general. With Linux, most writing is
done in a text editor, and files are kept in plain text.

When you keep a file in plain text, you can use command-line tools to
format the pages and paragraphs; add page numbers and headers; check the
spelling, style, and usage; count the lines, words, and characters it
contains; convert it to HTML and other formats; and even print the text
in a font of your choosing---all of which are described in the recipes
in this book. The text can be formatted, analyzed, cut, chopped, sliced,
diced, and otherwise processed by the vast array of Linux command-line
tools that work on text---over 750 in an average installation.

This approach may seem primitive at first---especially to those weaned
in a computing environment that dictates that all writing must be set in
a typeface from the moment of creation---but the word-processing
approach can be excessive compared to what Linux provides. You can, if
you like, view or print plain text in a font, with a single
command---which is what ninety percent of people want to do with a word
processor ninety percent of the time, anyway; to do this, see
@ref{Enscript, , Converting Plain Text for Output}.

It's my opinion that word processing is not a forward-thinking direction
for the handling of text, especially on Linux systems and especially now
that text is not always destined for printed output: text can end up on
a Web page, in an ``eBook,''@footnote{This is the term given to the
currently-fashionable hardware devices that allow for display and
reading of text. A book in plain text with or without formatting
commands is called an ``etext,'' but as more information is handled in
machine-readable form, the e- prefix will probably be dropped.} in an
email message, or possibly in print. The best common source for these
formats is plain text. Word processing programs, and the special file
formats they require, are anathema to the generalized, tools-based and
plain-text philosophy of Unix and Linux (@pxref{Tools Philosophy, , Unix
and the Tools Philosophy}). ``Word processing'' itself may be an
obsolete idea of the 1980s personal computing environment, and it may no
longer be a necessity in the age of the Web and email---mediums in which
plain text content is more native than proprietary word processor
formats.

If you do need to design a special layout for hardcopy, you can
@emph{typeset} the text. One could write a book on the subject of Linux
typesetting; unfortunately, no such book has yet been written, but this
chapter contains recipes for producing typeset text. They were selected
as being the easiest to prepare or most effective for their purpose.

@sp .25
@noindent
@strong{NOTE:} For more information on this subject, I recommend
Christopher B. Browne's excellent overview,
@uref{http://www.cbbrowne.com/info/wp.html, ``Word Processors for
Linux''}.

@menu
* Typesetting Overview::        Choosing the typesetting system to use.
* Enscript::                    Converting plain text to PostScript.
* LyX::                         LyX, a document processor.
* TeX::                         TeX and friends.
* SGML::                        SGML and markup language.
* Typesetting Systems::         Other typesetting systems.
@end menu


@node Typesetting Overview, Enscript, Typesetting, Typesetting
@comment  node-name,  next,  previous,  up
@section Choosing the Right Typesetting System for the Job
@cindex choosing the right typesetting system for the job
@cindex typesetting system, choosing the right one for the job
@cindex SGMLtools
@cindex Texinfo
@cindex LaTeX
@cindex HTML
@cindex LyX
@pindex banner
@pindex man
@pindex groff
@pindex enscript

@noindent
Choosing the proper typesetting system to use when you are about to
begin a project can be daunting: each has its own drawbacks and
abilities, and to the less experienced it may not be immediately clear
which is most appropriate for a particular document or project.

The following table can help you determine which system
is best for a particular task. There isn't one way of doing such
things, of course---these are only my recommendations. The
first column lists the kind of output you intend, the second gives
examples of the kind of documents, and the third suggests the
typesetting system(s) to use. These systems are described in the
remaining sections of this chapter.

@multitable @columnfractions .4 .3 .3
@item @sc{Intended Output} @tab @sc{Examples} @tab @sc{Typesetting System} 
@item Printed, typeset output @emph{and} electronic HTML or text file @tab Internet FAQ, white paper, dissertation @tab  @code{enscript}; Texinfo; SGMLtools @*

@item Printed, typeset output @emph{and} text file @* @tab @code{man} page, command reference card @* @tab @code{groff}

@item Printed, typeset output @tab Letter or other correspondence, report, book manuscript @* @tab LaTeX or LyX

@item Printed, typeset output @tab Brochure or newsletter with multiple columns and images @* @tab LyX

@item Printed, typeset output @tab Envelope, mailing label, other specialized document @* @tab @TeX{}

@item Printed text output in a font @* @tab Grocery list, saved email message, to-do list @* @tab @code{enscript}

@item Printed, typeset output @tab Poster, sign @tab @code{enscript}; HTML; LyX; @TeX{}

@item Large printed text output @tab Long banners for parties or other occasions @tab @code{banner}
@end multitable

@sp .25
@noindent
@strong{NOTE:} If you really don't need a document to be typeset, then
don't bother! Just keep it a plain text file, and use a text editor to
edit it (@pxref{Text Editing, , Text Editing}). Do this for writing notes,
email messages, Web pages, Usenet articles, and so forth. If you ever do
need to typeset it later, you will still be able to do so. And you can,
if you like, view or print plain text in nice fonts (@pxref{Font Text, ,
Outputting Text in a Font}).


@iftex
@page
@end iftex
@node Enscript, LyX, Typesetting Overview, Typesetting
@comment  node-name,  next,  previous,  up
@section Converting Plain Text for Output
@cindex converting plain text for output
@cindex text, converting to PostScript
@pindex enscript
@pindex ghostview
@pindex gs

@flushleft
@sf{Debian}: @file{enscript}
@sf{WWW}: @url{http://www.iki.fi/~mtr/genscript/}
@end flushleft
@*
@noindent
The simplest way to typeset plain text is to convert it to
PostScript. This is often done to prepare text for printing; the
original source text file remains as unformatted text, but the text of
the printed output is formatted in basic ways, such as being set in a
font.

The main tool for converting text to PostScript is called
@code{enscript}; it converts the text file that is specified as an
argument into PostScript, making any number of formatting changes in
between. It's great for quickly making nice output from a plain text
file---you can use it to do things such as output text in a font of your
choosing, or paginate text with graphical headers at the top of each
page.

By default, @code{enscript} paginates its input, outputs it in a
10-point Courier font, and puts a simple header at the top of each page
containing the file name, date and time, and page number in bold. Use
the @samp{-B} option to omit this header.

If you have a PostScript printer connected to your system,
@code{enscript} can be set up to spool its output right to the
printer. You can verify if your system is set up this way by looking at
the @code{enscript} configuration file, @file{/etc/enscript.cfg}. The
line

@example
DefaultOutputMethod: printer
@end example

@noindent
specifies that output is spooled directly to the printer; changing it to
@samp{stdout} instead of @samp{printer} sends the output to the standard
output instead.

Even if your default printer does not natively understand PostScript, it
may be able to take @code{enscript} output, anyway. Most Linux
installations these days have print filters set up so that PostScript
spooled for printing is automatically converted to a format the printer
understands (if your system doesn't have this setup for some reason,
convert the PostScript to a format recognized by your printer with the
@code{gs} tool, and then print that---see @ref{PS Conversions, ,
Converting PostScript}).

@itemize @bullet
@item
To convert the text file @file{saved-mail} to PostScript, with default
formatting, and spool the output right to the printer, type:

@example
$ @kbd{enscript saved-mail @key{RET}}
@end example
@end itemize

To write the output to a file instead of spooling it, give the name of
the file you want to output as an argument to the @samp{-p} option. This
is useful when you don't have a PostScript printer and you need to
convert the output first, or for when you just want to make a PostScript
image file from some text, or for previewing the output before you print
it. In the latter case, you can view it on the display screen with a
PostScript viewer application such as @code{ghostview}
(@pxref{Previewing PS, , Previewing a PostScript File}).

@itemize @bullet
@item
To write the text file @file{saved-mail} to a PostScript file,
@file{saved-mail.ps}, and then preview it in X, type: 

@example
$ @kbd{enscript -p report.ps saved-mail @key{RET}}
$ @kbd{ghostview saved-mail.ps @key{RET}}
@end example
@end itemize

The following recipes show how to use @code{enscript} to output text
with different effects and properties.

@sp .25
@noindent
@strong{NOTE:} Once you make a PostScript file from text input, you can
use any of the tools to format this new PostScript file, including
rearranging and resizing its pages (@pxref{PostScript, , PostScript}).

@menu
* Font Text::                   Outputting text in a font.
* Poster Text::                 Outputting text as posters or signs.
* Prettyprint Text::            Highlighting text based on syntax.
* Fancy Headers::               Making fancy headers.
* Landscape Text::              Outputting text in landscape orientation.
* Multiple Copies::             Outputting multiple copies of text.
* Selecting Text Pages::        Selecting which pages of text to output.
* Enscript Options::            More ways to output PostScript from text.
@end menu


@node Font Text, Poster Text, Enscript, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Text in a Font
@cindex outputting text in a font
@cindex text, outputting in a font
@cindex fonts, printing text with
@pindex enscript

@noindent
To output text in a particular PostScript font, use @code{enscript} and
give the name of the font you want to use as a quoted argument to the
@samp{-f} option.

Specify both the font family and size in points: give the capitalized
name of the font family (with hyphens to indicate spaces between words)
followed by the the size in points. For example, @samp{Courier14}
outputs text in the Courier font at 14 points, and
@samp{Times-Roman12.2} outputs text in the Times Roman font at 12.2
points. Some of the available font names are listed in the file
@file{/usr/share/enscript/afm/font.map}; the @code{enscript} @code{man}
page describes how to use additional fonts that might be installed on
your system.

@itemize @bullet
@item
To print the contents of the text file @file{saved-mail} on a PostScript
printer, with text set in the Helvetica font at 12 points, type: 

@example
$ @kbd{enscript -B -f "Helvetica12" saved-mail @key{RET}}
@end example

@item
To make a PostScript file called @file{saved-mail.ps} containing the
contents of the text file @file{saved-mail}, with text set in the
Helvetica font at 12 points, type: 

@example
$ @kbd{enscript -B -f "Helvetica12" -p saved-mail.ps saved-mail @key{RET}}
@end example
@end itemize

The @samp{-B} option was used in the preceding examples to omit the
output of a header on each page. When headers are used, they're normally
output in 10-point Courier Bold; to specify a different font for the
text in the header, give its name as an argument to the @samp{-F}
option.

@itemize @bullet
@item
To print the contents of the text file @file{saved-mail} to a PostScript
printer, with text set in 10-point Times Roman and header text set in
18-point Times Bold, type: 

@example
$ @kbd{enscript -f "Times-Roman10" -F "Times-Bold18" saved-mail @key{RET}}
@end example

@item
To make a PostScript file called @file{saved-mail.ps} containing the
contents of the text file @file{saved-mail}, with text and headers both
set in 16-point Palatino Roman, type: 

@example
$ @kbd{enscript -f "Palatino-Roman16" -F "Palatino-Roman16" -p
saved-mail.ps saved-mail @key{RET}}
@end example
@end itemize


@node Poster Text, Prettyprint Text, Font Text, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Text as a Poster or Sign
@cindex outputting text as a poster or sign
@cindex posters, outputting from text
@cindex signs, outputting from text
@pindex enscript

@noindent
You can output any text you type directly to the printer (or to a
PostScript file) by omitting the name of the input file; @code{enscript}
will read the text on the standard input until you type @kbd{C-d} on a
new line. 

This is especially useful for making a quick-and-dirty sign or
poster---to do this, specify a large font for the text, such as
Helvetica Bold at 72 points, and omit the display of default headers.

@itemize @bullet
@item
To print a sign in 72-point Helvetica Bold type to a PostScript printer,
type: 

@example
@cartouche
$ @kbd{enscript -B -f "Helvetica-Bold72" @key{RET}}
@kbd{@key{RET}}
@kbd{CAUTION @key{RET}}
@kbd{@key{RET}}
@kbd{WET PAINT! @key{RET}}
@kbd{C-d}
@end cartouche
@end example
@end itemize

72-point type is very large; use the @samp{--word-wrap} option with
longer lines of text to wrap lines at word boundaries if necessary. You
might need this option because at these larger font sizes, you run the
risk of making lines that are longer than could fit on the page. You can
also use the @samp{-r} option to print the text in landscape
orientation, as described in @ref{Landscape Text, , Outputting Text in
Landscape Orientation}.

@itemize @bullet
@item
To print a sign in 63-point Helvetica Bold across the long side of the
page, type:

@example
@cartouche
$ @kbd{enscript -B -r --word-wrap -f "Helvetica-Bold63" @key{RET}}
@kbd{@key{RET}}
@kbd{@key{RET}}
@kbd{CAUTION -- WET PAINT! @key{RET}}
@kbd{C-d}
@end cartouche
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} To make a snazzier or more detailed message or sign, you
would create a file in a text editor and justify the words on each line
in the file as you want them to print, with blank lines where
necessary. If you're getting that complicated with it, it would also be
wise to use the @samp{-p} option once to output to a file first, and
preview the file before printing it (@pxref{Previewing PS, , Previewing
a PostScript File}).


@node Prettyprint Text, Fancy Headers, Poster Text, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Text with Language Highlighting
@cindex outputting text with language highlighting
@cindex text, outputting with language highlighting
@cindex language highlighting, outputting text with 
@cindex pretty-printing

@noindent
The @code{enscript} tool currently recognizes the formatting of more
than forty languages and formats, from the Perl and C programming
languages to HTML, email, and Usenet news articles; @code{enscript} can
highlight portions of the text based on its syntax. In Unix-speak, this
is called @dfn{pretty-printing}.

The following table lists the names of some of the language filters that
are available at the time of this writing and describes the languages or
formats they're used for.

@multitable @columnfractions .30 .70
@item @sc{Filter}
@tab @sc{Language or Format}
@item @code{ada}
@tab Ada95 programming language.

@item @code{asm}
@tab Assembler listings.

@item @code{awk}
@tab AWK programming language.

@item @code{bash}
@tab Bourne-Again shell programming language.

@item @code{c}
@tab C programming language.

@item @code{changelog}
@tab ChangeLog files.

@item @code{cpp}
@tab C++ programming language.

@item @code{csh}
@tab C-Shell script language.

@item @code{delphi}
@tab Delphi programming language.

@item @code{diff}
@tab Normal ``difference reports'' made from @code{diff}.

@item @code{diffu}
@tab Unified ``difference reports'' made from @code{diff}.

@item @code{elisp}
@tab Emacs Lisp programming language.

@item @code{fortran}
@tab Fortran77 programming language.

@item @code{haskell}
@tab Haskell programming language.

@item @code{html}
@tab HyperText Markup Language (HTML).

@item @code{idl}
@tab IDL (CORBA Interface Definition Language).

@item @code{java}
@tab Java programming language.

@item @code{javascript}
@tab JavaScript programming language.

@item @code{ksh}
@tab Korn shell programming language.

@item @code{m4}
@tab M4 macro processor programming language.

@item @code{mail}
@tab Electronic mail and Usenet news articles.

@item @code{makefile}
@tab Rule files for @code{make}.

@item @code{nroff}
@tab Manual pages formatted with @code{nroff}.

@item @code{objc}
@tab Objective-C programming language.

@item @code{pascal}
@tab Pascal programming language.

@item @code{perl}
@tab Perl programming language.

@item @code{postscript}
@tab PostScript programming language.

@item @code{python}
@tab Python programming language.

@item @code{scheme}
@tab Scheme programming language.

@item @code{sh}
@tab Bourne shell programming language.

@item @code{skill}
@tab Cadence Design Systems Lisp-like language.

@item @code{sql}
@tab Sybase 11 SQL.

@item @code{states}
@tab Definition files for @code{states}.

@item @code{synopsys}
@tab Synopsys @code{dc} shell scripting language.

@item @code{tcl}
@tab Tcl programming language.

@item @code{tcsh}
@tab TC-Shell script language.

@item @code{vba}
@tab Visual Basic (for Applications).

@item @code{verilog}
@tab Verilog hardware description language.

@item @code{vhdl}
@tab VHSIC Hardware Description Language (VHDL).

@item @code{vrml}
@tab Virtual Reality Modeling Language (VRML97).

@item @code{zsh}
@tab Z-shell programming language.
@end multitable

To pretty-print a file, give the name of the filter to use as an
argument to the @samp{-E} option, without any whitespace between the
option and argument.

@itemize @bullet
@item
To pretty-print the HTML file @file{index.html}, type:

@example
$ @kbd{enscript -Ehtml index.html @key{RET}}
@end example

@item
To pretty-print an email message saved to the file
@file{important-mail}, and output it with no headers to a file named
@file{important-mail.ps}, type:

@example
$ @kbd{enscript -B -Email -p important-mail.ps important-mail @key{RET}}
@end example
@end itemize

Use the special @samp{--help-pretty-print} option to list the languages
supported by the copy of @code{enscript} you have.

@itemize @bullet
@item
To peruse a list of currently supported languages, type:

@example
$ @kbd{enscript --help-pretty-print | less @key{RET}}
@end example
@end itemize


@node Fancy Headers, Landscape Text, Prettyprint Text, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Text with Fancy Headers
@cindex outputting text with fancy headers
@cindex fancy headers, outputting text with
@cindex text, outputting with fancy headers
@pindex enscript

@noindent
To output text with fancy graphic headers, where the header text is set
in blocks of various shades of gray, use @code{enscript} with the
@samp{-G} option.

@itemize @bullet
@item
To print the contents of the text file @file{saved-mail} with fancy
headers on a PostScript printer, type:

@example
$ @kbd{enscript -G saved-mail @key{RET}}
@end example

@item
To make a PostScript file called @file{saved-mail.ps} containing the
contents of the text file @file{saved-mail}, with fancy headers, type: 

@example
$ @kbd{enscript -G -p saved-mail.ps saved-mail @key{RET}}
@end example
@end itemize

Without the @samp{-G} option, @code{enscript} outputs text with a plain
header in bold text, printing the file name and the time it was last
modified. The @samp{-B} option, as described earlier, omits all headers.

You can customize the header text by quoting the text you want to use as
an argument to the @samp{-b} option. Use the special symbol @samp{$%} to
specify the current page number in the header text.

@itemize @bullet
@item
To print the contents of the text file @file{saved-mail} with a custom
header label containing the current page number, type:

@example
$ @kbd{enscript -b "Page $% of the saved email archive" saved-mail @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} You can create your own custom fancy headers, too---this
is described in the @samp{CUSTOMIZATION} section of the @code{enscript}
@code{man} page.


@node Landscape Text, Multiple Copies, Fancy Headers, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Text in Landscape Orientation
@cindex outputting text in landscape orientation
@cindex text, outputting in landscape orientation
@cindex landscape orientation, outputting text in
@pindex enscript
@pindex figlet

@noindent
To output text in @dfn{landscape} orientation, where text is rotated 90
degrees counter-clockwise, use the @samp{-r} option.

@itemize @bullet
@item
To print the contents of the text file @file{saved-mail} to a PostScript
printer, with text set in 28-point Times Roman and oriented in landscape
orientation, type: 

@example
$ @kbd{enscript -f "Times-Roman28" -r saved-mail @key{RET}}
@end example
@end itemize

The @samp{-r} option is useful for making horizontal banners by passing
output of the @code{figlet} tool to @code{enscript} (@pxref{Figlet, ,
Horizontal Text Fonts}).

@itemize @bullet
@item
To output the text @samp{This is a long banner} in a @code{figlet} font
and write it to the default printer with text set at 18-point Courier
and in landscape orientation, type:  

@example
$ @kbd{figlet "A long banner" | enscript -B -r -f "Courier18" @key{RET}}
@end example
@end itemize


@node Multiple Copies, Selecting Text Pages, Landscape Text, Enscript
@comment  node-name,  next,  previous,  up
@subsection Outputting Multiple Copies of Text
@cindex outputting multiple copies of text
@cindex text, outputting multiple copies of
@pindex enscript
@pindex lpr

@noindent
To output multiple copies of text when sending to the printer with
@code{enscript}, give the number as an argument to the @samp{-#}
option. This option doesn't work when sending to a file, but note that
@code{lpr} takes the same option (@pxref{Printing Copies, , Printing
Multiple Copies of a Job}).

@itemize @bullet
@item
To print three copies of the text file @file{saved-mail} to a PostScript
printer with the default @code{enscript} headers, type: 

@example
$ @kbd{enscript -#3 saved-mail @key{RET}}
@end example
@end itemize


@node Selecting Text Pages, Enscript Options, Multiple Copies, Enscript
@comment  node-name,  next,  previous,  up
@subsection Selecting the Pages of Text to Output
@cindex selecting the pages of text to output
@cindex text, selecting the pages to output
@cindex booklets, printing
@pindex enscript

@noindent
To specify which pages of a text are output with @code{enscript}, give
the range of page number(s) as an argument to the @samp{-a} option.

@itemize @bullet
@item
To print pages two through ten of file @file{saved-mail} with the
default @code{enscript} headers, type:

@example
$ @kbd{enscript -a2-10 saved-mail @key{RET}}
@end example
@end itemize

To print just the odd or even pages, use the special @samp{odd} and
@samp{even} arguments. This is good for printing double-sided pages:
first print the odd-numbered pages, and then feed the output pages back
into the printer and print the even-numbered pages.

@itemize @bullet
@item
To print the odd-numbered pages of the file @file{saved-mail} with the
default headers, type:

@example
$ @kbd{enscript -a odd saved-mail @key{RET}}
@end example

@item
To print the even-numbered pages of the file @file{saved-mail} with the
default headers, type: 

@example
$ @kbd{enscript -a even saved-mail @key{RET}}
@end example
@end itemize


@node Enscript Options, , Selecting Text Pages, Enscript
@comment  node-name,  next,  previous,  up
@subsection Additional PostScript Output Options
@cindex additional PostScript output options
@cindex PostScript output options, additional
@pindex enscript

@noindent
The following table describes some of @code{enscript}'s other options.

@need 1000
@multitable @columnfractions .30 .70
@item @sc{Option}
@tab @sc{Description}
@item @code{-@var{number}}
@tab Specify number of columns per page; for example, to specify four
columns per page, use @samp{-4}.

@item @code{-a@var{pages}}
@tab Specify the page numbers to be printed, where @var{pages} is a
comma-delineated list of page numbers. Specify individual pages by their
numbers, and specify a range of pages by giving the first and last page
numbers in the range separated by a hyphen (@samp{-}). The special
@samp{odd} prints odd-numbered pages and @samp{even} prints
even-numbered pages.

@item @code{-d@var{printer}}
@tab Spool output to the printer named @var{printer}.

@item @code{-E@var{language}}
@tab ``Pretty-print'' the text written in the specified @var{language}
with context highlighting.

@item @code{-H@var{number}}
@tab Specify the height of highlight bars, in lines (without
@var{number}, the value of 2 is used).

@item @code{-i@var{number}}
@tab Indent lines by @var{number} characters, or follow @var{number}
with a letter denoting the unit to use: @samp{c} for centimeters,
@samp{i} for inches, or @samp{p} for PostScript points (1/72 inch).

@item @code{-I@var{filter}}
@tab Pass input files through @var{filter}, which can be a tool or
quoted command.

@item @code{-j}
@tab Print borders around columns.

@item @code{-L@var{numbers}}
@tab Specify the number of lines per page.

@item @code{-u@var{text}}
@tab Specify a quoted string ``underlay'' to print underneath every
page.

@item @code{-U@var{number}}
@tab Specify the number of logical pages to print on each page of
output.

@item @code{--highlight-bar-gray=@var{number}}
@tab Specify the level of gray color to be used in printing the
highlight bars, from 0.0 (gray) to 1.0 (white).

@item @code{--margins=@*@var{left}:@var{right}:@*@var{top}:@var{bottom}}
@tab Adjust left, right, top, and bottom page margins; the measurements
are in PostScript points, and, when specifying the values, any can be
omitted. (Given on one line all as one long option.)

@item @code{--rotate-even-pages}
@tab Rotate each even-numbered page 180 degrees.
@end multitable


@node LyX, TeX, Enscript, Typesetting
@comment  node-name,  next,  previous,  up
@section LyX Document Processing
@cindex LyX document processing
@cindex document processing, with LyX
@cindex WYSIWYM
@pindex lyx

@flushleft
@sf{Debian}: @file{lyx}
@sf{WWW}: @url{http://www.lyx.org/}
@end flushleft
@*
@noindent
LyX is a relative newcomer to the typesetting and word-processing arena,
and it is one of the most genuinely fresh ideas in the field: it's a
kind of word processor for writing LaTeX input (@pxref{TeX, ,
Typesetting with @TeX{} and Friends}). It's a visual, graphic editor for
X, but it doesn't emulate the output paper directly on the display
screen. In contrast to specifying exactly how each character in the
document will look (``make this word Helvetica Bold at 18 points''), you
specify the @emph{structure} of the text you write (``make this word a
chapter heading''). And, in contrast to the WYSIWYG paradigm, its
authors call the new approach WYSIWYM---``What you see is what you
@emph{mean}.''

LyX comes with many document @code{classes} already defined---such as
@code{letter}, @code{article}, @code{report}, and
@code{book}---containing definitions for the elements these document
types may contain. You can change the look of each element and the look
of the document as a whole, and you can change the look of individual
selections of text, but with these elements available, it's rarely
necessary.

Since LyX uses LaTeX as a back-end to do the actual typesetting, and
LyX is capable of exporting documents to LaTeX input format, you can
think of it as a way to write LaTeX input files in a GUI without having
to know the LaTeX language commands.

However, even those who @emph{do} use LaTeX and related typesetting
languages can get some use out of LyX: many people find it quick and
easy to create some documents in LyX that are much harder to do in
LaTeX, such as multi-column newsletter layouts with illustrations.

@ifhtml
(One excellent example of this is
@url{http://www.bcgs.org/newsletters/bcgs_newsletter-2000-01.pdf}) 
@end ifhtml

You can also import your LaTeX files (and plain text) into LyX for
further layout or manipulation.

The following recipes show how to get started using LyX, and where to go
to learn more about it. 

@menu
* LyX Features::                Features of LyX.
* LyX Documents::               Writing documents with LyX.
* LyX Tutorial::                Learning more about LyX.
@end menu


@node LyX Features, LyX Documents, LyX, LyX
@comment  node-name,  next,  previous,  up
@subsection Features of LyX
@cindex features of LyX
@cindex LyX, features of

@noindent
When editing in LyX, you'll see that it has all of the commands you'd
expect from a word processor---for example, some of the commands found
on the @code{Edit} menu include @code{Cut}, @code{Copy}, @code{Paste},
@code{Find and Replace}, and @code{Spell Check}.

Here are some of its major features:

@itemize @bullet
@item
Automatic generation of table of contents, nested lists, and numbering
of section @w{headings}.

@item
Easy insertion of PostScript figures and illustrations, which can be
rotated, scaled, and captioned.

@item
WYSIWYG construction of tables.

@item
Undo and redo of any operation or sequence of operations.

@item
All LyX functions available from both keyboard commands and pull-down
menus.

@item
All key-presses used for commands are configurable.
@end itemize


@node LyX Documents, LyX Tutorial, LyX Features, LyX
@comment  node-name,  next,  previous,  up
@subsection Writing Documents with LyX
@cindex writing documents with LyX
@cindex LyX, writing documents with 

@noindent
LyX runs under X, and you start it in the usual way---either by choosing
it from the applications menu provided by your window manager or by
typing @code{lyx} in an @code{xterm} window. (For more about starting
programs in X, @pxref{X Clients, , Running a Program in X}).

To start a new document from scratch, choose @code{New} from the
@code{File} menu. You can also make a document from one of the many
templates included with LyX, which have the basic layout and settings
for a particular kind of document all set up for you---just fill in the
elements for your actual document. To make a new document from a
template, choose @code{New from template} from the @code{File} menu, and
then select the name of the template to use.

The following table lists the names of some of the included templates
and the kind of documents they're usually used for:

@multitable @columnfractions .30 .70
@item @sc{Template File}
@tab @sc{Document Format}
@item @code{aapaper.lyx}
@tab Format suitable for papers submitted to @cite{Astronomy and
@w{Astrophysics}}.

@item @code{dinbrief.lyx}
@tab Format for letters typeset according to German conventions.

@item @code{docbook_template.lyx}
@tab Format for documents written in the SGML DocBook DTD.

@item @code{hollywood.lyx}
@tab Format for movie scripts as they are formatted in the U.S.@: film
industry.

@item @code{iletter.lyx}
@tab Format for letters typeset according to Italian conventions.

@item @code{latex8.lyx}
@tab Format suitable for article submissions to IEEE conferences.

@item @code{letter.lyx}
@tab Basic format for letters and correspondence.

@item @code{linuxdoctemplate.lyx}
@tab Format for documents written in the SGML LinuxDoc DTD, as formerly
used by the @uref{http://linuxdoc.org/, Linux Documentation Project}.

@item @code{revtex.lyx}
@tab Article format suitable for submission to publications of the
American Physical Society (APS), American Institute of Physics (AIP),
and Optical Society of America (OSA).

@item @code{slides.lyx}
@tab Format for producing slides and transparencies.
@end multitable

To view how the document will look when you print it, choose @code{View
DVI} from the @code{File} menu. This command starts the @code{xdvi}
tool, which previews the output on the screen. (For more on using
@code{xdvi}, @pxref{Previewing DVI, , Previewing a DVI File}).

To print the document, choose @code{Print} from the @code{File}
menu. You can also export it to LaTeX, PostScript, DVI, or plain text
formats; to do this, choose @code{Export} from the @code{File} menu and
then select the format to export to.

@sp .25
@noindent
@strong{NOTE:} If you plan on editing the document again in LyX, be sure
to save the actual @file{.lyx} document file.


@node LyX Tutorial, , LyX Documents, LyX
@comment  node-name,  next,  previous,  up
@subsection Learning More about LyX
@cindex learning more about LyX
@cindex LyX, learning more about 

@noindent
The LyX Documentation Project has overseen the creation of a great deal
of free documentation for LyX, including hands-on tutorials, user
manuals, and example documents.

@uref{http://www.lyx.org/about/lgt-1.0/lgt.html, The LyX Graphical Tour}
is a Web-based tutorial that shows you how to create and edit a simple
LyX file.

LyX has a comprehensive set of built-in manuals, which you can read
inside the LyX editor like any LyX document, or you can print them
out. All of the manuals are available from the @code{Help} menu.

@itemize @bullet
@item
To run LyX's built-in tutorial, choose @code{Tutorial} from the
@code{Help} menu. 
@end itemize

This command opens the LyX tutorial, which you can then read on the
screen or print out by selecting @code{Print} from the @code{File} menu.

The following table lists the names of the available manuals as they
appear on the @code{Help} menu, and describes what each contains:

@multitable @columnfractions .30 .70
@item @sc{Manual}
@tab @sc{Description}
@item @code{Introduction}
@tab An introduction to using the LyX manuals, describing their contents
and how to view and print them.

@item @code{Tutorial}
@tab A hands-on tutorial to writing documents with LyX.

@item @code{User's Guide}
@tab The main LyX usage manual, describing all of the commonly used
commands, options, and features. 

@item @code{Extended Features}
@tab This is ``Part II'' of the @cite{User's Guide}, describing advanced
features such as bibliographies, indices, documents with multiple files,
and techniques used in special-case situations, such as fax support,
SGML-Tools support, and using version control with LyX documents.

@item @code{Customization}
@tab Shows which elements of LyX can be customized and how to go about
doing that.

@item @code{Reference Manual}
@tab Describes all of the menu entries and internal functions.

@item @code{Known Bugs}
@tab LyX is in active development, and like any large application, bugs
have been found. They are listed and described in this document.

@item @code{LaTeX Configuration}
@tab This document is automatically generated by LyX when it is
installed on your system. It is an inventory of your LaTeX
configuration, including the version of LaTeX in use, available fonts,
available document classes, and other related packages that may be
installed on your system.
@end multitable

Finally, LyX includes example documents in the
@file{/usr/X11R6/share/lyx/examples} directory. Here's a partial listing
of these files with a description of what each contains:

@multitable @columnfractions .30 .70
@item @sc{Document File}
@tab @sc{Description}
@item @code{Foils.lyx}
@tab Describes how to make @dfn{foils}---slides or overhead
transparencies---with the FoilTeX package.

@item @code{ItemizeBullets.lyx}
@tab Examples of the various bullet styles for itemized lists.

@item @code{Literate.lyx}
@tab An example of using LyX as a composition environment for ``literate
programming.''

@item @code{MathLabeling.lyx}
@tab Techniques for numbering and labeling equations.

@item @code{Math_macros.lyx}
@tab Shows how to make macros in Math mode.

@item @code{Minipage.lyx}
@tab Shows how to write two-column bilingual documents.

@item @code{TableExamples.lyx}
@tab Examples of using tables in LyX.

@item @code{aa_head.lyx}@*@code{aa_paper.lyx}@*@code{aas_sample.lyx}
@tab @*Files discussing and showing the use of LyX in the field of astronomy.

@item @code{amsart-test.lyx}@*@code{amsbook-test.lyx}
@tab Examples of documents written in the format used by the American
Mathematical Society.

@item @code{docbook_example.lyx}
@tab Example of a DocBook document.

@item @code{multicol.lyx}
@tab Example of a multi-column format.

@item @code{scriptone.lyx}
@tab Example of a Hollywood script.
@end multitable


@node TeX, SGML, LyX, Typesetting
@comment  node-name,  next,  previous,  up
@section Typesetting with @TeX{} and Friends
@cindex typesetting with @TeX{} and friends
@cindex Knuth, Donald
@cindex @TeX{}
@cindex LaTeX
@cindex Metafont
@pindex tex
@pindex file

@flushleft
@sf{Debian}: @file{tetex-base}
@sf{Debian}: @file{tetex-bin}
@sf{Debian}: @file{tetex-doc}
@sf{Debian}: @file{tetex-extra}
@sf{Debian}: @file{tetex-lib}
@sf{WWW}: @url{http://www.tug.org/teTeX/}
@end flushleft
@*
@noindent
The most capable typesetting tool for use on Linux-based systems is the
@TeX{} typesetting system and related software. It is the premier
computer typesetting system---its output surpasses or rivals all other
systems to date. The advanced line and paragraph breaking, hyphenation,
kerning, and other font characteristic policies and algorithms it can
perform, and the level of precision at which it can do them, have yet to
be matched in word processors.

The @TeX{} system itself---not a word processor or single program, but a
large collection of files and data---is packaged in distributions;
te@TeX{} is the @TeX{} distribution designed for Linux.

@TeX{} input documents are plain text files written in the @TeX{}
formatting language, which the @TeX{} tools can process and write to
output files for printing or viewing. This approach has great benefits
for the writer: the plain text input files can be written with and
exchanged between many different computer systems regardless of
operating system or editing software, and these input files do not
become obsolete or unusable with new versions of the @TeX{} software.

Donald Knuth, the world's foremost authority on algorithms, wrote @TeX{}
in 1984 as a way to typeset
@uref{http://www-cs-faculty.stanford.edu/~knuth/taocp.html, his books},
because he wasn't satisfied with the quality of available systems. Since
its first release, many extensions to the @TeX{} formatting language
have been made---the most notable being Leslie Lamport's LaTeX, which is
a collection of sophisticated macros written in the @TeX{} formatting
language, designed to facilitate the typesetting of structured
documents. (LaTeX probably gets more day-to-day use than the plain
@TeX{} format, but in my experience, both systems are useful for
different kinds of documents.)

The collective family of @TeX{} and related programs are sometimes
called ``@TeX{} and friends,'' and abbreviated as @file{texmf} in some
@TeX{} references@footnote{The @samp{mf} also stands for ``Metafont,''
the name of the font language that is part of @TeX{}.}: for example, the
supplementary files included with the bare @TeX{} system are kept in the
@file{/usr/lib/texmf} directory tree.

The following recipes describe how to begin writing input for @TeX{} and
how to process these files for viewing and printing. While not everyone
wants or even has a need to write documents with @TeX{} and LaTeX, these
formats are widely used---especially on Linux systems---so every Linux
user has the potential to encounter one of these files, and ought to
know how to process them.

@sp .25
@noindent
@strong{NOTE:} ``@TeX{}'' doesn't sound like the name of a cowboy, nor
``LaTeX'' like a kind of paint: the letters @samp{T}, @samp{E}, and
@samp{X} represent the Greek characters tau, epsilon, and chi (from the
Greek @samp{techne}, meaning art and science). So the last sound in
``@TeX{}'' is like the @samp{ch} in @samp{Bach}, and ``LaTeX,''
depending on local dialect, is pronounced either @samp{lay-teck} or
@samp{lah-teck}. Those who become highly adept at using the system,
Knuth calls ``@TeX{}nicians.''

@menu
* Determining TeX::             Is it a TeX or LaTeX file?
* Processing TeX::              Processing TeX files.
* Processing LaTeX::            Processing LaTeX files.
* Writing TeX::                 Writing TeX files.
* TeX Templates::               TeX and LaTeX document templates.
@end menu


@node Determining TeX, Processing TeX, TeX, TeX
@comment  node-name,  next,  previous,  up
@subsection Is It a @TeX{} or LaTeX File?
@cindex is it a @TeX{} or LaTeX file?
@cindex @TeX{}, determining format
@cindex LaTeX, determining format
@pindex file
@pindex grep

@noindent
There are separate commands for processing @TeX{} and LaTeX files, and
they're not interchangeable, so when you want to process a @TeX{} or
LaTeX input file, you should first determine its format.

By convention, @TeX{} files always have a @file{.tex} file name
extension. LaTeX input files sometimes have a @file{.latex} or
@file{.ltx} file name extension instead, but not always---one way to
tell if a @file{.tex} file is actually in the LaTeX format is to use
@code{grep} to search the file for the text @samp{\document}, which
every LaTeX (and @emph{not} @TeX{}) document will have. So if it outputs
any lines that match, you have a LaTeX file. (The regular expression to
use with @code{grep} is @samp{\\document}, since backslash characters
must be specified with two backslashes.)

@itemize @bullet
@item
To determine whether the file @file{gentle.tex} is a @TeX{} or
LaTeX file, type:

@example
$ @kbd{grep '\\document' gentle.tex @key{RET}}
$
@end example
@end itemize

In this example, @code{grep} didn't return any matches, so it's safe to
assume that @file{gentle.tex} is a @TeX{} file and not a LaTeX file.

@sp .25
@noindent
@strong{NOTE:} For more on @code{grep} and searching for regular
expressions, see @ref{Regexps, , Regular Expressions---Matching Text
Patterns}.


@node Processing TeX, Processing LaTeX, Determining TeX, TeX
@comment  node-name,  next,  previous,  up
@subsection Processing @TeX{} Files
@cindex processing @TeX{} files
@cindex @TeX{} files, processing
@pindex tex
@pindex xdvi
@pindex dvips
@pindex lpr

@noindent
Use @code{tex} to process @TeX{} files. It takes as an argument the name
of the @TeX{} source file to process, and it writes an output file in
DVI (``DeVice Independent'') format, with the same base file name as the
source file, but with a @file{.dvi} extension.

@itemize @bullet
@item
To process the file @file{gentle.tex}, type:

@example
$ @kbd{tex gentle.tex @key{RET}}
@end example
@end itemize

Once you have produced a DVI output file with this method, you can do
the following with it:

@itemize @bullet
@item
Preview it on the screen with @code{xdvi}; see @ref{Previewing DVI, ,
Previewing a DVI File}

@item
Print it with @code{dvips} or @code{lpr}; see @ref{Dvips Printing, ,
Printing with Dvips}

@item
Convert it to PostScript with @code{dvips}; see @ref{Preparing DVI, ,
Preparing a DVI File for Printing}; (then, you can also convert the
PostScript output to PDF or plain text)
@end itemize


@node Processing LaTeX, Writing TeX, Processing TeX, TeX
@comment  node-name,  next,  previous,  up
@subsection Processing LaTeX Files
@cindex processing LaTeX files
@cindex LaTeX files, processing
@pindex latex

@noindent
The @code{latex} tool works just like @code{tex}, but is used to process
LaTeX files. 

@itemize @bullet
@item
To process the LaTeX file @file{lshort.tex}, type:

@example
$ @kbd{latex lshort.tex @key{RET}}
@end example
@end itemize

This command writes a DVI output file called @file{lshort.dvi}.

You may need to run @code{latex} on a file several times
consecutively. LaTeX documents sometimes have indices and cross
references, which, because of the way that LaTeX works, take two (and in
rare cases three or more) runs through @code{latex} to be fully
processed. Should you need to run @code{latex} through a file more than
once in order to generate the proper references, you'll see a message in
the @code{latex} processing output after you process it the first time
instructing you to process it again.

@itemize @bullet
@item
To ensure that all of the cross references in @file{lshort.tex} have
been generated properly, run the input file through @code{latex} once
more:

@example
$ @kbd{latex lshort.tex @key{RET}}
@end example
@end itemize

The @file{lshort.dvi} file will be rewritten with an updated version
containing the proper page numbers in the cross reference and index
entries. You can then view, print, or convert this DVI file as described
in the previous recipe for processing @TeX{} files.


@node Writing TeX, TeX Templates, Processing LaTeX, TeX
@comment  node-name,  next,  previous,  up
@subsection Writing Documents with @TeX{} and LaTeX
@cindex writing documents with @TeX{} and LaTeX
@cindex @TeX{}, writing documents with
@cindex LaTeX, writing documents with
@pindex LyX
@pindex SGMLtools
@pindex Texinfo
@pindex lynx
@pindex tex
@pindex latex

@flushleft
@sf{WWW}: @url{ftp://ctan.tug.org/tex-archive/documentation/gentle.tex}
@sf{WWW}: @url{ftp://ctan.tug.org/tex-archive/documentation/lshort/} 
@end flushleft
@*
@noindent
To create a document with @TeX{} or LaTeX, you generally use your
favorite text editor to write an @dfn{input file} containing the text in
@TeX{} or LaTeX formatting. Then, you process this @TeX{} or LaTeX input
file to create an @emph{output file} in the DVI format, which you can
preview, convert, or print.

It's an old tradition among programmers introducing a programming
language to give a simple program that just outputs the text
@samp{Hello, world} to the screen; such a program is usually just
detailed enough to give those unfamiliar with the language a feel for
its basic syntax.

We can do the same with document processing languages like @TeX{} and
LaTeX. Here's the ``Hello, world'' for a @TeX{} document:

@example
Hello, world
\end
@end example

If you processed this input file with @code{tex}, it would output a DVI
file that displayed the text @samp{Hello, world} in the default @TeX{}
font, on a default page size, and with default margins.

Here's the same ``Hello, world'' for LaTeX:

@example
\documentclass@{article@}
\begin@{document@}
Hello, world
\end@{document@}
@end example

Even though the @TeX{} example is much simpler, LaTeX is generally
easier to use fresh ``out of the box'' for writing certain kinds of
structured documents---such as correspondence and articles---because it
comes with predefined @dfn{document classes} which control the markup
for the structural elements the document contains@footnote{LyX, being in
essence a graphical front-end to LaTeX, uses these same document
classes.}. Plain @TeX{}, on the other hand, is better suited for more
experimental layouts or specialized documents.

The @TeX{} and LaTeX markup languages are worth a book each, and
providing an introduction to their use is well out of the scope of this
text. To learn how to write input for them, I suggest two excellent
tutorials, Michael Doob's @cite{A Gentle Introduction to @TeX{}}, and
Tobias Oetiker's @cite{The Not So Short Introduction to LaTeX}---each
available on the WWW at the URLs listed above. These files are each in
the respective format they describe; in order to read them, you must
@emph{process} these files first, as described in the two previous
recipes.

Good LaTeX documentation in HTML format can be found installed on many
Linux systems in the @file{/usr/share/texmf/doc/latex/latex2e-html/}
directory; use the @code{lynx} browser to view it (@pxref{Browsing
Files, , Browsing Files}).

Some other typesetting systems, such as LyX, SGMLtools, and Texinfo (all
described elsewhere in this chapter), write @TeX{} or LaTeX output,
too---so you can use those systems to produce said output without
actually learning the @TeX{} and LaTeX input formats. (This book was
written in Emacs in Texinfo format, and the typeset output was later
generated by @TeX{}.)

@sp .25
@noindent
@strong{NOTE:} The Oetiker text consists of several separate LaTeX files
in the @file{lshort} directory; download and save all of these files.


@node TeX Templates, , Writing TeX, TeX
@comment  node-name,  next,  previous,  up
@subsection @TeX{} and LaTeX Document Templates
@cindex @TeX{} and LaTeX document templates
@cindex templates, @TeX{} and LaTeX
@cindex Rutten, Rob
@cindex @TeX{} Catalogue Online
@cindex folders, LaTeX templates for
@cindex register labels, LaTeX templates for
@cindex Midnight Macros
@cindex Magnusson, Bj@"orn 
@pindex tex
@pindex latex

@flushleft
@sf{WWW}: @url{http://dsl.org/comp/templates/}
@end flushleft
@*
@noindent
A collection of sample templates for typesetting certain kinds of
documents in @TeX{} and LaTeX can be found at the URL listed above.
These templates include those for creating letters and correspondence,
articles and term papers, envelopes and mailing labels,@footnote{In
addition, a more advanced LaTeX style for printing many different kinds
of shipping and package labels is normally installed at
@file{/usr/share/texmf/tex/latex/labels/}.} and fax cover sheets. If
you're interested in making typeset output with @TeX{} and LaTeX, these
templates are well worth exploring.

To write a document with a template, insert the contents of the template
file into a new file that has a @file{.tex} or @file{.ltx} extension,
and edit that. (Use your favorite text editor to do this.)

To make sure that you don't accidentally overwrite the actual template
files, you can write-protect them (@pxref{Write Protection, ,
Write-Protecting a File}):

@example
$ @kbd{chmod a-w @var{template-file-names} @key{RET}}
@end example

In the templates themselves, the bracketed, uppercase text explains what
kind of text belongs there; fill in these lines with your own text, and
delete the lines you don't need. Then, process your new file with either
@code{latex} or @code{tex} as appropriate, and you've got a typeset
document!

The following table lists the file names of the @TeX{} templates, and
describes their use. Use @code{tex} to process files you make with these
templates (@pxref{Processing TeX, , Processing @TeX{} Files}).

@multitable @columnfractions .30 .70
@item @sc{Template File} @tab @sc{Description}
@item @code{fax.tex}
@tab A cover sheet for sending fax messages.

@item @code{envelope.tex}
@tab A No. 10 mailing envelope.

@item @code{label.tex}
@tab A single mailing label for printing on standard 15-up sheets.
@end multitable

The following table lists the file names of the LaTeX templates, and
describes their use.@footnote{The manuscript template requires that your
system has the LaTeX style file called @file{manuscript.sty}; most
@TeX{} distributions have this installed at
@file{/usr/share/texmf/tex/latex/misc/manuscript.sty}.} Use @code{latex}
to process files you make with these templates (@pxref{Processing LaTeX,
, Processing LaTeX Files}).

@multitable @columnfractions .30 .70
@item @sc{Template File}
@tab @sc{Description}
@item @code{letter.ltx}
@tab A letter or other correspondence.

@item @code{article.ltx}
@tab An article or a research or term paper.

@item @code{manuscript.ltx}
@tab A book manuscript.
@end multitable

There are more complex template packages available on the net that you
might want to look at:

@itemize @bullet
@item
Rob Rutten has assembled a very nice collection of LaTeX templates,
@uref{http://www.astro.uu.nl/~rutten/rrtex/templates/}

@item
The largest listing of LaTeX and TeX templates and style files is in the
@TeX{} Catalogue Online,
@uref{ftp://ftp.cdrom.com:21/pub/tex/ctan/help/Catalogue/hier.html}

@item
The Midnight Macros are a collection of @TeX{} macros for printing
booklets, bulk letters, and outlines,
@uref{ftp://ftp.cdrom.com/pub/tex/ctan/macros/generic/midnight/}  

@item
Bj@"orn Magnusson's LaTeX templates for folder and register labels,
@uref{http://www.ifm.liu.se/~bjmag/latex.shtml}
@end itemize


@node SGML, Typesetting Systems, TeX, Typesetting
@comment  node-name,  next,  previous,  up
@section Writing Documents with SGMLtools
@cindex writing documents with SGMLtools
@cindex SGMLtools, writing documents with
@cindex DTD
@cindex Document Type Definition (DTD)
@pindex SGMLtools
@pindex zcat
@pindex lpr
@pindex zless

@flushleft
@sf{Debian}: @file{sgml-tools}
@sf{WWW}: @url{http://www.sgmltools.org/}
@end flushleft
@*
@noindent
With the SGMLtools package, you can write documents and generate output
in many different kinds of formats---including HTML, plain text, PDF,
and PostScript---all from the same plain text input file. 

SGML (``Standard Generalized Markup Language'') is not an actual format,
but a specification for writing markup languages; the markup language
``formats'' themselves are called DTDs (``Document Type
Definition''). When you write a document in an SGML DTD, you write input
as a plain text file with markup tags.

The various SGML packages on Linux are currently in a state of
transition. The original SGML-Tools package (known as LinuxDoc-SGML in
another life; now SGMLtools v1) is considered obsolete and is no longer
being developed; however, the newer SGMLtools v2 (a.k.a. ``SGMLtools
Next Generation'' and ``SGMLtools '98'') is still alpha software, as is
@uref{http://sgmltools-lite.sourceforge.net/, SGMLtools-lite}, a new
subset of SGMLtools.

In the interim, if you want to dive in and get started making documents
with the early SGMLtools and the LinuxDoc DTD, it's not hard to
do. While the newer DocBook DTD has become very popular, it may be best
suited for technical books and other very large projects---for smaller
documents written by individual authors, such as a multi-part essay,
FAQ, or white paper, the LinuxDoc DTD still works fine.

And since the Linux HOWTOs are still written in LinuxDoc, the Debian
project has decided to maintain the SGMLtools 1.0 package independently.

The @cite{SGML-Tools User's Guide} comes installed with the
@file{sgml-tools} package, and is available in several formats in the
@file{/usr/doc/sgml-tools} directory. These files are compressed; if you
want to print or convert them, you have to uncompress them first
(@pxref{File Compression, , Compressed Files}).

@itemize @bullet
To peruse the compressed text version of the SGML-Tools guide, type:

@example
$ @kbd{zless /usr/doc/sgml-tools/guide.txt.gz @key{RET}}
@end example

@item
To print a copy of the PostScript version of the SGML-Tools guide to the
default printer, type:

@example
$ @kbd{zcat /usr/doc/sgml-tools/guide.ps.gz | lpr @key{RET}}
@end example
@end itemize


@menu
* SGML Elements::               Elements of an SGML document.
* SGML Syntax::                 Checking SGML document syntax.
* SGML Output::                 Making output from SGML source.
@end menu

@node SGML Elements, SGML Syntax, SGML, SGML
@comment  node-name,  next,  previous,  up
@subsection Elements of an SGML Document
@cindex elements of an SGML document
@cindex SGML document, elements of an

@noindent
A document written in an SGML DTD looks a lot like HTML---which is no
coincidence, since HTML is a subset of SGML. A very simple ``Hello,
world'' example in the LinuxDoc DTD might look like this:

@example
<!doctype linuxdoc system>
<article>
<title>An Example Document
<author>Ann Author
<date>4 May 2000
<abstract>
This is an example LinuxDoc document.
</abstract>

<sect>Introduction

<p>Hello, world.

</article>
@end example

A simple example document and the various output files it generates are
on the SGMLtools site at
@uref{http://www.sgmltools.org/old-site/example/index.html}.

The SGMLtools package also comes with a simple example file,
@file{example.sgml.gz}, which is installed in the
@file{/usr/doc/sgml-tools} directory.


@node SGML Syntax, SGML Output, SGML Elements, SGML
@comment  node-name,  next,  previous,  up
@subsection Checking SGML Document Syntax
@cindex checking SGML document syntax
@cindex SGML, checking document syntax
@pindex sgmlcheck

@noindent
Use @code{sgmlcheck} to make sure the syntax of an SGML document is
correct---it outputs any errors it finds in the document that is
specified as an argument.

@itemize @bullet
@item
To check the SGML file @file{myfile.sgml}, type:

@example
$ @kbd{sgmlcheck myfile.sgml @key{RET}}
@end example
@end itemize


@node SGML Output, , SGML Syntax, SGML
@comment  node-name,  next,  previous,  up
@subsection Generating Output from SGML
@cindex generating output from SGML
@cindex SGML, generating output from
@pindex sgml2html
@pindex sgml2latex
@pindex sgml2rtf
@pindex sgml2xml
@pindex sgml2info
@pindex sgml2lyx
@pindex sgml2txt
@pindex dvips
@pindex latex
@pindex ps2pdf

@noindent
The following table lists the SGML converter tools that come with
SGMLtools, and describes the kind of output they generate. All take the
name of the SGML file to work on as an argument, and they write a new
file with the same base file name and the file name extension of their
output format.

@multitable @columnfractions .30 .70
@item @sc{Tool}
@tab @sc{Description}
@item @code{sgml2html}
@tab Generates HTML files.

@item @code{sgml2info}
@tab Generates a GNU Info file.

@item @code{sgml2lyx}
@tab Generates a LyX input file.

@item @code{sgml2latex}
@tab Generates a LaTeX input file (useful for printing; first process as
in @ref{Processing LaTeX, , Processing LaTeX Files}, and then print the
resultant DVI or PostScript output file).

@item @code{sgml2rtf}
@tab Generates a file in Microsoft's ``Rich Text Format.''

@item @code{sgml2txt}
@tab Generates plain text format.

@item @code{sgml2xml}
@tab Generates XML format.
@end multitable

@itemize @bullet
@item
To make a plain text file from @file{myfile.sgml}, type:

@example
$ @kbd{sgml2txt myfile.sgml @key{RET}}
@end example
@end itemize

This command writes a plain text file called @file{myfile.txt}.

To make a PostScript or PDF file from an SGML file, first generate
a LaTeX input file, run it through LaTeX to make a DVI output file,
and then process that to make the final output.

@itemize @bullet
@item
To make a PostScript file from @file{myfile.sgml}, type:

@example
@cartouche
$ @kbd{sgml2latex myfile.sgml @key{RET}}
$ @kbd{latex myfile.latex @key{RET}}
$ @kbd{dvips -t letter -o myfile.ps myfile.dvi @key{RET}}
$
@end cartouche
@end example
@end itemize

In this example, @code{sgml2latex} writes a LaTeX input file from the
SGML source file, and then the @code{latex} tool processes the LaTeX
file to make DVI output, which is processed with @code{dvips} to get the
final output: a PostScript file called @file{myfile.ps} with a paper
size of US letter.

To make a PDF file from the PostScript file, you need to take one more
step and use @code{ps2pdf}, part of the @code{gs} or Ghostscript
package; this converts the PostScript to PDF.

@itemize @bullet
@item
To make a PDF file from the PostScript file @file{myfile.ps}, type:

@example
$ @kbd{ps2pdf myfile.ps myfile.pdf @key{RET}}
@end example
@end itemize


@node Typesetting Systems, , SGML, Typesetting
@comment  node-name,  next,  previous,  up
@section Other Word Processors and Typesetting Systems
@cindex other word processors and typesetting systems
@cindex word processors and typesetting systems, other
@cindex cassette labels, PostScript template for
@cindex video tape labels, PostScript template for
@cindex Zawinski, Jamie
@cindex Microsoft Word files, reading
@cindex AbiWord
@cindex Maxwell
@cindex StarOffice
@cindex StarWriter
@pindex cd-circleprint
@pindex cdlabelgen
@pindex groff
@pindex zcat
@pindex PostScript
@pindex texinfo

@noindent
The following table describes other popular word processors and
typesetting tools available for Linux. Those systems not in general use
have been silently omitted.

@multitable @columnfractions .30 .70
@item @sc{System}
@tab @sc{Description}
@item @code{AbiWord}
@tab A graphical, WYSIWYG-style word processor for Linux systems. It can
read Microsoft Word files.

@noindent
{@sf{WWW}}: @uref{http://www.abisource.com/}

@item @code{groff}
@tab GROFF is the latest in a line of phototypesetting systems that have been
available on Unix-based systems for years; the original in this line was
@code{roff} (``runoff,'' meaning that it was for files to be @emph{run
off} to the printer). @code{groff} is used in the typesetting of
@code{man} pages, but it's possible to use it to create other kinds of
documents, and it has a following of staunch adherents.

To output the tutorial file included with the @code{groff} distribution
to a DVI file called @file{intro.dvi}, type:
@smallexample
$ @kbd{zcat /usr/doc/groff/me-intro.me.gz | groff 
-me -T dvi > intro.dvi @key{RET}}@*
@end smallexample

@noindent
{@sf{Debian}}: @file{groff}

@item @code{Maxwell}
@tab A graphical word processor for use in X.

@noindent
{@sf{WWW}}: @uref{http://www.eeyore-mule.demon.co.uk/}

@item @code{PostScript}
@tab The PostScript language is generally considered to be a format
generated by software, but some people write straight PostScript!
@ref{Enscript, , Converting Plain Text for Output}, has recipes on
creating PostScript output from text, including outputting text in a
font.

People have written PostScript template files for creating all kinds of
documents---from desktop calendars to mandalas for meditation.  The
Debian @file{cdlabelgen} and @file{cd-circleprint} packages contain
tools for writing labels for compact discs. Also of interest are Jamie
Zawinski's templates for printing label inserts for video and audio
tapes; edit the files in a text editor and then view or print them as
you would any PostScript file.

@noindent
{@sf{WWW}}: @url{http://www.jwz.org/audio-tape.ps}

@noindent
{@sf{WWW}}: @url{http://www.jwz.org/video-tape.ps}

@item @code{StarWriter}
@tab A traditional word processor for Linux systems, part of the
StarOffice application suite. It can also read Microsoft Word files.

@noindent
{@sf{WWW}}: @uref{http://www.sun.com/staroffice/}

@item @code{Texinfo}
@tab Texinfo is the GNU Project's documentation system and is an
excellent system for writing FAQs or technical manuals. It allows for
the inclusion of in-line EPS images and can produce both @TeX{}-based,
HTML, and Info output---use it if this matches your needs.

@noindent
{@sf{Debian}}: @file{tetex-base}

@noindent
{@sf{WWW}}: @url{http://www.texinfo.org/}
@end multitable