MEP-0016

In Mallard, unlike most other formats, linking is limited to pages and sections. This is due in part to the complexity of the automatic linking features in Mallard, and the need for rich metadata for elements acting as link targets.

Many writers want to link to block elements, particularly figures and listings, and have to resort to extra sections to link close to them. Additionally, writers often want to link to items in a terms element.

This page proposes allowing inline links to various block and block-like elements. This is only a proposal for inline links using the xref attribute either on the inline link element or on any other inline element.

This is not a proposal to allow any sort of automatic linking with informational link elements. That would be a far more significant change. However, all of the changes outlined in this proposal would be necessary for that change as well, so this can be taken as a first step in fully linkable blocks.

This would affect all formal block elements that can optionally take title and info elements: comment, div, example, figure, list, listing, note, quote, steps, synopsis, table, terms, and tree. Additionally, this would affect item elements in terms elements only, but not item elements in other list elements. Terms list items require at least one title element, but do not currently allow an info element. Furthermore, we can consider linking to table rows. These do not accept either title or info elements, but th elements could serve as link titles.

All linkable block elements would need to take an optional id attribute. This would share the same ID space as sections. For background, currently page IDs need to be unique among pages in a document, and section IDs need to be unique among sections in the same page, but sections can have the same ID as pages. Sections and linkable blocks would have to have non-conflicting IDs, such that xref attributes in the form page_id#other_id are unambiguous, whether other_id points to a section or a block.

We have to address link text for inline link elements without content, as well as other link data. In the case of formal block elements with a title element, and optionally also with an info element, the link title lookup process would be exactly as it is for pages and sections. If a formal block element does not have a title or info element, we may define the behavior, or we may leave it up to processing tools. Authors should not do this. In fact, we could use the schema to enforce title elements in blocks with id attributes, though this may make the schemas excessively complex.

For terms list items, the link text would be the first title element in the item element. An item element in a terms list can take multiple title elements, but it must have at least one. The item element cannot take an info element, so there is currently no way to provide alternate link titles. An info element could probably be safely added to the content model in the future if this proves to be a problem.

If we make table rows (tr elements) linkable, we could use the first th element in the row if it exists, or the first td element if there is no th element.

We should also define how to get other types of link data for blocks, such as desc (especially after MEP-0008) and thumb (pending MEP-0004). For elements that can contain an info element, this is the same procedure as for pages and sections, except that those with a block desc could use that element as a final fallback. For elements without an info element, there would simply be no other link data.

This proposal will also require changes to the Cache File specification. Any block elements with an id attribute will need to be included in the cache file to allow link data to be extracted. Blocks should be nested in cache files. How to nest these elements in the cache files is an open question.