Section 4.28 URLs and External References
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>
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.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. One example of this is a regular footnote, which contains a
URL. The automatic footnote, inside another footnote, becomes problematic in some conversions. Better to squelch the footnote-within-a-footnote, and 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.
Subsection 4.28.2 Data URLs
A <dataurl> element is very similar to the <url> element just described. The purpose is to point to an actual file that will be of use to your readers. What actual happens when a reader clicks on it is dependent on the format of the PreTeXt output and that reader’s environment. Maybe the file will be downloaded, or maybe a particular application will open the file. That part is out of our hands. Use an @href attribute in the same way as for <url>, and the content and the @visual attribute also behave similarly.
The one key differerence is that you can also use a
@source attribute in place of
@href and point to a file that you provide as part of your project (not unlike providing a photographic image via the
<image> element). Place the file in your collection of external files (see
Section 5.6) and provide the path to your file from below the directory of external files in the
@source attribute. For
HTML output, PreTeXt will do the rest. For more static formats, you can set a base
URL (see
Subsection 44.4.2) and you will get a complete
URL that points to the instance of your file hosted with the rest of your
HTML output.
Notice that this element provides limited functionality, at best just a hyperlink to a file. For data files that you want a reader’s in-browser computer program to process, read about the
<datafile> element at
Section 4.16.
Subsection 4.28.3 Visual URLs
By a
visual URL we mean a version of a
URL that is simpler than the “real”
URL, but that provides enough information that a reader can type the
URL into some other device with a minimum of effort, and with success. Consider that your project may someday be a print (hardcopy) book, or that your project will be converted to braille for a blind reader. These are some ideas about making a
URL simpler. We welcome more ideas.
Remove standard/default protocols like http:// and https:// which most browsers will furnish in their absence.
Sites like
StackExchange 4 list posts with a long identifying number, followed by something that looks like the title. In practice, the number is enough.
Experiment with dropping a trailing slash—they are frequently unnecessary.
Often a leading www. in a domain name is not necessary.
Try providing just a domain name in place of a top-level landing page, it will often redirect to a longer
URL.
You could use a
URL shortener 5 , though some thought should be given to
its longevity 6 . Will you remember where your short
URLs point once they are no longer functional. Safer to have your long
URLs in an
@href in your source, and use PreTeXt to make them friendlier.
Subsection 4.28.4 Characters in URLs
A
URL can have a
query string, which has a list of parameters following a question-mark. The parameters are separated by ampersands (&), which will need to be escaped, so as to not confuse the
XML processor. So use
& anywhere the ampersand
character is necessary, such as a
@source attribute, or a monospace version of a
URL achieved with a
<c> element. Also, the question-mark character should
not be
URL-encoded (
%3F) (despite advice just given above), so if necessary edit it to be the actual character. General advice about exceptional characters in
XML source can be found in
Section 3.14.
mailto:nobody@example.com
