% introduction.tex
%
% \begin{stealth} \pspage{page_latex.ps} \end{stealth}

\chapter{Getting to Know LameTeX}

Hackers, just skip to the section ``Fast Track''.

\section{Copyright}

Don't sell LameTeX or this documentation, or use parts of it in
programs you sell. Don't even think about selling it. This isn't about
money. It's about cool hacking. Permission granted for everything
else. Thank you.

\section{About Text Formatters}

A {\it text formatter} is a program that helps you make nice looking
reports and documents. You write the document by typing the text into
an editor, adding formatting commands as needed. A {\em formatting
command} is not meant to be printed. Instead it is interpreted by the
text formatter program to accomplish special tricks such as centering
a line of text, that you would otherwise have to do by laboriously
typing the space bar a number of times.

LameTeX is a text formatting program that understands many of the 
most important text formatting commands of a popular text formatter,
LaTeX. Although not as powerful for normal text formatting, LameTeX
has a number of additional features for special effects.

\section{LameTeX is for Special Effects}

That said, if you want to write a plain report or do some fancy
mathematics, you should use LaTeX instead. LaTeX does a better
job for normal-looking documents (this page is an example
of a normal-looking LaTeX page), and LameTeX version 1.0 is not
capable of handling some of the more esoteric LaTeX functionality
like mathematics and command definition. That's why it's called
``Lame'' TeX!

\subsection{What LameTeX Can Do}

LameTeX's specialty is complete versatility of the printed page.  The
standard model for text formatters is that every page is necessarily
rectangular. LameTeX will let you format text inside a triangular
page, or a circle page. Just like professional magazine editors,
you can include pictures of {\it any} shape and ask the text to flow
around them or inside them.

These flexible arbitrarily-shaped margins are PostScript paths.  If
you don't know PostScript, there is a big library of interesting
LameTeX page margins here. With LameTeX you can fit several ``pages''
onto one 8.5x11 inch piece of paper, so you can easily make index
cards, labels, and half-pages of text.

Also, if you know how to write programs in PostScript, LameTeX allows
you to very tightly integrate your LameTeX commands with your
PostScript code. In fact, the PostScript that LameTeX outputs is
nicely formatted and commented so that you can modify it yourself
and see how it's done. LameTeX is written with PostScript version 1,
so it should run on all PostScript printers.

Finally, everything about LameTeX is set up to be compatible with
LaTeX. LameTeX can't do everything that LaTeX can, but the special
{\it stealth commands} guarantee that your fancy LameTeX document can
be processed by normal LaTeX.  This allows you to share it with anyone
who doesn't happen to have LameTeX. (Better yet: give them a copy;
LameTeX is free!)

\subsection{What you Need to Know to Learn LameTeX}

LameTeX is a tool to make things simple. You don't have to be a LaTeX
expert to use LameTeX, but you should be somewhat familiar with some
basic LaTeX commands before reading this document.

You don't need to know any PostScript to use LameTeX, although there
is a lot extra you can do with LameTeX if you can do just a little.

You {\it definitely} don't need to know anything about TeX to use
LameTeX.

LameTeX is written in C++ and PostScript from scratch. It is not based
on TeX macros or anything like that. It just happens to know the same
language as LaTeX, and also it snarfs fonts from LaTeX.

\section{The Fast Track}

If
% \begin{stealth} \begin{postscript}
% /Wizard LeftMarginIcon \end{postscript} \end{stealth}
it's 3 a.m. and you are a juggling, tetris-addicted hacker with a
taste for reheated Chinese take-out food, you may want to skip to the
good parts.
% The below text should only be printed in the LameTeX version. When 
% running LaTeX there are no little wizards to see!
% \begin{stealth} Look for the Little Wizard icon for interesting notes for
% experts who won't need to read this whole manual. \end{stealth}

\begin{itemize}

\item The LameTeX code for this document, {\tt lametex\_doc.tex}, and
all the files it includes, are good examples of what LameTeX code
looks like.  Read through it and you will notice it's not hard to make
% \begin{stealth} \begin{postscript}
% /Wizard LeftMarginIcon \end{postscript} \end{stealth}
a few special effects.  In general, just try lots of LaTeX commands,
and LameTeX will either handle them or attempt to skip them
gracefully.

\item Look in the appendix to see what commands LameTeX supports if in
doubt. {\Large \bf Warning! LameTeX lets you write sloppy code.} Try
writing your document in LaTeX first, to work the bugs out of the
``normal look'' and then start using LameTeX. Then you're guaranteed
% \begin{stealth} \begin{postscript}
% /Wizard LeftMarginIcon \end{postscript} \end{stealth}
that your document will work on both text formatters.

\item Also
glance at the section
on Stealth Commands, which are LameTeX commands over and above the
normal LaTeX commands. The stealth command {\tt \\ignore} tells LameTeX to
ignore LaTeX commands it doesn't know and can't skip gracefully.

\item
% \begin{stealth} \begin{postscript}
% /Wizard LeftMarginIcon \end{postscript} \end{stealth}
LameTeX is written in C++, and the code itself is documented
separately.

\item The
PostScript routine for breaking a PostScript path into tiles is
breakpath.ps. And the formatting language is handled by format.ps. You
might find these programs useful outside of LameTeX. For example, I
wrote a 3D drawing environment which used breakpath.ps for tiling.

\item There
is an appendix at the back on installing LameTeX.

\item The author is a nice guy who will be happy to help you out.
% \begin{stealth} \begin{postscript}
% /Wizard LeftMarginIcon \end{postscript} \end{stealth}
Send e-mail to {\tt jgm@cs.brown.edu}. I would like to know what you think
of LameTeX and if you found it useful. I am also accumulating a list
of enhancements to make to the program and would gratefully receive
your ideas on this subject.

\end{itemize}

\section{Major LaTeX Commands LameTeX Cannot Handle}

The most obvious difference between the two programs is that LameTeX
will never hyphenate words, and will tend to not have quite as nice
spacing as LaTeX does. LameTeX can only produce PostScript code, and
the code it does produce is complicated and therefore a little long.

LameTeX uses the LaTeX fonts and handles the computer modern font
robustly, but it cannot currently handle other font families or normal
PostScript fonts. You cannot use fancy non-ascii characters like
the heart and the copyright symbol.

You cannot define new commands in LameTeX, make boxes around words, or
use fancy document formats like ``titlepage'', or ``letter''. You
cannot do fancy tabbing or horizontal spacing.  Math mode is right
out.

A lot of new functionality will be added in the next version of
LameTeX coming late this year, but for the moment keep in mind that
LameTeX is meant primarily for placing special effects on rather basic
documents. Use normal LaTeX, or cut and paste between the two, if you
need math mode or want to nest lots of TeX code in your LaTeX files.
