From eddf3073a8f4953603e7a5d21fcbba7d1104d502 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 22 Feb 2021 21:52:11 +0000
Subject: spath3 (22feb21)

git-svn-id: svn://tug.org/texlive/trunk@57842 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/latex/spath3/spath3.tex | 272 ++++++++++++++++++--------
 1 file changed, 185 insertions(+), 87 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/spath3/spath3.tex')

diff --git a/Master/texmf-dist/doc/latex/spath3/spath3.tex b/Master/texmf-dist/doc/latex/spath3/spath3.tex
index 49b897c4816..7621db4a287 100644
--- a/Master/texmf-dist/doc/latex/spath3/spath3.tex
+++ b/Master/texmf-dist/doc/latex/spath3/spath3.tex
@@ -56,6 +56,8 @@
 
   \maketitle
 
+\tableofcontents
+
   \section{Introduction}
 
   The \texttt{spath3} package was originally designed as a low-level package for manipulating the \emph{soft paths} defined by PGF/TikZ.
@@ -124,59 +126,61 @@ Clones one soft path into another.
 In the second, the clone is global (the original need not be).
 \end{function}
 
-\begin{function}{restore, restore reverse}
+\begin{function}{use}
 \begin{syntax}
-|restore=|\meta{name}
-|restore reverse=|\meta{name}
+|use=|\meta{name}
+|use=|\marg{name, options}
 \end{syntax}
 
-Restores a previously saved soft path to the current path.
-The \Verb+reverse+ version reverses the soft path first.
-This happens immediately so can be issued in the options to the main command and then the path can be extended with normal drawing commands.
-Any keys that affect the soft path directly should be applied \emph{before} this one.
+This uses a previously saved soft path at the current juncture in the path declaration.
+If before the path has begun, it is the initial part of the new path.
+If during the path construction then it is stuck in at the current place.
+Note that any keys that affect the soft path directly should be applied \emph{before} this one.
+
+The path can be modified first by using the second form -- note that as far as the \Verb+use+ key is concerned, the whole thing is a single argument.
+The options is a comma separated list and can include:
+%
+\begin{itemize}
+\item |reverse| reverses the inserted path first.
+\item |weld|, |no weld| determines whether to weld the inserted path to the current path.
+Welding means that the |move to| at the start of the inserted path is removed.
+Note that this doesn't \emph{move} the inserted path so this will usually modify the first segment of the inserted path, possibly in unexpected ways.
+\item |move|, |no move| determines whether the inserted path is translated so that it starts where the current path ends.
+\item |transform=|\marg{transformations} applies the specified transformations to the inserted path.
+See the |transform| key in Section~\ref{sec:transform}
+\item Any other key is taken as the name of the path (so it doesn't have to be specified first) with the last one winning.
+\end{itemize}
 
 One thing should be noted about transformations.
 By the time a soft path is built, all available transformations have been applied.
 This means that when re-inserting a soft path back into a high level command (such as |\draw|), the effect of existing transformations might produce some confusing effects.
 When restoring a path then the library tries to set up various internals of TikZ correctly, but there may be some things I've overlooked or not accounted for particularly with regard to existing transformations; if you spot anything working oddly then please report it to me.
 
-Restoring a path also sets things right for positioning nodes along the path.
+In particular, restoring a path should sets things right for positioning nodes along the path.
 Using the \Verb+pos=D+ key on a node positions that node at a particular point on the path.
 Exactly how the parameter is interpreted is the same as for the \Verb+spath+ coordinate system described in Section~\ref{sec:coordinates}.
 \end{function}
 
 \begin{function}{
+  restore,
+  restore reverse
+  insert,
+  insert reverse,
   append,
   append reverse,
   append no move,
   append reverse no move
 }
-\begin{syntax}
-|append=|\meta{name}
-|append reverse=|\meta{name}
-|append no move=|\meta{name}
-|append reverse no move=|\meta{name}
-\end{syntax}
-
-This inserts a soft path, or its reverse, into the path at the current point, it is therefore more suited to being used part way through a path construction.
-In a sense, it is a little like a \texttt{pic} in that it enables the user to construct a path segment early to be reused at various places.
 
-The path is \emph{welded} on to the current path, meaning that the intervening \Verb+move+ is removed.
-This is particularly useful for creating filled regions.
-The first two versions translate the path so that it starts at the last point on the existing path, the second two versions don't do this translation (the intention being that in such a case the translation is omitted because it is \emph{unnecessary} rather than simply not wanted because the effect of removing the intervening move will adjust the initial segment of the appended path otherwise).
+These are all aliases to various versions of \Verb+use+ (they originally existed as separate code before I united them all as variants of \Verb+use+).
+The equivalences are:
 
-As with restoring a path, the last point and node positioning machinery is established.
-The positioning is relative to the appended part of the path, not the full path.
-\end{function}
-
-\begin{function}{insert, insert reverse}
-\begin{syntax}
-|insert=|\meta{name}
-|insert reverse=|\meta{name}
-\end{syntax}
-
-Like \Verb+append+ except that it doesn't remove the intervening \Verb+move+ and doesn't translate the inserted path.
-The \Verb+reverse+ version reverses the path first.
+\begin{itemize}
+\item |restore| and |insert| are aliases for |use|.
+\item |append| sets the |move| and |weld| keys.
+\item |append no move| just sets the |weld| key.
+\item |reverse| sets the |reverse| key.
+\end{itemize}
 \end{function}
 
 \begin{function}{to}
@@ -191,6 +195,7 @@ The path is transformed by rotation, translation, and uniform scaling so that it
 
 
 \subsection{Transformation Routines}
+\label{sec:transform}
 
 The following keys all apply some sort of transformation to the soft path.
 They do not render the path, but simply adjust it.
@@ -236,40 +241,6 @@ This transforms the named path so that it goes from the start point to the end p
 As with the \Verb+to+ path construction and the \Verb+splice+ method, this won't work if the path ends very close to where it starts.
 \end{function}
 
-\begin{function}{splice, splice global}
-\begin{syntax}
-|splice=|\marg{initial path}\marg{splice path}\marg{final path}
-|splice globally=|\marg{initial path}\marg{splice path}\marg{final path}
-\end{syntax}
-
-This splices the middle path into the gap between the initial and final paths.
-The middle path is transformed to fit (don't try this with a path whose starting and ending points are close together) and the paths are joined so that the last component of the initial path and the first component of the splice path become a single component, and similarly at the other end.
-\end{function}
-
-\begin{function}{join components with, join components globally with}
-\begin{syntax}
-|join components with=|\marg{path}\marg{splice path}
-|join components globally with=|\marg{path}\marg{splice path}
-\end{syntax}
-
-This inserts the |splice path| in the gaps between components of |path|.
-A \emph{spot weld} is performed first to join any components where the end of one is the start of the next.
-The result is a single component path.
-This does \emph{not} close the resulting path, for that see the key |close with|.
-\end{function}
-
-\begin{function}{close, close globally, close with, close globally with}
-\begin{syntax}
-|close=|\marg{path}
-|close globally=|\marg{path}
-|close with=|\marg{path}\marg{splice path}
-|close globally with=|\marg{path}\marg{splice path}
-\end{syntax}
-
-These all close the last component of the given path.
-The first two will insert a line segment if the initial and final points of the component are not sufficiently close.
-The latter two allow you to specify another path to insert.
-\end{function}
 
 \subsection{Intersection Routines}
 
@@ -317,6 +288,20 @@ The second path is not changed.
 This inserts breaks into a pair of paths at their mutual intersections.
 \end{function}
 
+\begin{function}{
+  replace lines,
+  replace lines globally
+}
+\begin{syntax}
+|replace lines=|\meta{path}
+|replace lines globally=|\meta{path}
+\end{syntax}
+
+The PGF intersection routines have difficulties with parallel, or near parallel, lines.
+One way to counter this is to replace all line segments by ``curves''.
+This is done so that the parametrisation of the curve matches that of the line segment that it is replacing.
+\end{function}
+
 \subsection{Working with Components}
 
 \begin{function}{
@@ -335,7 +320,7 @@ The macro can be used in a |\foreach|.
 
 The macro consists of a comma separated list of names of the components (the actual names used are of the form \Verb+anonymous_N+).
 To access an individual component, use the command \Verb+\getComponentOf+.
-This can be used directly in place of a path name in any other key, such as \Verb+restore+, (it is just the \LaTeX3 command \Verb+\clist_item:Nn+).
+This can be used directly in place of a path name in any other key, such as \Verb+use+, (it is just the \LaTeX3 command \Verb+\clist_item:Nn+).
 
 Note that these are \emph{copies} of the components of the original path.
 Changing a component doesn't update the original path.
@@ -365,11 +350,14 @@ It applies the following styles (in this order):
 }
 \begin{syntax}
 |insert gaps after components=|\marg{path}\marg{gap}\marg{components}
+|insert gaps after components=|\marg{path}\marg{gap}
 |insert gaps globally after components=|\marg{path}\marg{gap}\marg{components}
+|insert gaps globally after components=|\marg{path}\marg{gap}
 \end{syntax}
 
 This inserts a gap between components of a path by shortening the end of the specified component and start of the next one.
 The list of components is passed through a |\foreach| loop so that syntax like |2,4,...,16| can be used.
+If the list of components is not given the gaps are inserted between all components.
 \end{function}
 
 \begin{function}{
@@ -386,6 +374,31 @@ The list of components is processed by |\foreach|.
 If the component is the first one then it is joined to the last component.
 \end{function}
 
+\begin{function}{join components with, join components globally with, join components upright with, join components globally upright with}
+\begin{syntax}
+|join components with=|\marg{path}\marg{splice path}
+|join components with=|\marg{path}\marg{splice path}\marg{list}
+|join components upright with=|\marg{path}\marg{splice path}
+|join components upright with=|\marg{path}\marg{splice path}\marg{list}
+|join components globally with=|\marg{path}\marg{splice path}
+|join components globally with=|\marg{path}\marg{splice path}\marg{list}
+|join components globally upright with=|\marg{path}\marg{splice path}
+|join components globally upright with=|\marg{path}\marg{splice path}\marg{list}
+\end{syntax}
+
+This inserts the |splice path| in the gaps between components of |path| specified by a comma separated list.
+The splice is inserted between each specified component and the next one.
+If the \marg{list} is not given (or is empty) then the splice is inserted between every component except that a \emph{spot weld} is performed first to join any components where the end of one is the start of the next.
+The spot weld is only performed if the list of components is empty.
+
+This does \emph{not} close the resulting path, even if the last component is specified in the list, for that see the key |close with|.
+
+Note that because there is an optional third argument to this key, the second argument must always be enclosed in braces unless it is a single token.
+
+The |upright| versions do a little test to see if the gap is oriented upside-down and if so then they insert the reflection of the splice path.
+\end{function}
+
+
 \begin{function}{
   spot weld,
   spot weld globally
@@ -423,6 +436,31 @@ This removes the listed components of the path.
 As with other list routines, the list is parsed via |foreach| first.
 \end{function}
 
+
+\begin{function}{close, close globally, close with, close globally with}
+\begin{syntax}
+|close=|\marg{path}
+|close globally=|\marg{path}
+|close with=|\marg{path}\marg{splice path}
+|close globally with=|\marg{path}\marg{splice path}
+\end{syntax}
+
+These all close the last component of the given path.
+The first two will insert a line segment if the initial and final points of the component are not sufficiently close.
+The latter two allow you to specify another path to insert.
+\end{function}
+
+\begin{function}{splice, splice global}
+\begin{syntax}
+|splice=|\marg{initial path}\marg{splice path}\marg{final path}
+|splice globally=|\marg{initial path}\marg{splice path}\marg{final path}
+\end{syntax}
+
+This splices the middle path into the gap between the initial and final paths.
+The middle path is transformed to fit (don't try this with a path whose starting and ending points are close together) and the paths are joined so that the last component of the initial path and the first component of the splice path become a single component, and similarly at the other end.
+\end{function}
+
+
 \subsection{Shortening Paths}
 
 \begin{function}{
@@ -473,8 +511,8 @@ Saves the path to the file \texttt{path.svg} as an SVG document.
 \subsection{Knots}
 
 \begin{function}{
-  global knot,
   knot,
+  global knot,
   draft mode
 }
 \begin{syntax}
@@ -544,7 +582,7 @@ The intention with the second key is that it is similar to what happens with the
 \section{Examples}
 
 \begin{enumerate}
-\item Saving, restoring, inserting, and appending.
+\item Saving and re-using.
 
 \begin{example}
 \begin{tikzpicture}
@@ -554,10 +592,10 @@ The intention with the second key is that it is similar to what happens with the
   \node[above left] at (spath cs:rpath 0.\k) {\(0.\k\)};
 }
 \fill[green] (2,2) circle[radius=3pt];
-\draw[blue, spath/transform={rpath}{shift={(2,2)}}, spath/restore=rpath] node[right] {transform};
-\draw[orange] (3,0) [spath/insert=rpath] node[right] {insert};
+\draw[blue, spath/transform={rpath}{shift={(2,2)}}, spath/use=rpath] node[right] {transform};
+\draw[orange] (3,0) [spath/use={rpath, move}] node[right] {moving};
 \draw[red] (3,-1) -- +(0,2) [spath/append=rpath] node[above] {append};
-\draw[spath/restore=rpath] node[right] {restore};
+\draw[spath/use=rpath] node[right] {use};
 \end{tikzpicture}
 \end{example}
 
@@ -570,8 +608,8 @@ The intention with the second key is that it is similar to what happens with the
   green,
   draw=black,
   ultra thick,
-  spath/restore=apath
-] -- ++(0,-4) [spath/append reverse=apath] -- cycle;
+  spath/use=apath
+] -- ++(0,-4) [spath/use={apath, reverse, move, weld}] -- cycle;
 \end{tikzpicture}
 \end{example}
 
@@ -583,7 +621,7 @@ The intention with the second key is that it is similar to what happens with the
 \draw[rotate=45, xscale=2, yscale=3, ultra thick, red] (0,0) rectangle +(1,1);
 \draw[
   spath/transform={tpath}{rotate=45, xscale=2, yscale=3},
-  spath/restore={tpath}];
+  spath/use={tpath}];
 \end{tikzpicture}
 \end{example}
 
@@ -615,7 +653,7 @@ The intention with the second key is that it is similar to what happens with the
 (7,1) circle[radius=3pt]
 ;
 
-\draw[spath/restore=a];
+\draw[spath/use=a];
 \end{tikzpicture}
 \end{example}
 
@@ -653,9 +691,9 @@ The intention with the second key is that it is similar to what happens with the
   shorten at end={apath}{7pt},
   shorten at start={apath}{9pt},
   translate={apath}{0pt}{1pt},
-  restore=apath,
+  use=apath,
 ];
-\draw (0,0) circle[radius=9pt] [spath/insert=apath] circle[radius=7pt];
+\draw (0,0) circle[radius=9pt] [spath/use=apath] circle[radius=7pt];
 \end{tikzpicture}
 \end{example}
 
@@ -670,9 +708,9 @@ The intention with the second key is that it is similar to what happens with the
   shorten at end={apath}{7pt},
   shorten at start={apath}{9pt},
   translate={apath}{0pt}{1pt},
-  restore=apath,
+  use=apath,
 ];
-\draw (0,0) circle[radius=9pt] [spath/insert=apath] circle[radius=7pt];
+\draw (0,0) circle[radius=9pt] [spath/use=apath] circle[radius=7pt];
 \end{tikzpicture}
 \end{example}
 
@@ -699,7 +737,7 @@ The intention with the second key is that it is similar to what happens with the
     path \k/.try,
     spath/.cd,
     translate=\cpt{0pt}{\k pt},
-    restore=\cpt,
+    use=\cpt,
   ] +(0,3pt) -- +(0,-3pt);
   \node[text=red] at (spath cs:{\cpt} .5) {\(\k\)};
 }
@@ -734,12 +772,12 @@ One of the main motivations for implementing the intersection routines was to pr
 }
 
 \foreach[count=\k] \cpt in \pathAcomponents {
-  \draw[spath/restore=\cpt,-Circle];
+  \draw[spath/use=\cpt,-Circle];
   \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
 }
 
 \foreach[count=\k] \cpt in \pathBcomponents {
-  \draw[spath/restore=\cpt,-Circle];
+  \draw[spath/use=\cpt,-Circle];
   \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
 }
 \end{tikzpicture}
@@ -766,12 +804,12 @@ Although the paths were defined globally, the splitting in the previous example
 \fill[pattern=bricks, pattern color=white] (-.5,-.5) rectangle (8.5,1.5);
 
 \foreach[count=\k] \cpt in \pathAcomponents {
-  \draw[blue, line width=2pt,spath/restore=\cpt];
+  \draw[blue, line width=2pt,spath/use=\cpt];
   \node[fill=cyan, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .3) {\(\k\)};
 }
 
 \foreach[count=\k] \cpt in \pathBcomponents {
-  \draw[green, line width=2pt,spath/restore=\cpt];
+  \draw[green, line width=2pt,spath/use=\cpt];
   \node[fill=green!50, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .3) {\(\k\)};
 }
 \end{tikzpicture}
@@ -807,7 +845,7 @@ arc[radius=.5cm,start angle=90, delta angle=-180]
 }
 
 \foreach[count=\k] \cpt in \pathcomponents {
-  \draw[spath/restore=\cpt,-|];
+  \draw[spath/use=\cpt,-|];
   \node[fill=white, fill opacity=.5, circle, text opacity=1] at (spath cs:{\cpt} .5) {\(\k\)};
 }
 \end{tikzpicture}
@@ -826,7 +864,7 @@ arc[radius=.5cm,start angle=90, delta angle=-180]
 }
 
 \foreach[count=\k] \cpt in \pathcomponents {
-  \draw[blue, line width=2pt,spath/restore=\cpt];
+  \draw[blue, line width=2pt,spath/use=\cpt];
 }
 \end{tikzpicture}
 \end{example}
@@ -843,5 +881,65 @@ arc[radius=.5cm,start angle=90, delta angle=-180]
 \tikzset{spath/knot={trefoil}{8pt}{1,3,5}}
 \end{tikzpicture}
 \end{example}
+
+\item Here's how to mark intersections of paths with ``bridges''.
+\begin{example}
+\begin{tikzpicture}
+\coordinate (a) at (-1,0.5);
+\coordinate (b) at (8,0.5);
+\coordinate (c) at (3,-0.5);
+\path[spath/save=sine]
+(-1.57,-1)
+cos ++(1.57,1)
+sin ++(1.57,1)
+cos ++(1.57,-1)
+sin ++(1.57,-1)
+cos ++(1.57,1)
+sin ++(1.57,1);
+\path[spath/save=over] (a) -- (c) |- (b);
+
+\path[spath/save=arc] (0,0) arc[radius=1cm, start angle=180, delta angle=-180];
+
+\tikzset{
+  spath/split at intersections with={over}{sine},
+  spath/insert gaps after components={over}{8pt},
+  spath/join components upright with={over}{arc},
+  spath/split at intersections with={sine}{over},
+  spath/insert gaps after components={sine}{4pt},
+}
+
+\draw[spath/use=sine];
+\draw[spath/use=over];
+\end{tikzpicture}
+\end{example}
+
+\item If there are lots of paths like the previous example, here's a convenient style to put them together.
+\begin{example}
+\tikzset{
+  bridging path/.initial=arc,
+  bridging span/.initial=8pt,
+  bridging gap/.initial=4pt,
+  bridge/.style 2 args={
+    spath/split at intersections with={#1}{#2},
+    spath/insert gaps after components={#1}{\pgfkeysvalueof{/tikz/bridging span}},
+    spath/join components upright with={#1}{\pgfkeysvalueof{/tikz/bridging path}},
+    spath/split at intersections with={#2}{#1},
+    spath/insert gaps after components={#2}{\pgfkeysvalueof{/tikz/bridging gap}},
+  }
+}
+
+% If used in the preamble, this needs surrounding in \AtBeginDocument
+%\AtBeginDocument{
+\tikz[overlay] \path[spath/save=arc] (0,0) arc[radius=1cm, start angle=180, delta angle=-180];
+%}
+\begin{tikzpicture}
+\path[spath/save=over] (0,0) -| ++(1,1) -| ++(-1,1) -| ++(1,1) -| ++(-1,1);
+\path[spath/save=under] (.5,-.5) -- ++(0,4);
+\tikzset{bridge={over}{under}}
+\draw[spath/use=over];
+\draw[spath/use=under];
+\end{tikzpicture}
+\end{example}
+
 \end{enumerate}
   \end{document}
-- 
cgit v1.2.3

