WIP: issue-113 Allowed to xref within a module? #162
Conversation
emmurphy1
changed the title
There was a problem hiding this comment.
Glad to see tooling-related limitations be excluded from mod docs content. Thanks @emmurphy1 Approving pre-emptively since we discussed on the call.
|
/lgtm |
| @@ -34,7 +34,6 @@ The contents of a concept module give the user descriptions and explanations nee | |||
| //// | |||
| Optional. Delete if not used. | |||
| //// | |||
| * A bulleted list of links to other material closely related to the contents of the concept module. | |||
| * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module. | |||
| * A bulleted list of links or xrefs to other material closely related to the contents of the concept module. | |||
There was a problem hiding this comment.
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 :)
There was a problem hiding this comment.
FWIW, I prefer the specific inclusion of xref. URLs (using the link macro[1]), to content such as a KCS, were not forbidden. An xref to another file within the same repo was forbidden. There's a suggestion to prefer the xref macro to add a link to a relative AsciiDoc file[2].
[1] https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/
[2] Same as above, but scroll to the TIP under the "Link to a relative file" heading.
There was a problem hiding this comment.
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."
There was a problem hiding this comment.
With Preeti and Robert's thumbs up, I'll suggest a change to this line in the docs.
| @@ -34,7 +34,6 @@ The contents of a concept module give the user descriptions and explanations nee | |||
| //// | |||
| Optional. Delete if not used. | |||
| //// | |||
| * A bulleted list of links to other material closely related to the contents of the concept module. | |||
| * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module. | |||
| * A bulleted list of links or xrefs to other material closely related to the contents of the concept module. | |||
There was a problem hiding this comment.
With Preeti and Robert's thumbs up, I'll suggest a change to this line in the docs.
| @@ -34,7 +34,6 @@ The contents of a concept module give the user descriptions and explanations nee | |||
| //// | |||
| Optional. Delete if not used. | |||
| //// | |||
| * A bulleted list of links to other material closely related to the contents of the concept module. | |||
| * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module. | |||
| * A bulleted list of links or xrefs to other material closely related to the contents of the concept module. | |||
There was a problem hiding this comment.
| * A bulleted list of links or xrefs to other material closely related to the contents of the concept module. | |
| * A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. |
There was a problem hiding this comment.
I'm good with Rolfe's suggestion: https://github.com/redhat-documentation/modular-docs/pull/162/files#r608566774
|
Thanks folks. I've made the change that Rolfe suggested and I'll merge now. |
There are no long any issues with including xrefs in modules. There are some pantheon 2 syntax requirements, but these belong in the PV2 User Guide.