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 45.5.11 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.
This
index.html page is a part of your HTML output; it is not the same as a project landing page—the home page of a website devoted to your whole project. See Section 24.2 if a project landing page is what you are looking for.
Subsection 29.1.2 Banner Contents
The top of page banner normally features the title, subtitle, and author. If the subtitle or author list are long, or not particularly relevant for a given work, the publisher may wish to not render them at the top of each page. Of course, this information will still always be available at least once in places equivalent to a title page in the “front” of your document. See Subsection 45.5.4 for details on specifying what to display.
Brand Logo.
The banner has room in its upper-left corner for a small image—an institution’s mark, or an image of a printed version’s cover. Elect it with the
<brandlogo> element of the publication file (Subsection 45.5.3); with a @url attribute the image becomes a link, a natural way to reach a project’s landing page (Section 24.2).
The
@source attribute is a path relative to the external directory of the hosted output, not to your source tree: place the image file in the directory of externally-produced assets (Section 5.7) and give the path from there. When the pages are served, the image is fetched from that location alongside them.
Subsection 29.1.3 Read Aloud
One of the many reasons to use HTML output of PreTeXt is screen reader support, based largely on MathJax. While most accessibility-focused screen readers (like NVDA and JAWS) now do a very good job switching between MathJax-rendered mathematics and the surrounding text, a casual user of screen readers is unlikely to learn how to use this specialized software. Browser plugins that offer text-to-speech often fail to handle the text-to-math handoff.
So PreTeXt provides its own browser based screen reading support for the HTML output via the
@read-aloud attribute of the publication file (Subsection 45.5.29). This feature will turn on by default, but can be turned off by the publisher. When enabled, a small button appears in the navigation bar of each page. Clicking it will expose player controls to play/pause and skip back or ahead (by sentence). More complicated elements, like tables and interactive elements are announced and skipped.
Hidden knowls are also announced and skipped, unless the reader selects an option to read all of them. Alternatively, using the up and down arrow keys will jump the reader between different paragraphs, and pressing SPACE while on a knowl’s title will trigger reading it in full.
Additional options in the read-aloud settings menu (next to the playback controls) allow the reader to change the voice (which voices are included depends entirely on the browser and operating system), reading speed, and whether to continue to the next page once reaching the end.
Subsection 29.1.4 Annotation
A publisher may enable a third-party web-annotation service, which lets readers of the HTML output highlight passages and attach notes. This is a publisher decision, so it is configured in the publication file rather than in the source. At present the only supported service is
hypothes.is, enabled by setting the @platform attribute to hypothesis. See Subsection 45.5.6 for the exact publication-file entry.
Subsection 29.1.5 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. See Subsection 45.5.5 for details on specifying this option.
Subsection 29.1.6 HTML Favicon Configuration
A favicon is a graphical element (“icon”) that identifies a website. Perhaps its most recognizable use is its appearance in every browser tab open at that site. As publisher, you can associate an icon for your project to the HTML output of your project.
See Subsection 45.5.7 for details on this specification. When the attribute value is
none (the default), then your pages will not have a favicon.
If you set the attribute to
simple then you must provide two versions of your icon, in PNG format, in pixel sizes 16×16 and 32×32, with exactly the two filenames below (respectively), in the directory of provided external files (Section 5.7).favicon/favicon-16x16.png favicon/favicon-32x32.png
There are other ways to specify a favicon and some browsers expect different files. Try this scheme first, as it appears to have been sufficient since 2018. But if a new scheme needs implementation, we can consider a feature request.
Subsection 29.1.7 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 45.5.10 for details on specifying this option.
Subsection 29.1.8 DoenetML Activities
A DoenetML activity is a substantial piece of software. A page carrying a dozen of them once started every one the moment the page opened, and held every one in memory for as long as the reader stayed—enough, on a modest machine, that the activities could be slow to appear, or fail to appear at all. So a page carrying DoenetML activities loads a small coordinator script, served from the same place as the activities themselves, which takes charge of them: it starts them a couple at a time as the reader nears them, so an activity the reader never scrolls to is never started, and it puts away the ones the reader has left well behind. A reader’s work is saved before an activity is put away and restored if the reader returns to it, and the space the activity occupies on the page is held while it is away, so nothing shifts. This is on by default and needs nothing from an author, though a publisher can turn it off (Subsection 45.5.28).
The coordinator also lets the activities on a page share a pool of the background workers they compute in. A worker is the largest part of what an activity costs in memory, so the pool is most of the coordinator’s saving; it too can be turned off, giving each activity a worker of its own. Turning the coordinator off turns the pool off with it, since the coordinator is what owns the pool.
Two limits tune how much the coordinator allows at once: the number of activities kept running, and the number allowed to be starting up at the same time. A book whose activities are small might raise them; but raising them asks more of the reader’s machine, which is what the coordinator exists to avoid, and the defaults suit a reader on modest hardware.
The version of DoenetML in use, including the version of the coordinator, comes from the
<doenetml> element of <docinfo> rather than from the publication file, since it is a property of the source: see Section 4.25. A book that names no version, or names a partial one such as 0.7, gets the newest release, which is what this machinery is written for. A book that pins an exact version should pin 0.7.25 or later.
Two earlier boundaries matter to a book that does pin one. The coordinator first shipped with DoenetML
0.7.21, so a book pinned before that will not find the script at all and behaves as if the coordinator were turned off. From 0.7.21 through 0.7.24 the script is there, but it does not yet share a page well with a book that saves the reader’s work itself, as a Runestone or SCORM deployment does. Two parties then answer an activity’s request for its saved work—the coordinator, from what it took down when it put the activity away, and the book’s own saving—and before 0.7.25 each answer rebuilt the activity in turn, so every restore built the document twice over. That is the very cost the coordinator is there to avoid. And since the answer that arrived last was the one kept, a book whose saving answers out of storage it has to go and fetch could have the fresher copy the coordinator was holding overwritten by an older one, leaving the reader to find work they had just done replaced. A book pinned into that range should turn the coordinator off; a build that can see the combination will say so.
See Subsection 45.5.28 for the publication file entries controlling all of the above.
Subsection 29.1.9 GeoGebra Applets Behind a Play Button
A GeoGebra applet starts as soon as the page holding it does. One or two of these is nothing a reader will notice, but a page carrying a dozen starts a dozen at once, and on a modest machine that can leave the page slow to settle, or an applet slow to appear.
A publisher may instead ask GeoGebra to put a preview image and a play button in place of each applet, so that an applet starts only when a reader presses its button. This is GeoGebra’s own feature rather than something PreTeXt draws, and it is elected with the
@play-button attribute described at Subsection 45.5.27.
The image standing behind the button is the same screenshot PreTeXt makes of each interactive for the static versions, such as the PDF. A publisher electing the button will want those images to have been generated, since GeoGebra has a preview of its own only for an applet it hosts, and offers nothing at all for one built from a file or written from scratch.
That makes the order of work matter. While a diagram is still being written and adjusted, leave the button off: an applet that starts by itself is exactly what an author wants to see, and a preview taken from an unfinished diagram is only going to be taken again. Once a page has matured, generate its preview images, and elect the button then.
It is off by default, since the cost only becomes noticeable when a page carries several applets, and a reader who must click to see a single diagram is worse off than one who does not. A publisher whose pages are dense with GeoGebra is the one who stands to gain.
Subsection 29.1.10 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 45.5.2 for the specifics of this entry. Examples of use include links from Asymptote graphics (Section 30.8), and URLs pointing to locally-hosted data files (Section 4.17).
Subsection 29.1.11 Privacy Options for Video Embedding
When videos are embedded in HTML from sites like YouTube or Vimeo, 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 45.5.19 for details on specifying this option.
Subsection 29.1.12 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 45.5.21 for the specifics of this entry. This feature is off by default.
Subsection 29.1.13 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 45.5.22 for precise details.
