MEP-0008

Multiple desc Elements

This page proposes allowing multiple desc elements inside info elements. The desc elements would allow type and role attributes. Processing tools would select the appropriate desc element using a similar algorithm to that used to select titles.

Authors: Shaun McCance
Created: 2017-05-01
Status: proposed (2017-05-01)
Target: 1.1
Issue: https://github.com/projectmallard/projectmallard.org/issues/16
History:
show history
hide history
history
2017-05-01 proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.

Background

Mallard allows you to have multiple title elements in an info element. These info title elements can take type and role attributes. Users can provide different titles to be used in different situations. However, the same desc element is always used.

When it is useful to provide different titles for links, it may also be useful to provide different accompanying descs. With this proposal, you would be able to provide alternate descs with alternate titles.

Proposal

This page proposes allowing zero or more of the mal_info_desc pattern in mal_info_content, and changing the mal_info_desc_attr pattern to allow optional type and role attributes, mirroring those attributes on the info title element.

When a desc element is needed for link text for a links element (or, rarely, for a link element), a processing tool would follow the following steps:

  1. If the links or link element has a role attribute, and the target has a desc element with the type attribute set to "link" and the same role value as the linking element, that desc element is used.

  2. Otherwise, if the linking element is a links element, and it uses an implicit role to select a title, it also uses that implicit role to select a link desc.

  3. Otherwise, if there is a link desc without a role attribute, that is used.

  4. Otherwise, if there is a desc without a type attribute or a role attribute, that is used.

Note that info titles can also be used to provide titles for sorting, for text-only environment, and for other purposes that may be defined by extensions, implementations, or future specifications. There is less utility in these for desc elements, but the same mechanism for specifying multiple values exists if needed.

Examples

This section is not yet written. Discuss this proposal on mallard-list.

Internationalization

This section is not yet written. Discuss this proposal on mallard-list.

Alternatives

This section is not yet written. Discuss this proposal on mallard-list.

Compatibility and Fallback

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

The fallback behavior for a new info element is that it is ignored. However, if there are multiple desc elements, the behavior of a Mallard 1.0 processing tool is undefined when selecting the desc element for link text. A Mallard 1.0 processing tool could reasonably select any desc at random, or even the concatenation of them all. All known implementations select the first desc element if there are multiple. When using multiple desc elements, you sould place the fallback desc first for the best fallback behavior with older implementations.

Comparison to Other Formats

This section is not yet written. Discuss this proposal on mallard-list.

© 2017 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard
Hosted by Syllogist