dotfiles

Shell, editor and terminal configuration, the tools that go with them, and
szecret, an age-based secret manager whose store lives elsewhere.

History restarts here. What came before was not written to be read by
anyone else, and carried machine names, addresses and an encrypted secret
store; it is kept privately instead. What is left is meant to be safe on
any machine, including one whose owner is not me: see CLAUDE.md for the
rule it is written to.

1 files changed, 105 insertions, 0 deletions

diff --git a/skills/google-style-guide/reference/code.md b/skills/google-style-guide/reference/code.md
new file mode 100644
index 0000000..cb5af34
--- /dev/null
+++ b/skills/google-style-guide/reference/code.md
@@ -0,0 +1,105 @@
+# Code and API documentation detail
+
+Detail for: code font usage, code samples, command-line syntax, placeholders,
+API reference comments, semantic tagging, HTML/Markdown formatting. Source:
+developers.google.com/style (Code in text, Code samples, Code syntax,
+Placeholders, API reference comments, Semantic tagging, HTML formatting,
+Markdown).
+
+## Code font (inline code)
+
+Put in code font (backticks in Markdown, `code` in HTML) anything the reader
+types or that is a code entity. Non-exhaustive list:
+
+| Item | Example |
+|---|---|
+| Attribute names and values | "the `imageURL` attribute" |
+| Class names / method names | "the `SnapshotDiskOperator` class includes the `generate_snapshot_name` method" |
+| Command output | "The output is similar to the following: ..." |
+| Command-line utility names | "the `gcloud` tool", "the `kubectl` tool" |
+| Data types | "Nested data is represented as a `STRUCT` type" |
+| Database elements | "the `julianday` and `dayofweek` values from the `datetime` and `timestamp` columns" |
+| Element names (HTML/XML) | "the `script` and `df-messenger` HTML elements" (no angle brackets) |
+| Enum / constant values | "the constant `city` has the value `"San Francisco"`" |
+| Environment variables | "Set the `CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES` environment variable" |
+| Filenames, extensions, paths | "the `pg_hba.conf` file, in the `/etc/postgresql/13/main` directory" |
+| HTTP verbs / status codes / content types | "send a `POST` request", "the `500 Internal Server Error` status code" |
+| IP addresses, machine types, regions (when code-like) | "the `e2-highcpu-16` machine type in the `us-central1-a` region" |
+| Boolean values as literals | "If the update succeeds, returns `true`." |
+| Literal text the reader types into a field | "In the **Name** field, enter `my-instance-99`" |
+
+Do **not** use code font for: domain names (use example.com), product/service
+names, or URLs the reader follows in a browser (make them links with
+descriptive text instead).
+
+### Grammatical treatment of code elements
+
+- Never inflect code as English — no pluralizing, possessives, or verbing.
+  Include a noun after the code item and inflect that noun:
+  - "the value of the `ADDRESS` constant" (not "`ADDRESS`'s value")
+  - "send a `POST` request" (not "`POST` the data")
+  - "call the `close` method" (not "`Closeing` the file")
+- Follow code spelling/capitalization exactly.
+
+## Code samples (blocks)
+
+- Indent with spaces (two per level per Google style; follow the language's
+  style guide); wrap lines at ~80 chars.
+- Markdown: fenced code blocks with the language for syntax highlighting.
+  HTML: `<pre>`.
+- Introduce the sample with a sentence; end with a colon if the sample directly
+  follows, a period if material intervenes.
+- Show omissions with a language-appropriate comment ("... // Existing code").
+- Don't rely on code samples alone — explain what the code does when relevant.
+
+## Command-line syntax
+
+- Show the command plus its most common use case. Prefer click-to-copy simple
+  commands over exhaustive syntax.
+- Optional arguments: document the common options, not every flag. Keep
+  mutually exclusive options clear ("`-a` or `-b`, not both").
+- Placeholders (see below) for values the reader replaces.
+- When showing output, include only the relevant parts and introduce it
+  ("The output is similar to the following:").
+- Use "run the `gcloud` command", not "gcloud it".
+
+## Placeholders
+
+- Placeholders represent values the reader must replace. Give them descriptive
+  names: `PROJECT_ID`, `LOCATION`, `EMAIL_ADDRESS` — not `VALUE1`.
+- In inline text and code blocks, format per your project's convention (often
+  angle brackets `<PROJECT_ID>` in syntax docs, or italic/capitalized in code
+  samples — follow the house convention).
+- Explain each placeholder the first time it appears ("Replace `PROJECT_ID`
+  with your project's ID.").
+- Use placeholder names consistently within a document.
+
+## API reference comments
+
+- Document every public class, constant, method, parameter, and return value.
+- First line: a concise statement of purpose in present tense, imperative or
+  descriptive ("Creates a new task on the specified task list.").
+- Parameter descriptions: purpose and expected values; state behavior for
+  booleans and defaults explicitly ("If `true`, validates the certificate.").
+- Return value: what information is returned, not a restatement of the method.
+- Avoid redundancy with the signature; don't repeat the method name as the
+  whole description.
+- Deprecations: state the replacement and guidance for updating code.
+
+## Semantic tagging (HTML)
+
+- Use elements for their purpose: `em` = emphasis, `strong` = strong
+  importance, `cite` = titles of works, `kbd` = keyboard keys, `pre` =
+  preformatted, `b` = attention without importance (used for UI labels).
+- Use headings only for hierarchical structure, CSS for visual styling.
+- No tables or frames for layout.
+- See the HTML formatting rules: two-space indentation, lowercase elements and
+  attributes, no trailing spaces, 80-char lines (except URLs and meta lines).
+
+## Markdown vs HTML
+
+- Markdown is preferred for readability; switch to HTML (`code`, `kbd`, spans
+  for nonbreaking spaces, etc.) when you need effects Markdown can't express.
+- Follow the project's existing convention.
+- Don't use tabs for indentation (Markdown features expect spaces); no trailing
+  whitespace.
\ No newline at end of file