1 files changed, 332 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/pstricks/psd-help.tex b/Master/texmf-dist/source/generic/pstricks/psd-help.tex
new file mode 100644
index 00000000000..0c4bf708ab0
--- /dev/null
+++ b/Master/texmf-dist/source/generic/pstricks/psd-help.tex
@@ -0,0 +1,332 @@
+%% 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