<ref>

Description

A hyperlink to another BDML document, an identifying reference in the current document, or a raw URL hyperlink.

Ref elements provide two types of hyperlinking. The first is BDML hyperlinks, which may be to another BDML document or to an identifying reference in the same document. The second type of hyperlinking is raw links, which specify a URL unknown to BDML.

BDML links

When hyperlinking to external BDML documents, the relative path to the BDML document (without the file extension) is specified. When hyperlinking to an identifying reference in the current document, a document fragment, consisting of the element's identifier prefixed by the # character is specified. Identifying references in other BDML documents may also be specified by combining the the relative path to the BDML document (without the file extension) with the identifying document fragment.

During automatic table of contents generation, the Bora document processor and direct browser loading XSLT stylesheet both automatically populate the ids of all part, chapter, and heading elements. These ids may also be used to create internal references via <ref> elements. However, a better way to achieve this is to explicitly provide ids to these referenced elements, by adding id attributes to each element.

Each part, chapter, and heading element that has an explicit id will override the automatic id generation. The automatically generated table of contents will use these explicit ids instead of automatically generating ids for those elements.

The advantage of providing explicit ids for all referenced elements is that these ids will never change. If automatically generated ids are used for referencing, these references will need to be updated each time the document structure is changed, as the automatically generated ids use position information in order to guarantee uniqueness.

Raw links

When hyperlinking to URLs unknown to BDML, the raw URL is specified in the url attribute, and the type attribute specifies that the hyperlink is raw. In this case, no processing of the reference will take place and the raw url will be used verbatim.

Empty refs

When a <ref> element does not have any content to render, the Bora document processor automatically copies the url into the reference content. This allows <ref> elements to be written without the need to replicate the url.

When a <ref> element does have content to render, no such copying is performed.

If this automatic copying behaviour is not desired, it can be disabled for a particular <ref> element by adding the disable-repl attribute to the element.

Attributes

Attribute name	Description
url	The url to hyperlink to.
type	When present and set to raw, the url is an external URL unknown to BDML and will be used verbatim.
new	When present and set to true, the link will be opened in a new window if the target supports this.
disable-repl	When present and set to true, automatic copying of the url when the reference element has no content is disabled.

Immediate descendants

<ref> elements may contain text, interleaved with the following immediate descendants.

Element name	Description
<emph>	A emphasized span of text within the reference text.
<graphic>	An inline graphic within the reference text.
<span>	A span of text within the reference text.
<strong>	A strongly highlighted span of text within the reference text.
<sub>	A subscript span of text within the reference text.
<sup>	A superscript span of text within the reference text.

Immediate ancestors

Element name	Relation
<chapter>	The enclosing chapter containing the hyperlink.
<para>	The enclosing paragraph containing the hyperlink.
<section>	The enclosing section containing the hyperlink.

Examples

A BDML document reference.

<document xmlns="http://boradoc.org/1.0">
  <chapter>
    <para>
      Please see the section on 
      <ref url="reference/para">paragraphs</ref>
       for information on paragraphs.
    </para>
  </chapter>
</document>

The above BDML renders to the following:

Please see the section on paragraphs for information on paragraphs.

An internal document reference.

<document xmlns="http://boradoc.org/1.0">
  <chapter>
    <para>
      Please see the 
      <emph><ref></emph>
       
      <ref url="#docs-ref-examples">examples</ref>
      .
    </para>
  </chapter>
</document>

The above BDML renders to the following:

Please see the <ref> examples.

A raw URL.

<document xmlns="http://boradoc.org/1.0">
  <chapter>
    <para>
      The 
      <ref type="raw" url="https://www.w3.org/TR/html52">HTML</ref>
       specification provides information HTML metadata.
    </para>
  </chapter>
</document>

The above BDML renders to the following:

The HTML specification provides information HTML metadata.