Repository navigation
pcenv: keep the reader from skipping the gh authentication - #53
Conversation
Chapters 3 to 8 each end with their Windows and Mac subsections and nothing follows, so by chapter 9 a reader has learned to stop at their own platform and move on. 9.5 is the first chapter to put a shared step after the Mac subsection, which a Windows reader reaches only by reading past a heading addressed to someone else. The step it holds is the last one in the guide, and setup.sh does not run without it. Three one-line signals instead of a restructure: 9.5 says up front that it takes two steps and names where to go, each platform subsection ends by sending the reader to 9.5.3, and 9.5.3 opens by saying it applies to both. The heading text is unchanged on purpose. Its generated id is the anchor pcenv-setup-all.md links as #953-認証, and renaming the section would break that link silently. Claude-Session: https://claude.ai/code/session_01YKsiNxdgDg3uBfzMQSscCg
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| `curl: command not found` と出た場合は、先に `sudo apt install -y curl` を実行する。 | ||
|
|
||
| インストールが終わったら、**9.5.3 に進んで認証する。** |
There was a problem hiding this comment.
ℹ️ [LOW] 「インストールが終わったら、9.5.3 に進んで認証する。」という誘導文が Windows 節（9.5.1）と Mac 節（9.5.2）の両方に追加されており、意図通りです。ただし、将来的に節番号が変わった場合（例：節の追加・削除）、この「9.5.3」というハードコードされた番号が複数箇所で一致しなくなるリスクがあります。現時点では問題ありませんが、番号変更時には必ず3箇所（冒頭・9.5.1末尾・9.5.2末尾）を同時に更新する必要があることをコメントや編集ガイドに記録しておくと保守性が上がります。
There was a problem hiding this comment.
指摘の筋は理解しますが、据え置きます。番号参照はこの文書の既存の慣習であり、本 PR が持ち込んだリスクではありません。
pcenv/index.md の本文には、本 PR 以前から番号での相互参照が 5 箇所あります。
- 78 行目: 「ここでは再起動せず、4-8 章を続けて実行する。すべてのインストールが終わってから 9 章で一度だけ再起動する」
- 188 行目: 「3-8 章のインストールが終わったら…」
- 202 行目: 「9.1 で起動した Windows Terminal / ターミナル で以下を実行する」
- 235 行目: 「7 章で確認した Use WSL 2 instead of Hyper-V は…」
- 237 行目: 「Ubuntu は 9.3 で入れたので…」
本 PR が追加した 3 箇所は、これと同じ種類の参照です。節番号の変更時に本文を見直す必要があるという性質は文書全体に及ぶもので、そのうち 3 箇所だけに保守注記を付けると、残る 5 箇所が「注記が無いから追従不要」と読める方が危険です。
より重要な点として、節番号の変更で黙って壊れるのは本文の数字ではなく、見出しから生成される id です。#953-認証 は pcenv/pcenv-setup-all.md から参照されています。
$ gh api 'search/code?q=953-認証+org:smkwlab' --jq '.total_count, .items[].path'
1
pcenv/pcenv-setup-all.md
本文の「9.5.3 に進む」は番号がずれても読者が前後から復帰できますが、リンク切れは誰にも見えません。この拘束条件（見出しを改名しない理由）は PR 本文に明記済みで、注記を足すとすれば本文の数字ではなくこちらが対象です。既に記録されているため、追加の変更は行いません。
なお、アンカーがプレビューで存続していることは確認済みです。
$ curl -fsSL https://smkwlab.github.io/pr-preview/pr-53/pcenv/ | grep -o 'id="953-認証"'
id="953-認証"
| ### 9.5.3 認証 | ||
|
|
||
| OS を問わず、インストール後に認証を済ませておく。Windows では **Ubuntu の中で**実行する。 | ||
| **この節は Windows / Mac 共通である。** インストール後に認証を済ませておく。 |
There was a problem hiding this comment.
✨ [POSITIVE] 変更前: OS を問わず、インストール後に認証を済ませておく。Windows では **Ubuntu の中で**実行する。
変更後: **この節は Windows / Mac 共通である。** インストール後に認証を済ませておく。Windows では **Ubuntu の中で**実行する。
「Windows / Mac 共通」と明示したことで、9.5.3 に直接リンクで飛んできた読者にも文脈が伝わるようになっており、改善として評価できます。
問題
9.5.3（
gh auth login）は読み飛ばされる。3〜8 章はすべて「Windows の場合 / Mac の場合」で終わり、その後に何も続かない。読者は 6 章ぶんかけて「自分の OS の節を読んだら次の章へ」という読み方を学習する。9.5 はその型を破る最初の章で、共通手順が Mac 用の節の後ろに来る。
9.5.3 はガイド全体の最後の手順で、ここが済んでいないとリポジトリ作成スクリプトは動かない（
gh auth tokenでトークンを取得するため）。#52 で追加した節なので、まだ誰も踏んでいないうちに直す。対応
構成は変えず、1 行の案内を 3 箇所に入れる。
見出しは変えていません
当初は見出しを「9.5.3 認証（Windows / Mac 共通）」にしましたが、戻しました。生成される id が
pcenv-setup-all.mdの#953-認証の参照先で、改名するとこのリンクが黙って切れます。本文で同じことを言えるので、他の文書が参照している識別子は動かしません。
検証
反映後、以下が通ることを確認します。
https://claude.ai/code/session_01YKsiNxdgDg3uBfzMQSscCg