The design of `<href>` and `<xref>` is inconveient

[slon-aby]

Being as clickable hyperlink is a kind of formatting attribute similar to italic or underline, but with additional data (hyperlink target). And it is intermixed with other formatting.

Currently in DocLang references are part of a content element header and cannot be mixed with other formatting.
Suppose we have an italic line of text with hyperlink:

Find details at https://disney.com.

The natural way to represent would be

<text><italic>Find details at <href uri="https://disney.com">disney.com</href>.</italic></text>

But DocLang requires <href> to be in a head of a content element. Well, let's add a nested <text>

<text><italic>Find details at <text><href uri="https://disney.com"/>disney.com</text>.</italic></text>

It is still reasonable despite being a bit longer.
But DocLang still rejects is as <text> cannot be inside <italic>. We are forced to split one italic span into three to be conformant:

<text><italic><content>Find details at </content></italic><text><href uri="https://disney.com"/><italic>disney.com</italic></text><italic>.</italic></text>

This variant:

• Is much longer.
• Requires <content> to preserve boundary space.
• Does nor preserve original semantics as a single italic span is broken in three just due to DocLang limitations. There are no italic boundaries in the original text.

With <rtl> situation is much worse as it cannot bs split. if A, B, C, D, E, F are some characters of RTL bidi category, <rtl>ABCDEF</rtl> will result in a visual-order string FEDCBA, while <rtl>ABC</rtl><rtl>DEF</rtl> will give CBAFED.

[code2tan]

I think this issue exposes a deeper modeling question: should <href> and <xref> remain properties of an entire semantic component, or should they represent content ranges?

The current model works well for component-level references, for example making an entire <picture> clickable:

<picture>
  <href uri="https://example.com"/>
  <src uri="image.jpg"/>
</picture>

However, it does not compose naturally with inline formatting. A hyperlink or cross-reference is often a span over part of the text, just like italic, bold, or underline, but with an associated target. Treating it exclusively as an element-head property forces authors to introduce nested semantic elements and, in some cases, split an otherwise continuous formatting span.

For <rtl>, splitting is not merely verbose: it may change the effective bidirectional ordering, so the current workaround can lose the semantics of the source document.

I see two possible directions.

1. Add a backward-compatible inline wrapper

We could keep the existing component-head <href/> and <xref/> model and add a restricted inline element, for example:

<text>
  <italic>
    Find details at
    <span><href uri="https://disney.com"/>disney.com</span>.
  </italic>
</text>

The new <span> would:

• be allowed in raw-text and formatting contexts;
• accept exactly one <href> or <xref> at its head;
• contain only text, <content>, and inline formatting;
• not contain block-level semantic elements such as <picture>, <table>, or <list>;
• not allow nested reference spans.

This would solve the immediate problem without invalidating existing documents. The downside is that the syntax remains more verbose than the natural content-wrapping form.

2. Redesign <href> and <xref> as content-bearing elements

A cleaner long-term model would be:

<text>
  <italic>
    Find details at
    <href uri="https://disney.com">disney.com</href>.
  </italic>
</text>

and:

<text>
  See <xref thread_id="1">Figure 3</xref>.
</text>

This directly represents the referenced content range and composes naturally with <italic>, <bold>, <rtl>, and other inline elements.

However, we should not simply make <href> and <xref> content-bearing while also leaving them unchanged in the optional element head. At the beginning of a semantic element, an <href> could then be interpreted either as the component-head property or as the first inline body element. Besides the semantic ambiguity, this is likely to create an ambiguous XSD content model under the Unique Particle Attribution rule.

Therefore, the clean version of this design would probably require removing <href> and <xref> from element_head and introducing a separate, explicit mechanism for component-level references. Possible options include:

• a differently named component-head property;
• a reference wrapper that can contain a complete semantic component;
• or deciding that a referenced non-text component is itself wrapped by <href>/<xref>.

That would be a breaking format change affecting existing documents, validators, parsers, generators, and viewers.

Question for the maintainers

Since DocLang is still pre-1.0, should we use this opportunity to make the reference model structurally clean, even though it requires migration?

My preference would be:

• choose the content-bearing <href>/<xref> design if a format-version transition is acceptable and we can first define an equally clear replacement for component-level references;
• otherwise, add a restricted inline <span> now as a backward-compatible solution.

Before implementing either option, I think we should explicitly answer these questions:

1. Is attaching a reference to an entire non-text component, such as <picture>, a required first-class use case?
2. Should a reference identify a content range, a semantic component, or intentionally support both?
3. If both are supported, should they use distinct syntax so that their meaning and XSD grammar remain unambiguous?
4. Are nested references invalid?
5. Should an inline reference be allowed to contain only formatting and text, or arbitrary semantic elements?

Once those semantics are agreed upon, the XSD and Schematron changes should be relatively straightforward. The important decision is whether we want a compatibility-preserving extension or a cleaner reference model for the next format version.