Chapter 42 Publisher 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 (nor my inline exercises, nor proofs).
You can change that! See Section 27.2.
Knowls are fantastic! Can I have more?
Start at Section 27.2 and follow a cross-reference to details on the various options.
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?
Start at Subsection 40.4.7 to learn about how to specify alternate styles for HTML output, including an easy way to specify an existing alternate color file.
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
email@example.com 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.
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.
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 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.
My LMS breaks my HTML.
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.
I get a bad line break in HTML with a hyphen between text and mathematics.
When you author something like
<m>x</m>-axisthe 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?
My publisher file (or other auxiliary file) does not seem to be effective.
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 Documentson 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.