Appendix B FAQ: Frequently Asked Questions¶
Technical questions first, followed by questions about markup.
- On my local machine, why are the knowls/Sage cells empty?
Viewing a file on your computer is not the same as visiting a web page. There is no web server, so you should assume that things will be different.
The cause of the difficulty is that some browsers (Chrome and Safari, for example) will not fetch the content of knowls when viewing a file on your local computer. Those browsers consider opening a local knowl to be a security risk. As of the time of this writing, Firefox will open those knowls.
Your options are to use Firefox, to transfer the files to an online server, or to set up a local web server so that local files operate in the usual way.
To set up a local server:
- In a terminal, go to the directory containing the HTML files.
python -m SimpleHTTPServer
- Note the port indicated in the output (let's assume it is
- Go to
http://127.0.0.1:8000/to see a listing of the files. Click on a file and you will be viewing it exactly as if it was on the Web.
The instructions above are for Python 2. For Python 3, as well as further discussion, see the Author's Guide.
- How do I install
xsltprocon Ubuntu or Debian Linux?
sudo apt-get install xsltproc
- How do I install
pdf2svgis necessary for TikZ diagrams in HTML.
On Debian or Ubuntu Linux:
sudo apt-get install pdf2svg.
pdf2svgon a Mac, you will need to install MacPorts. Read the directions carefully, since you will need to install Xcode (available from the Mac App Store) first. Make sure that the command line tools are installed by running Xcode. After Xcode is installed read the directions to install Macports. Once MacPorts is installed run the following command to install
sudo port install pdf2svg. Be patient as this will take a few minutes. To get rid of any intermediate build files, run the command
sudo port clean --all all. Again be patient.
If you have trouble with MacPorts, try HomeBrew.
- Why is there no tag for bold?
Because the first principle of PreTeXt is that the markup captures the structure of the document, not the appearance.
A better question is: 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 Principle 1.
- Why do I get no 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.) If that was your mistake, then you should have seen a warning. Please check to see if there was a warning you missed. (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. Why do I now 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
- I have errors when I try to validate my markup, but everything looks okay when I make the HTML and the PDF. Should I be worried?
Occasionally the schema lags behind the code, so your first step is to post to
firstname.lastname@example.org find out if it is a problem with the schema.
Possibly there is another way to accomplish what you want, and that markup will fit the schema. Or maybe what you are doing meets the “common and reasonable” test and can become a feature request. The discussion on
pretext-supportshould provide an answer.
- 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.
- Why do I have LaTeX errors?
If you have errors when you run
xelatex, that is more likely to be caused by a problem with your LaTeX installation than with PreTeXt. It is difficult to make legitimate PreTeXt that fails to compile; an exception being math markup inside a math element (
<me>, and friends).
To check your LaTeX installation, run
pdflatex -version. If it reports something older than “TeX Live 2017”, then updating may help. If the trouble seems to be coming from a particular package, then check which version of the package is being used. For example, if the “tasks” package is causing a problem, run
kpsewhich tasks.styin the directory where you are compiling the LaTeX. If the package is in your personal texmf tree, that may be the problem.
If the PDF is created without errors, but something looks wrong in the PDF, then probably the PreTeXt source markup is wrong. Validate your source against the schema (see Section 5.5), and also carefully examine the HTML output. If that does not reveal the problem, seek expert help.
- I have great output, so why does validation produce 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 E.
- Why do I have an “extra” period at the end of a title?
Author your titles without punctuation at the end meant for spacing or separation (period, colon, semi-colon, hyphen). Do include punctuation which imparts meaning (question-mark, exclamation-point). PreTeXt will then add separation (a period, or spacing), as needed, in all the places where it is required. But PreTeXt will respect your question-marks and exclamation-points.
If you think you have an additional punctuation character that conveys meaning at the end of a title, please bring it to our attention.