rich-ri 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0ebea7b8adc8c270a62c2f34f0ede696b4440199e801d3126f1c828bd6606f6
+  data.tar.gz: 9d01b69cee3ae3f39c045240a67f7559ba9cf511fbd86dc6cb429dc0cfee38c3
+SHA512:
+  metadata.gz: 57e14eb941738b7a3d7850990b777f94ceaa1d1b30cd4b03068cf0dd7047cad15f0d858e66df315b10275d17bf01cebd4e92de5893bc31641fcf23db0ac42ac2
+  data.tar.gz: 982792737323335b89e85bd0fffa9f2fbd675d4192f14545ff654a14ac974815f76445758da6e2f4a49b4825029a82585d72748a496cdbda76245da016d22320

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+User-visible changes are recorded here. This project follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-05
+
+### Added
+
+- Shell integration tests can run in Docker or Podman when local shells are
+  unavailable, with the same required checks used in CI.
+- Compatibility checks for minimum runtime dependencies and older RI stores,
+  upstream Ruby documentation samples and repeatable CLI performance measurements.
+- Release artifact checksums, build attestations and a protected hotfix workflow.
+- Focused guides for reading, configuration, completion, troubleshooting,
+  compatibility, contribution and maintenance.
+- Optional user YAML configuration with RI, environment and command-line
+  precedence, effective-settings inspection and safe recovery from invalid files.
+- Terminal, dark and light themes, per-role style overrides, configurable color
+  depth and independent bat themes for shell commands and other languages.
+- Theme and style completion, an annotated configuration example and a full
+  configuration reference covering behavior, environment variables and trust.
+- A terminal reader for installed Ruby and gem documentation, with semantic
+  colors, Ruby syntax highlighting, Unicode-aware wrapping and plain output.
+- Conservative recognition of shell transcripts with optional bat highlighting.
+- Interactive discovery and dynamic completion for Bash, Zsh and Fish.
+- A bundled manual, explicit dependencies and a tested gem installation path.
+- Manual installation and terminal-width-aware formatting, with colors that
+  respect the user's pager settings.
+
+### Fixed
+
+- Long options require their full names so configuration selection and completion
+  cannot silently interpret abbreviations differently.
+- Missing optional gems for `--server` and `--profile` explain how to install them;
+  help and the manual describe these dependencies.
+- Required shell tests fail when Fish or Zsh is unavailable; test environment
+  cleanup preserves the suite's shell requirement flag.
+- Optional bat highlighting has time and size limits, handles invalid encoding
+  and falls back to the original text without blocking subsequent examples.
+- Incompatible RI cache formats explain how to regenerate documentation.
+- Preserve heading level markers and ASCII horizontal separators in colored and
+  plain output so readers can search for document sections in their pager.
+- Ruby highlighting recognizes predicate, bang, setter and operator methods,
+  including definitions and calls without parentheses. Symbols retain their
+  style, and modulo operators are distinct from percent literals.
+- Shell completion uses documentation sources configured in `RI`.
+- Interactive Tab completion includes its required Readline adapter.
+- Raw Markdown content cannot send terminal controls through rich rendering.
+- Invalid dump paths and a missing manual viewer produce actionable errors.
+- Contributor checks handle shallow pull request merge histories.
+
+[Unreleased]: https://github.com/hvpaiva/rich-ri/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/hvpaiva/rich-ri/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Highlander Paiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# rich-ri
+
+Read Ruby documentation with highlighted code, clear headings and colored
+references. rich-ri wraps Ruby's RI reader and uses the documentation already
+installed for your Ruby and gems.
+
+![The complete Object#then page: ri -f ansi on the left, rich-ri on the right, with highlighted Ruby method chains, strings, constants and symbols.](docs/images/ri-vs-rich-ri.png)
+
+The same page in `ri -f ansi` and rich-ri, using the same terminal palette.
+rich-ri adds Ruby syntax highlighting and keeps heading markers searchable.
+[Image details](docs/images/README.md).
+
+## Install and read
+
+Requires Ruby 3.4 or later on Linux or macOS.
+
+```sh
+gem install rich-ri
+```
+
+Read a method:
+
+```sh
+rich-ri Array#map
+rich-ri String#scan
+```
+
+RDoc, which provides RI, is installed as a gem dependency. If a page is missing,
+see [documentation sources](docs/usage.md#documentation-sources-and-missing-pages).
+
+Run `rich-ri` without a name for interactive lookup. Press Tab to discover
+classes and methods; enter an empty line to leave. You can also
+[enable shell completion](docs/shell-completion.md) for Bash, Zsh or Fish,
+and use `ri` as an alias.
+
+## Find your way around
+
+Names follow RI conventions: `Array#map` is an instance method;
+`File::open` is a class method. `Class.method` searches both kinds.
+
+```sh
+rich-ri Hash
+rich-ri --all Array
+rich-ri ruby:syntax/pattern_matching
+rich-ri --help
+```
+
+In less, use `/` to search, `n` for the next match and `q` to quit.
+Search for `^=== ` to jump between level-three headings.
+`rich-ri --man` opens the full manual.
+
+## Choose your colors
+
+The default colors follow your terminal palette. Ruby highlighting is built in;
+installing bat also highlights shell examples and other tagged languages.
+
+```sh
+rich-ri --theme=light Regexp
+rich-ri --style='comment=bright_black' String#scan
+rich-ri --no-color Array#map
+```
+
+Save preferences in `~/.config/rich-ri/config.yml`:
+
+```yaml
+theme: terminal
+styles:
+  method: cyan
+  comment: bright_black
+```
+
+The [configuration reference](docs/configuration.md) covers themes, individual
+styles, pager settings and environment variables. `rich-ri --show-config` prints
+your effective settings.
+
+## More
+
+- [Reading documentation](docs/usage.md): lookup, pager navigation and your own project's docs.
+- [Shell completion and aliases](docs/shell-completion.md).
+- [Troubleshooting](docs/troubleshooting.md) and [supported versions](docs/compatibility.md).
+- [Contributing](CONTRIBUTING.md): setup, tests and pull requests.
+- [Changelog](CHANGELOG.md) and [security policy](SECURITY.md).
+
+Questions and bug reports are welcome in [GitHub issues](https://github.com/hvpaiva/rich-ri/issues).
+Released under the [MIT license](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,55 @@
+# Security
+
+## Report a vulnerability
+
+Use [private vulnerability reporting](https://github.com/hvpaiva/rich-ri/security/advisories/new)
+or email [contact@hvpaiva.dev](mailto:contact@hvpaiva.dev) with affected versions,
+reproduction steps and impact. Please do not put exploit details or secrets in
+a public issue. The maintainer will coordinate a fix and disclosure with you;
+response time depends on availability.
+
+Security fixes target the latest released version. There is no promise to
+backport fixes to older 0.x releases. Ordinary bugs belong in GitHub issues.
+
+## Trust boundaries
+
+rich-ri reads the active Ruby's documentation and explicitly selected RI stores.
+RDoc uses Ruby Marshal caches, which can instantiate Ruby objects while loading.
+Do not point `--doc-dir` or `--dump` at untrusted files, or install untrusted
+documentation into a searched directory. Completion reads the same trusted stores.
+
+Ruby examples are parsed, never evaluated. Shell examples are tokenized, never
+executed. Optional bat receives source on stdin with separate command arguments.
+Its configuration file is disabled, and output that alters source is discarded.
+Execution time and output size are bounded; failed highlighting leaves plain code.
+Terminal controls in rich rendering are escaped; original RDoc formatters retain
+upstream behavior when explicitly selected with `--format`.
+
+Configuration files use safe YAML parsing: aliases, object tags, unknown keys and
+invalid values are rejected. There is no Ruby evaluation, shell interpolation or
+automatic project configuration search. Style strings use a restricted grammar;
+raw terminal escapes are not accepted. A custom file selected with `--config` or
+`RICH_RI_CONFIG` is still trusted input: it may select RI stores and a pager command.
+
+`pager` command strings, `--pager-command`, `RI_PAGER` and `PAGER` are trusted
+command settings interpreted by RDoc. `PATH` selects bat and other external
+programs. Do not accept these settings from untrusted input. `--show-config` may
+include command arguments and paths from your environment; review it before
+sharing its output. `--server` deliberately enables RDoc's HTTP server; consult
+RDoc before exposing it on a network.
+
+## Supply chain
+
+The gem declares runtime dependencies and its supported Ruby range. Development
+uses a committed lockfile, automated dependency updates and a vulnerability audit.
+GitHub Actions use pinned commits and minimal job permissions. Releases verify
+the tag, version, changelog and ancestry on main or the matching hotfix branch,
+then use RubyGems trusted publishing. Publication credentials are short-lived
+and scoped to this gem. Installation tests, publication and GitHub Releases use
+the same gem artifact, with a verified checksum and a GitHub build attestation.
+
+Changes to protected branches go through pull requests with signed commits and
+passing checks. Release tags and the publication environment are restricted,
+and published GitHub releases are immutable. Maintainers verify these settings
+before release. RubyGems trust must be configured for the repository, workflow
+and environment described in [Maintenance](docs/maintenance.md).

data/completions/rich-ri.bash

@@ -0,0 +1,23 @@
+# bash completion for rich-ri; requires bash-completion 2.x.
+# shellcheck shell=bash
+
+_rich_ri() {
+  # _init_completion assigns prev through Bash's dynamic scope.
+  # shellcheck disable=SC2034
+  local cur prev words cword value _description
+  COMPREPLY=()
+  _init_completion -n ':=' || return
+  while IFS=$'\t' read -r value _description; do
+    [[ -n $value ]] && COMPREPLY+=("$value")
+  done < <(command rich-ri --complete --shell=bash "${words[@]:1:cword}" 2>/dev/null)
+  if ((${#COMPREPLY[@]} == 1)) && [[ ${COMPREPLY[0]} == *[:.#/=] ]]; then
+    compopt -o nospace 2>/dev/null || :
+  fi
+  [[ $cur == *:* ]] && __ltrim_colon_completions "$cur"
+  if [[ $cur == *=* && $COMP_WORDBREAKS == *'='* ]]; then
+    COMPREPLY=("${COMPREPLY[@]#*=}")
+  fi
+  return 0
+}
+
+complete -o filenames -F _rich_ri rich-ri

data/completions/rich-ri.fish

@@ -0,0 +1,9 @@
+function __rich_ri_complete
+    set -l words (commandline -xpc 2>/dev/null)
+    or set words (commandline -opc | string unescape)
+    set -e words[1]
+    set -l current (commandline -ct | string unescape)
+    command rich-ri --complete $words "$current" 2>/dev/null
+end
+
+complete -c rich-ri -f -a '(__rich_ri_complete)'

data/completions/rich-ri.zsh

@@ -0,0 +1,18 @@
+#compdef rich-ri
+
+_rich_ri() {
+  local value description
+  local -a values descriptions
+  while IFS=$'\t' read -r value description; do
+    [[ -n $value ]] || continue
+    values+=("$value")
+    descriptions+=("$value${description:+ -- $description}")
+  done < <(command rich-ri --complete --shell=zsh "${words[@]:1:$((CURRENT - 1))}" 2>/dev/null)
+  if (( ${#values} == 1 )) && [[ ${values[1]} == *[:.#/=] ]]; then
+    compadd -S '' -d descriptions -- "${values[@]}"
+  else
+    compadd -d descriptions -- "${values[@]}"
+  fi
+}
+
+compdef _rich_ri rich-ri

data/docs/compatibility.md

@@ -0,0 +1,40 @@
+# Compatibility
+
+## Supported environments
+
+| Component | Support |
+| --- | --- |
+| Ruby | MRI 3.4 and 4.0. The gem requires Ruby 3.4 or later. |
+| Operating system | Linux and macOS. Other systems and Ruby engines are untested. |
+| RDoc | 8.1 or later in the 8.x series. |
+| RI stores | Current RDoc output, plus RDoc 6.14 stores on Ruby 3.4. Regenerate caches when moving between Ruby 3 and 4. |
+| Completion | Bash with bash-completion 2.x, Zsh and Fish. |
+| Terminal | Plain output works without ANSI support. Colors depend on the terminal palette and capabilities. |
+
+CI runs Ruby 3.4 and 4.0 on Linux and Ruby 4.0 on macOS. A separate Ruby 3.4 job
+tests the minimum runtime dependency set in [minimum.gemfile](../gemfiles/minimum.gemfile).
+Another job resolves current dependencies. The locked bundle is used for normal
+development and releases. Shell integrations run natively on both platforms;
+CI also checks the [container test environment](development.md#shell-tests)
+available to contributors.
+
+## Changes between versions
+
+The supported interface consists of the executable, documented options,
+configuration keys, environment variables and shell completion installation.
+The default heading markers remain available for pager searches. Page layout and
+syntax colors may improve in patch releases. Page output is intended for
+interactive reading and has no stable format for parsing by scripts.
+
+While rich-ri is below 1.0, patch releases preserve that interface. Incompatible
+changes require a minor release and migration instructions in the changelog.
+From 1.0 onward, incompatible changes require a major release. Ruby classes and
+the internal completion protocol are implementation details.
+
+Dropped Ruby, RDoc or platform support follows the same versioning policy. An
+upcoming removal is announced in the changelog at least one minor release ahead,
+except where a security fix requires an earlier change.
+
+Only the latest released version receives fixes. See the
+[security policy](../SECURITY.md) for vulnerability reports and
+[maintenance guide](maintenance.md) for urgent releases.

data/docs/config.example.yml

@@ -0,0 +1,49 @@
+# rich-ri configuration. Copy to ~/.config/rich-ri/config.yml,
+# or $XDG_CONFIG_HOME/rich-ri/config.yml when that variable is absolute.
+# Every key is optional. The active defaults follow your terminal and RI options.
+# CLI > dedicated environment > this file > RI > built-in defaults.
+# See configuration.md for all flags, environment variables and style grammar.
+
+theme: terminal          # terminal, dark or light
+color: auto              # auto, always or never
+color_depth: auto        # auto, basic, "256" or truecolor
+width: 80                # Integer >= 20; omit this key to follow terminal width.
+pager: true              # true, false, or a trusted command such as "less -R"
+bat_theme: base16         # Non-Ruby, non-shell examples; requires optional bat.
+shell_theme: ansi        # Shell examples and commands; requires optional bat.
+all: false               # Include all methods on class and module pages.
+expand_refs: true        # Expand references at the end of a page.
+
+doc_dirs: []             # Extra existing RI stores, added to RI/CLI directories.
+# doc_dirs:
+#   - ./ri               # Relative to this file's directory, not the shell's cwd.
+sources:
+  system: true
+  site: true
+  home: true
+  gems: true
+
+# This table reproduces the terminal preset. Delete entries to inherit the
+# selected preset; each entry replaces that role's complete style.
+# Values must be strings: quote "208" and "#7aa2f7". Use "none" to disable a role.
+# Example custom value: "fg=#7aa2f7:bg=#1a1b26:bold:underline"
+styles:
+  title: "cyan:bold"
+  heading: "blue:bold"
+  subheading: "magenta:bold"
+  code: "cyan"
+  reference: "cyan"
+  link: "cyan:underline"
+  label: "yellow:bold"
+  muted: "bright_black"
+  emphasis: "italic"
+  bold: "bold"
+  strike: "strike"
+  keyword: "magenta"
+  string: "green"
+  number: "yellow"
+  constant: "yellow"
+  symbol: "yellow"
+  method: "cyan"
+  comment: "bright_black"
+  operator: "magenta"

data/docs/configuration.md

@@ -0,0 +1,254 @@
+# Configuration
+
+rich-ri uses the original RDoc RI reader for documentation lookup. Its `RI`
+environment variable, installed documentation and pager settings still apply.
+The YAML file described here is specific to rich-ri; plain `ri` does not read it.
+All settings are optional.
+
+## Select a file
+
+The default path is `$XDG_CONFIG_HOME/rich-ri/config.yml` when `XDG_CONFIG_HOME`
+is a nonempty absolute path; otherwise it is `~/.config/rich-ri/config.yml`.
+A missing default file is fine. rich-ri never searches the current project for
+configuration, and installing the gem does not create or edit configuration.
+
+Use `RICH_RI_CONFIG` or `--config FILE` to choose a different file. The explicit
+file must exist and be readable. `--config=FILE` is equivalent. `--no-config`
+disables file loading, including `RICH_RI_CONFIG`. If `--config` and `--no-config`
+appear together, the last command-line selector wins.
+
+```sh
+rich-ri --config-path
+rich-ri --config "$HOME/my-rich-ri.yml" --show-config
+rich-ri --no-config --show-config
+```
+
+`--config-path` prints the selected file path without opening it. `--show-config`
+prints the effective preferences as YAML after validation and merging; it does not
+write a file or load documentation. It includes environment overrides, so check
+its contents before sharing it. It shows the requested color policy and depth;
+`auto` still depends on the terminal when rendering. `pager: true` means paging
+is allowed; redirected output still bypasses the pager. The `styles` map lists
+explicit role overrides; preset styles are selected by `theme`.
+
+Use a single YAML document containing a mapping; an empty file means no
+overrides. Files larger than 64 KiB, nesting deeper than 20 levels, duplicate or
+unknown keys, wrong types, invalid values, YAML aliases and object tags are
+rejected with a usage error. Values are not interpolated or evaluated as Ruby
+or shell code. A bad file does not prevent
+`--help`, `--version`, `--config-path` or printing a shell completion script.
+`--no-config` bypasses the bad file to let you continue using the reader.
+
+## Precedence and RI compatibility
+
+Settings are applied in this order, with later layers taking precedence:
+
+1. Built-in defaults.
+2. Default options in `RI`, split into shell words without shell evaluation.
+3. The selected YAML configuration file.
+4. Dedicated environment variables listed below.
+5. Explicit command-line options.
+
+The `RI` variable can contain default lookup and presentation options.
+For example, `RI='--no-standard-docs --doc-dir /path/to/ri'` works for both lookup
+and completion. rich-ri uses RDoc directly; the `ri` executable itself need not
+be on `PATH`. rich-ri's extra theme, style and utility flags are not supported
+by plain `ri`.
+
+Most values replace earlier values. `styles` merges by role: a later `method`
+style changes that role without dropping a `heading` style from an earlier layer.
+A role override replaces the preset's entire style for that role.
+Documentation directories are additive: `RI`, `doc_dirs` and repeatable
+`--doc-dir` options contribute directories in that order.
+
+`RI_PAGER` overrides a pager command from the file. `--pager-command` takes
+precedence over both. `PAGER` is used only when no specific pager command was
+selected. `--no-pager` disables paging even when a command is configured.
+Output redirected to a pipe or file is not paged.
+
+## File keys
+
+Every key is optional. The [annotated example](config.example.yml) includes all
+supported keys and style roles.
+
+| Key | Default | Accepted values and behavior |
+| --- | --- | --- |
+| `theme` | `terminal` | `terminal`, `dark` or `light`. |
+| `color` | `auto` | `auto`, `always` or `never`. |
+| `color_depth` | `auto` | `auto`, `basic`, `"256"` or `truecolor`. |
+| `width` | Terminal-based | Integer of at least 20; prose width in terminal columns. |
+| `pager` | `true` | `true` to allow paging, `false` to disable it, or a trusted command string such as `less -R`. |
+| `bat_theme` | `base16` | bat theme for tagged non-Ruby, non-shell examples. |
+| `shell_theme` | `ansi` | bat theme for shell examples and commands inside transcripts. |
+| `all` | `false` | Boolean; include all methods when reading a class or module. |
+| `expand_refs` | `true` | Boolean; ask RDoc to expand references at the end of a page. |
+| `doc_dirs` | `[]` | List of extra RI directories; relative entries are resolved from the configuration file's directory. |
+| `sources` | All enabled | Mapping of `system`, `site`, `home` and `gems` to booleans. |
+| `styles` | Theme preset | Mapping of semantic roles to style strings, described below. |
+
+When width is not specified, the reader uses the terminal width minus two
+columns, bounded between 30 and 96 columns. With redirected output it normally
+uses 78 columns. Code blocks retain their original content and indentation.
+
+`doc_dirs` must name existing directories. Use `sources` to disable selected
+standard documentation locations; use `--no-standard-docs` to disable all four
+from the command line. This changes which documentation is read, not which
+packages are installed. `--list-doc-dirs` prints the resulting search paths.
+RI stores contain Ruby Marshal data and must be trusted, even for completion.
+
+A pager command is a trusted executable setting: RDoc may execute it through a
+shell. Keep such commands under your own control. Merely reading or inspecting
+configuration does not start a pager.
+
+## Themes and styles
+
+`terminal` uses your terminal's ANSI palette, preserving rich-ri's default
+appearance. `dark` and `light` supply foreground colors suited to those
+backgrounds. They do not set the terminal background or try to detect it.
+Choose explicitly if your terminal palette needs different contrast.
+
+Each style is a colon-separated string. A bare color sets the foreground;
+`fg=COLOR` and `bg=COLOR` set foreground and background explicitly. Attributes
+can be combined with colors. Use `none` by itself to remove a role's styling.
+
+| Component | Values or example |
+| --- | --- |
+| ANSI foreground | `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` |
+| Bright ANSI foreground | `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white` |
+| Palette index | `"0"` through `"255"`, for example `"208"` |
+| RGB foreground | `"#RRGGBB"`, for example `"#7aa2f7"` |
+| Terminal default | `default`, `fg=default` or `bg=default`; restore the terminal's default foreground or background. |
+| Explicit colors | `"fg=#7aa2f7:bg=#1a1b26"` |
+| Attributes | `bold`, `italic`, `underline`, `dim`, `strike`, `reverse` |
+| Combined style | `"fg=cyan:bg=black:bold:underline"` |
+| Disable role | `"none"` |
+
+Names are lowercase. Each color component or attribute may appear only once.
+Quote numeric and hex styles in YAML so that they remain
+strings; an unquoted `#` starts a YAML comment. Raw ANSI escape sequences and
+unknown attributes are rejected. Attribute appearance depends on your terminal.
+
+| Role | Applies to |
+| --- | --- |
+| `title` | Page titles and the help usage heading. |
+| `heading` | Main section headings. |
+| `subheading` | Nested section headings. |
+| `code` | Inline code, Ruby variables, boolean literals, `self`, interpolation and shell prompts. |
+| `reference` | Recognized names, method lists, list markers and displayed URLs. |
+| `link` | Labeled documentation and external links. |
+| `label` | List labels and other labeled content. |
+| `muted` | Secondary metadata and separators. |
+| `emphasis` | Emphasized prose. |
+| `bold` | Strong prose. |
+| `strike` | Struck-through prose. |
+| `keyword` | Ruby keywords. |
+| `string` | Ruby strings, regular expressions and string-like literals. |
+| `number` | Ruby numeric literals. |
+| `constant` | Ruby constants. |
+| `symbol` | Ruby symbols. |
+| `method` | Ruby method definitions, calls and signatures. |
+| `comment` | Ruby comments. |
+| `operator` | Ruby operators and related syntax. |
+
+```yaml
+styles:
+  heading: "fg=#7aa2f7:bold"
+  method: "cyan"
+  comment: "bright_black"
+  link: "blue:underline"
+  muted: "none"
+```
+
+For a one-off change, use repeatable `--style=ROLE=STYLE` flags:
+
+```sh
+rich-ri --theme=dark --style='comment=#9ca3af' --style='method=cyan:bold' Regexp
+```
+
+`--format=NAME` selects an original RDoc formatter. Its formatting does not use
+rich-ri's theme, role styles or rich page layout.
+
+## Color policy and terminal capability
+
+`color: auto` emits colors only when stdout is a terminal, `NO_COLOR` is empty or
+unset, and `TERM` is not `dumb`. `--color` without a value means `always`.
+`--color=always` forces colors even in a pipe or with `NO_COLOR` or `TERM=dumb`.
+`--no-color` and `--color=never` preserve the page layout without ANSI colors.
+
+Color depth is separate from whether colors are enabled. `color_depth: auto`
+uses truecolor when `COLORTERM` is `truecolor` or `24bit`, 256 colors when `TERM`
+contains `256color`, and the basic ANSI palette otherwise. Set `basic`, `"256"`
+or `truecolor` explicitly to override detection. RGB and palette colors are
+approximated when the chosen depth cannot represent them directly.
+
+Ruby examples are highlighted in process and share these styles. No external
+highlighter is needed for Ruby or for the rest of the page. Optional bat handles
+other explicitly tagged languages and recognized shell commands. Its separate
+`bat_theme` and `shell_theme` settings select bat themes; role overrides do not
+recolor bat's tokens. Run `bat --list-themes` to see installed themes.
+
+The selected color depth applies to rich-ri's built-in styles; bat handles its
+own depth. rich-ri disables bat's configuration file and passes its own formatting
+options.
+If bat is missing, fails, exceeds two seconds or returns invalid text, the original
+code is shown without highlighting and bat is disabled for the rest of the page.
+Examples larger than 1 MiB bypass bat; its output is limited to 8 MiB.
+Disabling rich-ri colors also disables bat highlighting.
+
+## Environment variables
+
+Empty dedicated `RICH_RI_*` variables are ignored. Unset a variable, or set it to
+an empty value, to fall back to the file or an earlier layer.
+
+| Variable | Meaning |
+| --- | --- |
+| `RICH_RI_CONFIG` | Explicit configuration file path; overridden by `--config` or `--no-config`. |
+| `RICH_RI_THEME` | `theme` override. |
+| `RICH_RI_COLOR` | `color` override. |
+| `RICH_RI_COLOR_DEPTH` | `color_depth` override. |
+| `RICH_RI_WIDTH` | `width` override. |
+| `RICH_RI_BAT_THEME` | `bat_theme` override; takes precedence over `BAT_THEME`. |
+| `RICH_RI_SHELL_THEME` | `shell_theme` override. |
+| `RICH_RI_STYLE_<ROLE>` | Override a role using its uppercase name, for example `RICH_RI_STYLE_COMMENT=cyan`. |
+| `RI` | Default command-line options, parsed as shell words. |
+| `RI_PAGER` | Documentation pager command; overrides the file, below `--pager-command`. |
+| `PAGER` | Fallback documentation pager; also used by man according to its own rules. |
+| `LESS` | Options for less; rich-ri appends `-R` for its child documentation pager. |
+| `BAT_THEME` | Backward-compatible bat theme override when `RICH_RI_BAT_THEME` is unset. |
+| `NO_COLOR` | Nonempty values disable automatic colors. |
+| `TERM` | `dumb` disables automatic colors; `256color` indicates 256-color capability. |
+| `COLORTERM` | `truecolor` or `24bit` indicates truecolor capability in automatic depth mode. |
+| `XDG_CONFIG_HOME` | Absolute base directory for the default configuration file. |
+| `GEM_HOME`, `GEM_PATH` | RubyGems paths that affect installed documentation stores. |
+| `HOME` | Home configuration and RI documentation locations. |
+| `PATH` | Search path for external programs such as bat, less and man. |
+| `MANPAGER` | Manual viewer's pager, according to man. |
+| `MANROFFOPT`, `GROFF_NO_SGR`, `LESS_TERMCAP_*` | Existing manual rendering and palette settings. |
+| `MANPATH` | Manual search path for `man rich-ri`. |
+| `XDG_DATA_HOME` | Absolute base for `--install-man`; otherwise `~/.local/share` is used. |
+
+For Bash or Zsh, export variables with `export RICH_RI_THEME=light`. In Fish, use
+`set -gx RICH_RI_THEME light`. Flags and YAML have the same meaning in all shells.
+
+The bundled manual honors existing man pager and palette settings. rich-ri only
+supplies its manual palette when none of those settings are configured. Installing
+the manual copies the current bundled file; rerun `--install-man` after upgrades.
+
+## Troubleshooting
+
+- **A configuration error prevents lookup:** run `rich-ri --no-config --show-config`
+  to bypass the file, then inspect `rich-ri --config-path`. Dedicated environment
+  overrides still apply; correct or unset any invalid one named by the error.
+- **A theme appears unchanged:** check `--show-config`, `NO_COLOR`, redirected
+  stdout and whether you selected an original RDoc formatter with `--format`.
+- **Colors look different over SSH:** check `TERM` and `COLORTERM` in the remote
+  session, or select a color depth supported by the actual terminal.
+- **Only Ruby examples have colors:** install bat for other languages, and verify
+  that `bat_theme` and `shell_theme` name themes listed by `bat --list-themes`.
+- **Completion is empty:** run `--show-config` and `--list-doc-dirs`; completion
+  uses the same sources and cannot suggest documentation names when configuration
+  or stores are invalid. Option and theme suggestions remain available.
+
+Lookup, configuration and usage failures exit with status 1. Interrupts exit with
+130; success and a closed output pipe exit with 0. No configuration command edits
+shell files or installs completion scripts automatically.