kaishi の解説
はじめに#
ここでは、kaishiの構造や、独自コマンドなどの解説をします。
ここの話は知っておかなくても、テンプレをコピペして編集すれば、会誌記事を書く分には問題ないかと思います。
会誌のリポジトリ管理の引継ぎが主な目的です。
kaishi の歴史#
ここは読み飛ばしていいです。
思想やら目的がわかりやすいかと思うので、一応開発の歴史を簡単に述べます。
2016年度#
2016年度までの会誌は、WordでもLaTaXでもなんでもいいので、とりあえず各自記事を作成し、PDF化あるいは印刷して順番に並べてから手動でページ番号や目次を作っていました。
できるだけ自動化したいのと、やはりLaTeXで作った方が美しくできるので、来年からはみんなLaTeXで作りましょうということになりました。
2017年度#
夏に開催したOB会で去年の会誌を配布することになったのですが、良い機会なのでLaTeXで作り直すことにしました。
当時はまだGitHubは利用していませんでしたが、ソースコードはあとからリポジトリを作って置いています。
工夫した点は、記事毎にファイルを分割して、\input コマンンドで各記事を呼び出してマージしているぐらいです。
学園祭で配布した2017年度の会誌では、少しだけソースをきれいにしました。
この時点では、各記事が完全に完成してから、最後にまとめる作業をするという感じでした。
2018年度#
この年からは、記事のタイトル出力などのコマンド群をマクロ化し、表紙もLaTeXで作るようにしました（画像を読み込むだけですが）。
また、jsbookクラスの \chapter コマンドを改造して、目次に記事タイトルと著者を出力できるようにしました。
さらに、記事の更新とマージの作業を同時に行えるように努力した結果、リポジトリを見てもらえばわかるようにファイルがかなり散らかっています。
input コマンドの代わりにemathパッケージの \ReadTeXFile コマンドを使うことで、記事単体でもタイプセットでき、そのままマージもできるようになりました（読み込むファイルに \documentclass などが書いてあっても良い）。
とはいえ、記事の更新はSlackにアップロードされたファイルを、編集者がダウンロードして随時マージという作業をしていました。
どれが最新のファイルかわからなくなったり、同時作業で衝突し、進捗が消滅したりしていました。
2019年度#
2019年度からはLaTeXをある程度理解し、latexmkを明示的に使えるようになり、vscodeというエディタも使って効率的にタイプセットできるようになりました。
がっつりマクロを組み、ディレクトリ構造はスマートになり、マージする環境と記事を更新する環境を同じにしました。
input コマンドの代わりは emath のものはもう使わず、自分で改造したものを使っています。
また、この年からGitHubを使って共同開発するようにしました。
と言っても誰もGitが使えなかったので、ただのクラウドストレージとしての機能しか果たしていませんでしたが。
あとは、MacとWindowsでデフォルトのフォントが異なり、完成版のPDFに違いがでてしまうので、フリーの源ノというフォントを使うようにしました。
独自マクロなど非自明なことが増えたので、環境構築のマニュアルを簡単に作りました。
2020年度#
殆どは去年のものがベースになっていますが、細かいところを少し変更しました。
まず、今までは sty ファイルに色々マクロを書くことで jsbook クラスを改造していましたが、今回からはちゃんと cls ファイルを作ってそこに書くようにしました。
また、去年は各記事のプリアンブルは同一のファイルに書くようにしていましたが、同じファイルをみんなで弄るのはアレなので、記事毎に分割しました。
未だ全然使いこなせていませんが、一応もう少しGitのありがたみを感じるべく、branch運用を始めました。
開発環境はvscodeで統一することにしました。そのための設定ファイルや ltexmkrc なども用意しました。
という感じで年々開発が進んできましたが、そろそろ引き継がないとまずいので、ちゃんとマニュアルを作ることにしました。
kaishiのディレクトリ構造#
kaishiのディレクトリ構造は以下のようになっています；
kaishi/
|- etc/ % 設定メモなど、いろいろ
|- fonts/ % フォント（源ノ）を入れる
|- sty/ % texliveで標準インストールされないものや自作スタイルファイル
| |- v-hyperref.sty % hyperref.sty の改造版
| |- vkaishi.cls % 会誌のクラスファイル
| `- vuccaken.sty % 共通設定や細かいマクロ
|- tex/
| |- _BK/ % 表紙や奥付など
| |- _sample/ % 会誌記事サンプル
| |- _template/ % コピペ用テンプレート
| ...
|
|- .gitignore % git で無視するファイルを指定
|- .latexmkrc % latexmk の設定ファイル
`- merge.tex % 各texファイルをまとめる
/tex/ 以下に、記事毎にディレクトリを作り、その中で記事の更新作業を行います。
/merge.tex をタイプセットすることで、それらの記事を読み込み、マージして会誌を完成させます。
必要なstyファイルなどは /sty/ 以下に置いています。
ここにあるstyなどを、/merge.tex や各記事のtexファイルでロードするようにしています。
タイプセットに必要なLaTeXの環境設定は .latexmkrc に書かれています。
エディタvscodeのための設定ファイルのサンプルは /etc/ の中に置いています。
タイプセット方法#
会誌のtexファイルのタイプセットには latexmk コマンドを使います。
また、エディタ vscode を使えば、ボタン一つでタイプセットできます。
latexmk でタイプセット#
ターミナル（黒い画面のやつ）を開いて、GitHubからクローンした会誌のディレクトリの一番上（merge.tex がある階層）に移動します。
記事のtexファイル、例えば tex/nakasu/nakasu.tex をタイプセットするには、
ターミナルから次のコマンドを実行します；
latexmk -cd ./tex/nakasu/nakasu.tex
Info
サブディレクトリにあるtexファイルを latexmk コマンドでタイプセットするときは -cd オプションが必要です。
このオプションがないと、texファイルで読み込んでいる（画像などの）ファイルのパスが合わなくてうまくタイプセットできません。
Attention
merge.tex があるディレクトリからではなく、タイプセットしたいtexファイルがある tex/nakasu/ に移動してから latexmk nakasu.tex した方が楽と思うかもしれませんが、それではダメです。
latexmk コマンドのための設定ファイル .latexmkrc がカレントディレクトリにないと、タイプセットがうまくいかないからです。
また、記事を統合するための merge.tex をタイプセットするには、次のコマンドを実行します；
latexmk ./merge.tex
vscode でタイプセット#
vscodeを使ったタイプセット方法については、チュートリアルの方に書いてあるので、そちらを参照してください。
TeXworks や TeXShop では？#
TeXworks や TeXShop でも頑張れば kaishi をタイプセットすることはできますが、設定が面倒なのでオススメはしないでおきます。
どうしてもこの環境でてふてふしたい人は、LaTeX が詳しい人に相談してください。
その他エディタ#
latexmk コマンドが呼び出せれば、多分できると思います。
設定頑張ってください。
諸注意#
チュートリアルでは触れなかった、会誌を書くにあたっての注意点です。
ラベル名#
残念ながら、\label や \bibitem コマンドで指定する図・数式や参考文献などのラベル名は他人と被ってはいけません。
とりあえずは気にせず記事を書き進めてもらって構いませんが、 もしかすると全体と統合する際にラベル名の変更をお願いする場合があるということだけ覚えておいてください。
Info
ラベル名に重複があると、タイプセットの際に LaTeX が警告（エラーではない）をログに吐いてくれます。 エラーは出ずタイプセットは通ってしまうので、統合した際に警告が出ていないかチェックを忘れないようにしてください。
Failure
各記事を読み込む際にラベル名がユニークになるように \label や \ref を置換すればいいと思ったのですが、LaTeX の処理が複雑でなんか無理でした。
Success
本来は記事に挿入する画像のファイル名についても、ラベル名と同様に他人とかぶってはいけないという問題があります。 しかし、この問題に関しては、超人的なプログラミング力によって解決済みです。
よって、画像のファイル名に関しては、他の人とファイル名が被る心配はしなくても良いです。
句読点の自動置換#
句読点は、和文のもの（、。）ではなく、欧文の全角のもの（，．）で統一したいと思います。
そのため、（vscode で）タイプセットする際に、自動で句読点を置換するように設定していますので注意してください。
Error
句読点の自動置換は一旦やめることにしました。どうやら perl コマンドが使えないみたいです（パスが通っていない）。
latexmk が perl で動いているので、インストールはされているはずなのですが、Windows でのパスがわかりません。
Question
ということで、全体で統一せずに各自に任せるか、最終段階で一括置換するか、どうしましょう。
Note
一部（タイトルとか）で和文の句読点が使いたいときは、それぞれ句点 \vku、読点 \vtou のコマンドを書いてください。
記事のtexファイル#
まずは記事のtexファイルで使われているコマンドの解説をします。
最小限のソースコードは以下のような感じです；
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | |
上から順に説明していきます。
document class#
\documentclass[uplatex,dvipdfmx]{vkaishi}
おなじみの \documentclass コマンドです。
ここではひとつめの引数に uplatex と dvipdfmx を与えています。
これは、kaishiは uplatex でタイプセットし、dvipdfmx を使ってpdfを生成するということです。
ふたつめの引数 vkaishi は自作のクラスファイルの名前です。
ソースは /sty/ に置いてあります。
vkaishi クラスは、jsbook クラスという和文書籍のためのクラスを改造したものです。
実際、vkaishi.cls の中で jsbook クラスを読み込んでいます。
Note
クラスのオプションに analog というものを用意しています。
これを指定すると、見開きのページの間にマージン（スペース）を入れます。
会誌を紙で印刷し、製本する際にホチキス留めのスペースを確保するためのものです。
インナーマージンを入れると言っても、コンテンツ（本文）の領域（幅）を外側へ平行移動するだけなので、レイアウトが崩れるということはありません。
styファイルの読み込み#
プリアンブルではまず、styファイルを読み込んでいます；
% \usepackage{v-hyperref}
\usepackage{vuccaken}
\usepackage{template}
v-hyperref パッケージと vuccaken パッケージは自作のstyファイルで、こちらも /sty/ の中にソースがあります。
v-hyperref パッケージは、目次や式番号などにハイパーリンクを付けるためのパッケージ hyperref.sty を、自作のクラスファイル vkaishi.cls でもうまく機能するために改造（調整）したものです。
このパッケージを読み込むと、ハイパーリンクが埋め込まれますが、タイプセット回数が増えたりして少し重くなるので、記事作成中はコメントアウトしておくことをお勧めします。
vuccaken パッケージは、共通で必要なパッケージなどをまとめて読み込んだり、簡単なマクロを書いたりしています。
このパッケージは読み込んでいないとタイプセットに失敗するので、ちゃんと書いておいてください。
3つめに読み込んでいるのは、本来プリアンブルに書くべき、記事で必要なパッケージやマクロを別ファイル（styファイル）にしたものです。 これは、マージの過程でどうしても必要になってしまったので、面倒ですが、本来プリアンブルに書きたいことは別ファイルにして読み込んでください。
Info
各記事のtexファイルのプリアンブルに書かれていることは、マージする際には読み飛ばされます。
プリアンブル部分は別ファイルにし、merge.tex ではそれを記事のtexファイルとは別に読み込みます。
if文スイッチ#
プリアンブルにはまだ何か書かれています；
% \colorfalse
デフォルトではコメントアウトしていますが、これはif文のスイッチです。 コメントアウトを解除すると機能します。
\colorfalse は、カラー印刷用とモノクロ印刷用で図などを切り替えるためのスイッチです。
これをオンにすると、モノクロ印刷用にカラーをオフにします。
このスイッチでカラー用とモノクロ用で図などを切り替えるには、\vcolor コマンドを使って以下のようにします；
\vcolor{
%% if color true
\includegraphics{color.png}
}{
%% if color false
\includegraphics{black-white.png}
}
まあ使いたい人だけ使ってください。
タイトル出力など#
\begin{document} から \end{document} までが本文を書く部分になります。
まずはじめに以下のようなコマンドたちが書かれています；
\title{会誌原稿テンプレート} % タイトル
\author[テンプレ]{太郎} % 名前
\belong{テンプレ科学科}{4} % 所属・回生
\mokuji{2} % 目次出力
\maketitle % タイトル出力
\title は記事のタイトル、\author は著者名、\belong は著者の所属する学部学科と回生を指定するコマンドです。
ここで指定した値を、その下にある \maketitle というコマンドで出力します。
Note
n回生の数字はアラビア数字で統一しておきましょう。
著者名を指定する \author というコマンドは引数を2つとります。
それには名前を family name と first name に分けて入力します。
例えば、\author[中須]{かすみ} のような感じです。
Tip
名前の書き方には、family name と first name の間に半角や全角のスペースを入れたり入れなかったりといろいろ流儀があります。
別になんでも良いのですが、少なくとも会誌全体では統一したいので、一応こういうマクロを作りました。
Info
普通の文書クラスからの移行で、単に \author{中須かすみ} と書いてもエラーは出ないように、第1引数はオプション引数としました。
また、こちらも同じ理由で、標準では存在しない \belong コマンドは書いてなくても \maketitle できるようにしています。
なお、\date コマンドは必要ないので無視されます。
\mokuji{2} というコマンドでは、目次を出力しています。
引数の数字は、目次に表示するセクションの深さです。
目次確認用に良かれと思って作ったコマンドなので、要らなかったらコメントアウトしておいてください。
Info
普通に \tableofcontents コマンドを書いても大丈夫です。
2回以上 \tableofcontents が現れると無視するようにコマンドを再定義しました。
Info
\mokuji{#1} コマンドは、merge.tex 以外では次のように置き換えられます。
\frontmatter % ページ番号ローマ数字
\setcounter{tocdepth}{#1} % 目次に表示する深さ
\tableofcontents % 目次出力
\mainmatter % ページ番号アラビア数字
つまり、単にページ番号を変更して \tableofcontents で目次出力しているだけです。
見出し（セクション）#
記事のタイトルは結局のところ \chapter コマンドで出力しているので、会誌記事内で使える最大の見出しコマンドは \section です。
記事内で \chapter は使わず、\section 以下でうまくやりくりしてください。
Note
\section, \subsection, \subsubsection などが使えます。
参考文献#
参考文献は thebibliography 環境で出力します。
\begin{thebibliography}{99}
\bibitem{label-1} 著者1・著者2，『本のタイトル』，出版社，出版年．
\bibitem{label-2} ...
\end{thebibliography}
item 環境と同じような感じで使ってください。
ただし、\bibitem には必ず引数が必要です。
ここで指定したラベルを本文中で \cite{label} として呼び出すことで、文献番号を参照できます。
ラベルの指定の仕方は、著者名+出版年 がお勧めです。
例えば \bibitem{nakasu2020} のような感じです。
Attention
この \bibitem のラベルは、会誌全体を通して一意的でなくてはなりません。
ラベル名に重複があると、各記事を統合した際に、エラーとはなりませんが警告が出ます。 ラベル名が他人と被ってしまった際は、面倒ではありますが、どちらかの人にラベル名を変更してもらうようお願いします。
マージ用texファイル#
ここでは、各々が書いた会誌記事を読み込んでマージ（統合）するためのtexファイル merge.tex のソースコードについて解説します。
merge.tex の中身は以下のような感じです；
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | |
document class#
1行目はおなじみの \documentclass コマンドです；
\documentclass[uplatex,dvipdfmx,merge]{vkaishi}
記事中のtexファイルのときとの違いは、オプション引数に merge を指定していることです。
このオプションは、vkaishi.cls や vuccaken.sty の中で、if文のスイッチとして使用しています。
文書クラス（vkaishi）のオプションで merge が与えられていれば、そのtex文書は記事の統合のためのファイル、与えられていなければ単なる記事のファイルであると判断されます。
Note
紙に印刷して製本する場合は、クラスのオプションに analog を設定してください。
if文スイッチ#
% \colorfalse
これは記事中のtexファイルで説明したものと同じものです。
styファイルの読み込み#
\usepackage{v-hyperref}
\usepackage{vuccaken}
\usepackage{author01}
\usepackage{author02}
% ...
v-hyperref.sty と vuccaken.sty については、記事中のtexファイルで説明した通りです。
それに続いて読み込んでいるstyファイルは、各記事のtex文書にてプリアンブルの部分を分離したstyファイルです。
二度手間ですが、記事のtexファイルとは別に、各記事のプリアンブル部分を記したstyファイルをそれぞれ読み込んでいます。
記事のtex文書の読み込み#
document 環境内では、/tex/ 以下にある各記事のtexファイルを読み込んでいます。
フロント・メイン・バックの3つの部分に分けて説明します。
front部分#
\frontmatter
\vInputTeX[_BK]{01-frontCover} % 表紙（表）
\vInputTeX[_BK]{02-insideCover} % 表紙（中）
\vInputTeX[_BK]{03-kantogen} % 巻頭言
\tableofcontents % 目次
この部分では、表紙、中表紙、巻頭言のtexファイルを順に読み込み、その後に目次を作成しています。
\frontmatter コマンドは、ページ番号をアラビア数字（1, 2, 3）ではなくローマ数字（i, ii, iii）で出力するためのものです。
書籍のフロント部分はページ番号をローマ数字で表示するのが主流です。
\vInputTeX コマンドは、標準で定義されている、texファイルを読み込んで挿入するコマンド \input を改造したものです。
このコマンドの使い方は、例えば \vInputTeX[nakasu]{kasumi} と書くと、/tex/nakasu/kasumi.tex の内容の \begin{document} ~ \end{document} の中身の部分だけが読み込まれ、そのコマンドを書いた箇所に挿入されます。
ディレクトリ名とファイル名が同じ場合は、一つめの引数（[ ] ）は省略可能です。
例えば、/tex/kasumin/kasumin.tex を読み込む場合は、一つめの引数を省略して単に \vInputTeX{kasumin} と書くだけでも良いです。
main部分#
\mainmatter
\vInputTeX{author01}
\vInputTeX{author02}
% ...
この部分で、会誌記事のtexファイルを読み込みます。
\mainmatter コマンドで、ページ番号をローマ数字からアラビア数字へと戻しています。
その後に並べられている \vInputTeX コマンドでは、会誌記事のtexファイルを読み込んで挿入しています。
会誌参加者の各記事を手動で適宜追加して行ってください。 ただし、プリアンブル部分のstyファイルの読み込みも忘れないでください。
back部分#
\backmatter
\vInputTeX[_BK]{04-hensyukoki} % 編集後記
\vInputTeX[_BK]{05-okuduke} % 奥付
\vInputTeX[_BK]{06-backCover} % 表紙（裏）
メインの会誌記事を読み込んだ後に、編集後記、奥付、裏表紙を挿入しています。
\backmatter コマンドは、ページ番号は変わりませんが、一応メインの本文とは区別するためのコマンドです。
Info
\backmatter コマンド以降では、例えば \chapter に番号が振られなかったりとかするらしいですが、多分この会誌ではあまり役には立っていません。
それでも一応 \backmatter コマンドを書いておくことにします。
記事以外の部分#
ここでは、メインとなる会誌記事以外の部分について解説します。
/tex/_BK/ 以下に配置している、表紙や巻頭言、奥付などの部分についてです。
巻頭言・編集後記#
例年の恒例で、会誌記事の前に巻頭言を、後に編集後記を書いています。
巻頭言は、いわゆる序論的なやつです。 会長が代表して、最近のサークルの活動状況とか、辞世の句などを書いたりします。 ラフな感じでとりあえず何かしらを自由に書きます。
編集後記は、会誌が完成した後、会誌の取りまとめなどを行った感想を書いたりします。 こちらも会長が書けばいいと思いますが、他に適役がいればその人が書いてもいいでしょう。
巻頭言・編集後記はそれぞれ tex/_BK/03-kantogen.tex と tex/_BK/04-hensyukoki.tex の中に書きます。
例えば、tex/_BK/03-kantogen.tex の中身は以下のようになっています；
\documentclass[uplatex,dvipdfmx]{vkaishi}
\usepackage{vuccaken}
\begin{document}
\author[中須]{かすみ} % 名前
\belong{普通科}{1} % 学部学科・回生
\position{会長} % 役職
\date{2020年12月19日} % 日付
\begin{preface}{巻頭言}
この中に巻頭言を書いていきます。
ほげほげ。
\end{preface}
\end{document}
\maketitle のときと同じように \author で名前、\belong で所属と学年、\position でサークルでの役職、\date で巻頭言あるいは編集後記を書いた日付を書きます。
役職が平社員の場合は、\position コマンドをコメントアウトしておいてください。
役職の代わりに所属学科が出力されます。
巻頭言・編集後記の内容は preface 環境の中に書きます。
この環境は引数を1つ取るので、そこに 巻頭言 あるいは 編集後記 を指定します。
表紙#
表紙もLaTeXで作成します！ と言っても、会誌のタイトルを書いて画像を挿入するだけですが。
例年、会員の誰かに表紙の絵を描いてもらっています。 それをデカデカと会誌の表紙に載せます（光栄！）。
表紙に挿入する画像以外の情報（会誌タイトルや出版年度など）は、/sty/vuccaken.sty の中でまとめて指定できるようにしました。
vucckaken.sty の中に書いた次のコマンドたちで指定します；
\newcommand\vTitle{白夜}
\newcommand\vTitleRoma{BYAKUYA}
\newcommand\vNumbering{第五号}
\newcommand\vNumberingRoma{V}
\newcommand\vNendo{令和二年度}
\newcommand\vYear{2020}
\newcommand\vDate{2020.08.23}
挿入する画像は、表紙は /tex/_BK/01-frontCover.tex、裏表紙は /tex/_BK/06-backCover.tex の中で、画像のパスを指定します。
Fail
上に書いたことも含め、表紙の出力の仕方とかその辺はまだ決めかねています。 詳細はとりあえず保留にしておきます。
奥付#
奥付とは、著者（ここでは幣研究会）の経歴や、「XX年YY月 初版出版」とかを書くところです。
というような認識でしかなくて、あんまりよくわかっていませんが、とりあえずそれっぽいものを作ってみました！
/tex/_BK/05-okuduke.tex がそれを作るtexファイルですが、指定すべき情報は全て /sty/vuccaken.sty の中に書くようにしています；
\newcommand\vEditor{編集者名}
\newcommand\vIllustrator{表紙イラスト製作者}
\newcommand\vPublish{
2019年 & 12月 & 1日 & 初版発行 \\
% 2020年 & 1月 & 1日 & 第2版発行
}
\newcommand\vHistory{
1949年 & 核物理研究会として発足 \\
% ...
2020年 & コロナ禍で学園祭中止 \\
& 会誌『白夜 第五号』出版
}
Fail
表紙と同じく、こちらもまだいろいろと決めかねている状況です。 変更するかもしれません。
おわりに#
とりあえず、一通り説明をしたつもりです。
イミワカンナイところやバグなどありましたら、 会誌のリポジトリの「Issues」 というページで質問・報告してください。
どうしたらいいか、みんなで考えましょう。