Skip to main content

Section 4.22 URLs and External References

Subsection 4.22.1 URLs to External Web Pages

The <url> tag can be used to point to external items (as distinct from other internal portions of your current document, which is accomplished with the <xref/> element, Section 3.4). It always needs a value for the @href attribute, most likely a URL. Most of this time, this will point to some resource available on the Internet but it could be a file on the system hosting your document, perhaps using a relative address (but see the rest of this section for some cautions). Here are three scenarios:

  • The <url> element is empty. Then the value of the @href is also used for the visible text of the link, verbatim, and usually in a monospace font. Use percent-encoding (aka URL encoding) for the @href attribute to include special characters, such as spaces.

  • The <url> element has content. Now the content should be authored as you would any other text in a sentence. Potentially problematic characters, such as a tilde should be authored with provided empty elements (as distinct from being authored literally in the @href attribute).

  • The <url> element has content, but you want this content to look like a URL. Use the <c> element around the content, and follow the rules for verbatim text. I do this often for simple URLs that point to the top level of a website. The @href is a complete URL like https://pretextbook.org/ but for content I use a less-imposing reader-friendly version like pretextbook.org.

You can place an external reference into a <title> element, but conversions may choose to simply render it as text, and not as an active link.

For output it gets quite 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 . We handle most of these situations, but we always appreciate reports of missed cases.

Subsection 4.22.2 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 &amp; 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.

Subsection 4.22.3 URLs to External Data Files

The <url> element can be used to make data files available to your reader. Consider the example of a spreadsheet containing a large data set that a reader needs to analyze as part of an exercise. Here are our recommendations on how to accomplish this:

  • If the file is hosted on some server unassociated with your project, and does not have a license compatible with your project, then just set the @href to the complete address. Be sure to include enough of the address for the reader of a a print version to be able to type in the URL, either as the content of the <url> or in close vicinity.

  • If you authored the spreadsheet, or you are allowed to legally copy and distribute it, then place it on your server where you host your book project. Then do as above and use the full URL for the @href attribute, with a visible version available for PDF and print versions.

  • If you have control over the placement of the file, you can host it on your server, and use a URL relative to the location of your HTML, PDF, or other files that comprise your document. This might be a good choice if your book will be posted many places and you can give it to others as an archive, like a *.zip file. It is a bad idea if a reader downloads a PDF without the data file following along and remaining in the same relative location. It is an impossible idea if your document gets printed on paper and there is no idea what a relative URL means and there is not even a link to click on.

Consider your audience and think about how much guidance they need about using context menus or helper/viewer applications to make use of the file formats you are providing. This advice may be different depending on the type of files and the types of output for your document.