kazutan/tufte_test.Rmd

## tufte_test.Rmd
---
title: "Tufte htmlのテスト"
subtitle: "tufte handoutのテンプレを思いっきり端折りながら"
author: "kazutan"
date: "`r Sys.Date()`"
output:
  tufte::tufte_html: default
bibliography: skeleton.bib
link-citations: yes
---

```{r setup, include=FALSE}
library(tufte)
# invalidate cache when the tufte version changes
knitr::opts_chunk$set(tidy = FALSE, cache.extra = packageVersion('tufte'))
options(htmltools.dir.version = FALSE)
```

このドキュメントを生成したRmdファイルのコードは[このgist](https://gist.github.com/kazutan/447bc69b33a3286f830f)においてます。

# 導入

これはTufte handout スタイルというもので、詳しくは適当にググってください。特徴は大きめなサイドノートがあり、図と文章がうまいことできて、そしてタイポグラフィもいい感じです。

このスタイルの元はLaTexやHTML/CSS^[See Github repositories [tufte-latex](https://github.com/tufte-latex/tufte-latex) and [tufte-css](https://github.com/edwardtufte/tufte-css)]からきているようです。これらを[**tufte** パッケージ](https://github.com/rstudio/tufte)に詰め込んで、R Markdownに使えるようにしたとのことです。これを使うには、まずCRAN
から**tufte**をインストールしてください。その後、R Markdownドキュメント冒頭のYAMLメタデータに、以下のように記述すればOKです:

```yaml
---
title: "sushi tabetai"
author: "kazutan"
output:
  tufte::tufte_html: default
---
```

このパッケージの目的は2つあるそうです:

1. 同一のR Markdownドキュメントから、PDFとHTMLの両方の出力をほぼ同じように提供すること;
1. サイドノート領域や余白の図といったTufte styleの要素を書き出すのにシンプルなシンタックスを提供することです。実際すごくシンプルです。

# 見出し

第1レベルと第2レベルの見出ししか拾いません。要するに`#`と`##`のみです。あと、段落の最初部分に以下の様なおしゃれなものをつけることもできますが、日本語には関係ない気がするのでテンプレのをそのまま残しときます:

`r newthought('In his later books')`^[[Beautiful Evidence](http://www.edwardtufte.com/tufte/books_be)], Tufte starts each section with a bit of vertical space, a non-indented paragraph, and sets the first few words of the sentence in small caps. To accomplish this using this style, call the `newthought()` function in **tufte** in an _inline R expression_ `` `r ` `` as demonstrated at the beginning of this paragraph.^[Note you should not assume **tufte** has been attached to your R session. You should either `library(tufte)` in your R Markdown document before you call `newthought()`, or use `tufte::newthought()`.]

# 図

## 余白の図

余白に図を配置するには、**knitr**チャンクオプションで`fig.margin = TRUE`としてしまえばOKです。以下チャンクの例です:

```
\```{r fig-margin, fig.margin = TRUE, fig.cap = "MPG vs horsepower, colored by transmission.", fig.width=3.5, fig.height=3.5, cache=TRUE}
library(ggplot2)
mtcars2 <- mtcars
mtcars2$am <- factor(
  mtcars$am, labels = c('automatic', 'manual')
)
ggplot(mtcars2, aes(hp, mpg, color = am)) +
  geom_point() + geom_smooth() +
  theme(legend.position = 'bottom')
\```
````

行頭の`\`はエスケープさせるために入れています。無視してください。このチャンクを入れると以下(右?)のようになります:

```{r fig-margin, fig.margin = TRUE, fig.cap = "MPG vs horsepower, colored by transmission.", fig.width=3.5, fig.height=3.5, cache=TRUE}
library(ggplot2)
mtcars2 <- mtcars
mtcars2$am <- factor(
  mtcars$am, labels = c('automatic', 'manual')
)
ggplot(mtcars2, aes(hp, mpg, color = am)) +
  geom_point() + geom_smooth() +
  theme(legend.position = 'bottom')
```

チャンクオプションの`fig.cap`は図のキャプションを提供します。また、`fig.width`や`fig.height`でサイズ指定できます(inchです)。なお、ハンドアウトの余白に合わせて自動的に調整されます。

## 任意の余白コンテンツ

ぶっちゃけ、余白部分には`marginfigure`という**knitr**エンジンでいろんなのを放り込めます。以下のようなコードがあるとします:

```
\```{marginfigure}
We know from _the first fundamental theorem of calculus_ that for $x$ in $[a, b]$:
$$\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x).$$
\```
```

これをドキュメント内に入れておいてKnitすると、余白部分に上記の内容が出てきます。数式もOKです。

```{marginfigure}
We know from _the first fundamental theorem of calculus_ that for $x$ in $[a, b]$:
$$\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x).$$
```

ただ、この`marginefigure`ブロック内では、できるだけシンプルなものにとどめておくようにしてください。**太字**(`**太字**`)や_イタリック_(`_イタリック_`)ぐらいにしておいて、この中でさらに脚注とか参照とかブロックレベルの要素(リストや引用など)は避けときましょう。

## フルワイドな図

チャンクオプションで`fig.fullwidth = TRUE`と指定すれば、メイン部分と余白部分の両方にまたがる、フルワイドな図を描けます。以下チャンクの例です:

```
\```{r fig-fullwidth, fig.width = 10, fig.height = 2, fig.fullwidth = TRUE, fig.cap = "A full width figure.", warning=FALSE, cache=TRUE}
ggplot(diamonds, aes(carat, price)) + geom_smooth() +
  facet_grid(~ cut)
\```
```

このチャンクを含んでKnitすると、以下のようになります:

```{r fig-fullwidth, fig.width = 10, fig.height = 2, fig.fullwidth = TRUE, fig.cap = "A full width figure.", warning=FALSE, cache=TRUE}
ggplot(diamonds, aes(carat, price)) + geom_smooth() +
  facet_grid(~ cut)
```

他のチャンクオプションとも併用できますし、`fig.width`, `fig.cap`, `out.width`など対応してます。

## メイン部分の図

もちろんメイン部分にも図を描けますし、むしろこれがデフォルトです。以下チャンク例です:

```
\```{r fig-main, fig.cap = "A figure in the main column.", cache=TRUE}
ggplot(diamonds, aes(cut, price)) + geom_boxplot()
\```
```

このチャンクを含んでKnitすると、以下のようになります:

```{r fig-main, fig.cap = "A figure in the main column.", cache=TRUE}
ggplot(diamonds, aes(cut, price)) + geom_boxplot()
```

キャプションは余白部分に表示されるようになります。

# サイドノート

このスタイルの最も主要な機能は、やはりこのサイドノートかと。使い方は簡単で、ノートを入れたい場所で、`^[ほげほげ]`^[ほげほげ]と入れてください。`ほげほげ`はノートの本文です。なおこれは本来脚注で、それが文末にではなく横にくるように設定してある、と考えてください。

なお、これは自動的に通し番号が振られるようになります。もし自動的に番号を割り振ってほしくない場合、**tufte**パッケージの`margin_note()`関数をインラインRチャンクで挿入してください。`r margin_note("うなぎの白焼き食べたいですよね")` ただし、この`margin_note()`で差し込んだテキストではMarkdownシンタックスは評価されません。Markdownシンタックスなどいろいろしたいときは、先に紹介した`marginfigure`ブロックを利用してください。

# References

HTML出力の場合、リファレンスは巻末ではなく余白ノート部分に出てきます。こまかいところは省略します。tufteのテンプレに書いてありますのでそっちを参照してください。

# Tables

`knitr::kable`で作ってもらえば、このtufteスタイルの表が出力されます:

```{r}
knitr::kable(
  mtcars[1:6, 1:6], caption = 'A subset of mtcars.'
)
```

# 引用

Markdownシンタックス同様、`>`で引用となります。さらに、**tufte**パッケージ内の`quote_footer()`関数も使えます。以下サンプルです:

```
> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
>
> `\r tufte::quote_footer('--- teramonagi')`
```

三行目のrの前の`\`は取り除いてください。これを評価させるとこうなります:

> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
>
> `r tufte::quote_footer('--- teramonagi')`

ちなみに`quote_footer()`を使わないと、普通の引用文として評価されるのでイマイチです:

> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
>
> --- teramonagi

# レスポンシブ

HTML出力されたものはレスポンシブです。ページ幅が760pxを下回ると、サイドノートと余白ノートは隠れるようにデフォルトで設定されています。サイドノートはその番号をクリックすると見れますし、余白ノートはその場所の丸印をクリックすると見れます。

このドキュメントの幅を小さくしてみて確認してみてください。

# More Examples

テンプレのドキュメントに実用的なサンプルが記載されていましたが、ここでは省略します。実際にこの**tufte**パッケージをインストールして、テンプレを確認してみてください。

本家のテンプレRmdをみてみたい方は、[このGitHubへのリンク](https://github.com/rstudio/tufte/raw/master/inst/rmarkdown/templates/tufte_html/skeleton/skeleton.Rmd)、 もしくはRStudio (`File -> New File -> R Markdown -> From Template`)などから確認してください。

Enjoy!!

```{r bib, include=FALSE}
# create a bib file for the R packages used in this document
knitr::write_bib(c('base', 'rmarkdown'), file = 'skeleton.bib')
```
	---
	title: "Tufte htmlのテスト"
	subtitle: "tufte handoutのテンプレを思いっきり端折りながら"
	author: "kazutan"
	date: "`r Sys.Date()`"
	output:
	tufte::tufte_html: default
	bibliography: skeleton.bib
	link-citations: yes
	---

	```{r setup, include=FALSE}
	library(tufte)
	# invalidate cache when the tufte version changes
	knitr::opts_chunk$set(tidy = FALSE, cache.extra = packageVersion('tufte'))
	options(htmltools.dir.version = FALSE)
	```

	このドキュメントを生成したRmdファイルのコードは[このgist](https://gist.github.com/kazutan/447bc69b33a3286f830f)においてます。

	# 導入

	これはTufte handout スタイルというもので、詳しくは適当にググってください。特徴は大きめなサイドノートがあり、図と文章がうまいことできて、そしてタイポグラフィもいい感じです。

	このスタイルの元はLaTexやHTML/CSS^[See Github repositories [tufte-latex](https://github.com/tufte-latex/tufte-latex) and [tufte-css](https://github.com/edwardtufte/tufte-css)]からきているようです。これらを[tufte パッケージ](https://github.com/rstudio/tufte)に詰め込んで、R Markdownに使えるようにしたとのことです。これを使うには、まずCRAN
	からtufteをインストールしてください。その後、R Markdownドキュメント冒頭のYAMLメタデータに、以下のように記述すればOKです:

	```yaml
	---
	title: "sushi tabetai"
	author: "kazutan"
	output:
	tufte::tufte_html: default
	---
	```

	このパッケージの目的は2つあるそうです:

	1. 同一のR Markdownドキュメントから、PDFとHTMLの両方の出力をほぼ同じように提供すること;
	1. サイドノート領域や余白の図といったTufte styleの要素を書き出すのにシンプルなシンタックスを提供することです。実際すごくシンプルです。

	# 見出し

	第1レベルと第2レベルの見出ししか拾いません。要するに`#`と`##`のみです。あと、段落の最初部分に以下の様なおしゃれなものをつけることもできますが、日本語には関係ない気がするのでテンプレのをそのまま残しときます:

	`r newthought('In his later books')`^[[Beautiful Evidence](http://www.edwardtufte.com/tufte/books_be)], Tufte starts each section with a bit of vertical space, a non-indented paragraph, and sets the first few words of the sentence in small caps. To accomplish this using this style, call the `newthought()` function in tufte in an _inline R expression_ `` `r ` `` as demonstrated at the beginning of this paragraph.^[Note you should not assume tufte has been attached to your R session. You should either `library(tufte)` in your R Markdown document before you call `newthought()`, or use `tufte::newthought()`.]

	# 図

	## 余白の図

	余白に図を配置するには、knitrチャンクオプションで`fig.margin = TRUE`としてしまえばOKです。以下チャンクの例です:

	```
	\```{r fig-margin, fig.margin = TRUE, fig.cap = "MPG vs horsepower, colored by transmission.", fig.width=3.5, fig.height=3.5, cache=TRUE}
	library(ggplot2)
	mtcars2 <- mtcars
	mtcars2$am <- factor(
	mtcars$am, labels = c('automatic', 'manual')
	)
	ggplot(mtcars2, aes(hp, mpg, color = am)) +
	geom_point() + geom_smooth() +
	theme(legend.position = 'bottom')
	\```
	````

	行頭の`\`はエスケープさせるために入れています。無視してください。このチャンクを入れると以下(右?)のようになります:

	```{r fig-margin, fig.margin = TRUE, fig.cap = "MPG vs horsepower, colored by transmission.", fig.width=3.5, fig.height=3.5, cache=TRUE}
	library(ggplot2)
	mtcars2 <- mtcars
	mtcars2$am <- factor(
	mtcars$am, labels = c('automatic', 'manual')
	)
	ggplot(mtcars2, aes(hp, mpg, color = am)) +
	geom_point() + geom_smooth() +
	theme(legend.position = 'bottom')
	```

	チャンクオプションの`fig.cap`は図のキャプションを提供します。また、`fig.width`や`fig.height`でサイズ指定できます(inchです)。なお、ハンドアウトの余白に合わせて自動的に調整されます。

	## 任意の余白コンテンツ

	ぶっちゃけ、余白部分には`marginfigure`というknitrエンジンでいろんなのを放り込めます。以下のようなコードがあるとします:

	```
	\```{marginfigure}
	We know from _the first fundamental theorem of calculus_ that for $x$ in $[a, b]$:
	$$\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x).$$
	\```
	```

	これをドキュメント内に入れておいてKnitすると、余白部分に上記の内容が出てきます。数式もOKです。

	```{marginfigure}
	We know from _the first fundamental theorem of calculus_ that for $x$ in $[a, b]$:
	$$\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x).$$
	```

	ただ、この`marginefigure`ブロック内では、できるだけシンプルなものにとどめておくようにしてください。太字(`太字`)や_イタリック_(`_イタリック_`)ぐらいにしておいて、この中でさらに脚注とか参照とかブロックレベルの要素(リストや引用など)は避けときましょう。

	## フルワイドな図

	チャンクオプションで`fig.fullwidth = TRUE`と指定すれば、メイン部分と余白部分の両方にまたがる、フルワイドな図を描けます。以下チャンクの例です:

	```
	\```{r fig-fullwidth, fig.width = 10, fig.height = 2, fig.fullwidth = TRUE, fig.cap = "A full width figure.", warning=FALSE, cache=TRUE}
	ggplot(diamonds, aes(carat, price)) + geom_smooth() +
	facet_grid(~ cut)
	\```
	```

	このチャンクを含んでKnitすると、以下のようになります:

	```{r fig-fullwidth, fig.width = 10, fig.height = 2, fig.fullwidth = TRUE, fig.cap = "A full width figure.", warning=FALSE, cache=TRUE}
	ggplot(diamonds, aes(carat, price)) + geom_smooth() +
	facet_grid(~ cut)
	```

	他のチャンクオプションとも併用できますし、`fig.width`, `fig.cap`, `out.width`など対応してます。

	## メイン部分の図

	もちろんメイン部分にも図を描けますし、むしろこれがデフォルトです。以下チャンク例です:

	```
	\```{r fig-main, fig.cap = "A figure in the main column.", cache=TRUE}
	ggplot(diamonds, aes(cut, price)) + geom_boxplot()
	\```
	```

	このチャンクを含んでKnitすると、以下のようになります:

	```{r fig-main, fig.cap = "A figure in the main column.", cache=TRUE}
	ggplot(diamonds, aes(cut, price)) + geom_boxplot()
	```

	キャプションは余白部分に表示されるようになります。

	# サイドノート

	このスタイルの最も主要な機能は、やはりこのサイドノートかと。使い方は簡単で、ノートを入れたい場所で、`^[ほげほげ]`^[ほげほげ]と入れてください。`ほげほげ`はノートの本文です。なおこれは本来脚注で、それが文末にではなく横にくるように設定してある、と考えてください。

	なお、これは自動的に通し番号が振られるようになります。もし自動的に番号を割り振ってほしくない場合、tufteパッケージの`margin_note()`関数をインラインRチャンクで挿入してください。`r margin_note("うなぎの白焼き食べたいですよね")` ただし、この`margin_note()`で差し込んだテキストではMarkdownシンタックスは評価されません。Markdownシンタックスなどいろいろしたいときは、先に紹介した`marginfigure`ブロックを利用してください。

	# References

	HTML出力の場合、リファレンスは巻末ではなく余白ノート部分に出てきます。こまかいところは省略します。tufteのテンプレに書いてありますのでそっちを参照してください。

	# Tables

	`knitr::kable`で作ってもらえば、このtufteスタイルの表が出力されます:

	```{r}
	knitr::kable(
	mtcars[1:6, 1:6], caption = 'A subset of mtcars.'
	)
	```

	# 引用

	Markdownシンタックス同様、`>`で引用となります。さらに、tufteパッケージ内の`quote_footer()`関数も使えます。以下サンプルです:

	```
	> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
	>
	> `\r tufte::quote_footer('--- teramonagi')`
	```

	三行目のrの前の`\`は取り除いてください。これを評価させるとこうなります:

	> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
	>
	> `r tufte::quote_footer('--- teramonagi')`

	ちなみに`quote_footer()`を使わないと、普通の引用文として評価されるのでイマイチです:

	> "オープンソースのバグに文句だけ言う輩より、issueが即クローズされようとも、手を動かし続けるホクソエムらは素敵だなって思いますね"
	>
	> --- teramonagi

	# レスポンシブ

	HTML出力されたものはレスポンシブです。ページ幅が760pxを下回ると、サイドノートと余白ノートは隠れるようにデフォルトで設定されています。サイドノートはその番号をクリックすると見れますし、余白ノートはその場所の丸印をクリックすると見れます。

	このドキュメントの幅を小さくしてみて確認してみてください。

	# More Examples

	テンプレのドキュメントに実用的なサンプルが記載されていましたが、ここでは省略します。実際にこのtufteパッケージをインストールして、テンプレを確認してみてください。

	本家のテンプレRmdをみてみたい方は、[このGitHubへのリンク](https://github.com/rstudio/tufte/raw/master/inst/rmarkdown/templates/tufte_html/skeleton/skeleton.Rmd)、もしくはRStudio (`File -> New File -> R Markdown -> From Template`)などから確認してください。

	Enjoy!!

	```{r bib, include=FALSE}
	# create a bib file for the R packages used in this document
	knitr::write_bib(c('base', 'rmarkdown'), file = 'skeleton.bib')
	```