Three API examples are held off the docs site's Ruby pages #92

Summary

The docs site leaves three of this repository's API example programs off the Ruby API pages: examples/api/workspace_apply.rb, examples/api/control.rb and examples/api/async_control.rb. Each Ruby API page tells the reader to save the program in an empty directory with a one-gem Gemfile and to use tmux 3.3a or newer. workspace_apply.rb cannot run that way, and the two control programs need tmux 3.7. libtmux/docs#247 added the hold, so the LibTmux::Workspace and control-connection pages publish without a complete program until these change here.

Motivation

workspace_apply.rb loads a file beside the examples directory, which a reader who saved only the program does not have, so it stops with LibTmux::Workspace::ConfigError:

workspace = LibTmux::Workspace.load(File.expand_path("../workspace.yaml", __dir__))

(examples/api/workspace_apply.rb)

control.rb and async_control.rb call open_control, which the library refuses below tmux 3.7:

Capability.new(id: "control-mode", name: "Control mode", since: "3.7", handling: :refuse, error: ERROR,

(gems/libtmux/lib/libtmux/capabilities.rb)

The docs generator writes the same intro for every program, from examples/manifest.json, whose entries carry only id, path, gem and api. Nothing there says a program needs a newer tmux than the library's floor, so the page would state 3.3a for a program that raises UnsupportedFeatureError on 3.3a. The intro, in libtmux/docs packages/api-model/src/languages/ruby-examples.ts:

intro: `${api.description.replace(/\n/g, ' ')} Use Ruby 3.3 or newer with Bundler, and tmux 3.3a or newer, on Unix with \`/bin/cat\` and \`/bin/sh\` available. In an empty directory, save this \`Gemfile\`:`,

The hold and its stated conditions, in the same file:

export const HELD_RUBY_PROGRAMS: Readonly<Record<string, string>> = {
  'examples/api/workspace_apply.rb':
    'Saved alone in an empty directory it stops with Workspace::ConfigError: it loads ../workspace.yaml, '
    + 'which no page shows. Returns once libtmux-ruby writes the document inside the program.',
  'examples/api/control.rb':
    'The intro states tmux 3.3a or newer, but the library refuses a control client below tmux 3.7 (capability '
    + 'control-mode). The manifest has no field for a program\'s tmux floor and the model states 3.7 only in '
    + 'prose, so no floor is read. Returns once the manifest declares it and this generator uses it.',

The ConfigError is the hold's stated reason; it was not re-run for this issue.

Proposal

• workspace_apply.rb writes its workspace document itself, for example from a heredoc into a temporary file, so the program runs saved alone.
• Each program entry in examples/manifest.json can declare the tmux release it needs when that is above the library's floor, and control.rb and async_control.rb declare 3.7.

The docs side then reads the declared release into the intro and drops each hold once the pinned revision carries the change; that is a follow-up in libtmux/docs.

References

• libtmux/docs#247: added the hold.
• Fix what the verification pass flagged in alpha.3 #54: its item that the README never says control connections need tmux 3.7.
• Add a standalone, CI-run example program for each core capability #86: a standalone, CI-run example program for each core capability.
• examples/manifest.json at 25b51c8