Skip to content

Support & in matrices without catcode change #1081

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 19 commits into
base: master
Choose a base branch
from
Open

Support & in matrices without catcode change #1081

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
2407ff0
Fix "\matrix{a \\ b &[between origins] c};"
gabor-braun Nov 24, 2015
85f842a
Break up \pgf@matrix@endcell for future changes.
gabor-braun Nov 15, 2015
3418205
pgfmatrix: Smuggle row and column separation out of all cells.
gabor-braun Nov 27, 2021
70a400a
pgfmatrix: delay handling column separation.
gabor-braun Nov 23, 2015
11f8ab9
Remove \ifpgf@matrix@last@cell@in@row.
gabor-braun Nov 15, 2015
a7ab036
Remove one \pgf@matrix@maxxN initialization, no longer needed.
gabor-braun Nov 24, 2015
739b4a5
pgfmatrix: remove unused \pgf@matrix@eom@found.
gabor-braun Dec 1, 2021
59fe51c
Simplify detecting empty cell.
gabor-braun May 21, 2016
3c127e2
pgfmatrix: Care for & when parsing optional arguments.
gabor-braun Nov 27, 2015
b4c3b7c
Remove a no longer needed global assignment.
gabor-braun Jan 1, 2019
ef27e67
pgfmatrix: support & as cell separator, simplify last cell test.
gabor-braun Dec 25, 2018
9181d20
No longer make & active in TikZ matrices.
gabor-braun Nov 27, 2021
d660a5a
pgfmatrix: Remove internal variable \pgf@matrix@paddingskip.
gabor-braun Nov 22, 2015
d4ebe22
pgfmatrix: Simplify by removing \ifpgf@matrix@empty@cell.
gabor-braun Nov 27, 2021
ab2bedf
Recombine \pgf@matrix@endcell.
gabor-braun Dec 13, 2018
2a365ea
\pgfmatrix: deduplicate halign header.
gabor-braun Dec 1, 2021
aea0349
\pgfmatrix: slightly simplify adding row separation.
gabor-braun Dec 1, 2021
fbcaa39
\pgfmatrix: Optimize out \pgf@matrix@column@sep@N.
gabor-braun Dec 1, 2021
10a77b1
matrices: Add some tests for & as cell separator.
gabor-braun Dec 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 45 additions & 51 deletions doc/generic/pgf/pgfmanual-en-base-matrices.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,12 @@ \subsection{Overview}

\subsection{Cell Pictures and Their Alignment}

A matrix consists of rows of \emph{cells}. Cells are separated using the
A matrix consists of rows of \emph{cells}. Cells are separated using
|&| or the
special command |\pgfmatrixnextcell|, rows are ended using the command
|\pgfmatrixendrow| (the command |\\| is set up to mean the same as
|\pgfmatrixendrow| by default). Each cell contains a \emph{cell picture},
|\pgfmatrixendrow| by default), including the last row.
Each cell contains a \emph{cell picture},
although cell pictures are not complete pictures as they lack layers. However,
each cell picture has its own bounding box like a normal picture does. These
bounding boxes are important for the alignment as explained in the following.
Expand All @@ -56,13 +58,13 @@ \subsection{Cell Pictures and Their Alignment}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\fill (0,-3) rectangle (1,1);\atorig1 \pgfmatrixnextcell
\fill (-1,0) rectangle (1,1);\atorig2 \pgfmatrixnextcell
\fill (-1,-2) rectangle (0,0);\atorig3 \pgfmatrixnextcell
\fill (0,-3) rectangle (1,1);\atorig1 &
\fill (-1,0) rectangle (1,1);\atorig2 &
\fill (-1,-2) rectangle (0,0);\atorig3 &
\fill (-1,-1) rectangle (0,3);\atorig4 \\
\fill (-1,0) rectangle (4,1);\atorig5 \pgfmatrixnextcell
\fill (0,-1) rectangle (1,1);\atorig6 \pgfmatrixnextcell
\fill (0,0) rectangle (1,4);\atorig7 \pgfmatrixnextcell
\fill (-1,0) rectangle (4,1);\atorig5 &
\fill (0,-1) rectangle (1,1);\atorig6 &
\fill (0,0) rectangle (1,4);\atorig7 &
\fill (-1,-1) rectangle (0,0);\atorig8 \\
}
\end{tikzpicture}
Expand Down Expand Up @@ -94,12 +96,9 @@ \subsection{The Matrix Command}
rules for indicating cells:
%
\begin{enumerate}
\item Cells in the same row must be separated using the macro
|\pgfmatrixnextcell| rather than |&|. Using |&| will result in an
error message.

However, you can make |&| an active character and have it expand to
|\pgfmatrixnextcell|. This way, it will ``look'' as if |&| is used.
\item Cells in the same row are separated by |&|.
You can also use |\pgfmatrixnextcell| for compatibility
to old versions of \pgfname.
\item Rows are ended using the command |\pgfmatrixendrow|, but |\\| is
set up to mean the same by default. However, some environments like
|{minipage}| redefine |\\|, so it is good to have
Expand All @@ -108,7 +107,8 @@ \subsection{The Matrix Command}
command |\\| or |\pgfmatrixendrow|.
\end{enumerate}

Both |\pgfmatrixnextcell| and |\pgfmatrixendrow| (and, thus, also |\\|)
Both |&| and |\pgfmatrixendrow| (and, thus, also
|\pgfmatrixnextcell| and |\\|)
take an optional argument as explained in the
Section~\ref{section-matrix-spacing}
%
Expand All @@ -117,8 +117,8 @@ \subsection{The Matrix Command}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\node {a}; \pgfmatrixnextcell \node {b}; \pgfmatrixendrow
\node {c}; \pgfmatrixnextcell \node {d}; \pgfmatrixendrow
\node {a}; & \node {b}; \pgfmatrixendrow
\node {c}; & \node {d}; \pgfmatrixendrow
}
\end{tikzpicture}
\end{codeexample}
Expand Down Expand Up @@ -172,10 +172,6 @@ \subsection{The Matrix Command}
outside the matrix itself. It can be used for different purposes:
%
\begin{enumerate}
\item It can be used to simplify the next cell macro. For example,
saying |\let\&=\pgfmatrixnextcell| allows you to use |\&| instead
of |\pgfmatrixnextcell|. You can also set the catcode of |&| to
active.
\item It can be used to issue an |\aftergroup| command. This allows you
to regain control after the |\pgfmatrix| command. (If you do not
know the |\aftergroup| command, you are probably blessed with a
Expand All @@ -191,9 +187,9 @@ \subsection{The Matrix Command}
wish to be aware of:
%
\begin{itemize}
\item It is not necessary to actually mention |\pgfmatrixnextcell| or
\item It is not necessary to actually mention |&| or
|\pgfmatrixendrow| inside the \meta{matrix cells}. It suffices that
the macros inside \meta{matrix cells} expand to these macros
the macros inside \meta{matrix cells} expand to these
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now that the row is changed anyway, we can directly remove one of the remaining "double space" instances :)

Suggested change
the macros inside \meta{matrix cells} expand to these
the macros inside \meta{matrix cells} expand to these

sooner or later.
\item In particular, you can define clever macros that insert columns
and rows as needed for special effects.
Expand All @@ -213,21 +209,21 @@ \subsection{Row and Column Spacing}
format of this list are explained in the description of the next command.
\end{command}

\begin{command}{\pgfmatrixnextcell\opt{\oarg{additional sep list}}}
\begin{command}{&\opt{\oarg{additional sep list}}}
This command has two purposes: First, it is used to separate cells. Second,
by providing the optional argument \meta{additional sep list} you can
modify the spacing between the columns that are separated by this command.

The optional \meta{additional sep list} may only be provided when the
|\pgfmatrixnextcell| command starts a new column. Normally, this will only
|&| command starts a new column. Normally, this will only
be the case in the first row, but sometimes a later row has more elements
than the first row. In this case, the |\pgfmatrixnextcell| commands that
than the first row. In this case, the |&| commands that
start the new columns in the later row may also have the optional argument.
Once a column has been started, subsequent uses of this optional argument
for the column have no effect.

To determine the space between the two columns that are separated by
|\pgfmatrixnextcell|, the following algorithm is executed:
|&|, the following algorithm is executed:
%
\begin{enumerate}
\item Both the default separation list (as set up by
Expand Down Expand Up @@ -258,9 +254,6 @@ \subsection{Row and Column Spacing}
cell pictures in both pictures lie on two vertical lines. The
spacing between the two columns is set up such that the horizontal
distance between these two lines is exactly $d$.

This mode may only be used between columns \emph{already introduced
in the first row}.
\end{itemize}
%
All of the above rules boil down to the following effects:
Expand All @@ -278,17 +271,17 @@ \subsection{Row and Column Spacing}
to specify that horizontal space between the origins of cell
pictures in adjacent columns should be 1cm by default -- regardless
of the actual size of the cell pictures.
\item You can now use the optional argument of |\pgfmatrixnextcell| to
\item You can now use the optional argument of |&| to
locally overrule the spacing between two columns. By saying
|\pgfmatrixnextcell[5pt]| you \emph{add} 5pt to the space between
|&[5pt]| you \emph{add} 5pt to the space between
of the two columns, regardless of the mode.

You can also (locally) change the spacing mode for these two
columns. For example, even if the normal spacing mode is
|between origins|, you can say
%
\begin{verbatim}
\pgfmatrixnextcell[5pt,between borders]
&[5pt,between borders]
\end{verbatim}
%
to locally change the mode for these columns to |between borders|.
Expand All @@ -298,11 +291,11 @@ \subsection{Row and Column Spacing}
\begin{tikzpicture}[every node/.style=draw]
\pgfsetmatrixcolumnsep{1mm}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\
\node {3}; \& \node{5}; \& \node {7}; \\
\node {4}; \& \node{9}; \& \node {2}; \\
\node {8}; &[2mm] \node{1}; &[-1mm] \node {6}; \\
\node {3}; & \node{5}; & \node {7}; \\
\node {4}; & \node{9}; & \node {2}; \\
}
\end{tikzpicture}
\end{codeexample}
Expand All @@ -311,11 +304,11 @@ \subsection{Row and Column Spacing}
\begin{tikzpicture}[every node/.style=draw]
\pgfsetmatrixcolumnsep{1mm}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\
\node {3}; \& \node {5}; \& \node {7}; \\
\node {4}; \& \node {9}; \& \node {2}; \\
\node {8}; &[2mm] \node(a){1}; &[1cm,between origins] \node(b){6}; \\
\node {3}; & \node {5}; & \node {7}; \\
\node {4}; & \node {9}; & \node {2}; \\
}
\draw [<->,red,thick,every node/.style=] (a.center) -- (b.center)
node [above,midway] {11mm};
Expand All @@ -326,11 +319,12 @@ \subsection{Row and Column Spacing}
\begin{tikzpicture}[every node/.style=draw]
\pgfsetmatrixcolumnsep{1cm,between origins}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\
\node {3}; \& \node {5}; \& \node {7}; \\
\node {4}; \& \node {9}; \& \node {2}; \\
\node {10}; \\
\node (a) {8}; & \node (b) {1}; &[between borders] \node (c) {6}; \\
\node {3}; & \node {5}; & \node {7}; \\
\node {4}; & \node {9}; & \node {2}; \\
}
\begin{scope}[every node/.style=]
\draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
Expand Down Expand Up @@ -377,10 +371,10 @@ \subsection{Callbacks}
\begin{tikzpicture}
\def\pgfmatrixemptycode{\node{empty};}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
{\pgfusepath{}}{\pgfpointorigin}{}
{
\node {a}; \& \& \node {b}; \\
\& \node{c}; \& \node {d}; \& \\
\node {a}; & & \node {b}; \\
& \node{c}; & \node {d}; & \\
}
\end{tikzpicture}
\end{codeexample}
Expand All @@ -399,10 +393,10 @@ \subsection{Callbacks}
\def\pgfmatrixbegincode{\node[draw]\bgroup}
\def\pgfmatrixendcode{\egroup;}
\pgfmatrix{rectangle}{center}{mymatrix}
{\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
{\pgfusepath{}}{\pgfpointorigin}{}
{
a \& b \& c \\
d \& \& e \\
a & b & c \\
d & & e \\
}
\end{tikzpicture}
\end{codeexample}
Expand Down
29 changes: 7 additions & 22 deletions doc/generic/pgf/pgfmanual-en-tikz-matrices.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,6 @@ \subsection{Matrices are Nodes}
transformation matrix is reset.
\item For multi-part shapes you can only set the |text| part of the node.
\item All options starting with |text| such as |text width| have no effect.
\item If you place a matrix on a path, the matrix contents will be
collected into a macro, which tokenizes them. This means that |&| will
lose its meaning as an alignment character, resulting in an error. If
you need to place a matrix on a path, use |ampersand replacement| to
work around that problem.
\end{enumerate}


Expand Down Expand Up @@ -250,16 +245,12 @@ \subsubsection{Setting and Adjusting Column and Row Spacing}
cells in the first column (remember that they all lie on straight line) and
the origins of all the cells in the second column is exactly the given
distance.

\emph{The }|between origins|\emph{ option can only be used for columns
mentioned in the first row, that is, you cannot specify this option for
columns introduced only in later rows.}
%
\begin{codeexample}[]
\begin{tikzpicture}
\matrix [draw,column sep={1cm,between origins},nodes=draw]
{
\node(a) {123}; & \node (b) {1}; & \node {1}; \\
\node(a) {123}; & \node (b) {1}; \\
\node {12}; & \node {12}; & \node {1}; \\
\node {1}; & \node {123}; & \node {1}; \\
};
Expand Down Expand Up @@ -701,21 +692,15 @@ \subsection{Anchoring a Matrix}
\end{key}


\subsection{Considerations Concerning Active Characters}
\subsection{Compatibility to old versions of \tikzname}

Even though \tikzname\ seems to use |&| to separate cells, \pgfname\ actually
uses a different command to separate cells, namely the command
|\pgfmatrixnextcell| and using a normal |&| character will normally fail. What
happens is that, \tikzname\ makes |&| an active character and then defines this
character to be equal to |\pgfmatrixnextcell|. In most situations this will
work nicely, but sometimes |&| cannot be made active; for instance because the
matrix is used in an argument of some macro or the matrix contains nodes that
contain normal |{tabular}| environments. In this case you can use the following
option to avoid having to type |\pgfmatrixnextcell| each time:
The following obsolete option provides a way to use a macro instead of |&|
as cell separator. It is provided for compatibility with old versions
of \tikzname.

\begin{key}{/tikz/ampersand replacement=\meta{macro name or empty}}
If a macro name is provided, this macro will be defined to be equal to
|\pgfmatrixnextcell| inside matrices and |&| will not be made active. For
If a macro name is provided, this macro will be defined as the
cell separator inside matrices instead of |&|. For
instance, you could say |ampersand replacement=\&| and then use |\&| to
separate columns as in the following example:
%
Expand Down
Loading