%% BEGIN psd-help.tex

\appendix\part*{Help}

\Section{Boxes\label{S-boxes}}

Many of the PSTricks macros have an argument for text that is processed in
restricted horizontal mode (in \LaTeX{} parlance, LR-mode) and then transformed
in some way. This is always the macro's last argument, and it is written
"{<stuff>}" in this \emph{User's Guide}. Examples are the framing, rotating,
scaling, positioning and node macros. I will call these ``LR-box'' macros, and
use framing as the leading example in the discussion below.

In restricted horizontal mode, the input, consisting of regular characters and
boxes, is made into one (long or short) line. There is no line-breaking, nor
can there be vertical mode material such as an entire displayed equation.
However, the fact that you can include another box means that this isn't
really a restriction.

For one thing, alignment environments such as "\halign" or \LaTeX's "tabular"
are just boxes, and thus present no problem. Picture environments and the box
macros themselves are also just boxes. Actually, there isn't a single PSTricks
command that cannot be put directly in the argument of an LR-box macro.
However, entire paragraphs or other vertical mode material such as displayed
equations need to be nested in a "\vbox" or \LaTeX{} "\parbox" or "minipage".
\LaTeX{} users should see "fancybox.sty" and its documentation, "fancybox.doc",
for extensive tips and trick for using LR-box commands.

The PSTricks LR-box macros have some features that are not found in most other
LR-box macros, such as the standard \LaTeX{} LR-box commands.

With \LaTeX{} LR-box commands, the contents is always processed in text mode,
even when the box occurs in math mode. PSTricks, on the other hand, preserves
math mode, and attempts to preserve the math style as well. \TeX{} has four
math styles: text, display, script and scriptscript. Generally, if the box
macro occurs in displayed math (but not in sub- or superscript math), the
contents are processed in display style, and otherwise the contents are
processed in text style (even here the PSTricks macros can make mistakes, but
through no fault of their own). If you don't get the right style, explicitly
include a "\textstyle", "\displaystyle", "\scriptstyle" or
"\scriptscriptstyle" command at the beginning of the box macro's argument.

  In case you want your PSTricks LR-box commands to treat math in the same as
your other LR-box commands, you can switch this feature on and off with the
commands
\begin{Ex}
  \object  \psmathboxtrue
  \object  \psmathboxfalse
\end{Ex}

You can  have commands (such as, but not restricted to, the math style
commands) automatically inserted at the beginning of each LR-box using the
  \Mac  \everypsbox{commands}
command.\footnote{This is a token register.}

If you would like to define an LR-box environment <name> from an LR-box
command <cmd>, use
  \Mac  \pslongbox{name}{cmd}
For example, after
\begin{LVerbatim}
  \pslongbox{MyFrame}{\psframebox}
\end{LVerbatim}
you can write
\begin{LVerbatim}
  \MyFrame <stuff>\endMyFrame
\end{LVerbatim}
instead of
\begin{LVerbatim}
  \psframebox{<stuff>}
\end{LVerbatim}
Also, \LaTeX{} users can write
\begin{LVerbatim}
  \begin{MyFrame} <stuff>\end{MyFrame}
\end{LVerbatim}
It is up to you to be sure that <cmd> is a PSTricks LR-box command; if it
isn't, nasty errors can arise.

Environments like have nice properties:
\begin{itemize}
  \item The syntax is clearer when <stuff> is long.
  \item It is easier to build composite LR-box commands. For example, here is
a framed minipage environment for \LaTeX:
\begin{LVerb}
  \pslongbox{MyFrame}{\psframebox}
  \newenvironment{fminipage}%
    {\MyFrame\begin{minipage}}%
    {\end{minipage}\endMyFrame}
\end{LVerb}
  \item You include verbatim text and other "\catcode" tricks in <stuff>.
\end{itemize}

The rest of this section elaborates on the inclusion of verbatim text in
LR-box environments and commands, for those who are interested. "fancybox.sty"
also contains some nice verbatim macros and tricks, some of which are useful
for LR-box commands.

The reason that you cannot normally include verbatim text in an LR-box
commands argument is that \TeX{} reads the whole argument before processing the
"\catcode" changes, at which point it is too late to change the category
codes. If this is all Greek to you,\footnote{%
Incidentally, many foreign language macros, such as "greek.tex", use
"\catcode" tricks which can cause problems in LR-box macros.} then just try
this \LaTeX{} example to see the problem:
\begin{LVerbatim}
  \psframebox{\verb+\foo{bar}+}
\end{LVerbatim}

The LR-box environments defined with \n\pslongbox{} do not have this problem
because <stuff> is not processed as an argument. Thus, this works:
\begin{example}
  \pslongbox{MyFrame}{\psframebox}
  \MyFrame \verb+\foo{bar}+\endMyFrame
\end{example}

The commands
\begin{Ex}
  \object  \psverbboxtrue
  \object  \psverbboxfalse
\end{Ex}
switch into and out of, respectively, a special PSTricks mode that lets you
include verbatim text in any LR-box command. For example:
\begin{example}
  \psverbboxtrue
  \psframebox{\verb+\foo{bar}+}
\end{example}
However, this is not as robust. You must explicitly group color commands in
<stuff>, and LR-box commands that usually ignore spaces that follow
"{<stuff>}" might not do so when \n\psverbboxtrue{} is in effect.


\Section{Tips and More Tricks\label{tips}}

\faq{How do I rotate/frame this or that with \LaTeX?}

See "fancybox.sty" and its documentation.

\faq{How can I suppress the PostScript so that I can use my document with a
non-PostScript dvi driver?}

Put the command
  \Mac  \PSTricksOff
at the beginning of your document. You should then be able to print or preview
drafts of your document (minus the PostScript, and perhaps pretty strange
looking) with any dvi driver.


\faq{How can I improve the rendering of halftones?}

This can be an important consideration when you have a halftone in the
background and text on top. You can try putting
\begin{LVerb}
  \pstverb{106 45 {dup mul exch dup mul add 1.0 exch sub} setscreen}
\end{LVerb}
before the halftone, or in a header (as in headers and footers, not as in
PostScript header files),  if you want it to have an effect on every page.

"setscreen" is a device-dependent operator.

\faq{What special characters can be active with PSTricks?}

\Section{Including PostScript code\label{S-raw}}

To learn about the PostScript language, consult Adobe's \emph{PostScript
Language Tutorial and Cookbook} (the ``Blue Book''), or Henry McGilton and
Mary Campione's \emph{PostScript by Example} (1992). Both are published by
Addison-Wesley. You may find that the Appendix of the Blue Book, plus an
understanding of how the stack works, is all you need to write simple code for
computing numbers (e.g., to specify coordinates or plots using PostScript).

You may want to define \TeX{} macros for including PostScript fragments in
various places. All \TeX{} macros are expanded before being passed on to
PostScript. It is not always clear what this means. For example, suppose you
write
\begin{LVerb}
  \SpecialCoor
  \def\mydata{23 43}
  \psline(!47 \mydata add)
  \psline(!47 \mydata\ add)
  \psline(!47 \mydata~add)
  \psline(!47 \mydata{} add)
\end{LVerb}
You will get a PostScript error in each of the \n\psline{} commands. To see
what the argument is expanding to, try use \TeX's "\edef" and "\show". E.g.,
\begin{LVerb}
  \def\mydata{23 43}
  \edef\temp{47 \mydata add}
  \show\temp
  \edef\temp{47 \mydata\ add}
  \show\temp
  \edef\temp{47 \mydata~add}
  \show\temp
  \edef\temp{47 \mydata{} add}
  \show\temp
\end{LVerb}
\TeX{} expands the code, assigns its value to "\temp", and then displays the
value of "\temp" on your console. Hit <return> to procede. You fill find that
the four samples expand, respectively, to:
\begin{LVerb}
  47 23 43add
  47 23 43\ add
  47 23 43\penalty \@M \ add
  47 23 43{} add
\end{LVerb}
All you really wanted was a space between the "43" and "add". The command
"\space" will do the trick:
\begin{LVerb}
  \psline(!47 \mydata\space add)
\end{LVerb}

You can include balance braces "{"~"}"; these will be passed on verbatim to
PostScript. However, to include an unbalanced left or right brace, you have to
use, respectively,
\begin{Ex}
  \object  \pslbrace
  \object  \psrbrace
\end{Ex}
Don't bother trying "\}" or "\{".

Whenever you insert PostScript code in a PSTricks argument, the dictionary on
the top of the dictionary stack is "tx@Dict", which is PSTrick's main
dictionary. If you want to define you own variables, you have two options:
\begin{description}
  \item[Simplest] Always include a "@" in the variable names, because PSTricks
never uses "@" in its variables names. You are at a risk of overflowing the
"tx@Dict" dictionary, depending on your PostScript interpreter. You are also
more likely to collide with someone else's definitions, if there are multiple
authors contributing to the document.
  \item[Safest] Create a dictionary named "TDict" for your scratch
computations. Be sure to remove it from the dictionary stack at the end of any
code you insert in an argument. E.g.,
\begin{LVerb}
  TDict 10 dict def TDict begin <your code> end
\end{LVerb}
\end{description}

\section{Troubleshooting\label{troubleshooting}}
\setcounter{faq}{0}

\faq{Why does the document bomb in the printer when the first item in a
\LaTeX{} file is a float?}

When the first item in a \LaTeX{} file is a float, "\special"'s in the preamble
are discarded. In particular, the "\special" for including PSTricks's header
file is lost. The workaround is to but something before the float, or to
include the header file by a command-line option with your dvi-to-ps driver.

\faq{I converted a \texttt{.dvi} file to PostScript, and then mailed it to a
colleague. It prints fine for me but bombs on her printer.}

Here is the most likely (but not the only) cause of this problem. The
PostScript files you get when using PSTricks can contain long lines. This
should be acceptable to any proper PostScript interpreter, but the lines can
get chopped when mailing the file. There is no way to fix this in PSTricks,
but you can make a point of wrapping the lines of your PostScript files when
mailing them. E.g., on UNIX you can use "uuencode" and "uudecode", or you can
use the following AWK script to wrap the lines:
\begin{LVerb}
  #! /bin/sh
  # This script wraps all lines
  # Usage (if script is named wrap):
  #    wrap < infile > outfile
  awk '
  BEGIN {
    N = 78    # Max line length
  }
  {  if (length($0)<=N)
      print
    else {
      currlength = 0
      for (i = 1; i <=NF; i++) {
        if ((currlength = currlength + length($i) + 1) > N) {
          printf "\n"
          printf "%s", $i
          currlength = length($i)
          }
        else
          printf \ %s", $i
        }
      printf "\n"
    }
  } '
\end{LVerb}

\faq{The color commands cause extraneous vertical space to be inserted.}

For example, this can happen if you start a \LaTeX{} "\parbox" or a "p{}"
column with a color command. The solution usually is to precede the color
command with "\leavevmode".


\faq{The color commands interfere with other color macros I use.}

Try putting the command \Main\altcolormode{} at the beginning of your document.
This may or may not help. Be extra careful that the scope of color commands
does not extend across pages. This is generally a less robust color scheme.

\faq{How do I stop floats from being the same color as surrounding material?}

That's easy: Just put an explicit color command at the beginning of the float,
e.g., \n\black.

\faq{When I use some color command in box macros or with \texttt{\string\setbox},
the colors get all screwed up.}

\label{colorboxproblems}%
If "\mybox" is a box register, and you write
\begin{LVerb}
  \green Ho Hum.
  \setbox\mybox=\hbox{Foo bar \blue fee fum}
  Hi Ho. \red Diddley-dee
  \box\mybox hum dee do
\end{LVerb}
then when "\mybox" is inserted, the current color is red and so "Foo bar"
comes out red (rather than green, which was the color in effect when the box
was set). The command that returns from \n\blue{} to the current color "green",
when the box is set, is executed after the "\hbox" is closed, which means that
"Hi Ho" is green, but "hum dee do" is still blue.

This odd behavior is due to the fact that \TeX{} does not support color
internally, the way it supports font commands. The first thing to do is to
explicitly bracket any color commands inside the box. Second, be sure that the
current color is black when setting the box. Third, make other explicit color
changes where necessary if you still have problems. The color scheme invoked
by \n\altcolormode{} is slightly better behaved if you follow the first two
rules.

Note that various box macros use "\setbox" and so these anomalies can arise
unexpectedly.

\endinput

%% END psd-help.tex
