AppendixAFAQ: Frequently Asked Questions¶
This is a list of answers to frequent questions, in no particular order.
- Why is there no tag for bold?
That would be presentation, not content. I will answer that question with a question: why do you want to print something in bold? Is it emphasis? (See
<em>.) Is it the volume number of a journal? (See
<journal>.) Do you want to SHOUT? Try
<alert>. And so on. There are lots of good answers, some of which are not yet implemented. We would love to hear about elements you need that are about expressing content, and not about altering presentation. See Item 1.1.1:1 in the .
- Why does your 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 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 Item 1.1.1:4 in the .
- Everything looks right, but why do I get empty output and some warnings about bugs?
There is a good chance you have “modularized” your source files and have not included the
--xincludeswitch on the command-line when you ran
xsltproc. (See Section 4.2.) We can often recognize this mistake—did you not get a warning? (If not, we can improve the warning if you tell us how your source was organized. So please do, since we would love to hear about it.)
- I don't like surprises and have not updated in months. Now I have a problem.
We almost never release mistaken code that breaks output produced from valid source (Chapter 5). And when we have, the cause is usually a small typo, or something that gets fixed easily and quickly. We do sometimes make backwards-incompatible changes, but you always get warnings, often the changes can wait, there are announcements on the mailing lists, and whenever possible, we update tools that automate the changes.
As volunteers, we cannot support problems from old versions, and sometimes we have to implement changes in reaction to third-party software (like MathJax), which is beyond our control. So while development is rapid, we implore you to remain on the
devbranch of the repository and
git pullregularly. Such as daily, with your morning coffee as you sit down to write, or with your last compilation of the evening. You will have far fewer unpleasant surprises this way, and we can help you better.
We understand that PreTeXt is a moving target, but we are iterating to a better state, and it is best to have everybody along for the whole ride.
- How do I put mathematics into my list labels?
First, realize that the way LaTeX uses the term label in the context of lists is different from how much of the rest of the world uses the term in this context. In our case the
@labelattribute describes the style of the grouping markers. For example, bullets versus squares on items of an unordered list, or Roman numerals versus Arabic numerals on an ordered list. So this attribute conveys information about the list, not content of the list. And even if you tried putting an
<m>tag into the value of the attribute, you would not have any luck since XML does not even allow that construction. Finally, there is no real good way to accomplish this in HTML, so conversion to that format would be difficult.
The alternative is to use a description list, with tag
<dl>. You are reading one right now. Put your mathematics in the
<title>and the associated content into the remainder of the
- Why are theorems, definitions, examples, remarks, etc. all numbered using the same counter?
The following is an argument in favor of using common counters for blocks of similar appearance. The argument is stronger in the context of using a printed copy of the book, where physical page flipping is necessary, but also applies to scrolling through a (long) page in a web browser.
Suppose your math professor gave you a note to review Theorem 2.4.7 in your textbook. The “2.4” is useful information directing you to Chapter 2, Section 4. You can tell by the “7” that the theorem is probably not right at the beginning of the section, so you open to the middle of the section. You find yourself on a page with no theorems, but you do see Example 2.4.11. What do you do: flip forward or flip backward?
If theorems and examples are numbered using separate counters, you have no information about which way to go. You need to make a random decision, and flip pages until you find another theorem that you can use as a guidepost. And theorems may be rare and sparse, so it may take quite a bit of page flipping to find that guidepost. You may end up at Theorem 2.4.8, telling you that you need to flip backward now. But how far? Will it be one page earlier or twenty?
If theorems and examples are using the same counter, then you know that you need to flip backward. And perhaps more importantly, the oblivious reader who thinks they are looking for “2.4.7” (and is not thinking about “Theorem”) sees the “2.4.11” and correctly flips backward without even realizing the potential for different counters. As they pass Definition 2.4.10 and Example 2.4.9, they have a sense of the pace at which they are converging on Theorem 2.4.7. This is the main argument for the use of common counters: it makes everything easier to locate.
For another point, perhaps you have read a math book in the past and have seen something like “and according to 2.4.7…”. What if the book has Theorem 2.4.7 and also Example 2.4.7? Which one is the author talking about? If you are lucky, you are conscious that there are multiple possibilities. If you are unlucky, you flip to Example 2.4.7 but the author meant Theorem 2.4.7, and you go a bit mad trying to make Example 2.4.7 logically relevant to the reference.
PreTeXt makes it easy to avoid this particular annoyance, because cross references can identify their “type”, especially through the use of the global “autonaming” feature. But even when the text explicitly says “and according to Theorem 2.4.7…”, with humans being human, some readers will still focus on the “2.4.7” and begin a search for that number rather than the theorem with that number. With common counters, once 2.4.7 is a Theorem, there will never be an Example 2.4.7.
One counterargument is that it feels “wrong” to allow for an Example 2.4.9 and an Example 2.4.11 with no Example 2.4.10 existing in between. This violates our instinct to categorize and order objects. And perhaps the “missing” Example 2.4.10 will indeed cause some confusion to some readers. However, we suggest that such idealized views should be subservient to our goal of producing textbooks that provide a useful resource for the vast majority of our students.
We plan to allow figures and tables to use different counters, since they look obviously different, so you can quickly distinguish the previous, or next, item as you scan a page. Notice that it is their distinctive appearance that is the criteria for an independent counter. For example, numbers for displayed equations meet this criteria. They have their own counter, they are displayed distinctively when originlly formatted, and a cross-reference emphasizes their distinctive type through the use of parentheses (e.g., Equation (2.4.7)).
Also, as an author, recognize that there is a very flexible mechanism for making lists of objects that may be included in the
<backmatter>. To continue the example here, you could make a list of all the theorems in the book, and a separate list of all the examples. Each list would be in the order of appearance, include the number (and a title if you provide one). In HTML output, each is a knowl which will quickly provide the content (independent of location), and also provides an “in-context” link to take you to the location for surrounding material. This useful feature requires very little additional effort, especially if you title your blocks as you author them.
- I do not want my examples in knowls.
You can change that! See the section on conversions in the Publisher's Guide.
- 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 Section 4.9). 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.
- My LaTeX output has errors.
Almost certainly your PreTeXt is not correct. Or your LaTeX syntax within a math element (
<me>, and friends) is not correct. You have to be very deliberate to make legitimate PreTeXt that produces LaTeX that fails to compile. The converse is that LaTeX compilation is a good check on the quality of your PreTeXt, even if you do not care about print output for your project.
If the LaTeX error does not help you locate the problem, a good first step in this case is to validate your PreTeXt source—see Chapter 5.
- I have great output, but validation produces hundreds of errors.
Success with a tool like
xsltproc, in terms of no errors and great-looking output, does not mean your source is correct. XSLT processing can be forgiving, and many invalid constructions just work, and look great. But that is no guaranteee this situation will continue, or the same happy accidents occur for a conversion to a different output format.
We do raise some errors during processing with
xsltproc, but error-checking your input is a job for a validator, so in theory we should not ever produce any errors during a conversion. So strive for having 100% valid PreTeXt source, not simply great-looking results. See Chapter 5 and Appendix C.
- I'd like to make one small adjustment in my output.
There are no plans to make it easy to change one thing in the layout (such as changing the title of all sub-sub-sections from flush-left to centered). If you know enough, then you can hack such things yourself. But doing so is inadvisable, except in the case where you are the rare person who has done a lot of studying and put a lot of effort into learning book design. If that is the case, then it would be better to make a completely new layout and then share it so it is an option for other people to use. See Principle 1.1.1:7.
- 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.