メインコンテンツにスキップ

citezot で論文を書く

このガイドでは、1 本の論文について、最初の引用からレンダリング済みの文書までの流れを追います。Zotero アカウントが必要なチャンクは表示のみで実行せず、オフラインで動く部分は実行します。

library(citezot)

セットアップ

始める前に、Zotero の API キー、~/.Renviron に書いたユーザー ID、そして項目の引用キーが必要です。手順はセットアップガイドにあります。citezot が認証情報を認識できているか確認しましょう（キーが表示されることはありません）。

cz_auth()
#> <cz_auth> user library 1234567 (API key hidden)

引用→更新→レンダリングの流れ

manuscript.qmd では通常どおり引用し、citezot が書き出すファイルを Quarto に指定します。

---
title: "On the Origin of Species"
bibliography: references.bib
---

The origin of species is explained by @Darwin1859; see also @Weiß2015.

citezot は本文中の引用を見つけます。コードチャンクと、@fig-map のような Quarto の相互参照は無視されます。

qmd <- tempfile(fileext = ".qmd")
writeLines(c(
  "---",
  "bibliography: references.bib",
  "---",
  "The origin of species is explained by @Darwin1859; see also @Weiß2015 and @fig-map.",
  "",
  "```{r}",
  "x@slot  # not a citation",
  "```"
), qmd)

cz_qmd_keys(qmd)
#> [1] "Darwin1859" "Weiß2015"

では、参考文献ファイルを書き出します。

cz_update_bib("manuscript.qmd")
#> ✔ 2/2 cited keys found; 'references.bib' updated.

あとは、いつもどおり Quarto で文書をレンダリングします（quarto render manuscript.qmd。HTML、PDF、Typst のいずれでも可）。書き出されるのは引用した項目だけで、キー順に、Zotero のエクスポーターから直接得た BibLaTeX 形式になります。CSL-YAML にしたい場合は .yaml の名前を指定します: cz_update_bib("manuscript.qmd", out = "references.yaml")

キーが見つからないとき

本文が @Kent2002 を引用しているのに、Zotero にその引用キーを持つ項目がないとします。更新は中断され、既存のファイルには触れません。

cz_update_bib("manuscript.qmd")
#> Error in `cz_update_bib()`:
#> ! Cited in the documents but not found in Zotero: "Kent2002".
#> ✖ 'references.bib' was NOT touched, because an incomplete bibliography would
#>   break the render.
#> ℹ Pin the citekey in Zotero (see `cz_pin_key()`), check the spelling, or use
#>   `allow_incomplete = TRUE` to write what was found.

原因は 3 つ考えられ、citezot はそれぞれに対応できます。

  1. タイプミス、または項目が別のキーで登録されている。 検索します。

    cz_find("kent blat")
cz_find(doi = "10.1101/gr.229202")

  2. 項目は Zotero にあるが、まだキーがない。 キーを固定します。書き込みはすべてそうですが、指示するまではドライランです。

    cz_pin_key("10.1101/gr.229202", "Kent2002")                  # プレビュー
cz_pin_key("10.1101/gr.229202", "Kent2002", dry_run = FALSE) # 書き込み

  3. 項目がライブラリにない。 DOI から追加します。

    cz_add("10.1101/gr.229202", key = "Kent2002")                  # プレビュー
cz_add("10.1101/gr.229202", key = "Kent2002", dry_run = FALSE) # 作成

    プレビューには、作成される項目のタイトル、著者、日付、キーが表示されます。cz_add() は、まず DOI とキーがライブラリにまだないことを確認します。（現時点では、Crossref に登録された DOI のみ対応しています。）

もう一度 cz_update_bib() を実行すれば、文書は完成です。

項目を修正する

日付が間違っているとします。変更をプレビューしてから、適用します。

cz_update_item("Regnier2024", list(date = "in press"))
#> ℹ Dry run: nothing written. Use `dry_run = FALSE` to apply to item ABCD2345 (...).
#> • date: "2026" -> "in press"

cz_update_item("Regnier2024", list(date = "in press"), dry_run = FALSE)

実際に変わるフィールドだけが、項目のバージョンとともに送信されます。citezot が読み取った後に誰か（または Zotero デスクトップ）が項目を編集していた場合、Zotero は HTTP 412 を返し、何も上書きされません。cz_get_item("Regnier2024") で項目を確認してから、もう一度コマンドを実行してください。作成者、タグ、コレクションは丸ごと置き換えられるため、タグを 1 つ追加するには、タグの完全なリストを渡します。識別用のフィールド（key、version、itemType、追加日・更新日）と引用キーはここでは変更できません。キーの変更には cz_pin_key() を使います。

引用キー

Better BibTeX を使っている場合、キーは auth.lower + year + shorttitle(1).lower のようなパターンに従っています。citezot は、新しい項目に対して同じパターンでキーを生成できます。

item <- list(
  itemType = "journalArticle",
  title = "On the origin of species by means of natural selection",
  date = "1859",
  creators = list(list(creatorType = "author", firstName = "Charles", lastName = "Darwin"))
)

cz_suggest_key(item, "auth.lower + year + shorttitle(1).lower")
#> [1] "darwin1859origin"

# すでに使われているキーには文字が付く
cz_suggest_key(item, "auth.lower + year + shorttitle(1).lower",
               existing = "darwin1859origin")
#> [1] "darwin1859origina"

# Better BibTeX 自身の既定のパターン
cz_suggest_key(item, "auth.lower + shorttitle(3,3) + year")
#> [1] "darwinOriginSpeciesMeans1859"

cz_add(..., key = "auto") は cz_key_format() のパターンを使います。citezot.key_format オプションを設定していればそれ、なければ Better BibTeX が Zotero のプロファイルに保存したもの、それもなければ Better BibTeX の既定です。書式言語は一部（auth、year、shorttitle、title、いくつかのフィルター、+）のみ対応しており、それ以外はキーが変わるのではなくエラーになります。Better BibTeX 自体は必要ありません。cz_pin_key() で固定したキーや cz_add() に渡したキーは、どれも使えます。

タイトル中の単語は Better BibTeX の規則に従います。HTML タグは除かれ、タイトルは最初のコロンまたは文末で切られ、“a” や “the” のような短い機能語は飛ばされ、単語内のハイフンなどの記号は取り除かれます（early-diverging は earlydiverging になります）。

速度

大きなライブラリを初めてダウンロードするには数十秒かかります。キャッシュを有効にすると、2 回目以降は変更分だけを取得します。

options(citezot.cache = TRUE)   # .Rprofile に書いておきましょう
system.time(cz_update_bib("manuscript.qmd"))
#>    user  system elapsed
#>   0.121   0.019   0.342

キャッシュは tools::R_user_dir("citezot", "cache") にあり、保存されるのは書誌情報のみです。cz_fetch_items(refresh = TRUE) で全件を再ダウンロードでき、cz_clear_cache() でキャッシュを削除できます。

自動化

_quarto.yml に pre-render ステップを追加すると、プロジェクトをレンダリングするたびに参考文献ファイルが更新されます。

project:
  pre-render: Rscript -e 'citezot::cz_update_bib()'

targets のパイプラインでは、パスを返し、ファイルの追跡は targets に任せます。

tar_target(
  references,
  cz_update_bib("manuscript.qmd", quiet = TRUE),
  format = "file",
  cue = tar_cue(mode = "always")
)

cz_update_bib() は変更がないときファイルに触れないので、参考文献が実際に変わったときだけ再レンダリングされます。

トラブルシューティング

  • 「Zotero credentials not found.」 この R セッションで環境変数が設定されていません。Sys.getenv("ZOTERO_API_KEY") != "" を確認し、~/.Renviron を編集したら R を再起動してください。
  • HTTP 403。 キーが無効か、必要な権限がありません。書き込みには、書き込み権限のあるキーが必要です。
  • 更新時の HTTP 412。 読み取った後に項目が変更されました。cz_get_item() でもう一度確認し、意図して再試行してください。
  • 項目が Zotero にあるのに、引用キーが「見つからない」。 項目に引用キーが保存されていない（または別のキーが保存されている）ためです。cz_find() で項目のキーを確認し、cz_pin_key() で設定してください。
  • 変わった文字（?? など）を含むキーは、文書から引用できません。Zotero で直すか、cz_pin_key(..., overwrite = TRUE) で修正してください。