%# -*- coding: utf-8 -*-
\ifx\epTeXinputencoding\undefined\else % defined in e-pTeX (> TL2016)
  \epTeXinputencoding utf8    % ensure utf-8 encoding for platex
\fi

\documentclass[a4paper]{jsarticle}
\usepackage{doc}
\makeatletter
%%% import from jltxdoc.cls
\def\verb{\relax\ifmmode\hbox\else\leavevmode\vadjust{}\fi
  \bgroup \let\do\do@noligs \verbatim@nolig@list
    \ttfamily \verb@eol@error \let\do\@makeother \dospecials
    \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}}
\xspcode"5C=3 %% \
\xspcode"22=3 %% "
%%% dangerous bend
\font\man=manfnt at 10pt
\def\dbend{\leavevmode\raise0pt\hbox{\man\char'177}}
\newenvironment{dangerous}{%
  \ifnum\@listdepth>\z@
    \GenericError{}{Do not use `dangerous' environment inside any list}{}{}
  \fi
  \par\addvspace\medskipamount
  \@tempdima=\dimexpr\textwidth-2zw\relax\small
  \divide\@tempdima by\dimexpr1zw\relax\@tempcnta=\@tempdima
  \leftskip=\dimexpr\textwidth-\@tempcnta zw\relax
    \@totalleftmargin\dimexpr\leftskip+0zw
    \linewidth=\dimexpr\@tempcnta zw-0zw
  \parindent1zw\noindent\kern-\leftskip\hbox to\leftskip{\dbend\hss}%
  \everypar{\everypar{}}\ignorespaces
}{\par\addvspace\medskipamount}
%%% misc
\newcommand{\Meta}[1]{$\langle$\mbox{}\textit{#1}\mbox{}$\rangle$}
\newcommand{\jMeta}[1]{$\langle$\mbox{}\textsf{#1}\mbox{}$\rangle$}
%%%
\makeatother
\usepackage{longtable}
\usepackage{pxgentombow}
\usepackage{bounddvi}
\GetFileInfo{pxgentombow.sty}
\title{Package \textsf{pxgentombow} \fileversion}
\author{Hironobu Yamashita}
\date{\filedate}
\begin{document}

\maketitle

\begin{center}
English version is available: see \textsf{gentombow} package!
\end{center}

日本の出版では、たとえば仕上がり寸法がA4サイズの場合、一回り大きな
B4サイズの用紙の中央にトンボ付きで印刷することがあるようです。
このドキュメントは、実際にA4用紙をB4用紙の中央にトンボ付きで
配置している事例です。

\textsf{pxgentombow}パッケージは、クラスファイルなどが想定している用紙
サイズ情報（\verb+\paperwidth+, \verb+\paperheight+）を検知し、
それより一回り大きなサイズの用紙の中央にトンボ付きで出力するために
必要な機能を提供します。
ただし、このパッケージは実際の出力サイズ指定を発行しませんので、
以下のいずれかのパッケージと併用するとよいでしょう：
\begin{itemize}
\item \textsf{bounddvi}パッケージ（\textsf{platex-tools}バンドル）
\item \textsf{bxpapersize}パッケージ（ZRさん作）
\item \textsf{graphicx}パッケージの2016年以降の版
  （\texttt{setpagesize}機能つきのもの）
\end{itemize}
\textsf{bounddvi}パッケージは、\textsf{pxgentombow}と同じく
\textsf{platex-tools}バンドルに収録されていますが、
名前のとおりDVIを経由する場合にしか利用できません。
一方、\textsf{bxpapersize}パッケージは汎用で、Lua\TeX のような
PDF直接出力の場合にも利用できます。また、\textsf{graphicx}パッケージ
は画像挿入用のパッケージですが、2016年以降は自動的に出力サイズ指定も
行うようです（$\verb+\mag+ \ne 1000$の場合には機能しません）。

使い方の例は
\begin{verbatim}
  \documentclass[a4j]{jarticle}
  \usepackage{pxgentombow}
  \usepackage{bounddvi}
  \begin{document}
  …本文…
  \end{document}
\end{verbatim}
です。p\LaTeX における横組と縦組の両方で使え、また\textsf{jsclasses}の
ような版面拡大(\verb+\mag+)が使われた場合にも対応しています。
なお、\textsf{pxgentombow}パッケージはp\LaTeX とup\LaTeX および
Lua\TeX-jaのみで動作します。その他（pdf\LaTeX など）で使いたい
場合は、代わりに\textsf{gentombow}パッケージを使用してください。

本パッケージは、\textsf{platex-tools}バンドルの一部として
配布されています：
\begin{verbatim}
  https://github.com/aminophen/platex-tools
\end{verbatim}

\section*{用紙サイズの自動検知による出力サイズ決定}

パッケージにはあらかじめA系列(\texttt{a0}--\texttt{a10})、
B系列(\texttt{b0}--\texttt{b10})、C系列(\texttt{c0}--\texttt{c10})と
\texttt{letter}, \texttt{legal}, \texttt{executive}の用紙サイズが
定義されています。ここで、B系列はISOではなくJISです。
また、変型版として\texttt{a4var}（\texttt{a4}の変型）と
\texttt{b5var}（\texttt{b5}の変型）も定義されています。

これらのうちいずれか（ただし\texttt{a0}, \texttt{b0}, \texttt{c0}を
除く）の用紙サイズを検知すると、
出力サイズが次の規則で自動的に決定されます\footnote{なお、
C系列と\texttt{letter}, \texttt{legal}, \texttt{executive}については
日本での慣習が不明の
ため、現時点ではA系列のサイズで出力することにしています。}。
\begin{itemize}
\item 用紙サイズがA系列のとき：
        出力サイズは一回り大きなB系列
\item 用紙サイズがB, C系列または
      \texttt{letter}, \texttt{legal}, \texttt{executive}のとき：
        出力サイズは一回り大きなA系列
\end{itemize}
この場合、パッケージを読みこんだだけでトンボが付きます。
なお、用紙サイズが横長の場合は自動的に出力も横長になり、
縦長の場合は自動的に縦長になります。

よく使われる用紙サイズの例を挙げます。
\begin{longtable}[c]{cc}
  \hline
  用紙サイズ & 出力サイズ \\
  \hline
  a6 & b6 \\
  b6 & a5 \\
  a5 & b5 \\
  b5 & a4 \\
  a4 & b4 \\
  b4 & a3 \\
  a3 & b3 \\
  b3 & a2 \\
  \hline
  c6 & a5 \\
  c5 & a4 \\
  c4 & a3 \\
  c3 & a2 \\
  \hline
  letter    & a3 \\
  legal     & a3 \\
  executive & a4 \\
  \hline
\end{longtable}

\section*{用紙サイズの自動検知に失敗した場合の出力サイズ決定}

仮に用紙サイズが定義済みのいずれとも異なる場合は、デフォルトでは
用紙の天地左右に1インチずつのノビを付けたサイズで出力します。
たとえば、幅$100\,\mathrm{mm}$、高さ$200\,\mathrm{mm}$の用紙の場合、
出力サイズは幅$100\,\mathrm{mm}+2\,\mathrm{in}$、
高さ$200\,\mathrm{mm}+2\,\mathrm{in}$になります。

\section*{オプションによる出力サイズの明示指定}

自動決定されるサイズと異なるサイズに出力したい場合、
パッケージオプションで明示的に指定することができます。たとえば
\begin{verbatim}
  \documentclass[a4j]{jarticle}
  \usepackage[tombow-a3]{pxgentombow}
  \begin{document}
  …本文…
  \end{document}
\end{verbatim}
とすると、出力サイズは（自動決定のb4は無視されて）a3に変わります。
指定可能なサイズは、定義済みの用紙サイズと同じものです。すなわち、
A系列(\texttt{a0}--\texttt{a10})、
B系列(\texttt{b0}--\texttt{b10})、
C系列(\texttt{c0}--\texttt{c10})と
\texttt{a4var}, \texttt{b5var},
\texttt{letter}, \texttt{legal}, \texttt{executive}です。
なお、ここでも用紙サイズが横長の場合は自動的に出力も横長になり、
縦長の場合は自動的に縦長になります。

オプションは\jMeta{トンボ形式}\texttt{-}\jMeta{出力サイズ}の書式で与えます。
トンボ形式は、p\LaTeX の標準クラスと同じで
\verb+tombow+, \verb+tombo+, \verb+mentuke+のいずれかを選びます
（\verb+tombow+はジョブ情報を表示し、\verb+tombo+は表示しません。
また、\verb+mentuke+はトンボの線を表示しません）。

\section*{トンボに表示するジョブ情報の有無}

用紙サイズの自動検知によって出力サイズが決まる場合、デフォルトでは
\makeatletter\texttt{\the\@bannertoken}\makeatother
のようにトンボにジョブ情報が出力されます。これを無効化するには
\begin{verbatim}
  \documentclass[a4j]{jarticle}
  \usepackage[notombowdate]{pxgentombow}
  \begin{document}
  …本文…
  \end{document}
\end{verbatim}
とします。

\section*{\textsf{jsclasses}で使用する場合の注意}

奥村晴彦氏による\textsf{jsclasses}のクラス（2016年以降は日本語\TeX 開発
コミュニティが管理）を使用していて、10pt以外のサイズオプションを
指定する場合は、以下のいずれかの方法をとってください。
\begin{itemize}
\item クラスオプションに「トンボオプション」
      （\verb+tombow+または\verb+tombo+）を追加する。
\item クラスオプションに「\verb+\mag+を使わないオプション」
      （\verb+nomag+または\verb+nomag*+）を追加する。
\end{itemize}
これは、\textsf{jsclasses}クラス内で行われる\verb+\oddsidemargin+と
\verb+\topmargin+の計算の都合からくる制約です。たとえば
\begin{verbatim}
  \documentclass[a4j,14pt]{jarticle}
  \usepackage{pxgentombow}
\end{verbatim}
という使い方は\emph{誤り}です（このままでは誤った余白設定が
適用されますので、安全のため\textsf{pxgentombow}パッケージ
がエラーを出すようにしてあります）。代わりに
\begin{verbatim}
  \documentclass[a4j,14pt,tombow]{jarticle}
  \usepackage{pxgentombow}
\end{verbatim}
と書くようにしてください。

同様に、ZR氏による\textsf{BXjscls}のクラスを使用していて、10pt以外の
サイズオプションを指定する場合は
\begin{itemize}
\item クラスオプションに「\verb+\mag+を使わないオプション」
      （\verb+nomag+または\verb+nomag*+）を追加する。
\end{itemize}
という対処が必要です（\textsf{BXjscls}クラスでは「トンボオプション」が
機能しないダミーになっていることに注意）。

\section*{レイアウト設定の注意}

余白などのレイアウト設定でありがちですが、
\verb+\hoffset+や\verb+\voffset+の値を$0$以外に設定するのは
避けてください。このような設定は\textsf{pxgentombow}パッケージの
トンボ出力機能と衝突するため、正しい出力が得られません。
レイアウト設定のために変更すべきなのはこれらの寸法ではなく、
\verb+\oddsidemargin+や\verb+\topmargin+であることがほとんどです。
したがって、それらを適切な値に設定するか、レイアウトの設定すべてを
\textsf{geometry}パッケージに任せてしまうのも一つの方法です。

\begin{dangerous}
たとえば左右の余白を$25\,\mathrm{mm}$に、上下の余白を
$30\,\mathrm{mm}$にしたいとき\footnote{ここでは「本文の領域以外」を
余白と定義します。すなわち、ヘッダとフッタは余白の一部です。}、
まず「\TeX の1インチ」を
削除してから\verb+\oddsidemargin+や\verb+\topmargin+を変更すると、
「見かけ上は」期待どおりの結果になることがあります。
\begin{verbatim}
  \setlength{\hoffset}{-1in}% <== NG
  \setlength{\voffset}{-1in}% <== NG
  \setlength{\oddsidemargin}{25mm}
  \setlength{\topmargin}{30mm}
  \setlength{\textwidth}{\paperwidth}
  \addtolength{\textwidth}{-2\oddsidemargin}
  \setlength{\textheight}{\paperheight}
  \addtolength{\textheight}{-2\topmargin}
  \addtolength{\topmargin}{-\headheight}
  \addtolength{\topmargin}{-\headsep}
\end{verbatim}
しかし、この設定では\textsf{pxgentombow}パッケージがトンボを
追加するとき、正しい余白を維持することができません。

一方、\verb+\hoffset+や\verb+\voffset+は$0$のままで、以下のように
\verb+\oddsidemargin+や\verb+\topmargin+を設定していれば問題ありません。
\begin{verbatim}
  \setlength{\oddsidemargin}{-0.4mm}% 25mm = 1inch - 0.4mm
  \setlength{\topmargin}{4.6mm}%      30mm = 1inch + 4.6mm
  \setlength{\textwidth}{\paperwidth}
  \addtolength{\textwidth}{-50mm}
  \addtolength{\topmargin}{-\headheight}
  \addtolength{\topmargin}{-\headsep}
  \setlength{\textheight}{\paperheight}
  \addtolength{\textheight}{-60mm}
\end{verbatim}
これと同等のレイアウト設定は、以下のように\textsf{geometry}パッケージで
行うのが簡単です。
\begin{verbatim}
  \usepackage[lmargin=25mm,rmargin=25mm,
              tmargin=30mm,bmargin=30mm]{geometry}
\end{verbatim}
\end{dangerous}

\section*{雑記}

発端はこの話です。
\begin{itemize}
\item 齋藤修三郎 (@psi\_tau) on Twitter, 2017年2月9日\\
  \texttt{https://twitter.com/psi\_tau/status/829873082911248386}
\end{itemize}

また、現在検討中の事項を挙げておきます。
\begin{itemize}
\item 現状では、用紙の横長・縦長がそのまま出力に反映されるので、
  これを逆転させるオプションの実装。また、任意の出力サイズを
  指定できるインタインタフェースの実現。
\item 自動で決定できる出力サイズの拡張。現状では用紙サイズが
  定義値に完全一致する場合のみ自動決定されるが、中間のサイズでも
  その一回り大きなサイズに出力することは可能と思われる。
\item 出版用途ではカラー印刷の場合に、CMYKの版ごとにトンボを作る
  必要がある。\textsf{color}パッケージが読み込まれている場合に、
  オプション次第でCKなど必要に応じた色を選べるようにするとよい
  のではないか\footnote{ただし作者の本業は出版ではないので、
  商用を含む実用には程遠いかもしれない。}。
\item $\verb+\mag+ \ne 1000$の場合について、\textsf{jsclasses}以外での
  動作は未確認。特に、\textsf{geometry}とは共存しない可能性が高い。
\item \verb+\stockwidth+/\verb+\stockheight+が
  \verb+\paperwidth+/\verb+\paperheight+より小さい場合の動作。
  現在は警告を出すだけとしているが、さらに天地左右1inに
  フォールバックしたほうが無難だろうか。
\item p\LaTeX/up\LaTeX/Lua\TeX-ja以外のサポート。
\end{itemize}

\section*{変更履歴}

\begin{itemize}
  \item 2017/02/10 v0.1 最初の公開版
  \item 2017/03/01 v0.4 トンボ形式の修正など
  \item 2017/05/05 v0.5 \textsf{jsclasses}の$\verb+\mag+ \ne 1000$に対応、
                        最初のCTANリリース版
  \item 2017/05/06 v0.6 \textsf{jsclasses}との共存時のチェック強化、
                        Lua\TeX-jaでの動作確認
  \item 2017/07/23 v0.7 ドキュメント更新、CTANリリース版
  \item 2017/12/17 v0.9 \textsf{gentombow}パッケージの新設、CTANリリース版
\end{itemize}

\end{document}
