Fix glossterm macro usage #1569
Conversation
👷 Deploy Preview for redpanda-docs-preview processing.
|
📝 WalkthroughWalkthroughThe pull request updates AsciiDoc glossterm markup syntax in the Linux bootstrap documentation file. Three glossterm references for Kafka broker configuration are modified: correcting the syntax for listener references, seed server references, and standardizing advertised listener notation. The surrounding documentation content and examples remain unchanged. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@modules/deploy/partials/linux/bootstrap.adoc`:
- Line 4: Update the three glossterm macro usages on the line to remove the
comma between the term and the optional display text: change
glossterm:listener[,listeners] to glossterm:listener[listeners], glossterm:seed
server[,seed servers] to glossterm:seed server[seed servers], and
glossterm:advertised listener[,advertised listeners] to glossterm:advertised
listener[advertised listeners] so they follow the correct
glossterm:<term>[<display>] syntax.
| = Bootstrap broker configurations | ||
|
|
||
| Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the glossterm:listener[listeners], glossterm:seed-server[,seed servers], and glossterm:advertised listener[,advertised listeners], which ensure proper network connectivity and accessibility. | ||
| Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the glossterm:listener[,listeners], glossterm:seed server[,seed servers], and glossterm:advertised listener[,advertised listeners], which ensure proper network connectivity and accessibility. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Find glossary-related files and check for term definitions
find . -type f \( -name "*glossary*" -o -name "*terms*" \) | head -20Repository: redpanda-data/docs
Length of output: 101
🏁 Script executed:
# Search for glossterm macro usage and glossary definitions
rg -n 'glossterm:' --type=asciidoc | head -30Repository: redpanda-data/docs
Length of output: 9401
🏁 Script executed:
# Look for glossary definition patterns (likely using [[...]] or similar)
rg -n '\[\[.*\]\]' --type=asciidoc | grep -E '(listener|seed|advertised)' | head -20Repository: redpanda-data/docs
Length of output: 143
🌐 Web query:
AsciiDoc glossterm macro syntax comma notation
💡 Result:
In AsciiDoc / Asciidoctor, the glossterm macro is written using the inline macro “target + attribute list” form:
- Syntax:
glossterm:<term>[<definition>] - Example:
glossterm:my term[myDefinition](definition is optional in some implementations) [1], [2]
So the “comma notation” (i.e., macro:[a, b, c]) is not part of glossterm’s syntax; commas are generally used to separate multiple positional attributes in an attribute list for macros that define more than one positional attribute (e.g., indexterm:[primary, secondary, tertiary]) [3]. By contrast, glossterm takes the term as the target (after :) and (optionally) the definition as the first positional attribute (inside []) [1], [2].
If you’re thinking of commas because you saw them used inside other macros (e.g., kbd:[Ctrl,T]), that’s a macro-specific shorthand for that macro, not a general rule that applies to glossterm [4].
Sources: [1] (Redpanda docs-extensions-and-macros README: glossterm usage), [2] (antora-extensions-and-macros package docs: glossterm usage), [3] (Asciidoctor user manual: indexterm comma-separated positional attributes), [4] (Asciidoctor keyboard macro: comma-separated keys).
🌐 Web query:
AsciiDoc glossterm macro correct syntax example
💡 Result:
glossterm is not a built-in AsciiDoc/Asciidoctor macro; it’s provided by glossary extensions (e.g., antora-extensions-and-macros / redpanda-data docs-extensions-and-macros). In those extensions, the inline macro syntax is:
glossterm:my term[myDefinition]- target: the term (
my term) - attribute list / positional: the definition (
myDefinition, often optional if defined elsewhere) [1][2]
Minimal working example (with the matching glossary block macro used by the same extensions):
A glossterm:broker[A server that stores and serves messages] is part of the system.
glossary::[]This collects glossterm definitions and renders them as a glossary/definition list when glossary::[] is placed later in the document [3].
Sources: [1] [2] [3]
🏁 Script executed:
# Get the glossary file and search for the terms in question
cat modules/reference/pages/glossary.adoc | head -100Repository: redpanda-data/docs
Length of output: 267
🏁 Script executed:
# Search for the specific term definitions
rg -n -A3 '(listener|seed|advertised)' modules/reference/pages/glossary.adoc | head -50Repository: redpanda-data/docs
Length of output: 44
🏁 Script executed:
# Search for how terms are defined in the glossary file (look for patterns like [[term]] or similar)
rg -n '^\[\[' modules/reference/pages/glossary.adoc | head -20Repository: redpanda-data/docs
Length of output: 44
🏁 Script executed:
# Check glossary file size and structure
wc -l modules/reference/pages/glossary.adocRepository: redpanda-data/docs
Length of output: 102
🏁 Script executed:
# Get the full glossary file
cat modules/reference/pages/glossary.adocRepository: redpanda-data/docs
Length of output: 267
🏁 Script executed:
# Search for all term ID patterns in glossary
rg -n '\[\[' modules/reference/pages/glossary.adocRepository: redpanda-data/docs
Length of output: 44
🏁 Script executed:
# Look for inline macro definitions or term patterns
rg -n 'term::|::' modules/reference/pages/glossary.adoc | head -20Repository: redpanda-data/docs
Length of output: 44
🏁 Script executed:
# Search for glossary or glossterm extension configuration
find . -type f \( -name "*.js" -o -name "*.json" -o -name "*.yml" -o -name "*.yaml" \) | xargs grep -l "glossterm\|glossary" 2>/dev/null | head -10Repository: redpanda-data/docs
Length of output: 255
🏁 Script executed:
# Look for where term definitions might be stored
rg -n 'listener::|listener:' --type=asciidoc | grep -v glossterm | head -20Repository: redpanda-data/docs
Length of output: 2141
🏁 Script executed:
# Search for antora or extension related files that might define glossterm macro behavior
find . -type f -name "*.js" -o -name "*.json" | xargs grep -l "glossterm" 2>/dev/nullRepository: redpanda-data/docs
Length of output: 227
🏁 Script executed:
# Check if there's a docs configuration that shows how glossterm works
find . -type f \( -name "antora.yml" -o -name "package.json" \) | head -5Repository: redpanda-data/docs
Length of output: 89
🏁 Script executed:
# Check antora.yml for glossterm extension configuration
cat ./antora.ymlRepository: redpanda-data/docs
Length of output: 5750
🏁 Script executed:
# Check package.json for dependencies related to glossterm or macro extensions
cat ./package.jsonRepository: redpanda-data/docs
Length of output: 1321
🏁 Script executed:
# Search for any documentation about the glossterm macro in the repo
rg -n 'glossterm' --type=asciidoc modules/ROOT/pages/ | head -20Repository: redpanda-data/docs
Length of output: 121
🏁 Script executed:
# Check if there's a custom extension directory
find . -type d -name "extensions" -o -name "*macro*" 2>/dev/nullRepository: redpanda-data/docs
Length of output: 44
🏁 Script executed:
# Search for documentation about the docs-extensions-and-macros in the repo
rg -n 'docs-extensions-and-macros' --type=adoc --type=md | head -10Repository: redpanda-data/docs
Length of output: 90
🏁 Script executed:
# Look for any README or documentation about the extension
find . -type f \( -name "README*" -o -name "*.md" \) | xargs grep -l "glossterm\|docs-extensions" 2>/dev/nullRepository: redpanda-data/docs
Length of output: 46
🏁 Script executed:
# Check if there's a local extensions folder
find . -type d -name "extensions" -o -type d -name "*extension*" 2>/dev/null | head -10Repository: redpanda-data/docs
Length of output: 44
🌐 Web query:
@redpanda-data/docs-extensions-and-macros glossterm syntax documentation
💡 Result:
In @redpanda-data/docs-extensions-and-macros, the glossterm macro is an inline AsciiDoc macro with this syntax:
- Define/reference a term (with optional definition):
glossterm:<term>[<definition>]- Example:
glossterm:my term[myDefinition]
- Parameters:
term(required)definition(optional) — can be omitted if the term is already defined in thesharedcomponent or inlocal-termsinantora.yml. (github.com)
Related attributes (configuration options):
glossary-log-termsglossary-term-role(default role isglossary-term)glossary-links(set tofalseto disable links)glossary-page(resource ID of the page that contains the glossary)glossary-tooltip(title,true, ordata-<attribute-name>) (github.com)
Citations:
- 1: https://github.com/redpanda-data/docs-extensions-and-macros?utm_source=openai
- 2: https://github.com/redpanda-data/docs-extensions-and-macros?utm_source=openai
Remove the comma from glossterm macro syntax.
The glossterm macros use incorrect syntax with a comma separator: glossterm:<term>[,<display>]. Per the @redpanda-data/docs-extensions-and-macros documentation, the correct syntax is glossterm:<term>[<display>] without the comma. Update the three glossterm calls on this line to remove the leading comma:
glossterm:listener[listeners]glossterm:seed server[seed servers]glossterm:advertised listener[advertised listeners]
🤖 Prompt for AI Agents
In `@modules/deploy/partials/linux/bootstrap.adoc` at line 4, Update the three
glossterm macro usages on the line to remove the comma between the term and the
optional display text: change glossterm:listener[,listeners] to
glossterm:listener[listeners], glossterm:seed server[,seed servers] to
glossterm:seed server[seed servers], and glossterm:advertised
listener[,advertised listeners] to glossterm:advertised listener[advertised
listeners] so they follow the correct glossterm:<term>[<display>] syntax.
1 participant
Description
Fix incorrect gloss term macros found by testing new CC skill: https://github.com/redpanda-data/docs-team-standards/pull/2843
Resolves https://redpandadata.atlassian.net/browse/
Review deadline:
Page previews
Checks