summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/braids/braids_code.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/contrib/braids/braids_code.dtx')
-rw-r--r--graphics/pgf/contrib/braids/braids_code.dtx159
1 files changed, 128 insertions, 31 deletions
diff --git a/graphics/pgf/contrib/braids/braids_code.dtx b/graphics/pgf/contrib/braids/braids_code.dtx
index f1f59c29b0..7ea298c6cd 100644
--- a/graphics/pgf/contrib/braids/braids_code.dtx
+++ b/graphics/pgf/contrib/braids/braids_code.dtx
@@ -4,14 +4,17 @@
%</internal>
%<*readme>
----------------------------------------------------------------
-braids --- a style file for drawing braid diagrams with TikZ/PGF
-E-mail: loopspace@mathforge.org
+braids --- a TikZ library for drawing braid diagrams
+bundle version: v2.3 2024/01/09
+E-mail: Andrew Stacey <loopspace@mathforge.org>
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
-This package defines some commands for drawing braid diagrams with TikZ/PGF.
-The initial idea of this package came from a question and answer on the site http://tex.stackexchange.com.
+This library defines some commands for drawing braid diagrams with TikZ/PGF.
+The initial idea of this package came from a question and answer on the site https://tex.stackexchange.com.
+
+The package comes in two versions: a package (braids.sty) and a TikZ library (tikzlibrarybraids.code.tex). The original package (braids.sty) is depreciated and has been frozen at version 1.1. The TikZ library is maintained and should be used in preference, except for legacy code.
%</readme>
%<*internal>
\fi
@@ -26,8 +29,9 @@ The initial idea of this package came from a question and answer on the site htt
\askforoverwritefalse
\preamble
----------------------------------------------------------------
-braids --- a style file for drawing braid diagrams with TikZ/PGF
-E-mail: loopspace@mathforge.org
+braids --- a TikZ library for drawing braid diagrams
+bundle version: v2.3 2024/01/09
+E-mail: Andrew Stacey <loopspace@mathforge.org>
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------
@@ -35,7 +39,7 @@ See http://www.latex-project.org/lppl.txt
\endpreamble
\postamble
-Copyright (C) 2011-2022 by Andrew Stacey <loopspace@mathforge.org>
+Copyright (C) 2011-2024 by Andrew Stacey <loopspace@mathforge.org>
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License (LPPL), either
@@ -82,16 +86,12 @@ and the derived files README.txt,
\expandafter\endgroup
\fi
%</internal>
-%<*package>
-\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{braids}[2011/10/18 v1.1 Tikz/PGF commands for drawing braid diagrams]
-%</package>
%<*driver>
\documentclass{l3doc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{tikz}
-\usepackage{braids}
+\usepackage[nowarning]{braids}
\usetikzlibrary{braids}
\EnableCrossrefs
@@ -103,7 +103,7 @@ and the derived files README.txt,
%</driver>
% \fi
%
-% \CheckSum{2352}
+% \CheckSum{2401}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -127,6 +127,7 @@ and the derived files README.txt,
% \changes{2.0}{2019/03/20}{Converted TikZ library}
% \changes{2.1}{2019/08/14}{Extended crossing capability}
% \changes{2.2}{2022/10/26}{Advanced positioning}
+% \changes{2.3}{2024/01/09}{Disambiguated height}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
@@ -162,9 +163,21 @@ and the derived files README.txt,
%
% Issue a notice that this is a depreciated version of the braids package.
% \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{braids}[2011/10/18 v1.1 Tikz/PGF commands for drawing braid diagrams (depreciated package)]
+\newif\if@braids@warning@
+\@braids@warning@true
+\DeclareOption{nowarning}{%
+\@braids@warning@false
+}
+
+\ProcessOptions
+
+\if@braids@warning@
\PackageWarning{braids}{%
- This package has been reimplemented as a TikZ library; if starting with a fresh document, please consider using that instead.%
+ This package is frozen at v1.1 from 2011/10/18 and has been reimplemented as a TikZ library; if starting with a fresh document, please consider using that instead.%
}%
+\fi
% \end{macrocode}
%
% \begin{macro}[internal]{\ge@addto@macro}
@@ -1183,7 +1196,7 @@ and the derived files README.txt,
% Life is so much easier with \LaTeX3.
% \begin{macrocode}
\ProvidesFile{tikzlibrarybraids.code.tex}[%
- 2022/10/26 v2.2 Tikz/PGF library for drawing braid diagrams%
+ 2024/01/09 v2.3 Tikz/PGF library for drawing braid diagrams%
]
\RequirePackage{expl3}
\ExplSyntaxOn
@@ -1227,33 +1240,33 @@ and the derived files README.txt,
\seq_new:N \l_@@_anchor_seq
\seq_new:N \l_@@_floors_seq
\str_new:N \l_@@_tmpa_str
-\str_new:N \l_@@_sup_str
-\str_set:Nn \l_@@_sup_str {^}
-\str_new:N \l_@@_sub_str
-\str_set:Nn \l_@@_sub_str {_}
-\str_new:N \l_@@_hyphen_str
-\str_set:Nn \l_@@_hyphen_str {-}
-\str_new:N \l_@@_bar_str
-\str_set:Nn \l_@@_bar_str {|}
-\str_new:N \l_@@_one_str
-\str_set:Nn \l_@@_one_str {1}
\bool_new:N \l_@@_step_level_bool
\bool_new:N \l_@@_swap_crossing_bool
+\bool_new:N \l_@@_default_crossing_bool
+\bool_new:N \l_@@_default_symbol_bool
+\bool_set_true:N \l_@@_default_crossing_bool
+\bool_set_true:N \l_@@_default_symbol_bool
\bool_new:N \l_@@_floor_bool
+\bool_new:N \l_@@_height_bool
+\bool_new:N \l_@@_crossing_height_bool
\prop_new:N \l_@@_strands_prop
\prop_new:N \l_@@_permutation_prop
\prop_new:N \l_@@_crossing_permutation_prop
\prop_new:N \l_@@_inverse_prop
\prop_new:N \l_@@_anchor_prop
+\msg_new:nnn {braids} {height} {The~ keys~ "height"~ and~ "crossing~ height"~ shouldn't~ be~ used~ together~ (the~ setting~ for~ "crossing~ height"~ will~ be~ used)}
\cs_generate_variant:Nn \seq_set_split:Nnn {NVn}
+\cs_generate_variant:Nn \str_compare:nNnTF {VNnTF}
% \end{macrocode}
% Our interface is through a TikZ pic.
% \begin{macrocode}
\tikzset{
braid/.pic={
+ \begin{scope}[every~ braid/.try]
\@@_parse_word:n {#1}
\@@_count:
\@@_render:
+ \end{scope}
},
floor/.pic={
\path[pic~ actions, draw=none] (0,0) rectangle (1,1);
@@ -1276,9 +1289,86 @@ and the derived files README.txt,
% \begin{macrocode}
number~ of~ strands/.initial=0,
% \end{macrocode}
-% \Verb+height+ is the distance between crossings (can be negative).
+%
+% These keys determine whether crossings are over or under by default.
+% \begin{macrocode}
+ crossing~ convention/.is~choice,
+ crossing~ convention/over/.code={
+ \bool_set_true:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/down/.code={
+ \bool_set_true:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/under/.code={
+ \bool_set_false:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/up/.code={
+ \bool_set_false:N \l_@@_default_crossing_bool
+ },
+ crossing~ convention/.default=over,
+% \end{macrocode}
+%
+% \begin{macrocode}
+ flip~ crossing~ convention/.code={
+ \bool_set_inverse:N \l_@@_default_crossing_bool
+ },
+% \end{macrocode}
+%
+% These keys determine whether elements should be inverted by default.
+% \begin{macrocode}
+ set~ symbols/.is~choice,
+ set~ symbols/over/.code={
+ \bool_set_true:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/down/.code={
+ \bool_set_true:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/under/.code={
+ \bool_set_false:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/up/.code={
+ \bool_set_false:N \l_@@_default_symbol_bool
+ },
+ set~ symbols/.default=over,
+% \end{macrocode}
+%
+% \begin{macrocode}
+ flip~ symbols/.code={
+ \bool_set_inverse:N \l_@@_default_symbol_bool
+ },
+% \end{macrocode}
+%
+% The next two keys are used to control the separation between the crossings.
+% The original braid package used the \Verb+height+ as part of how it determined the direction of the braid on the page.
+% In particular, the \Verb+height+ could be negative, and indeed the default is for it to be so since a vertical braid usually flows from top to bottom.
+% Now that the drawing is reimplemented as a \Verb+pic+ then the direction is better controlled using transformations.
+% So then \Verb+height+ should be simply to set the gap between crossings in whatever orientation.
+% In particular, \Verb+height+ should be a positive length.
+%
+% To avoid backwards incompatibility, the original (counter-intuitive) version of \Verb+height+ is retained but a new key, \Verb+crossing height+, is introduced which can only be positive (rather, the code will take its absolute value so you can \emph{declare} it to be negative but the code will laugh at you and ignore the sign).
+%
+% To ensure that \Verb+crossing height+ wins, we use a boolean to see if it has been invoked by the user.
% \begin{macrocode}
height/.initial=-1cm,
+ height/.code={
+ \bool_if:NTF \l_@@_crossing_height_bool
+ {
+ \msg_term:nn {braids} {height}
+ }
+ {
+ \pgfkeyssetvalue{/tikz/braid/height}{#1}
+ \bool_set_true:N \l_@@_height_bool
+ }
+ },
+ crossing~ height/.code={
+ \bool_if:NT \l_@@_height_bool
+ {
+ \msg_term:nn {braids} {height}
+ }
+ \exp_args:Nnx \pgfkeyssetvalue {/tikz/braid/height}
+ {\dim_eval:n {-\dim_abs:n{#1}}}
+ \bool_set_true:N \l_@@_crossing_height_bool
+ },
% \end{macrocode}
% \Verb+width+ is the distance between strands (can be negative).
% \begin{macrocode}
@@ -1464,7 +1554,7 @@ and the derived files README.txt,
{
\seq_put_right:Nx \l_@@_crossing_seq {\int_eval:n {#1 + 1} }
}
- \bool_if:NF \l_@@_swap_crossing_bool
+ \bool_xor:nnT {\l_@@_swap_crossing_bool} {\l_@@_default_symbol_bool}
{
\seq_reverse:N \l_@@_crossing_seq
}
@@ -1473,7 +1563,7 @@ and the derived files README.txt,
% \end{macro}
%
% \begin{macro}{\@@_parse_exponent:n}
-% Parse an exponent, basically testing to see if it is \(-1\) in which case our crossing numbers should be reversed..
+% Parse an exponent, basically testing to see if it is \(-1\) in which case our crossing numbers should be reversed.
% \begin{macrocode}
\cs_new_nopar:Npn \@@_parse_exponent:n #1
{
@@ -1838,7 +1928,7 @@ and the derived files README.txt,
\fp_zero:N \l_@@_height_fp
\fp_zero:N \l_@@_nudge_fp
\fp_zero:N \l_@@_control_fp
-% \end{macrocode}
+% \end{macrocode}
% This holds our current \Verb+height+ of our strands.
% \begin{macrocode}
\fp_set:Nn \l_@@_height_fp
@@ -2008,8 +2098,15 @@ and the derived files README.txt,
% \begin{macrocode}
\int_step_inline:nnn {2} {\seq_count:N \l_@@_crossing_seq}
{
- \int_set:Nn \l_@@_tmpa_int {####1}
- \int_set:Nn \l_@@_tmpb_int {####1 - 1}
+ \bool_if:NTF \l_@@_default_crossing_bool
+ {
+ \int_set:Nn \l_@@_tmpa_int {####1}
+ \int_set:Nn \l_@@_tmpb_int {####1 - 1}
+ }
+ {
+ \int_set:Nn \l_@@_tmpa_int {####1 - 1}
+ \int_set:Nn \l_@@_tmpb_int {####1}
+ }
% \end{macrocode}
% Keep track of the current permutation.
% \begin{macrocode}