braids (8may19)

git-svn-id: svn://tug.org/texlive/trunk@51048 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 481 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/braids/braids.tex b/Master/texmf-dist/doc/latex/braids/braids.tex
new file mode 100644
index 00000000000..7dab9f08738
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/braids/braids.tex
@@ -0,0 +1,481 @@
+\documentclass{ltxdoc}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{morefloats}
+\usepackage{tikz}
+\usepackage{braids}
+\usetikzlibrary{braids}
+\usepackage[numbered]{hypdoc}
+\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9} 
+ 
+\usepackage{listings}
+\lstloadlanguages{[LaTeX]TeX}
+\lstset{breakatwhitespace=true,breaklines=true,language=TeX}
+ 
+\usepackage{fancyvrb}
+
+\newenvironment{example}
+  {\VerbatimEnvironment
+   \begin{VerbatimOut}{example.out}}
+  {\end{VerbatimOut}
+   \begin{center}
+   \setlength{\parindent}{0pt}
+   \fbox{\begin{minipage}{.9\linewidth}
+     \lstset{breakatwhitespace=true,breaklines=true,language=TeX,basicstyle=\small}
+     \lstinputlisting[]{example.out}
+   \end{minipage}}
+
+   \fbox{\begin{minipage}{.9\linewidth}
+     \input{example.out}
+   \end{minipage}}
+\end{center}
+}
+
+\providecommand*{\url}{\texttt}
+\GetFileInfo{tikzlibrarybraids.code.tex}
+
+\title{The \textsf{braids} Package: Documentation}
+\author{Andrew Stacey \\ \texttt{loopspace@mathforge.org}}
+\date{\fileversion~from \filedate}
+
+\begin{document}
+
+\maketitle
+
+\begin{center}
+  \begin{tikzpicture}
+  \pic[
+    line width=1.5pt,
+    red,
+    line cap=round,
+    braid/.cd,
+    width=.75cm,
+    height=.5cm,
+    strand 3/.style={gray,line width=1pt},
+    strand 6/.style={gray,line width=1pt},
+    strand 7/.style={gray,line width=1pt},
+    strand 10/.style={gray,line width=1pt},
+    strand 14/.style={gray,line width=1pt},
+    strand 15/.style={gray,line width=1pt},
+    strand 16/.style={gray,line width=1pt},
+    strand 18/.style={gray,line width=1pt},
+  ] {braid={s_1-s_4-s_8-s_{12}-s_{16} s_2-s_5-s_7-s_9-s_{13}-s_{15} s_2-s_5-s_7-s_9-s_{15} s_1-s_4-s_8-s_{16} s_1-s_4-s_7-s_9-s_{17} s_2-s_5-s_{17} s_2-s_{13}-s_{16} s_1-s_{12}-s_{15}}};
+\end{tikzpicture}
+\end{center}
+
+\section{Introduction}
+
+This is a package for drawing braid diagrams using PGF/TikZ.
+An example follows.
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\pic[
+  rotate=90,
+  braid/.cd,
+  every strand/.style={ultra thick},
+  strand 1/.style={red},
+  strand 2/.style={green},
+  strand 3/.style={blue},
+] {braid={s_1 s_2^{-1} s_1 s_2^{-1} s_1 s_2^{-1}}};
+\end{tikzpicture}
+\end{center}
+\end{example}
+
+\section{TikZ Library Usage}
+
+Version 2.0 changed the implementation to use the TikZ \Verb+pic+ syntax.
+It also converted it to a TikZ library, so to use it put the following in the preamble.
+
+\begin{verbatim}
+\usetikzlibrary{braids}
+\end{verbatim}
+
+(Or add it to the copious list of TikZ libraries that you are already using.)
+
+\bigskip
+
+\DescribeMacro{braid}
+A braid is specified by the pic name \Verb+braid+.
+The usual syntax for this is as follows:
+
+\Verb+\pic[options] at (coordinate) {braid={braid-word}};+
+
+\DescribeMacro{braid-word}
+The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1} s_{3,5}+.
+The generator labels are not significant.
+If the subscript is a single number, as in \Verb+s_2+, the crossing goes from that number over the next.
+If the subscript is two numbers, as in \Verb+s_{2,4}+, the crossing goes from the first over the second, with both the crossing strands passing over all of the intervening strands.
+The exponent can be \Verb+1+, \Verb+{-1}+, or missing (in which case it defaults to \Verb+1+, note also that the exponent is read as a \TeX-token so \Verb+{1}+ is also legal).
+If the exponent is \(-1\) then the over and under strands swap.
+
+\begin{itemize}
+\item \Verb+s_1+ is strand \(1\) over strand \(2\).
+\item \Verb+s_1^{-1}+ is strand \(2\) over strand \(1\).
+\item \Verb+s_{1,3}+ is strand \(1\) over strand \(3\), and both are over strand \(2\).
+\end{itemize}
+
+Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid.
+These extras are as follows.
+
+\begin{enumerate}
+\item To get crossings to render at the same height, separate them with a hyphen (note: no check is made to ensure that the crossings can legally be put at the same height; \emph{caveat emptor}).
+For example, \Verb+s_1-s_3+.
+
+\item To draw a \emph{floor} -- which is a rectangle behind the braid occupying some number of levels (the default being one level) -- precede the braid element by a vertical line, as in \Verb+s_1 | s_2+.
+The floor is itself a pic which, by default, consists of a rectangle and two horizontal lines.
+The rectangle picks up any \Verb+fill+ options and the lines any \Verb+draw+ options that are set in the \Verb+braid/every floor+ and \Verb+braid/floor <n>+ styles.
+The \Verb+n+ is the level number, starting at \(1\).
+
+More general floors can be drawn using the key \Verb+braid/add floor+.
+This takes one argument which is a comma separated list of parameters that specifies the position and size floor:
+%
+\begin{verbatim}
+braid/add floor={x,y,width,height,name}
+\end{verbatim}
+%
+The units used are the ``natural'' units of the braid: strand separation and level height.
+The \Verb+name+ is optional and if given can be used to style the floor in that the style \Verb+braid/floor <name>+ is applied to that floor.
+
+Replacing the floor pic will change how it is drawn.
+The coordinate system is set up for the floor pic so that the floor is a unit square with lower left corner at the origin.
+
+\item The identity element can occur in the braid-word.
+It is represented by \Verb+1+.
+This inserts the identity which corresponds to no crossing.
+However, it takes the same amount of space as if there were a crossing.
+
+\end{enumerate}
+
+\subsection{Style Options}
+\label{sec:picstyleopts}
+
+There are various keys that change the behaviour or rendering of the braid.
+All of these are in the \Verb+/tikz/braid/+ namespace.
+
+\DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid.
+The number of strands will grow according to the terms in the braid word so this merely sets a lower bound.
+If not set, the number of strands will be determined by the terms in the braid word.
+
+\DescribeMacro{height}
+The key \Verb+height+ sets the height of the piece of the braid corresponding to an element in the group.
+This can be negative.
+
+\DescribeMacro{width}
+The key \Verb+width+ sets the separation of the strands in the braid.
+This can be negative.
+
+\DescribeMacro{border height}
+The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid.
+
+\DescribeMacro{gap}
+The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing.
+This should be a number strictly between 0 and .5.
+The curve is drawn using a cubic bezier and the gap is in terms of the time parameter, so the gap will not increase exactly proportionally to the value given by this key, though that is a reasonable approximation.
+
+\DescribeMacro{control factor}
+As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve.
+The control points are vertically above or below their respective end point.
+This key determines that vertical separation.
+It is multiplied by the \Verb+height+ so that it scales properly.
+It can be set to 0 whereupon the strands in the crossing are straight lines.
+The default is 0.5.
+
+\DescribeMacro{nudge factor}
+The crossings are not quite placed one after another.
+There is a small ``nudge'' between the end of one crossing and the start of another.
+Due to the way that the strands are lengthened, if there is no ``nudge'' then some PDF renderers produce slightly strange results at certain magnifications.
+This key controls how much that ``nudge'' is, as a factor of the \Verb+height+.
+For the aforementioned reason, it should not be set to 0 (the default is 0.05).
+Note that this does not change the height of a crossing.
+Rather, it nudges the height at which the strands start to cross over.
+
+\DescribeMacro{every strand, strand <n>}
+The style of the strands are controlled by two types of option.
+Style options that are set on the \Verb+pic+ are passed to every strand.
+It is also possible to add style options to individual strands using the keys \Verb+every strand+ and \Verb+strand <n>+.
+The strands are numbered by their starting position.
+
+\DescribeMacro{every floor, floor <n>}
+When a floor is requested behind a crossing, it is rendered as a pic.
+These keys control how the floor is styled.
+
+\subsection{Coordinates and Anchors}
+
+The braid is littered with coordinates.
+Each strand gets a coordinate at each end, and at every level between crossings.
+These are labelled and numbered by the initial strand position and the crossing level.
+They are also labelled and numbered by the final strand position with the prefix \Verb+rev+.
+With a \Verb+name prefix+, the coordinate names look like the following:
+%
+\begin{verbatim}
+<name prefix>-<strand number>-<crossing number>
+<name prefix>-rev-<strand number>-<crossing number>
+\end{verbatim}
+%
+The crossing number can also be either \Verb+s+ or \Verb+e+ for the start and end of the strand.
+Note that \Verb+-1-0+ and \Verb+-1-s+ are slightly different in that \Verb+s+ includes the border height.
+
+\DescribeMacro{anchor}
+The key \Verb+anchor+ (in the \Verb+braid+ name space) can be used to shift the braid so that a different part of it is at the specified location.
+It uses the same syntax as the coordinates, except without the \Verb+<name prefix>-+.
+In the following example, the braid is shifted so that where the third strand starts the second level is at the position \Verb+(1,1)+
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\fill[purple] (1,1) circle[radius=3mm];
+\pic[braid/anchor=3-2,rotate=90] at (1,1) {braid={s_2 s_1 s_2 s_1}};
+\end{tikzpicture}
+\end{center}
+\end{example}
+
+
+\section{Examples}
+
+Here are more detailed examples.
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\pic[
+  braid/every floor/.style={fill=yellow},
+  braid/floor 1/.style={draw=black,dashed,fill=yellow!50!green},
+  line width=2pt,
+  braid/strand 1/.style={red},
+  braid/strand 2/.style={blue},
+  braid/strand 3/.style={green},
+  braid/add floor={2,4,3,2,a},
+  braid/floor a/.style={fill=pink},
+  name prefix=braid,
+] at (2,0) {braid={| s_1-s_3-s_5 | s_2^{-1}-s_4| s_1-s_4 s_2^{-1} s_1-s_3 s_2^{-1}-s_4^{-1}}};
+\fill[yellow] (2,0) circle (4pt);
+\node[at=(braid-3-s),pin=north west:strand 3 start] {};
+\node[at=(braid-3-e),pin=south west:strand 3 end] {};
+\node[at=(braid-rev-3-s),pin=north east:strand 3 (from bottom) start] {};
+\node[at=(braid-rev-3-e),pin=south east:strand 3 (from bottom) end] {};
+\end{tikzpicture}
+\end{center}
+\end{example}
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\pic[
+  braid/.cd,
+  number of strands=3,
+  line width=8pt,
+  strand 1/.style={red},
+  strand 2/.style={green},
+  strand 3/.style={blue},
+  gap=0.1,
+  control factor=0,
+  nudge factor=0,
+  name prefix=braid,
+] {braid={a_2 a_1 a_2^{-1} a_1}};
+\node[circle,draw,fill=white,inner sep=0pt] at (braid-2-1) {\(+\)};
+\node[circle,draw,fill=white,inner sep=0pt] at (braid-3-1) {\(-\)};
+\node[circle,draw,fill=white,inner sep=0pt] at (braid-2-3) {\(+\)};
+\end{tikzpicture}
+\end{center}
+
+\end{example}
+
+\newpage
+
+\section{Original Package Usage (Depreciated)}
+
+The original version was as a separate package.
+This is still included for backwards compatibility.
+To use this package, you need to put the following in the preamble.
+
+\begin{verbatim}
+\usepackage{braids}
+\end{verbatim}
+
+\DescribeMacro{\braid}
+A braid is specified by the command \Verb+\braid+.
+The syntax for this command is as follows:
+
+\Verb+\braid[style options] (name) at (coordinate) braid-word;+
+
+\DescribeMacro{braid-word}
+The \Verb+braid-word+ is an expression in the braid group, such as \Verb+s_1 s_2^{-1}+.
+The generator labels are not significant.
+The exponent can be \Verb+1+, \Verb+{-1}+, or missing (in which case it defaults to \Verb+1+, note also that the exponent is read as a \TeX-token so \Verb+{1}+ is also legal).
+Certain other symbols are allowed in the \Verb+braid-word+ which control the rendering of the braid.
+These extras are as follows.
+
+\begin{enumerate}
+\item To get crossings to render at the same height, separate them with a hyphen (note: no check is made to ensure that the crossings can legally be put at the same height; \emph{caveat emptor}).
+
+\item To draw a \emph{floor}, precede the braid element by a vertical line.
+What happens then is that when the braid is rendered, the coordinates of the rectangle behind that crossing (wide enough to encompass all the strands) is passed to a command.
+The intention is that this command draw something behind the braid.
+The command is configurable by a key (see \ref{sec:styleopts}).
+
+\item The identity element can occur in the braid-word.
+It is represented by \Verb+1+.
+This inserts the identity which corresponds to no crossing.
+However, it takes the same amount of space as if there were a crossing.
+
+\item Strands can be labelled between crossings.
+To do this, the commands \Verb+\label+, \Verb+\olabel+, and \Verb+\clabel+ are provided.
+These take three arguments, the first is optional.
+The result of this command is to place a node on top of a particular strand between the crossings where the command is given.
+The first (optional) argument can be used to pass style options to this node.
+The second argument is the strand number.
+The third argument is the label text.
+
+The three commands differ as to how they interpret the strand number.
+For \Verb+\olabel+, the strand number is taken to mean the strand that starts at that position.
+For \Verb+\clabel+, the strand number is taken to mean the strand that is currently at that position.
+The behaviour of \Verb+\label+ is to choose one or other of these depending on whether the key \Verb+strand label by origin+ is true or false.
+This key only has an effect at the start of the braid-word; it cannot be reset in the middle.
+
+\item Style options can be given in the middle of a braid-word by enclosing them in square brackets.
+There are not many style options that it makes sense to change in the middle of the braid-word, since the strands are rendered all in one go at the end.
+
+\item Scoping is handled by using braces.
+Thus to change a style only briefly, enclose the desired scope in braces.
+\end{enumerate}
+
+\DescribeMacro{name}
+The (optional) \Verb+name+ acts a little like the \Verb+name+ of a TikZ node.
+When it is specified, the routine that renders the braid also saves certain coordinates as if they were node anchors.
+Specifically, \Verb+coordinate+ nodes are placed at the centre of the braid diagram and at the ends of each strand.
+The centre has the label \Verb+name+, the strands are labelled \Verb+name-number-end+ and \Verb+name-rev-number-end+, where \Verb+name+ is the name given to the braid, \Verb+number+ is the number of the strand counting from the left, and \Verb+end+ is either \Verb+s+ for the start or \Verb+e+ for the end.
+If the version with \Verb+rev+ is used then the numbers correspond to the \emph{final} positions of the braids.
+The name can also be specified with the \Verb+name+ key.
+
+\DescribeMacro{at}
+The (optional) \Verb+at (coordinate)+ syntax positions the braid at the \Verb+coordinate+ in the current picture.
+Due to the implementation, the coordinate has to be known at the start, but the width and height of the braid are only known at the end.
+Therefore, the braid is positioned so that the start of the first strand is at \Verb+(coordinate)+.
+This can also be specified using the \Verb+at+ key.
+
+\DescribeMacro{style options}
+The \Verb+style options+ set the style for the braid strands.
+They can be grouped into three types: options that set up the main parameters for the braid, options that set the default style for the strands, and options that set up styles for individual strands.
+The options are as follows.
+
+\subsection{Style Options}
+\label{sec:styleopts}
+
+\DescribeMacro{number of strands} The key \Verb+number of strands+ sets the minimum number of strands for the braid.
+The number of strands will grow according to the terms in the braid word so this merely sets a lower bound.
+If not set, the number of strands will be determined by the terms in the braid word.
+
+\DescribeMacro{height}
+The key \Verb+height+ sets the height of the piece of the braid corresponding to an element in the group.
+
+\DescribeMacro{width}
+The key \Verb+width+ sets the separation of the strands in the braid.
+
+\DescribeMacro{border height}
+The key \Verb+border height+ adds a little extra length to the strands at the start and end of the braid.
+
+\DescribeMacro{gap}
+The key \Verb+gap+ is used to determine how much of a gap to leave in the under strand at a crossing.
+This should be a number strictly between 0 and .5.
+The curve is drawn using a cubic bezier and the gap is in terms of the time parameter, so the gap will not increase exactly proportionally to the value given by this key, though that is a reasonable approximation.
+
+\DescribeMacro{control factor}
+As just said, the parts of the strands involved in a crossing are drawn using a cubic bezier curve.
+The control points are vertically above or below their respective end point.
+This key determines that vertical separation.
+It is multiplied by the \Verb+height+ so that it scales properly.
+It can be set to 0 whereupon the strands in the crossing are straight lines.
+The default is 0.5.
+
+\DescribeMacro{nudge factor}
+The crossings are not quite placed one after another.
+There is a small ``nudge'' between the end of one crossing and the start of another.
+Due to the way that the strands are lengthened, if there is no ``nudge'' then some PDF renderers produce slightly strange results at certain magnifications.
+This key controls how much that ``nudge'' is, as a factor of the \Verb+height+.
+For the aforementioned reason, it should not be set to 0 (the default is 0.05).
+Note that this does not change the height of a crossing.
+Rather, it nudges the height at which the strands start to cross over.
+
+\DescribeMacro{style strands}
+The style of the strands are controlled by two types of option.
+Style options that are set on the \Verb+\braid+ command are passed to every strand.
+It is also possible to add style options to individual strands using the key \Verb+style strands+.
+This takes two options, a comma-delimited list of strand numbers (which could be just a single number) and a list of options to be applied to that strand.
+Thus, the syntax is \Verb+style strands={n,m,...}{options}+.
+The strands are numbered by their starting position.
+Not all of the standard TikZ style options are possible due to the way that the strands are constructed.
+Basically, the options that are allowed are those that do not require changing the path or drawing it more than once.
+
+\DescribeMacro{floor command}
+When a floor is requested behind a crossing, the actual way to render it is determined by a command.
+This key allows the user to define that command.
+The argument to this key should be the code that should be executed for each floor.
+To avoid the hassle of getting the number of hashes right, the command should take no arguments.
+Rather, the coordinates of the rectangle are saved in to macros \Verb+\floorsx+, \Verb+\floorsy+, \Verb+\floorex+, \Verb+\floorey+ (these macros will expand to something like \Verb+10pt+) and the command should use these to position the drawing.
+The default is to draw a line at the top and at the bottom of the rectangle.
+
+\DescribeMacro{style floors}
+\DescribeMacro{style all floors}
+In the spirit of separating \emph{style} and \emph{content}, the style options for the floors can be specified separately to the command (of course, they could be built in to the command).
+One advantage of this over building them in to the command is to allow them to be overridden for individual floors.
+The \Verb+style all floors+ sets up options to be used for \emph{all} floors, whilst the \Verb+style floors={n,m,...}{options}+ sets up options to be used only for the listed floor.
+Anything specified in the \Verb+floor command+ will take precedence over both of these.
+
+Any other style options are passed to the underlying TikZ/PGF system and so may influence how the braid is drawn (but note that not all keys make sense due to the implementation).
+
+
+\section{Examples}
+
+Here are more detailed examples.
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\braid[
+  style all floors={fill=yellow},
+  style floors={1}{dashed,fill=yellow!50!green},
+  floor command={%
+   \fill (\floorsx,\floorsy) rectangle (\floorex,\floorey);
+   \draw (\floorsx,\floorsy) -- (\floorex,\floorsy);
+  },
+  line width=2pt,
+  style strands={1}{red},
+  style strands={2}{blue},
+  style strands={3}{green}
+] (braid) at (2,0) | s_1-s_3-s_5 | s_2^{-1}-s_4| s_1-s_4 s_2^{-1} s_1-s_3 s_2^{-1}-s_4^{-1};
+\fill[yellow] (2,0) circle (4pt);
+\fill[purple] (braid) circle (4pt);
+\node[at=(braid-3-s),pin=north west:strand 3] {};
+\node[at=(braid-3-e),pin=south west:strand 3] {};
+\node[at=(braid-rev-3-s),pin=north east:strand 3 (from bottom)] {};
+\node[at=(braid-rev-3-e),pin=south east:strand 3 (from bottom)] {};
+\end{tikzpicture}
+\end{center}
+\end{example}
+
+\begin{example}
+\begin{center}
+\begin{tikzpicture}
+\braid[
+  number of strands=3,
+  line width=8pt,
+  style strands={1}{red},
+  style strands={2}{green},
+  style strands={3}{blue},
+  gap=0.1,
+  control factor=0,
+  nudge factor=0,
+  strand label by origin=true,
+  strand label/.style={circle,draw,fill=white,inner sep=0pt},
+  yscale=1] (braid_1) a_2 \label{2}{\(+\)} \clabel{2}{\(-\)} a_1 a_2^{-1} \olabel{2}{\(+\)} a_1;
+\end{tikzpicture}
+\end{center}
+
+\end{example}
+
+\end{document}
+% Local Variables:
+% tex-output-type: "pdf18"
+% End: