WIP: issue-113 Allowed to xref within a module? by emmurphy1 · Pull Request #162 · redhat-documentation/modular-docs (original) (raw)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this necessary? Xrefs are just another kind of a link. As we're not calling out the specific AsciiDoc macros (link:) -- we're just talking about links -- then I see no point in adding "xrefs".

(Same for the other two templates.)

Not to mention that using "xrefs" as a word is really jargony :)

I think mentioning cross-references is helpful. Otherwise, some writers might interpret the phrase as excluding the xref: macro and continuing "the ban on xrefs."

To help folks who aren't familiar with xrefs, we could apply the proposed change, "...bulleted list of links to other material closely," and append something like "These links can include link: and xref: macros."