Subsection 4.28.1 URLs to External Web Pages
The
<url> element is used to point to external web pages, or other online resources (as distinct from other internal portions of your current document, which is accomplished with the <xref/> element, Section 3.4). The @href attribute is always necessary, as it contains the full and complete address of the external page or resource. Include everything the URL needs, such as the protocol, since this will be most reliable, and as you will see it never needs to be visible. The element always allows, and then employs, a @visual attribute for a provided more-friendly version of the address. Finally, the content of the element, which becomes the clickable text in electronic formats, can be authored with the full range of PreTeXt markup generally available in a title or sentence. A typical use might look like<url href="https://example.com/" visual="example.com">Demo Site</url>
This will render as Demo Site 1 . Note the automatic footnote providing the visual version in a monospace font. If a
<url> has content, and no @visual attribute is given, then the @href will be placed in a footnote, though there will be an attempt to remove standard protocols. Compare<url href="https://example.com/">Demo Site</url>
<url href="mailto:nobody@example.com">Bouncing Email</url>
which will render as Bouncing Email 3 .
If you do not provide any content for a
<url/> element, then the clickable text will be the actual URL with a preference for the (optional) @visual attribute, rather than the mandatory @href attribute. This should be considered as disruptive to the flow of your text, and so a poor alternative to the content version just discussed (see Best Practice 4.28.3.1). But it might be a good choice in something like a list of interesting web sites. Whether or not a simplified version of the address, via the @visual attribute, is desirable will depend on the application. As an example, using the optional @visual attribute we have<url href="https://example.com/" visual="example.com"/>
This will render as
example.com. Note that there is no footnote since the visual version is already apparent.If you want to squelch the automatic footnote on a
<url> element with content, you can explicitly set the @visual attribute to an empty string as visual="". This signal will inhibit the automatic footnote. This should be a very rare occurence, since you are denying readers of some formats from seeing even a hint of the actual URL.An extreme example of this behavior is a regular footnote which contains a URL. Because an automatic footnote, inside another footnote, becomes problematic in some conversions, we squelch the footnote-within-a-footnote. A best practice here is to just list nearby a URL, likely using the
<c> element to get a monospace font.A
<url> inside a <title> has been accounted for, but should be used with caution.As with the rest of PreTeXt we have taken care to handle all of the exceptional characters that might arise in a
<url>. So author normally, using the necessary keyboard characters, only taking care with the two XML characters, < and &, which need escaping (see Section 3.14). Use percent-encoding (aka URL encoding) for the @href attribute, if necesary, to include special characters, such as spaces. See Subsection 4.28.4 below for a common need for the ampersand character, and a further caution about percent-encoding of URLs.Finally, for conversion to LaTeX/PDF output it gets extremely tricky to handle all the various meanings of certain escape characters in URLs in more complicated contexts (such as tables, footnotes, and titles), so there may be some special cases where the formatting is off or you get an error when compiling your LaTeX. We have anticipated most of these situations, but we always appreciate reports of missed cases.
example.comexample.com/mailto:nobody@example.com
