執筆支援

Octavo は、自分が守っている書き方のルールと、信頼できる言い回し（フレーズバンク）を、原稿のいま書いている部分に合わせて AI アシスタントに渡せる。書く前に段落の構成表を置いておき、書いたあとで本文と構成表の食い違いを見ることもできる。このページは、その準備と使い方を、出てくる順に説明する。説明するのは Octavo がファイルをどう扱うかで、どんなルールがよいかは書かない。中身は自分で決める。

Octavo はルールの中身を解釈しない。ファイルを選んで並べ、当てはまらないものと外した項目を除き、残りをアシスタントが読む形に出すだけ。

1. パック

1.1 パックの置き場所

パックは Markdown のファイルを入れたフォルダー1つ。書き方のルールは rules/、フレーズバンクは phrases/ に入れ、pack.md を置いてもよい（任意）。パックを探す場所は2つ。

両方に同じパックの同じ名前のファイルがあれば、プロジェクトのほうを使う。パックのフォルダーを作らずに notes/writing/rules/ と notes/writing/phrases/ に直接置いたファイルは、local という名前のパックになり、いつもいちばん後ろに来る。前からのプロジェクトの writing/ フォルダーも読む（notes/writing/ のほうが勝つ）。

~/.config/octavo/writing/
  general/
    pack.md
    rules/
      sentences.md
      paragraphs.md
    phrases/
      paragraphs.md
  field/
    pack.md
    rules/
      results.md
    phrases/
      introduction.md
      results.md

パックを別のリポジトリで管理しているなら、コピーせずにフォルダーをリンクする。

ln -s ~/projects/my-writing/packs ~/.config/octavo/writing

octavo writing で、見つかったファイルが、パック・言語・原稿の種類・節と一緒に一覧になる。

octavo writing

1.2 pack.md

---
title: Empirical papers in my field
extends: general
sections: [puzzle, cases]
---

Rules and phrases for empirical papers. Comes after `general` and wins where they disagree.

本文の最初の段落は、サイドバーに出るパックの説明になる。

2. ファイルの書き方

2.1 ファイルと項目

ファイルは冒頭（フロントマター）から始め、その下の ## の見出し1つが項目1つになる。コードブロックの中の ## は見出しにならず、### はその上の項目に含まれる。冒頭と最初の ## の間の文章は、ファイルと一緒に出る（項目の使い方を書いておくのによい）。

---
title: Sentences
lang: en
applies: [paper, lecture]
---

How these rules are meant to be used, if it needs saying.

## One claim per sentence

Rule: Put one claim in a sentence.
Why: The reader need not look for where one claim ends.
Good: Staff numbers fell. How fast they fell differed between municipalities.
Bad: Staff numbers fell, but at different speeds across municipalities, which …

2.2 ルール

ルールの項目は、書いたとおりに出る。Octavo はどの行も読み取らない。下の行は、アシスタントに伝えてある決まり（AGENTS.md の「各ルールの Rule に従う」）。

ほかの行（Source: や自分のメモ）も、そのまま出る。

2.3 フレーズ

フレーズの項目は、場面1つ、または段落の種類1つ。そこで使ってよい型を箇条書きで並べる。〈 〉の所は埋める。〈A / B〉 は、並べた言葉から1つを選ぶ。

---
title: Results
lang: en
applies: [paper]
section: results
---

## The main result

When: The paragraph that reports the main estimate.
Contains: the table or figure; the estimate and its uncertainty; what it means for the hypothesis
Note: Say what the reader should see, then the estimate.
Source: own
- Open: Table 〈2〉 〈presents / reports〉 〈the estimates from X〉.
- Body: The coefficient on 〈X〉 is 〈positive〉 and 〈statistically〉 significant.
- Close: 〈These results〉 provide support for 〈H1〉.

行の名前は行の頭で、: か ： が続くときに当たる。箇条書きの型は、octavo outline --paragraphs が本文の中から探すものになる（5.1）。

3. 原稿が読むものを選ぶ

3.1 パックとその順

選ばなければ、見つかったパックをすべて使う。選ぶときは一般的なものから順に並べる。食い違えば後ろのものが勝つ。パックの extends は、そのパックの前に自動で入る。

プロジェクト全体には octavo.config.py に:

CONFIG = {
    'writing': ['general', 'field'],
}

その原稿だけには、原稿の冒頭に:

---
title: My paper
writing: [field]
---

原稿の冒頭の writing: は、その原稿ではプロジェクトの設定に代わる。local はいつも最後に足される。サイドバーでは、原稿の「文章のルール」→「パックを選ぶ…」で、一般的なものから1つずつ選ぶ。

3.2 項目を外す

使わないものは writing_off に書く。

---
writing_off: [general/sentences#one-claim-per-sentence]
---

ほかの設定と違い、writing_off はプロジェクトの分と原稿の分を合わせて使う。# の後ろは、項目の見出しから作る slug：小文字にし、文字と数字以外の続きを - 1つにしたもの（## One claim per sentence → one-claim-per-sentence。同じ見出しの2つ目は -2 が付く）。見出しを変えると slug も変わり、外した項目がまた使われる。そのとき octavo check は「writing_off に当たる項目がない」と出す。サイドバーでは、項目を右クリック →「この原稿では使わない」。

3.3 読まれるファイル

原稿の種類は出力から決まる。論文と回のない配布資料（word や tex を作るものも）は paper、回のある講義ノートは lecture、スライド・台本・Beamer は slides、ポスターは poster。1つの原稿がいくつかの種類になることもある。

3.4 行の節の決まり方

アシスタントが行を指して聞く（--file … --line …）と、Octavo はその行のすぐ上の見出しから浅い見出しへさかのぼり、節の名前に当たる最初の見出しを使う。1つの見出しの中では、先に出てくる言葉が勝つ（Results and robustness → results）。パックが足した節は、組み込みの節より先に見る。{.appendix} の付いた見出しとその後ろ、付録のファイルは appendix。

パックが足した節（sections: [puzzle]）は、その名前の言葉で当たる（puzzle。case-selection なら「case selection」）。どの節にも当たらない見出しの下では、section: のないファイルだけを読む。

3.5 読まれるものを見る

octavo writing --for my-paper
octavo writing --for my-paper --section results --print
octavo writing --file docs/my-paper/my-paper.md --line 120 --print

1つ目は原稿が使うパックとファイルの一覧。--print を付けると重ねた本文が出る。これがアシスタントの読むもの。--all ならすべての節。VS Code では、原稿にカーソルを置いて「カーソルの所のルールを見る」（エディターの右クリック、またはサイドバーの原稿の「文章のルール」）。

4. 段落の構成表

4.1 印

パックのフレーズバンクが段落の種類ごとに書いてあれば、節を書く前に構成を決めておける。各段落のすぐ上に印を1つ置き、その段落の種類と、段落が言う1文の主張を書く。

## Results {#sec-results}

<!-- para: field/results#the-main-result | Divisions that changed more were redrawn more often -->
Divisions whose composition of work had shifted more were redrawn more often (@tbl-main).

<!-- para: field/results#the-size-of-the-effect | The effect is about a third of the mean -->

<!-- para: | Robust to dropping the largest ministries -->

• 種類はフレーズの項目で、writing_off と同じ書き方（パック/ファイル#slug、または ファイル#slug。 2つのパックにあれば後ろのもの）。種類も主張も省ける。<!-- para: | 主張 --> は、種類をまだ決めていない段落。
• 段落の本文は、印のすぐ次の行から。印の次が空行なら、まだ書いていない段落（構成表）。
• 印の前には空行を入れる。 本文の行のすぐ後に印を書くと、pandoc はそれを上の段落の一部として読み、 2つの段落がつながる。
• 印はコメントなので、PDF にもスライドにも Word にも出ない。

4.2 段階ごとのコマンド

種類を指定しても、ルールは指定しないときと同じ。絞られるのはフレーズだけ。--kind は何度でも、またコンマで区切っても書ける。種類は、その原稿が使うフレーズのファイル（選んだパックの、applies と lang が合い、外していないもの）から、節を問わず探す。使わないファイルの種類は、警告して除く。

5. 書いたあと

5.1 構成の一覧

octavo outline my-paper --paragraphs

で、見出しごとに各段落の種類・主張・本文の最初の文が並ぶ。本文が構成表どおりのことを言っているかを見比べられる。付く印は次のとおり。

1つの見出しの下で同じ型が2回使われていれば、それも知らせる。型が使われたと見なすのは、〈 〉の外の言葉がすべて、1つの文の中に同じ順で出るとき（〈A / B〉 はどれか1つ）。大文字で始まる型は文の頭で、 . で終わる型は文の終わりで当たる。決まった言葉が2語に満たない型は探さない。比べるのは、その見出しの節の型（と section: のないファイルの型）で、その原稿が使うものだけ。

5.2 著者への問い

本文に要る数字や出典が、原稿にも分析にもないとき、アシスタントはごまかして書かず、問いを残すように指示されている。

<!-- ask: the number of ministries in the sample -->

octavo outline … --paragraphs が問いを行番号つきで並べ、octavo check は答えて消すまで「著者への問い」を警告として出す。

6. アシスタントに使わせる

• プロジェクトの AGENTS.md（octavo init が書く）が、アシスタントに次のことを伝えている。文章を書いたり直したりする前に octavo writing --file … --line … --print を実行してルールに従うこと、フレーズバンクは型が合う所でだけ使うこと、印で構成を決め、一覧で確かめること、ask のコメントを残すこと、パックのファイルは直さないこと。これらの節がまだなかった頃のプロジェクトには、次で入る。

octavo migrate --rules

• サイドバー：各原稿の「文章のルール」に、その原稿が使うパックと、そのファイル・項目が並ぶ。「パックを選ぶ…」でその原稿の writing: を決め、項目を右クリックして外したり戻したりできる。「カーソルの所のルールを見る」で、アシスタントがカーソルの所で読むものが見られる。
• パックがあると、octavo check に「文章のルール」の行が出る。不明なパック名・節名と、何にも当たらない writing_off を知らせる。

7. うまくいかないとき