%% pxpgftate.tex -- documentation for the pxpgftate package
%%
%% Copyright (c) 2015-2026 Munehiro Yamamoto <munepixyz@gmail.com>
%% License: LPPL 1.3c or later and/or GPL 2 or later
%%
%% Build: make pxpgftate.pdf
%%   (runs uplatex+dvipdfmx on test-pxpgftate.tex for the example pages,
%%    then pdflatex pxpgftate.tex twice)
\documentclass{article}
\usepackage[margin=28mm]{geometry}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage[colorlinks, allcolors=blue!50!black]{hyperref}
\newcommand*\pxpversion{v1.0 (2026/11/04)}
\newcommand*\cs[1]{\texttt{\char`\\#1}}
\newcommand*\pkg[1]{\textsf{#1}}
\newcommand*\opt[1]{\texttt{#1}}
\newcommand*\meta[1]{$\langle$\textit{#1}$\rangle$}

\title{The \pkg{pxpgftate} package\\
  \large PGF/Ti\textit{k}Z in the vertical (tate) direction of (u)p\LaTeX}
\author{Munehiro Yamamoto\\
  \url{https://github.com/munepi/pxpgftate}}
\date{\pxpversion}

\begin{document}
\maketitle

\section{Introduction}

In the vertical (tate) direction of p\TeX{} and up\TeX, the DVI drivers
place the characters rotated, but PGF draws its pictures in the
unrotated page coordinate system.  Without this package,
\begin{itemize}
\item pictures in tate text come out sideways relative to the text
  (\opt{dvipdfmx});
\item shadings, patterns and fadings stop p\LaTeX{} with
\begin{verbatim}
! Incompatible direction list can't be unboxed.
\end{verbatim}
  because the material that PGF collects for the beginning of the page
  is set in the tate direction, but unboxed at shipout in the yoko
  direction;
\item \opt{remember picture}, \opt{overlay} and the \opt{current page}
  node use page positions that are not rotated into the picture.
\end{itemize}

With this package, a picture that begins in the tate direction is
rotated like the surrounding text: its $x$-axis points in the direction
of the line (downwards) and its $y$-axis points to the right.  Text in
nodes is typeset in the tate direction.  The direction is determined at
the beginning of each picture, so yoko boxes inside tate text keep
working as before.

Supported:
\begin{itemize}
\item paths, nodes, transformations (\opt{rotate}, \opt{transform
  shape}), colors;
\item shadings, patterns, fadings, transparency groups;
\item \opt{remember picture}, \opt{overlay} and the \opt{current page}
  node;
\item tcolorbox (also \opt{enhanced}, \opt{breakable},
  \opt{drop shadow}).
\end{itemize}

Figure~\ref{fig:example} shows the top of the first page of the test
document
\texttt{test-pxpgftate.tex}, typeset with up\LaTeX{} and
\opt{dvipdfmx}.

\begin{figure}[htbp]
  \centering
  \fbox{\includegraphics[page=1,viewport=50 520 545 810,clip,
    width=.9\linewidth]{test-pxpgftate-uplatex-dvipdfmx.pdf}}
  \caption{\texttt{test-pxpgftate.tex} (utarticle, up\LaTeX{} $+$
    \opt{dvipdfmx}, top of page~1).  Read the columns from right to
    left.}
  \label{fig:example}
\end{figure}

The package is meant for \TeX\ Live 2012 up to the release of PGF that
supports the tate direction itself.  When the loaded PGF supports it
already (it defines \cs{pgfsys@ptex@tate@supported}), the package does
nothing.

\section{Requirements}

\begin{itemize}
\item p\LaTeX{} or up\LaTeX{} (\TeX\ Live 2012 or later);
\item PGF 2.10 or later;
\item the \opt{dvipdfmx} or \opt{dvips} driver.  With other drivers,
  and with engines other than p\TeX{} and up\TeX, the package does
  nothing.
\end{itemize}

\section{Usage}

Load the package after \pkg{tikz} (or \pkg{pgf}):
\begin{verbatim}
\documentclass[dvipdfmx]{tarticle}
\usepackage{tikz}
\usepackage{pxpgftate}
\begin{document}
...\tikz\draw[->] (0,0) -- (1,0);...
\end{document}
\end{verbatim}
Loading it before PGF works, too; the patches are then applied at
\verb|\begin{document}|.  The package has no options.  It writes to the
log which driver it patched, or why it does nothing.

\section{When PGF supports the tate direction itself}

Support for the tate direction has also been proposed for PGF itself
(\href{https://github.com/pgf-tikz/pgf/pull/1487}{pgf-tikz/pgf\#1487}).
Once a release of PGF includes it, PGF handles pictures in tate text by
itself, and this package does nothing: it leaves PGF alone and only
writes the following to the log:
\begin{verbatim}
Package pxpgftate Info: PGF supports the tate direction itself.
(pxpgftate)             Nothing is done on input line ....
\end{verbatim}
So you can keep \verb|\usepackage{pxpgftate}| in your documents: they
work both with older \TeX\ Live (where the package does the work) and
with newer \TeX\ Live (where PGF does it), and look the same.  You may
remove the line once you use only a PGF with the native support.

\section{What it changes}

The package wraps the driver macros of PGF instead of copying them, so
that the same code works with the different PGF versions of
\TeX\ Live 2012--2026.  It does not replace any file of PGF.

\begin{itemize}
\item \cs{pgfsys@beginpicture}, \cs{pgfsys@endpicture}: rotate the
  picture in the tate direction (\opt{dvipdfmx}; \opt{dvips} rotates
  PostScript specials by itself).
\item \cs{pgfsys@hbox}, \cs{pgfsys@hboxsynced},
  \cs{pgfsys@transparencygroupfrombox}: undo the rotation around the
  current point for boxes and XObjects (\opt{dvipdfmx}).  This uses
  \verb|pdf:bcontent| rather than \verb|pdf:btrans|, which is misplaced
  inside \verb|pdf:bcontent| and in XObjects with \opt{dvipdfmx} before
  \TeX\ Live 2021.  With PGF 2.10 (\TeX\ Live 2012), the box macros of
  PGF 3.0 are used in tate pictures, since the ones of PGF 2.10 only
  work in unrotated pictures.
\item \cs{pgfsys@getposition}, \opt{current page}: rotate page
  positions into the coordinate system of a tate picture.
\item \cs{pgfutil@insertatbegincurrentpagefrombox},
  \cs{pgfdeclarefading}, \cs{tikzfadingfrompicture}, \cs{tikzfading}:
  always use the yoko direction, since this material is unboxed at
  shipout in the yoko direction.
\item With \LaTeX{} before 2020-10-01 and \pkg{everyshi} v3: the shipout
  hooks are run in the yoko direction, as the \pkg{pxeveryshi} package
  does.  This affects all users of \pkg{everyshi} in tate documents.
  Nothing is done when \pkg{pxeveryshi} is loaded.
\end{itemize}

\section{Limitations}

\begin{itemize}
\item Only the tate direction is handled; the \cs{dtou} direction is
  not.
\item Fadings are always defined in the yoko direction, also when they
  are declared in tate text.
\item \opt{remember picture}, \opt{overlay} and \opt{current page} need
  the position tracking of PGF, which PGF enables for p\LaTeX{} only from
  \TeX\ Live 2018 on.  This is the same in yoko documents.
\item With \opt{dvips}, fadings need a PGF that supports them with
  \opt{dvips} (not the one of \TeX\ Live 2016 or earlier), and Japanese
  fonts need the usual font map setup for \opt{dvips} and Ghostscript.
  Both are independent of this package.
\end{itemize}

\section{Tests}

The repository ships \texttt{test-pxpgftate.tex}, which exercises all
the features listed above.  \verb|make test| typesets it with the
installed \TeX\ Live, with p\LaTeX{} and up\LaTeX{}, \opt{dvipdfmx} and
\opt{dvips}, and checks that there are no errors and that pxpgftate
patched the driver.  \verb|make test-matrix| (\texttt{run-matrix.sh},
not part of the CTAN archive) does the same with every \TeX\ Live
from 2012 to 2026 (installed in \texttt{/opt/texlive/}\meta{year}),
and renders the first page of each result for a visual check.

\section{History}

This package grew out of patches for PGF in the tate direction that the
author has been developing since 2015 for book production with
p\LaTeX{} and \opt{dvipdfmx}.  In 2024 they were put together as
\texttt{pgfsys-dvipdfmx-ptextate.sty} and two patched copies of
\texttt{pgfutil-latex.def}.  The package was then rewritten to
patch PGF without replacing its files, and extended to \opt{dvips} and to
the PGF versions of \TeX\ Live 2012--2026.

\begin{description}
\item[v1.0 (2026/11/04)] First release.
\end{description}

\section{License}

This package may be distributed and/or modified under the conditions of
the \LaTeX{} Project Public License, version~1.3c or (at your option)
any later version, and/or under the GNU General Public License,
version~2 or (at your option) any later version, like PGF itself.  See
the file \texttt{LICENSE}.

\medskip
\noindent
Copyright \copyright{} 2015--2026 Munehiro Yamamoto

\end{document}