HTML Publisher Options

Section 29.1 HTML Publisher Options

Subsection 29.1.1 `index.html` Page

The conversion to HTML always creates a file named index.html. We do this because if a reader requests the URL

platypus.mammal-institute.org/aota/html

then most modern web servers will automatically return the page

platypus.mammal-institute.org/aota/html/index.html

So you can advertise the shorter version to potential readers. What is in index.html? Simple code to redirect to another one of your pages. Which one? Any one you like!

Within the <publication> element of your publication file (Section 26.1) include an <html> element, with a child element <index-page> having an attribute @ref. The value must be the @xml:id of a division which is rendered as an entire web page at the requested level of chunking. See Subsection 44.4.6 for details on specifying this option.

For example, if a <book> is being chunked into <chapter>, and your source has

<chapter xml:id="birds">

then you can set ref="birds" and the page for that chapter will be the default page for the shorter URL. In practice, you probably really want a page that looks like the front matter or a Table of Contents.

The default is to first have index.html redirect to a page for the <frontmatter>, and if this is not possible, then it will redirect to a page for the top-level of your content. If your document is short or simple, you may just have a single web page. You could choose to not distribute the index.html file and then just use a concise and descriptive @xml:id for your top-level element (e.g. <article>) to fashion an attractive URL that points to your shorter work.

Subsection 29.1.2 Embedded Calculator

You may elect to have an embedded online calculator in each page of your online version. It will appear in the right margin, and will stay there as a reader scrolls the page up and down. A button near the masthead can be used to contol visibility. By default no calculator is available, so you need to explicitly request this feature. As of 2020-05-30 there are four calculators available from the GeoGebra Project

www.geogebra.org

. See Subsection 44.4.3 for details on specifying this option.

Subsection 29.1.3 ActiveCode Programming Windows

A window that allows for entering, and executing, computer programs can be made available for every page. The reader can click on a pencil icon to activate this window. Some languages can run in a web browser as part of any HTML output, while some other languages require infrastructure on a Runestone server to execute, and so are only available when you specify that hosting option. Note that the publisher will select a single language for use with the entire document. See Subsection 44.4.5 for details on specifying this option.

Subsection 29.1.4 Base URL

The base URL of a hosted version of HTML output may be specified as an entry in a publication file. Then certain aspects of other output (typically PDF/LaTeX) will link to corresponding aspects of the HTML output. See Subsection 44.4.2 for the specifics of this entry. Examples of use include links from Asymptote graphics (Section 30.7), and URLs pointing to locally-hosted data files (Section 4.16).

Subsection 29.1.5 Privacy Options for Video Embedding

When videos are embedded in HTML from sites like YouTube

youtube.com

or Vimeo

vimeo.com

, they come with whatever tracking cookies these sites want to include. Some of these can be helpful; for example, to let the viewer keep track of what they have watched. Others are designed to target advertising, and load when the page loads, rather than when the video plays, which can increase the time it takes for your book to load.

Currently YouTube offers an “enhanced privacy mode” that disables tracking cookies on page load. The assumption is that publishers will want to protect their readers’ privacy and optimage page load time, so this mode is turned on by default for YouTube videos. It is not known to be available for other platforms, but can be added if this changes. Note that the behavior and appearance of your videos may change slightly depending on which option you choose.

Within the <publication> element of your publication file include an <html> element, with a child element <video> having an attribute @privacy. The value must be either yes (use enhanced privacy, if available), or no (allow all tracking cookies). If your publication file does not have this element (or you do not have a publication file) you will get a warning message, and the default will be used. See Subsection 44.4.12 for details on specifying this option.

Subsection 29.1.6 Links to full-size versions of Asymptote diagrams

Asymptote diagrams are embedded in HTML as a canvas element within an iframe. Unlike image elements, web browsers will not provide the option to “view image”, and clicking on the image will not enlarge it. Since 3D Asymptote diagrams are interactive, a reader may wish that they could interact with a larger version of the graphic.

You may elect to place a “Link to full-sized image” link below each Asymptote diagram. Clicking on the link will open the Asymptote HTML file directly, and the digram will be displayed at a much larger size.

See Subsection 44.4.14 for the specifics of this entry. This feature is off by default.

Subsection 29.1.7 HTML Feedback Button

You can elect to have a “Feedback” button in the footer of your HTML pages. You must provide a URL via an attribute. But where that URL points, and what happens there, is your responsibility. In other words, PreTeXt is no more help here, you just get a functional button pointing somewhere of your choosing or design. An example use case may be that you want to make it very easy for your readers to submit reports of small errors, like “typos.” So you setup an online form with a free service, which will help you manage this communication. Or maybe you want to run a reader survey via a form, so you point to that.

The default text on the button is Feedback, which will be in the language in effect for the page. You can override this choice (e.g., Bug Report), but it needs to be raw text (no markup) and then it will not react to language changes for your document. See Subsection 44.4.15 for precise details.

Subsection 29.1.8 HTML Navigation

There are publisher file entries to control how navigation between pages behaves. The “Up” button may be turned on and off. An entry for the logic of these buttons can be set to the values of linear (the default) or tree. The former causes the Previous and Next buttons to behave as if the divisions are arranged as in a printed book, i.e. linearly. The latter option means that when a reader comes to the last subdivision of a division, the Next button will be not be active, and they will need to return (up the hierarchy/tree) to the division and move to the next division. Turning off the Up button while electing the tree model is likely to lead to a frustrating navigation experience.

The HTML target offers two views of the Table of Contents (ToC). The default is to fully expand the ToC to the depth indicated by the the common Table of Contents level 44.1.2 publisher setting. There is also a focused view that uses an expandable ToC and only initially fully expands the path to the current page.

Prev Top Next