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

  • 9
    いいね
  • 0
    コメント

概要

この記事は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 氏)によるアドベントカレンダー記事を見てもよいかもしれません。

この投稿は R Advent Calendar 201624日目の記事です。