Skip to content

Doc fixes for lang_relationships (8.x): grammar, dead links, metaparameter-note scoping, lint #331

@miharp

Description

@miharp

Summary

While reviewing docs/_openvox_8x/lang_relationships.markdown (served at /openvox/8.x/lang_relationships.html), a few correctness, link, and consistency issues turned up. All internal cross-references and in-page anchors resolve correctly; the items below are the remaining fixes.

Items

Correctness

  • Grammar (subject/verb agreement) — around line 279: "it skips the subsequent resource and log the following messages" should read "and logs".

External links

  • Dead link — around line 290: http://projects.puppetlabs.com/issues/7486. The old Redmine tracker was decommissioned years ago (connection refused). The referenced design issue would now live in Puppet's Jira-style tracker, if it still exists. Update or drop the link.
  • Likely-stale link — around line 182: https://tickets.puppetlabs.com/browse/PUP-1410. Worth confirming this still resolves; if not, repoint or remove.

Add a best-practices note (relationship metaparameters vs. chaining arrows)

Add a Note to the "Syntax: Chaining arrows" section recommending relationship metaparameters over chaining arrows as a best practice. This mirrors the equivalent note in the upstream Puppet doc (Chaining arrows), which reads: "When possible, use relationship metaparameters, not chaining arrows. Metaparameters are more explicit and easier to maintain."

Placement: immediately after the ->/~> operator descriptions, before the ### Operands subheading.

Proposed wording (scoped to resources — see the caveat below):

Note: When possible, use relationship metaparameters rather than chaining arrows to order individual resources. Metaparameters are more explicit and easier to maintain.

Important caveat — scope the note to individual resources. Do not phrase it as a blanket "avoid chaining arrows." Chaining arrows (and the require function) remain the correct tool for ordering whole classes and collectors, which cannot be expressed with metaparameters. This same file already chains classes around line 216 (Class['site::certificates'] ~> Class['apache::ssl']), and bgtm.md's containment example chains contained classes — both legitimate uses the note must not appear to contradict.

Markdownlint (advisory)

  • Around lines 281 and 296: fenced code blocks with no language specified (MD040). These are log/error output, so ```text is appropriate.
  • Around line 302: file does not end with a single trailing newline (MD047).

Terminology (observation, lower priority)

  • The page uses "Puppet applies resources / Puppet logs…" to describe runtime behavior, where the project terminology guide prefers "OpenVox" (reserving "Puppet" for the language/DSL). This is inherited upstream text; flagging in case a consistency pass is wanted, but it's an editorial call rather than a defect.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions