cf-docs-rfc-proposal

Variable survey

Status: draft, incomplete — covers what is known as of 2026-10-11.

This survey counts every variable the book’s pages use and every value the book defines, and records where each use sits and what each value holds. It was done on 2026-10-11 to choose the test pages of the variables round and to know which cases a conversion has to handle (R-04 variables everywhere).

Terms used below:

File What it is
uses.csv One row per ERB expression in the surveyed files (1,676 rows), each with a GitHub link at the surveyed commit: what it is, the variable’s name, whether it is defined, what its value holds, its place and the elements around it
values.csv One row per key of the book’s file (273), of the MkDocs tutorial’s extra: (2), and per name pages use but no key defines (28): what the value holds, how often pages use it, and where
shas.txt The 15 repositories and the commit surveyed in each, the notes survey’s list
survey.py Finds the expressions and reads the variables file; writes the two CSV files
summary.py Prints the counts below from the two CSV files

Scope

Method

survey.py reads each file and finds every ERB tag. For each tag it records:

Field What is recorded
kind variable (the tag reads vars.name), partial, helper (another Ruby method: image_tag, mermaid_diagram, …), build-time (Time.now), control (end), comment; in docs-bosh, bosh-template
defined, value_kind whether the book’s file has the key and a value, and what the value holds (below)
method expression when the tag does more than print one variable (a condition, a string built from variables); such a tag gets a row per variable it reads
place front-matter; erb-code (a <% %> tag); fenced-code (between ``` or ~~~ lines); indented-code (four columns past the margin or the enclosing list item, after a blank line); pre (inside <pre>); code-span (inside backticks or <code>); link-url (in a Markdown link’s target, a reference definition, or an href or src); html-attribute (another attribute); heading (a # line or <h1>–<h6>); link-text (in a Markdown link’s text or inside <a>); prose otherwise. The first that applies wins
table, note, list, html whether the use sits in a Markdown pipe table or an HTML cell, in an HTML note (<p class="note">), in a list (indented under a Markdown item, or in an open <li>), and the innermost HTML block element around it
links_resolve for a value with links relative to the page: whether each link, resolved from the page’s published folder, reaches a page of the book, directly or through a redirect in redirects.rb

A value is text, url, path (a file or partial name, a relative link target), html (it holds an HTML element), markdown (a link [text](url), backticks, **, emphasis, list lines, a fence, an escaped \_), html+markdown, empty, or erb (it holds an ERB tag; none does). HTML elements are read with a tag pattern; an HTML tag left open inside a table cell or list item is taken to end where HTML ends it.

The places are read from the source. Two limits: an indented code block is found by indentation alone, the way CommonMark finds it, and the book’s Markdown processor (Redcarpet) may differ at the edges; and inline HTML left open in the source (an <a> never closed, a </xth> typo) is ended at the next blank line or closed cell.

The YAML file is read without a YAML library. Its parse was compared with PyYAML 6.0.2: all 273 keys and values are the same (see How to rerun).

Totals

  Variables Partials Helpers and control Comments Build-time All
The book (12 repositories) 1,503 45 9 13 0 1,570
The book repository’s pages and layouts 5 7 19 1 1 33
bosh.io (docs-bosh) — — — — — 41 ERB tags shown as code
MkDocs tutorial (docs-dotnet-core-tutorial) 32 {{ name }} — — — — 32

The 1,503 variable uses are in 169 files and read 180 names: docs-dev-guide 496, docs-cloudfoundry-concepts 362, docs-cf-admin 265, docs-buildpacks 115, docs-loggregator 100, docs-services 100, docs-uaa 29, docs-deploying-cf 15, docs-running-cf 9, docs-cf-cli 5, docs-credhub 4, docs-bbr 3. Every one is in a .erb file, so every one is read by ERB. 29 are in partials, 8 in archive/ folders.

Where variables sit

Place Uses Detail
Text (prose) 1,205  
Inline code 98 70 in backticks, 28 in <code>
Fenced code block 92  
<pre> block 44  
Link text 33 all in Markdown links: [<%= vars.app_runtime_abbr %> Security](security.html)
Heading 27 on 15 pages; every one has an explicit <a id>, so no published id depends on a value (the hyphen-prefixed second id does, for example -configuring-ssh-access-for-cloud-foundry)
Link target 3 two Markdown ([metrics](<%= vars.gorouter_metrics_link %>), troubleshooting-router-error-responses L40; […](<%= vars.product_url %>), notifications L15), one HTML href in a table cell (L388)
ERB code 1 the page title, set from a variable (below)
Front matter, page description 0 the book’s pages have no description; no front matter holds a tag
Another HTML attribute 0  
Indented code block 0  
Inside another variable’s value 0 no value holds an ERB tag

Around the uses, in every place: 96 sit in table cells (74 HTML, 22 Markdown pipe tables), 22 in HTML notes, 326 in lists (288 Markdown, 38 HTML <li>).

Expressions that do more than print. Three tags, five variable references:

Partial names in variables. At these commits no page picks its partial from a variable. Eight keys hold a partial’s name (scale_table, roles_table, suspended_roles_table, concepts_product_model_text, gorouter_client_cert, ssl_termin_gorouter, ssl_termin_lb_only, ssl_termin_gorouter_lb) and no page reads them; overview names its partial directly after a comment that mentions the variable (L216-L217). The partials round owns this case (R-05 partials and reuse).

What the values hold

The 273 keys. Text 73, HTML 60, Markdown 56, HTML and Markdown 15, a path or partial name 14, a URL 4, empty 51.

Used and unused. Pages use 156 keys; 117 keys are used by no page (29 text, 27 HTML, 20 empty, 16 Markdown, 13 paths, 10 HTML and Markdown, 2 URLs). Some of those are read by the layouts (below).

Product names. 1,060 of the 1,503 uses (71%) read a variable whose value is the product’s name, “Cloud Foundry”, “CF” or “cf”: app_runtime_abbr 809, platform_name 87, app_runtime_first 64, company_name 28, recommended_by 20, app_runtime_abbr_lc 19, app_runtime_full 16, product_short 9, and four more. They cover every heading use and every link-text use. 174 more read an example domain (app_domain 124, private_app_domain 36, tcp_app_domain 14). The variables exist so that other books could build the same pages with other values: a comment in overview says “For private/commercial books, the partial and image files come from a private repository” (L210-L213). Whether any other book still builds from these repositories was not found in them.

Variables used but not defined, or empty

Not defined: 28 names, 38 uses. The tables round found metadata_ref and bosh_cli_link; both are confirmed, with 26 more: GSG_intro_sentence (4 uses), bosh_cli_link (4), configure_system_logging_link (3), mutual_tls_ssh (3), and one use each of app_graceful_shutdown_config, app_man_network, app_svc_links, app_traffic_logging, asg_note, autoscaler_note_dev_guide, best_practices_link, capi_link, cli_install_link, compliance_links, custom_metrics_footnote, dns_warning, docker_auth1, domains_on_hosted, external_lb, garden_runc, gather_routing_logs, gsg_app_video_link, metadata_ref, ops_manager, pcf_pools, ssl_cert_ert, tiledev_link, vm_note.

Empty: 31 keys, 44 uses, for example dev_console_note (4 uses), gen_GSG (4), ssl (1); all in text. Both kinds render as nothing on the published pages: app-ssh-overview uses mutual_tls_ssh between two paragraphs, and the published page has nothing there (published copy, lines 528-531). The build reports neither.

Values that hold markup, and where they are used

ERB prints a value before Redcarpet reads the page, so a value’s HTML is markup and its Markdown is read as Markdown, as if the page held it. Two exceptions follow from Markdown’s rules, not from the variables:

HTML values are used inline more often than as blocks: of the 49 uses of an HTML value, 28 sit inside a sentence (… (one-time). <%= vars.config_ssh_link %>), 6 are inline values alone on a line, and 15 are block values (notes, lists, headings) alone on a line.

Variables the layouts read

Variables also fill the site’s frame, not only pages:

These are site settings, not page content: they belong in each tool’s site configuration or template.

Other expressions and other variable sources

How to rerun

Run from a working directory outside this repository, with python3 -I. SURVEY stands for this folder, concepts/variables/survey. Each repository is fetched at its commit, without history:

mkdir -p repos
git init -q repos/docs-bbr
git -C repos/docs-bbr fetch -q --depth 1 https://github.com/cloudfoundry/docs-bbr.git 51465950ce3a2196d66a9339086b94feed280c3e
git -C repos/docs-bbr checkout -q FETCH_HEAD
# … the same three lines for each repository in SURVEY/shas.txt

python3 -I SURVEY/survey.py repos SURVEY/shas.txt uses.csv values.csv
cmp uses.csv SURVEY/uses.csv && cmp values.csv SURVEY/values.csv
python3 -I SURVEY/summary.py SURVEY/uses.csv SURVEY/values.csv

survey.py prints the totals per kind; summary.py prints every count on this page. The scripts read files only; they run nothing from the clones. To compare the YAML reading with a YAML library, load repos/docs-book-cloudfoundry/config/template_variables.yml with PyYAML (yaml.safe_load) and survey.py’s parse_variables function, and compare the two mappings key by key; on 2026-10-11 they matched for all 273 keys.