From shaunm at gnome.org  Sat Jun  6 08:56:02 2015
From: shaunm at gnome.org (Shaun McCance)
Date: Sat, 06 Jun 2015 08:56:02 -0400
Subject: MEP: External Info Links
Message-ID: <1433595362.18902.33.camel@gnome.org>

= MEP-XXXX
- 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.

== 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.

[example]
[code]
<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>

-------------- next part --------------
<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="mep"
      id="mepXXXX">

<info>
  <link type="guide" xref="index" group="1.1"/>

  <!--
  <link type="mep:depends" xref="mepYYYY"/>
  <link type="mep:replaces" xref="mepYYYY"/>
  <link type="seealso" xref="mepYYYY"/>
  -->

  <credit type="author copyright">
    <name>Shaun McCance</name>
    <email>shaunm at gnome.org</email>
    <years>2015</years>
  </credit>

  <include href="../cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  <revision date="2015-06-06" docversion="1.1" status="proposed"/>

  <title type="text">External Info Links</title>
  <title type="link">MEP-XXXX: External Info Links</title>

  <desc>Allow informational links to point to external pages with an
  <code>href</code> attribute.</desc>
</info>

<title>MEP-XXXX</title>
<subtitle>External Info Links</subtitle>

<p style="lead">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.</p>

<links type="section"/>

<section id="background">
  <title>Background</title>

  <p>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.</p>

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

  <p>This page proposes allowing informational links with an
  <code>href</code> 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.</p>
</section>

<section id="proposal">
  <title>Proposal</title>

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

  <p>Under this proposal, informational <code>link</code> elements with
  an <code>href</code> 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.</p>

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

  <p>Link sets using informational links rely on information found in
  the <code>info</code> 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 <code>link</code> element to provide that
  information.</p>

  <p>The allowed contents of informational <code>link</code> element
  would then be
  <code href="http://projectmallard.org/1.0/mal_info#schema">mal_info_content</code>.
  The current allowed contents is any external-namespace content. This
  is allowed in <code>mal_info_content</code>, so there would be no
  backwards compatibility issues for validity.</p>

  <p>The information supplied with the <code>link</code> element would
  <em>only</em> be used for external links. It would not override or
  supplement information for <code>xref</code> 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.</p>
</section>

<!--
<section id="addendums">
  <title>Addendums</title>
</section>
-->

<section id="examples">
  <title>Examples</title>

  <p>Include the Ten Minute Tour in your seealso links.</p>

  <example>
    <code><![CDATA[
<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>
]]></code>
</example>
</section>

<section id="i18n">
  <title>Internationalization</title>
</section>

<section id="alternatives">
  <title>Alternatives</title>
</section>

<section id="compatibility">
  <title>Compatibility and Fallback</title>
</section>

<section id="comparison">
  <title>Comparison to Other Formats</title>
</section>

</page>