Add sentence to avoid references in titles

[tomschr]

Problem

Although we have a section about Cross references, the section doesn't tell you NOT to include <xref/>s into titles.

It says:

Do not create references to paragraphs (<para/>) or other elements that have no title.

This is the structure you should avoid:

<title><xref linkend="..."/></title>

Cross references in titles has some issues:

• The title should not be clickable.
• It mostly looks bad
• It can create other issues when linking to such a title in a different paragraph.
• The stylesheets currently don't support it (Toms doesn't like it. 😉 )

Proposal

The section should be amended with another sentence:

Do not insert cross references (<xref/>) into a <title> element.

Maybe even restructure all the "Do not" sentences into a list to make it easier to absorb.

[dariavladykina]

By 'amended with another sentence', you mean adding another 'don't', right? :-)

So the section would look like this?

---

Use the <xref/> element (read: “cross ref”) when referring to an appendix, chapter, example, figure, part, preface, section, table, or question and answer set. The element referenced needs to have an xml:id attribute.

Do not insert cross references (<xref linkend="..."/>) into a <title> element. The title should not be clickable, and a cross reference in a title can create issues when linking to such a title in a different paragraph.

Do not prefix or suffix cross references with text labels such as “appendix,” “chapter,” “table,” or “figure.” Such labels are generated automatically.

Do not create references to paragraphs (<para/>) or other elements that have no title. An exception to this rule is the element <step/> to which you may create references. If a reference to an element without a title is vital to the document, use the attribute xreflabel to assign a title.

---

toms: Added better visual distinction, add missing backticks to display element names

[tomschr]

By 'amended with another sentence', you mean adding another 'don't', right? :-)

Yes. :-)

So the section would look like this?

Looks good from the wording. The only thing that I don't like is the mix of "use this" and "don't do this". After looking at section "7.5 Cross references" again, I think we need to rearrange the paragraphs a bit. For example, the important sentence about the identifiers comes too late in my humble opinion.

My suggestion would be to describe what you need first and how to use xrefs. Collect everything what you need to know to create a good xref. Maybe add the example. After you described this usage part, then, and only then, give the recommendations what you need to avoid.

So my suggestion would be to start with:

Use the <xref/> element (read: “cross ref”) when referring to an appendix, chapter, example, figure, part, preface, section, table, or question and answer set.
The element referenced needs to have an xml:id attribute, an identifier.

That paragraph didn't change much (just added for clarification "an identifier" at the end). Then move this paragraph (before the example) and change the order of the two sentences:

Create identifiers to reference from cross references using the rules under Section 7.12, “Identifiers”.
Other types of references to resources are described in Section 7.19, “References to other external resources” and Section 7.8, “External links”.

and add it to the first paragraph. This makes sure all the "do this" parts are together.

Continue to show the two examples. After the examples, I would collect all the "don't do this". For better readability, I would present them in a list. Probably you have to introduce them with a sentence like:

Avoid the following situations as they are discouraged and cause problems:

* Don't ...
* Don't ...

Does that make sense?

[dariavladykina]

Thanks very much! I'll create the PR to implement your recommendations.

[dariavladykina]

Closing this issue as the content has been entered into DSG.