Skip to main content

Appendix A FAQ: Frequently Asked Questions

This is a list of answers to frequent questions, in no particular order.

Why does the conversion to HTML use a fixed width for the text?

There is an optimal number of characters per line for human readers, based on research and centuries of book design. So we set a fixed width such that the default font comes close to achieving this optimal value. We also use responsive design to accomodate the constraints of a small screen as best as possible. A reader will not want to have to carefully resize a browser window to achieve the optimal width, nor should a line of text spread to many, many characters across a very expansive screen. See Principle 4.

I do not want my examples in knowls.

You can change that! See Section 4.1.

Why are my knowls empty?

When viewing the HTML version on your laptop or local computer as files, do not expect knowls to render properly. This is a known bug/feature, and there is nothing to be done about it, unless you run a web server on your own machine, which fortunately is a very easy thing to do (see the section of the Author's Guide about testing HTML output locally). Think of it this way: the knowl content comes from a server, but on your laptop there is no web server. You are just looking at files.

A possible added confusion is that some knowls, such as proofs, will appear. That is because their content is embedded in the page, not taken from a file.

How can I change the colors in the HTML version?

There are several colors schemes available. They (currently) have a name in the form mathbook-X.css, where \(X \in \{0,1,2,3,4,5,6,7,\text{ups},\text{manitoba},\text{bucknell}\}\text{.}\)

The options for colors are currently being revised, and soon it will be easier to create your own color scheme.

To use one of the above color schemes, you can use a stringparam on the command line, like this:

--stringparam html.css.file "mathbook-X.css"

where \(X\) is chosen from the list above. Or in your thin XSL stylesheet you can add the line

<xsl:param name="html.css.file" select="'mathbook-X.css'" />
Something looks wrong in the HTML output. How can I customize the layout of the HTML version?

If there are some anomalies in the HTML version of your book, probably that was just an oversight and can be fixed easily. Send a message to pretext-support@googlegroups.com describing the problem and including a live link to the page showing the error. Do not make a minimal example. (CSS issues are handled in a completely different way than other software issues.)

The long-term plan is to have a variety of different layout options, which can be chosen as easily as choosing a color scheme. See Principle 7. The first step is to rewrite the current CSS so that it is easy to develop alternate layouts. That should be done by the end of Spring, 2018. Then people can develop new styles! Until that happens, either suffer with the current style, or hack away at your own peril. (Note that the PreTeXt support groups will not provide any help with hacking the layout, but a lot of help will be available when it is time to develop alternate layouts.)

Why does the HTML output load so many external resources?

The subtext perhaps being, “Why shouldn't I host these on my own server?” A main goal for PreTeXt is to spare authors the headaches of learning new technologies just so they can get their content in front of readers. That knowledge should be built into software, so an author can work at a higher level, explaining the intricacies of their discipline. So we only assume an author can place locally-built HTML output onto some public server they have permission to use. Any extra enabling techology we do not want to create ourselves gets pulled from other public servers. MathJax, both code and fonts, is a good example, as one of the enabling projects. Perhaps it is the enabling project.

This way,

  • Authors can concentrate on their writing, not updating services on their server.
  • Servers that are hostile to ad-hoc configurations (think “learning management systems”) are not an impediment to hosting projects.
  • For the most part, updates to external resources happen automatically. This allows authors and PreTeXt developers to concentrate on other aspects of their work.

We get MathJax from a content delivery network (CDN). Once we have that dependency, then fonts and search from Google, CSS and Javascript from the American Institute of Mathematics, and other components, all have the same dependency: a decent internet connection. Our experience over several years is that these resources have good uptimes and good bandwidth, and so are not a source of problems. A good offline version, with resources packaged via a script, would be a good long-term project.

Finally, we do not load minor resources indiscriminately. Something in your source should suggest they are necessary and we perform those checks, document-wide. However, since a cross-reference is usually implemented as a knowl, and we cannot be sure what a knowl might contain, we do tend to load resources on every page, even if only needed once. We hope to improve this situation. And you are enouraged to help if you have technical skills in these areas.

Searching my PDF output is broken.

PreTeXt goes to great lengths to make a high-quality PDF, but if you manipulate it by adding in new pages, or adjust the intermediate to use other fonts, you run the risk of breaking some of the features.

A ligature is a combination of two characters into one, like a lower-case “f” followed closely by a lower-case “i” without a dot. These can confuse a search. Verbatim text sometimes ends up with “smart” quotes, where left and right versions are inverted. This frustrates copying source code into an actual program. And so on. If you see problems like this with un-customized PDF output, we would like to hear about it.