MEP-0007

External Info Links

This page outlines a way to link to external pages within informational link sets like topic and seealso links, and proposes a way to specify title, desc, and other information for those pages.

Authors: Shaun McCance
Created: 2015-11-04
Status: final (2019-01-31)
Target: 1.1
Issue: https://github.com/projectmallard/projectmallard.org/issues/30
History:
show history
hide history
history
2015-11-04 1.1 proposed
2016-01-03 1.1 implemented
2019-01-31 1.1 final

Background

Mallard allows semantic information links for a number of things. Most notably, this is the basis for Mallard's topic/guide navigation structure, and it provides reciprocal seealso links. More info link types can be provided by extensions or future Mallard versions.

Informational links, however, are limited to links within the same document using the xref attribute (or, potentially, to other documents within a site or controlled document set using an extended xref syntax).

This page proposes allowing informational links with an href attribute to point to arbitrary external pages. Obviously, external pages cannot be made to automatically reciprocate links, so this feature should be used with care. Furthermore, it may only make sense to support external info links for certain link types. For example, creating a series out of next links requires each page to specify its next page. An external page would necessarily be the final page in a series.

Proposal

This page proposes allowing informational link elements with an href attribute to be processed in certain semantic link sets. The href attribute is already allowed by the Mallard 1.0 schema, but there is no specified behavior.

Under this proposal, informational link elements with an href attribute would be included in topic, guide, and seealso link sets for the source page or section. They would not be used by next link sets, but they could be used by extensions or by link sets defined in future Mallard versions. Each informational link type should specify whether it can use external links.

This page currently does not propose anything with the action attribute, although that linking attribute is also currently allowed by the Mallard 1.0 schema.

Link sets using informational links rely on information found in the info element of the target node. Because we can't reasonably expect processing tools to try to find such information on external pages, this page proposes allowing informational elements as child elements to the link element to provide that information.

The allowed contents of informational link element would then be mal_info_content. The current allowed contents is any external-namespace content. This is allowed in mal_info_content, so there would be no backwards compatibility issues for validity.

The information supplied with the link element would only be used for external links. It would not override or supplement information for xref links in any way. It may, in fact, be better to split the schema definitions to only allow the informational child elements for external links.

Examples

Include the Ten Minute Tour in your seealso links.

<info>
  <link type="seealso" href="http://projectmallard.org/about/learn/tenminutes">
    <title>Ten Minute Tour</title>
    <desc>Create a multiple-page document in only ten minutes.</desc>
  </link>
</info>

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 section is not yet written. Discuss this proposal on mallard-list.

Comparison to Other Formats

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

© 2015 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