The PreTeXt Guide

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.

You can change that! See Section 29.2.

Start at Section 29.2 and follow a cross-reference to details on the various options.

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 Section 5.11 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.

Start at Subsection 44.4.10 to learn about how to specify alternate styles for HTML output, including an easy way to specify an existing alternate color file.

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.)

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.

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.

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 LaTeX 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.

Suppose your HTML output seems to work fine, but once you place it inside your university’s Learning Management System (LMS) it no longer works very well.

A likely culprit is that your LMS is adding material to your files, ruining them in the process.

When you author something like <m>x</m>-axis the code produced by MathJax may allow a web browser to break a line just before the hyphen. Yes, this looks very bad. No, it is not a problem PreTeXt can easily solve. So we will wait for MathJax and web browsers to do a better job. You might let us know when this happens?

Does the filename, or any other directory in the complete path to the file, have a space in it? A common culprit might be My Documents on Windows. If so, the failure is likely our fault. Doing a test where you move your project someplace clear of filenames or directory names with spaces would be a big help to us. And then a careful report of the offending situation will let us make a fix for the next author or publisher. Thank-you.

See Section 30.17 and especially the contained Best Practice 30.17.1.