tutorial.tex

\documentclass[a4paper]{ltxdoc}
\def\pgfautoxrefs{1} % !!!!!!
\usepackage[left=2.25cm,right=2.25cm,
            top=2.5cm,bottom=2.5cm,nohead]{geometry}
\usepackage[utf8]{inputenc}
%\usepackage{makeidx}
%\makeindex
\usepackage{hyperref}
\hypersetup{%
        colorlinks=true,
        linkcolor=blue,
        filecolor=blue,
        urlcolor=blue,
        citecolor=blue,
        pdfborder=0 0 0,
}
\usepackage{amssymb}
\usepackage{amsthm}
\usepackage{sseqpages}
\usepackage{environ}
\usepackage{verbatim}
\usepackage[listings]{tcolorbox}

\makeatletter          % !!!!
\input{pgfmanual.code} % !!!!
\makeatother           % !!!!

\usepackage{calc} %
\include{pgfmanual-en-macros}

\usetikzlibrary{arrows}
\theoremstyle{definition}
\newtheorem{ex}{Example}
\def\endex{\newpage}
\parskip=10pt
\parindent=0pt
\makeatletter
\MakeShortVerb{\|}
\title{A quick |sseqpages| tutorial}

\definecolor{Option}{rgb}{0.118,0.546,0.222}

\newtcblisting{sseqlisting}[1][]{
    listing options={
        style=tcblatex,
        texcsstyle={\color{red!40!black}},
        breaklines=false,
        moretexcs={class,printpage},
        keywordstyle=\color{blue},
        morekeywords={sseqdata},
        moredelim={[s][\color{purple}]{(}{)}}
    },
    #1
}
\begin{document}
\begin{ex}
The |sseqpages| package provides two environments -- the |sseqdata| environment, for specifying the raw data of a spectral sequence, and the |sseqpage| environment, for printing a page of a spectral sequence. There is also a command |\printpage| for when the body of |sseqpage| is empty. This package is built very closely on top of Tikz, so for the most part, standard Tikz options carry over to do the same thing when used with |sseqpages|. Because of this, the package is much easier to use if you already know how to use Tikz. Since that seems to be a minority of potential users, I will make sure to explain exactly what features are inherited from Tikz.

Here is a very short example to illustrate the most basic usage:

\begin{codeexample}[]
\begin{sseqdata}[name=example1,degree={#1}{-#1+1}]
\class(0,0)
\class(2,0)
\class(0,1)
\class(2,1)
\d2(0,1)
\end{sseqdata}
\printpage[name=example1,page=2]
\printpage[name=example1,page=3]
\end{codeexample}
The option |degree={#1}{-#1+1}| specifies that the bidegree of the $E_r$ differential is $(r,-r+1)$ -- that is, a page $r$ differential goes right $r$ and down $r-1$. |example1| is name of this spectral sequence. The command |\class(|\meta{x}|,|\meta{y}|)| places a class at (\meta{x},\meta{y}). We place four classes, then use the command |\d2(2,0)| which places a differential connecting the class at (2,0) to the one at (0,1). Then we use |\printpage| to display pages two and three of the spectral sequence. We see a single differential on page two. On page three, its source and target disappear. This is the general behavior of the package -- whenever a class supports or accepts a differential, it disappears on subsequent pages.

I think these rectangles are too large, and they'd look better if they were filled. If I want to change the appearance on this one page I can say:
%\begin{codeexample}[]
%\printpage[name=example1,page=2,classes={inner sep=0.2ex,fill}]
%\end{codeexample}
\end{ex}

%\tikzset{arrows={Classical TikZ Rightarrow[length=5mm]}}
%\begin{tikzpicture}
%\draw[->] (0,0)--(1,1);
%\end{tikzpicture}

\sseqset{degree={#1}{-#1+1},classes={inner sep=0.3ex},differentials={->}} % Make sure to keep this in the code for the next example
\begin{ex}
The appearance of example 1 was pretty rough. This example polishes it up a bit. The |sseqpages| package offers a number of "style" options that control the appearance of certain features of the spectral sequence. For instance, |classes| controls the appearance of every class and |differentials| controls the appearance of every differential. There are also options |permanent cycles| and |transient cycles|, that respectively affect the appearance of only classes that never support or are hit by a differential, or that are eventually hit by a differential.

Classes are internally drawn as Tikz nodes, so the options that you provide to |classes|, |permanent cycles|, |transient cycles|, and individual |\class| commands are mostly the same as options that you would provide to the |\node| command. Differentials are drawn as Tikz edges, so the options you can provide to |differentials| or a |\d| command are mostly the same as the options you would provide to |\draw|.
\sseqset{degree={#1}{-#1+1},classes={inner sep=0.2ex},differentials=->}


\begin{codeexample}[]
\sseqset{degree={#1}{-#1+1},classes={inner sep=0.2ex},differentials=->}
\begin{sseqdata}[
    name=example2,
    classes={fill,circle},
    differentials=blue,
    permanent cycles={double=white,draw,distance=1,inner sep=0.2ex+0.35pt},
    transient cycles=red
]
\node[background,font=\small] at (\xmin/2+\xmax/2,\ymax+1) {\textup{Page \page{}}};
\foreach \x in {0,2} \foreach \y in {0,1}{
    \class(\x,\y)
}
\d2(0,1)
\end{sseqdata}
\printpage[name=example2,page=2]
\printpage[name=example2,page=3]
\end{codeexample}

The command |\sseqset| sets options for all spectral sequences in the current scope. Note in particular that these changes are local to the current environment. The option |classes| adds the given options to the style |every class| which controls the appearance of all classes. The classes above were too large for my taste, so I asked for them to be somewhat smaller by default in all future diagrams using the Tikz option |inner sep=0.2ex|. Also, the option |differentials=->| will make all future differentials end in an arrow tip, the same as it does in the Tikz command |\draw[->] |\meta{source}|--|\meta{target}|;|.

For this particular diagram, I asked for the classes to be filled circles with |classes={fill,circle}|, and for the differentials to be blue by setting |differentials=blue|. We ask for permanent cycles to be drawn with an extra circle around them, and for transient cycles to be red. All of these are also Tikz options.


The command |\node[background,font=\small] at (\xmin/2+\xmax/2,\ymax+1) {\textup{Page \sseqthepage{}}};| adds a title to the background that says what page it is. This is actually a direct Tikz command, although the commands |\xmin|, |\xmax|, |\ymax|, and |\sseqthepage| are defined by |sseqpages|. The option |background| is specific to |sseqpages| and it tells the package to put this Tikz command in the background (rather than on top of all classes, structlines, and differentials as is the default).

Instead of calling the |\class| command four times by hand, we use the Tikz command |\foreach| (actually |\foreach| is from PGF, but whatever).
\end{ex}

\tikzset{execute at begin node=$, execute at end node=$}% fix this to work with \sseqset
\begin{ex}
Named cells and the |\replaceclass| command.
\begin{codeexample}[]
\begin{sseqdata}[
    name=example3,
    classes={draw=none}
]
\foreach \x in {0,2} \foreach \y in {0,1}{
    \class["\mathbb{Z}"](\x,\y)
}
\d["\cdot 2"]2(0,1)
\replaceclass["\mathbb{Z}/2"](2,0)
\end{sseqdata}
\printpage[name=example3,page=2]
\printpage[name=example3,page=3]
\end{codeexample}

All of the labels in this document are in math mode, so I ask Tikz to automatically put every node in math mode using the options |execute at begin node=$, execute at end node=$|. This includes both the names of classes and any labels given for differentials.

If you want to put something in the body of the node printed by the |\class| command, this is specified in quotes. For instance the command |\class["\mathbb{Z}"](\x,\y)| puts a $\mathbb{Z}$ in the node. Likewise, to label a differential, place the desired label in quotes, like |\d["\cdot 2"]2(0,1)|. (For differentials, this uses Tikz |edge quotes|.)  I don't want the $\mathbb{Z}$ to be surrounded by a drawn border so I pass the global option |classes={draw=none}| to tell Tikz not to draw the boundary of the node.

Note also the use of the command |\replaceclass["\mathbb{Z}/2"](2,0)|. After a class supports or is hit by a differential (or both), it will disappear on subsequent pages. If you want to put a new node in the same location (or the same node), it is necessary to use the |\replaceclass| command.
\end{ex}

\begin{ex}
Multiple nodes in the same location and the |\structline| command.
\begin{codeexample}[]
\begin{sseqdata}[name=example4,classes={circle,fill},differentials=blue,scale=0.7]
\class(0,2)\class(0,2)
\class[red](3,0)\class[green](3,0)\class[blue](3,0)
\class(3,2)

\foreach \y in {1,...,5} {
    \class(3,\y)
    \structline(3,\y-1,-1)(3,\y,-1)
}
\class(3,4)
\class(1,3)
\d2(1,3,,-1)
\d3(0,2,1,2)
\d3(0,2,-1,-1)
\class(0,0)
\draw[->,green](3,0,1)--(0,0);
\end{sseqdata}
\printpage[name=example4,page=0]
\printpage[name=example4,page=0,class placement transform={rotate=40}]
\printpage[name=example4,page=4,class placement transform={rotate=40}]
\end{codeexample}

The option |yscale=0.7| is a Tikz coordinate transformation option that rescales the y-axis to be 0.7 times its original length.

If you set |page=0|, then |sseqpages| will draw all differentials of any length as well as all classes. In this example, we see the differentials of length three and one differential of length two in the same diagram.

Multiple nodes in the same location are automatically arranged in a standard pattern. In the future it will be possible for the user to exert a significant amount of control over this pattern, but right now, there's only one choice. The |sseqpages| option |class placement transform| allows the user to specify a Tikz coordinate transform to adjust the relative position of multiple nodes in the same position. This coordinate transform can only involve rotation and scaling, no translation. In this case, |class placement transform={rotate=40}| rotates the classes in the same position by 40 degrees. %TODO: in the future

To place multiple nodes in the same location, you just call |\class| with the same coordinate twice. To place a differential where the source or target have multiple nodes, you say |\d|\meta{r}|(|\meta{x source}|,|\meta{y source}|,|\meta{n source}|,|\meta{n target}|)| where \meta{n source} and \meta{n target} specify which of the nodes in the source and target location to use. If the number \meta{n} is positive, it counts from the first node placed in that position, whereas if it is negative, it counts from the most recent node placed in that position.

The command |\structline|\meta{source coord}\meta{target coord} places a line from the source class to the target class, but will only draw this line on pages where both the source and target are still alive. If multiple nodes are in the same position, then the syntax for the coordinate is |(|\meta{x}|,|\meta{y}|,|\meta{n}|)|, where as with |\d|, if \meta{n} is negative it counts backwards from the most recently placed node.

Using negative values is particularly useful when drawing repeated structures. This way, independent of how many classes are already present in a given position, the new structure will be properly grouped. Consider, for instance, the following code:

\begin{minipage}{0.7\textwidth}
\begin{verbatim}
\sseqnewgroup\tower{
    \class(0,0)
    \class(0,2)
    \foreach \y in {1,...,5} {
        \class(0,\y)
        \structline(0,\y-1,-1)(0,\y,-1)
    }
    \structline[black](0,1,-1)(0,2,-2)
    \structline(0,2,-2)(0,3,-1)
}

\begin{sseqdata}[name=example5,classes={circle,fill}]
\class(1,1)\class(1,2)
\class(2,3)\class(2,3)\class(2,5)
\tower[classes=blue](0,0)
\tower[dashed,orange](1,0)
\tower[struct lines=red](2,0)
\end{sseqdata}
\printpage[name=example5,page=0]
\end{verbatim}
\end{minipage}
\begin{minipage}{0.25\textwidth}
\sseqnewgroup\tower{
    \class(0,0)
    \class(0,2)
    \foreach \y in {1,...,5} {
        \class(0,\y)
        \structline(0,\y-1,-1)(0,\y,-1)
    }
    \structline[black](0,1,-1)(0,2,-2)
    \structline(0,2,-2)(0,3,-1)
}

\begin{sseqdata}[name=example5,classes={circle,fill}]
\class(1,1)\class(1,2)
\class(2,3)\class(2,3)\class(2,5)
\tower[classes=blue](0,0)
\tower[struct lines=dashed,orange](1,0)
\tower[struct lines=red](2,0)
\end{sseqdata}
\printpage[name=example5,page=0]
\end{minipage}
\end{ex}
\end{document}