% manual2.tex - the compact, citable tenkz language manual.
%
% From the repository root, build to convergence with:
%   python3 scripts/tenkz_manual_build.py build --require-engine
%
\documentclass[11pt]{article}
\usepackage{tenkzmanual2}
\usepackage[colorlinks=true,linkcolor=tenkzMarked,
            urlcolor=tenkzMarked]{hyperref}
\pdfstringdefDisableCommands{%
  \def\tncmd#1{\textbackslash #1}%
  \def\tnenv#1{#1}%
  \def\tnkey#1{#1}%
  \def\tnval#1{#1}%
  \def\tnfile#1{#1}%
}
\hypersetup{pdftitle={The tikz-tensor-networks manual},
            pdfauthor={The TNLean project}}

\newcommand\pkg{\texttt{tikz-tensor-networks}}
\providecommand{\doi}[1]{\href{https://doi.org/#1}{\nolinkurl{doi:#1}}}
\providecommand{\arxiv}[1]{\href{https://arxiv.org/abs/#1}{\nolinkurl{arXiv:#1}}}

\begin{document}

\thispagestyle{empty}
\begin{fullwidth}
  \centering
  \vspace*{16mm}
  {\Huge \pkg\par}
  \vspace{3mm}
  {\Large Language manual\par}
  \vspace{3mm}
  {\Large Declarative tensor-network diagrams in \LaTeX\par}
  \vspace{4mm}
  {September 2026\par}
  \vspace{1mm}
  % The release policy's version agreement (RELEASE-POLICY.md section 3) is
  % checkable only if the manual states a version; tenkz_manual_build.py
  % holds this line to tikz-tensor-networks.sty's \ProvidesPackage version.
  {\small manual for \pkg{} version 0.8.0\par}
  \vspace{16mm}

  \begin{tenkz}[cols=3]
    \tn[ports={180:virtual:$\alpha$, 0:virtual, 90:physical:$i_1$}]{A} &
    \tn[ports={180:virtual, 0:virtual, 90:physical:$i_2$}]{A} &
    \tn[ports={180:virtual, 0:virtual:$\beta$, 90:physical:$i_3$}]{A}
  \end{tenkz}
  \hspace{13mm}
  \begin{tenkz}[rows={ket,bra}, cols=1, west=open, east={cup=$X$}]
    \tn[label pos=90]{A} \\
    \tn[label pos=270]{$\overline{A}$}
  \end{tenkz}

  \vspace{16mm}
  \begin{minipage}{0.78\mfullwidth}
    \large
    A picture chooses one layout; its options declare topology and
    policy; its body declares atoms, connections, regions, and
    annotations.
  \end{minipage}
\end{fullwidth}

\clearpage
\setcounter{tocdepth}{1}
\tableofcontents

\input{chapters2/ch-mathematics}
\input{chapters2/ch-modes}
\input{chapters2/ch-tutorial}
\input{chapters2/ch-worked}
\input{chapters2/ch-catalogue}
\input{chapters2/ch-reference}
\input{chapters2/ch-house}
\input{chapters2/ch-rmp}
\input{chapters2/ch-trouble}
\input{chapters2/ch-references}

\begin{quickrefcard}[The tenkz language at a glance]
  \qrsection{Layout and frame}
  \qritem{tenkz}{one typed tensor network in one frame}

  \qrsection{The five grammatical classes}
  \qritem{atoms}{tn, tnfuse, tntree}
  \qritem{connections}{tnwire, tnbond, implicit bonds, cups, traces}
  \qritem{annotations}{tnmark, labels}
  \qritem{composition}{TeX equations, alignment, tngroup}
  \qritem{setup}{tnset, tndeclare, themes}

  \qrsection{Boundary conditions}
  \qritem{boundary=open}{mints the side legs and puts them in the
    signature; an unstated side draws no leg}
  \qritem{boundary=none}{the explicit spelling of the default}
  \qritem{boundary=periodic}{returns each row to itself}
  \qritem{west=cup / east=cup}{connects adjacent layers, and outranks
    boundary= on its own side}
  \qritem{.tnlog}{records the resolved boundary signature}

  \qrsection{Stylistic conventions}
  \qritem{one layout}{choose from topology, not silhouette}
  \qritem{explicit scope}{document, picture, object, connection}
  \qritem{typed ports}{virtual joins virtual; physical joins physical}
  \qritem{role/species}{semantic style, never topology}
  \qritem{route=arc}{leaves and enters along its ends' faces; the family is straight, orth, arc}

  \qrsection{Verification and tools}
  \qritem{xelatex}{compile the exact source}
  \qritem{tenkz\_audit.py}{audit the versioned semantic event stream}
  \qritem{tenkz\_lint.py}{reject non-canonical source}
  \qritem{pdftocairo}{render and inspect the affected pages}
  \qritem{tenkz\_rmp.py}{build the separate 130-target benchmark book}
\end{quickrefcard}

\end{document}