Plain wording on the merge tag pages

- The reference intro says what the page lists and where its outputs come from,
  without dashes or "verified ... not invented".
- Headings: "Merge tags" in sentence case; "Merge tag {x}" and "Modifier :x" with
  the tag in code, instead of "Modifier: :value".
- "Solid value" becomes "Same for every entry"; "Canonical output" becomes "Example
  output".
- Field-kind lists end with ", and", and the examples line reads "Output from the real
  plugin code, run against a test entry."

Author: zackkatz

src/components/merge-tags/ModifierPage.jsx

@@ -2,12 +2,18 @@ import Layout from '@theme/Layout';
 import { MergeTagsNav, PRODUCT_NAMES, SECTIONS, requiresText, sectionOf } from './shared';
 import Examples, { UsageExample } from './Examples';
 
+/** "a and b", "a, b, and c" */
+function listText(items) {
+  if (items.length < 3) return items.join(' and ');
+  return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+
 function appliesToText(modifier, fieldTypeNames = {}) {
   const tags = modifier.applies_to?.tags;
   const types = modifier.applies_to?.field_types;
-  const tagText = Array.isArray(tags) ? tags.map((t) => (t === '*field*' ? 'form fields' : `{${t}}`)).join(', ') : 'any merge tag';
+  const tagText = Array.isArray(tags) ? listText(tags.map((t) => (t === '*field*' ? 'form fields' : `{${t}}`))) : 'any merge tag';
   if (!Array.isArray(types)) return tagText;
-  const typeText = types.map((t) => fieldTypeNames[t] || t).join(', ');
+  const typeText = listText(types.map((t) => fieldTypeNames[t] || t));
   return tagText === 'form fields' ? `${typeText} fields` : `${tagText} (${typeText})`;
 }
 
@@ -46,7 +52,7 @@ function Entry({ entry, index, many, reasons, fieldTypeNames }) {
           {modifier.exclusive && (
             <tr>
               <th scope="row">Combining</th>
-              <td>Only works on its own: with any other modifier, it is ignored.</td>
+              <td>Use it alone. Combined with any other modifier, it is ignored.</td>
             </tr>
           )}
         </tbody>
@@ -64,7 +70,7 @@ function Entry({ entry, index, many, reasons, fieldTypeNames }) {
       {examples.length > 0 && (
         <>
           <h3>Examples</h3>
-          <p>Rendered by real Gravity Forms and GravityKit PHP against a test entry.</p>
+          <p>Output from the real plugin code, run against a test entry.</p>
           <Examples examples={examples} />
         </>
       )}
@@ -143,12 +149,14 @@ export default function ModifierPage({ data }) {
         <MergeTagsNav current="modifier" />
         <article className="theme-doc-markdown markdown">
           <header>
-            <h1>Modifier: :{name}</h1>
+            <h1>
+              Modifier <code>:{name}</code>
+            </h1>
           </header>
           {many ? (
             <>
               <p>
-                <code>:{name}</code> means different things depending on the merge tag or the kind of field:
+                <code>:{name}</code> does different things depending on the merge tag or the kind of field:
               </p>
               <ul>
                 {entries.map((entry, index) => (

src/components/merge-tags/TagPage.jsx

@@ -22,7 +22,9 @@ export default function TagPage({ data }) {
         <MergeTagsNav current="tag" />
         <article className="theme-doc-markdown markdown">
           <header>
-            <h1>Merge tag: {tag.syntax}</h1>
+            <h1>
+              Merge tag <code>{tag.syntax}</code>
+            </h1>
           </header>
           <p>
             <strong>{tag.label}.</strong> {tag.description}
@@ -42,7 +44,7 @@ export default function TagPage({ data }) {
               )}
               <tr>
                 <th scope="row">Needs an entry</th>
-                <td>{tag.entry_dependent ? 'Yes: its value comes from a form entry' : 'No'}</td>
+                <td>{tag.entry_dependent ? 'Yes. Its value comes from a form entry.' : 'No'}</td>
               </tr>
             </tbody>
           </table>
@@ -156,7 +158,7 @@ export default function TagPage({ data }) {
           {(plain.length > 0 || withModifier.length > 0) && (
             <>
               <h2 id="examples">Examples</h2>
-              <p>Rendered by real Gravity Forms and GravityKit PHP against a test entry.</p>
+              <p>Output from the real plugin code, run against a test entry.</p>
               {plain.length > 0 && <Examples examples={plain} showBefore={false} />}
               {withModifier.length > 0 && (
                 <>
@@ -169,7 +171,7 @@ export default function TagPage({ data }) {
 
           {isField && (
             <p>
-              Each modifier's own page has examples on real fields: see <a href="/merge-tags/fields/">Modifiers by field</a>.
+              For examples on each kind of field, open a modifier from <a href="/merge-tags/fields/">Modifiers by field</a>.
             </p>
           )}
         </article>

src/pages/merge-tags.jsx

@@ -75,8 +75,8 @@ const HAZARD_REPARSES_INPUT_ORDER = 'reparses-input-order';
 const HAZARD_ANNOTATIONS = {
   [HAZARD_REPARSES_INPUT_ORDER]:
     'This modifier re-reads the text the earlier steps produced and interprets it as a date. ' +
-    'Because an earlier step already reshaped that text, the result is silently wrong — often ' +
-    "today's date instead of the field's. Put the re-parsing modifier first so it reads the field's own value.",
+    'Because an earlier step already changed that text, the result is wrong with no warning, often ' +
+    "today's date instead of the field's. Put this modifier first so it reads the field's own value.",
 };
 
 function hazardAnnotation(hazard) {
@@ -116,12 +116,12 @@ function entryDependenceBadge(row) {
   if (row.type === 'tag') {
     return tagEntryDependent(row.entry)
       ? { text: 'Varies by entry', tone: 'entryVaries' }
-      : { text: 'Solid value', tone: 'entrySolid' };
+      : { text: 'Same for every entry', tone: 'entrySolid' };
   }
   if (!hasEntryDependenceOverride(row.entry)) return null;
   return row.entry.entry_dependent === false
-    ? { text: 'Forces a solid value', tone: 'entrySolid' }
-    : { text: 'Forces varying by entry', tone: 'entryVaries' };
+    ? { text: 'Makes it the same for every entry', tone: 'entrySolid' }
+    : { text: 'Makes it vary by entry', tone: 'entryVaries' };
 }
 
 /**
@@ -326,7 +326,7 @@ function CaptureOutput({ out }) {
   return (
     <details>
       <summary style={{ cursor: 'pointer', color: 'var(--ifm-color-emphasis-600)' }}>
-        {out.length.toLocaleString()} characters &mdash; expand to view
+        {out.length.toLocaleString()} characters. Expand to view.
       </summary>
       <pre style={{ maxHeight: 320, overflow: 'auto', background: 'var(--ifm-color-emphasis-100)', padding: 8, borderRadius: 4 }}>
         <code>{out}</code>
@@ -432,7 +432,7 @@ function TagRow({ entry, catalog, expanded, onToggle }) {
             <p style={{ fontSize: 12, color: 'var(--ifm-color-emphasis-600)' }}>
               {entryDependence?.tone === 'entryVaries'
                 ? 'Changes depending on which entry is being viewed.'
-                : "Renders the same value no matter which entry is selected — a solid value, not read from the entry."}
+                : 'Shows the same value whichever entry is selected. It is not read from the entry.'}
             </p>
             <CapturePair capture={canonical} />
             {entry.requires ? (
@@ -488,9 +488,9 @@ function ModifierRow({ entry, catalog, expanded, onToggle }) {
                 cross-entry total. */}
             {entryDependence ? (
               <p style={{ fontSize: 12, color: 'var(--ifm-color-emphasis-600)' }}>
-                <strong>{entryDependence.text}:</strong> the field this modifies normally changes per entry, but this
-                modifier computes a total, count, or average across every entry in scope — not this one — so the
-                result is the same no matter which entry is selected.
+                <strong>{entryDependence.text}:</strong> the field normally changes from entry to entry, but this
+                modifier adds up, counts, or averages every entry in scope, so the result is the same whichever
+                entry is selected.
               </p>
             ) : null}
             {captures.length ? captures.map((c) => <CapturePair key={c.in} capture={c} />) : <CapturePair capture={null} />}
@@ -623,9 +623,9 @@ function MergeTagTable({ catalog }) {
           title="Whether a tag's rendered value changes depending on which entry is being viewed"
           style={{ padding: '6px 10px', borderRadius: 6 }}
         >
-          <option value="all">Varies or solid</option>
+          <option value="all">Varies or not</option>
           <option value="varies">Varies by entry</option>
-          <option value="solid">Solid value</option>
+          <option value="solid">Same for every entry</option>
         </select>
         <span style={{ color: 'var(--ifm-color-emphasis-600)', fontSize: 14 }}>
           {filtered.length} entries &middot; {catalog.captures?.count ?? 0} captured renders
@@ -641,7 +641,7 @@ function MergeTagTable({ catalog }) {
               <th style={{ width: '120px' }}>Kind / group</th>
               <th style={{ width: '180px' }}>Scope</th>
               <th>Label</th>
-              <th>Canonical output</th>
+              <th>Example output</th>
             </tr>
           </thead>
           <tbody>
@@ -673,22 +673,21 @@ export default function MergeTagsPage() {
 
   return (
     <Layout
-      title="GravityKit Merge Tags"
+      title="GravityKit merge tags"
       description="Every merge tag and modifier across GravityKit and the products it extends, with real rendered examples."
     >
       <main className="container margin-vert--lg">
         <MergeTagsNav current="all" />
-        <h1>Merge Tags</h1>
+        <h1>Merge tags</h1>
         <p>
-          Every merge tag GravityKit and the products it extends can resolve, every modifier each one accepts, and a
-          real captured render for each &mdash; verified against actual PHP on a frozen fixture, not invented.
-          Search, or filter by product and kind. This table is generated from the same schema the merge tag picker
-          in wp-admin uses, so it never drifts from what the picker offers.
+          Every merge tag that Gravity Forms and GravityKit products understand, the modifiers each one takes, and
+          the output each one gives. The outputs come from running the real plugin code against a test entry.
+          Search, or filter by product and kind. The list is built from the same data as the merge tag picker in
+          WordPress, so the two always match.
         </p>
         <p>
-          Want to try a tag against your own data? The merge tag picker in wp-admin renders live, against your
-          site's real entries &mdash; this page can't do that (there's no site behind it), so it documents instead
-          of guessing.
+          To see a tag's output for your own entries, use the merge tag picker in WordPress. It shows each tag's
+          value from your site as you build.
         </p>
 
         <MergeTagTable catalog={catalog} />

src/pages/merge-tags/compare.jsx

@@ -100,7 +100,7 @@ export default function MergeTagComparePage() {
                             const item = byName.get(column.name);
                             const modifier = item && byId.get(item.id);
                             const locked = item?.locked;
-                            const title = modifier ? `${modifier.label} (${requiresText(modifier.requires)})${locked ? ` — locked: ${locked}` : ''}` : undefined;
+                            const title = modifier ? `${modifier.label} (${requiresText(modifier.requires)})${locked ? `. Locked: ${locked}` : ''}` : undefined;
                             return (
                               <td key={column.name} title={title} className={item ? styles[`cell_${column.section}`] : undefined}>
                                 {item ? (locked ? '○' : '●') : ''}

src/pages/merge-tags/fields.jsx

@@ -174,7 +174,7 @@ export default function MergeTagFieldsPage() {
   };
 
   return (
-    <Layout title="Modifiers by field" description="What the merge tag picker offers for each kind of Gravity Forms field, and why the rest is left out.">
+    <Layout title="Modifiers by field" description="What the merge tag picker offers for each kind of Gravity Forms field, and why it leaves out the rest.">
       <main className="container margin-vert--lg">
         <MergeTagsNav current="fields" />
         <h1>Modifiers by field</h1>