📖✨：write the six unwritten handbook rules

collections/_docs/handbook/style/capitalization.md

@@ -1,14 +1,102 @@
 ---
 title: Capitalization
 key_point: When to capitalize, and when to leave a word lowercase.
-stub: true
 ---
 
-> [!NOTE]
->
-> This page is a placeholder. It is linked from elsewhere in the handbook and is
-> yet to be written.
+Capitalize a name. Leave everything else alone. Most disagreements about
+capitalization are really disagreements about whether a thing is a name, and
+answering that question settles the spelling.
+
+A capital letter is a claim that a word is the name of one particular thing.
+Applying it to an ordinary noun — a feature, a format, a role — asks the reader
+to look for a proper noun that is not there.
 
 ## Capitalization in headings
 
-Yet to be written.
+A page title is set in title case, capitalizing the first word, the last word,
+and everything between them except articles, coordinating conjunctions, and
+prepositions.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> Documenting Command-Line
+  Syntax
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> Documenting Command Line
+  Syntax
+</p>
+
+A heading inside a page is set in sentence case: the first word capitalized, and
+after that only what would be capitalized in running text.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> Explaining placeholders
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> Explaining Placeholders
+</p>
+
+A page adapted from someone else's writing keeps the capitalization it arrived
+with. Rewriting the headings of a page that carries an attribution line makes it
+harder to check the adaptation against its source.
+
+## The name of the project
+
+The project is **OpenINF**. One capital at the front for _Open_, three at the
+back for _INF_, and nothing else.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> OpenINF
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> OPENINF, Openinf, openINF
+</p>
+
+Setting the name in full capitals is shouting it, and a name that shouts in
+running text is a name the reader learns to skip. This holds in headings, in
+navigation, and in the small print at the foot of a page — nowhere is it
+`OPENINF`.
+
+The scope on npm is lowercase, because npm scopes are lowercase: `@openinf`.
+Write a package name exactly as it is published, in code font, and never
+capitalize it to start a sentence. Rewrite the sentence instead.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> The
+  <code>@openinf/util-types</code> package has no dependencies.
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span>
+  <code>@openinf/util-types</code> has no dependencies.
+</p>
+
+## Words that only look like names
+
+Technologies, formats, and general concepts are ordinary nouns. They take a
+capital only where a name is embedded in them.
+
+| Write                | Not                  |
+| :------------------- | :------------------- |
+| open source          | Open Source          |
+| the web              | the Web              |
+| the internet         | the Internet         |
+| a pull request       | a Pull Request       |
+| the command line     | the Command Line     |
+| JavaScript, npm, Git | Javascript, NPM, git |
+
+The last row is the exception that proves the rule: those three are names, and
+each has one correct spelling that is neither all lowercase nor all capitals.
+
+## After a colon
+
+A colon does not start a new sentence, so what follows it is capitalized only if
+it would be capitalized anywhere else. See [Colons][] for when the colon is the
+right mark at all.
+
+<!-- prettier-ignore-start -->
+<!-- LINK DEFINITION LABELS - START -->
+
+[Colons]: https://open.inf.is/docs/handbook/style/colons/
+
+<!-- LINK DEFINITION LABELS - END -->
+<!-- prettier-ignore-end -->

collections/_docs/handbook/style/code-in-text.md

@@ -1,18 +1,94 @@
 ---
 title: Code in Text
 key_point: What to set in code font, and how to explain placeholders.
-stub: true
 ---
 
-> [!NOTE]
->
-> This page is a placeholder. The sections below are linked from elsewhere in
-> the handbook and are yet to be written.
+Code font marks text the computer reads as-is. It tells the reader that what is
+between the marks is to be typed, or found, exactly as written — that the
+capitalization matters, the underscore is really there, and the plural `s` is
+not part of it.
+
+Use it for what the machine reads. Do not use it for emphasis; that is what
+**bold** is for, and a reader who has learned that code font means _literal_ is
+misled every time it means _important_.
+
+## Some specific items to put in code font
+
+| Item                     | Example                             |
+| :----------------------- | :---------------------------------- |
+| File and directory names | `eleventy.config.mjs`, `_includes/` |
+| Commands and flags       | `pnpm install`, `--frozen-lockfile` |
+| Package and scope names  | `@openinf/util-types`               |
+| Identifiers in code      | `replaceInlineSvg`, `$utilities`    |
+| Literal values           | `true`, `null`, `0`, `"production"` |
+| Environment variables    | `ELEVENTY_ENV`                      |
+| HTML elements            | `<var>`, `<code>`                   |
+| Selectors and classes    | `.doc-prose`, `#sidebar-toggle`     |
+| Git refs and trailers    | `live`, `Signed-off-by`             |
+
+Leave in ordinary text the things that are names of concepts rather than strings
+to be typed: a pull request, the commit queue, the style handbook.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> Run <code>nps test</code>
+  before opening a pull request.
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> Run <code>nps test</code>
+  before opening a <code>pull request</code>.
+</p>
+
+A trailing punctuation mark belongs outside the code font unless the mark is
+part of the thing being named.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> The config lives in
+  <code>eleventy.config.mjs</code>.
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> The config lives in
+  <code>eleventy.config.mjs.</code>
+</p>
 
 ## Explaining placeholders
 
-Yet to be written.
+A placeholder stands where the reader supplies a value of their own. Mark it
+with the `<var>` element so it is visibly not a literal, and give it a name that
+says what kind of value belongs there.
 
-## Some specific items to put in code font
+<p class="example">
+  <span class="compare-better">Recommended:</span>
+  <code>gh pr view <var>number</var></code>
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span>
+  <code>gh pr view NUMBER</code>
+</p>
+
+Then say what to put there. A placeholder the reader has to guess at is worse
+than no placeholder, because it looks like it has already been explained.
+
+Explain it in the sentence that introduces the sample, or in a list directly
+after it, naming each placeholder in the order shown:
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> Replace
+  <var>number</var> with the pull request's number, which
+  <code>gh pr list</code> prints.
+</p>
+
+Do not explain a placeholder whose name already answers the question.
+<var>number</var> in a command that plainly takes a pull request needs no
+sentence of its own; <var>ref</var> does, because a reader cannot tell whether
+it wants a branch, a tag, or a commit.
+
+For how placeholders are set in command-line syntax specifically — including
+optional and repeated arguments — see [Documenting Command-Line Syntax][].
+
+<!-- prettier-ignore-start -->
+<!-- LINK DEFINITION LABELS - START -->
+
+[Documenting Command-Line Syntax]: https://open.inf.is/docs/handbook/style/code-syntax/
 
-Yet to be written.
+<!-- LINK DEFINITION LABELS - END -->
+<!-- prettier-ignore-end -->

collections/_docs/handbook/style/code-samples.md

@@ -1,14 +1,88 @@
 ---
 title: Code Samples
 key_point: How to introduce and present a code sample.
-stub: true
 ---
 
-> [!NOTE]
->
-> This page is a placeholder. The section below is linked from elsewhere in the
-> handbook and is yet to be written.
+A sample is read by someone about to run it. Show what they should type, show
+what they should expect back, and leave out everything they would have to undo.
 
 ## Intros
 
-Yet to be written.
+Introduce a sample with a complete sentence ending in a colon, saying what the
+sample does rather than that it exists:
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> Compare the vendored copy
+  against what upstream serves:
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> Example:
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span> Run the following command:
+</p>
+
+The second says nothing the reader cannot see. The third describes the shape of
+the page instead of the work.
+
+Where the sample is the object of the introducing sentence, no colon is needed
+and none should be added:
+
+<p class="example">
+  <span class="compare-better">Recommended:</span> The queue is triggered by
+  applying the <code>🚀 Status: Commit Queue</code> label.
+</p>
+
+## Show the command, not the ceremony
+
+Give the shortest sample that actually works. Leave out flags that repeat a
+default, directory changes the reader does not need, and output that carries no
+information.
+
+<p class="example">
+  <span class="compare-better">Recommended:</span>
+  <code>pnpm install</code>
+</p>
+<p class="example">
+  <span class="compare-worse">Not recommended:</span>
+  <code>cd ~/projects &amp;&amp; pnpm install --silent=false</code>
+</p>
+
+Every line the reader has to skip is a line they might instead run.
+
+## Prompts
+
+A shell prompt marks which lines are typed and which are output. Which lines
+carry a `$` is settled by [Documenting Command-Line Syntax][], which owns that
+rule: every line of a multi-line input, optional on a lone command, and
+consistent across a page that mixes the two.
+
+Nothing here argues with that, because on this site the prompt costs the reader
+nothing. It is set in a `<span class="prompt">` styled `user-select: none`, so
+selecting the line copies the command and leaves the `$` behind. Where a prompt
+cannot be marked up that way, a reader who has to strip it after pasting is
+better served without it.
+
+Never show a root prompt (`#`) for something that does not need root.
+
+## Placeholders and long lines
+
+Set a value the reader supplies in a `<var>` element and say what belongs there
+— see [Explaining placeholders][].
+
+Keep lines short enough not to wrap. A wrapped command reads as two commands,
+and the reader cannot tell where the break was ours and where it was theirs. If
+a command genuinely cannot fit, break it at a point the shell accepts and say so
+in the sentence above it.
+
+For the notation used to show optional and repeated arguments, see [Documenting
+Command-Line Syntax][].
+
+<!-- prettier-ignore-start -->
+<!-- LINK DEFINITION LABELS - START -->
+
+[Explaining placeholders]: https://open.inf.is/docs/handbook/style/code-in-text/#explaining-placeholders
+[Documenting Command-Line Syntax]: https://open.inf.is/docs/handbook/style/code-syntax/
+
+<!-- LINK DEFINITION LABELS - END -->
+<!-- prettier-ignore-end -->