R言語関連書籍を執筆＆翻訳したときに使っていたルールまとめ

概要

この記事はR Advent Calendar 2016の24日目の記事です。
今までいくつかのR言語関連書籍に携わらせてもらったのですが、その際に使用していた執筆のルールをここにまとめておきたいと思います。基本的にはMarkdownでやりたいのですが、なんやかんやで文章の装飾まで考えるとTeXの方が便利なので、TeXを使っちゃってます。ここに記載している内容は、もちろん出版社さん依存の点もありますが、まぁどこも基本は同じだろうということで。

執筆・翻訳共通

文体

• 文体は「だ，である」調（ものによっては「です、ます」調）
• 句読点は　，と　．ただし後で出版社側で一括変更するので、気にする必要はなし

表記法

パッケージおよび関数、利用するデータを表現する方法として以下の表記法を用いる。

• パッケージ名
  • ボールド体
  • LaTeXでは \textbf{} で囲む
  • 例：\textbf{package} パッケージ
• 関数名
  • タイプライター体
  • LaTeXでは \texttt{} で囲む。原則として丸括弧を付与
  • パッケージ間の関数名の衝突を避けるため \texttt{package.name::function()}と表記することもOK
  • 例：\texttt{mean()}
• コードの一部(データ名、オブジェクト名、タグなど)
  • タイプライター体：LaTeXでは \texttt{} あるいは \verb|| で囲む
  • 例：\texttt{<p>}, \texttt{iris} , \texttt{iris %>% select(Species)}
  • 例：\verb|iris %>% select(Species)|
• コードブロック
  • \begin{verbatim} 環境を想定

\begin{verbatim}
R> mean(NA)
[1] HOXO-M 
\end{verbatim}

• 強調
  • 組織名など：鉤括弧
    • ボールド体が必要であれば \textgt{} で挟む
    • 例：「\textgt{ほくそえむ}」
  • 日本語強調：\textgt{}
    • 例：\textgt{日本語強調}
  • 欧文強調：\textbf{}
    • 例：\textbf{Wonderful}

コーディングスタイル

原則としてHadely Wickhamのスタイルに従う。

グラフの挿入

• 図はレポジトリ直下にfigというフォルダを用意、chap3あるいはchap6などのサブフォルダを作成、その中にFig1.1.epsあるいはFig1.2.epsなどとして保存
• フォーマット；pdf か eps か png の何れか(この優先順位)
• サイズ：cairo_ps のデフォルトが width = 7, height = 7 それぞれインチで定義されているため、とりあえずこれで
  • 例：ggsave("test.eps". width = 7, height = 7 , units = "in") `

\begin{figure}[hbtp]
    \includegraphics{ ~/fig/chap1/Fig1_1.eps }
    \caption{ キャプション }
    \label{ ラベル }
\end{figure}

表

ここらへんを参考にがんばる。

\begin{table}[htb]
  \begin{tabular}{lcrr}
    メニュー & サイズ & 値段 & カロリー \\
    牛丼 & 並盛 & 500円 & 600 kcal \\
    牛丼 & 大盛 & 1,000円 & 800 kcal \\
    牛丼 & 特盛 & 1,500円 & 1,000 kcal \\
    牛皿 & 並盛 & 300円 & 250 kcal \\
    牛皿 & 大盛 & 700円 & 300 kcal \\
    牛皿 & 特盛 & 1,000円 & 350 kcal
  \end{tabular}
\end{table}

索引

• 索引に載せたいタームなどは \index{} を使用
• 漢字は、アットマークを使って「ひらがな」を併記すること
• どれを索引に載せるかの選択は任意、しかし、可能な限り追記

これを汎関数\index{はんかんすう@汎関数}という。
コーディングスタイル\index{コーディングスタイル}はGoogleに従う。カタカナはそのまま
これをラムダ式\index{らむだしき@ラムダ式|see{汎関数}} という。こう書くと、「この項目は「汎関数」を見よ」という表示になる
ここで線形モデルの出力 \index{せんけいもでる@線形モデル!のしゅつりょく@--の出力} を参照しよう。こうすると「出力」は線形モデルの下位項目となる。

注

• 脚注とし、\footnote{}を用いる

無ければ自分で作る\footnote{それがホクソエムの誓いのはず。}。

相互参照

• 図などの場合、原則は原書のラベルのまんま
• ラベルは語頭は大文字、残りは小文字と数値とドットで構成する
  • 例：他の章、節、画像などを参照するには \label{Chap1.1} と記述(第1章2節のラベル。章-節-項をドットでつなぐ)
• ファイル名とは異なり、参照の場合一ケタの数値であっても0はつけない（Chap01.1とはしない）
• \ref{Chap1.1} # そこへの参照
• \label{Figure1.1} # - \ref{Figure1.1}

翻訳の場合

原文

確認しやすいように、原文を以下のcommentディレクティブを使って訳文の上に添える

\begin{comment}
This is an awesome book!
$\sin \pi =0$
\end{comment}

まとめ

この記事では今までどのようにR言語の書籍を執筆・翻訳してきたについて説明してきました。
将来的には継続的インテグレーション(CI, Continuous Integration)ツールなんかを使ったり、
今年のjapan.R 2016 であったbookdown packageなども活用していきたいなと考えています。
bookdownパッケージについては、同著者(@kazutan 氏)によるアドベントカレンダー記事を見てもよいかもしれません。