The PreTeXt Guide

The “” could be a knowl that appears empty. Or a sage cell that appears empty. Or an interactive element of some sort that seems broken. Or any component of the HTML page that is “fancy”.

Viewing an HTML file on your own computer is not the same as visiting it on a website. There is no web server, so you should assume that things will be different.

The cause of the difficulty is that some web browsers will behave differently when viewing a local file compared with viewing it on a website. If there are other resources to fetch (for example, the content of a knowl) the browser may consider it a security risk to fetch them while viewing a local file.

Try viewing your HTML file using a different browser, and you may find that the feature is working there. However the real test is to transfer the files to an actual web server, or to set up a local web server so that local files operate in the usual way.

To set up a local server, see Section 5.11.

pdf2svg is necessary for TikZ diagrams in HTML.

On Debian or Ubuntu Linux: sudo apt-get install pdf2svg.

To install pdf2svg on 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 pdf2svg: 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.

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.

Unlikely. PreTeXt is designed around XML markup, so using a text editor to create a text file is the intended process for creating source. When you create a file with other word processors it is likely to use different characters in some places, such as “smart quotes”, and convert other things you type, such as converting three periods into a single ellipsis character. And if you make font changes, such as italics for emphasis, that will not translate directly to PreTeXt.

Perhaps you know somebody technically-minded you want to convert your word-processor files for you? First, this is a tedious job. Second, they may not accurately translate your intent. Third, you cannot make any edits and you will be reliant on them alone to maintain your project for you.

If you insist on authoring with a traditional word-processor, then you should. But you will get whatever output that tool provides, and miss out on the benefits of the semantic markup that allows us to create all the various output formats PreTeXt provides.

There is a good chance you have “modularized” your source files and have not included an <xi:include> for each modularized file. (See Section 5.3.) 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.)

We almost never release mistaken code that breaks output produced from valid source (Chapter 6). 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 dev branch of the repository and git pull regularly. 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.

Changes on our end which produce new warnings are almost always announced on the pretext-announce Google Group. This is a very low-traffic, announcement-only list, so you could skim the messages you missed. Also, read warnings carefully, as they often have explicit suggestions about what to do next.

We do not support creating new blocks. But you can repurpose an existing one. See Subsection 4.2.4.

List markers are an organizational device for grouping small bits of information. It is not appropriate to use mathematics in this situation. (Even if LaTeX list item “labels” allow such a construction.) The alternative is to use a description list, with a <dl> element. Put your mathematics in the <title> and put the associated content into the remainder of the <li>. Or, put titles on the list items of an ordered or unordered list, and include mathematics there.

Occasionally the schema lags behind the code, so your first step is to post to pretext-support@googlegroups.com to 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-support should provide an answer.

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 professor gave you a note to review Example 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 example 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 examples, but you do see Remark 2.4.11. What do you do: flip forward or flip backward?

If examples and remarks 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 example that you can use as a guidepost. And examples might be rare and sparse, so it may take quite a bit of page flipping to find that guidepost. You may end up at Example 2.4.8, telling you that you need to flip backward now. But how far? Will it be one page earlier or twenty?

For a more expansive discussion along these lines, see Section 26.3.

Also, as an author, recognize that there is a very flexible mechanism for making lists of objects that may be included in the <backmatter> (or elsewhere). To continue the example here, you could make a list of all the examples in the book, and a separate list of all the remarks. 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.

If you have errors when you run pdflatex or 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 (<m>, <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.sty in 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 6.5), and also carefully examine the HTML output. If that does not reveal the problem, seek expert help.

Success with a tool like the PreTeXt-CLI (see Section 5.2), 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 the PreTeXt-CLI, 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 6 and Appendix E.

If you were somehow able to mix-in a dollar sign into your PreTeXt document, how would you then write “The bus ride cost me $2.50”? The LaTeX solution, \$, is not going to help you. It is a shortcoming of TeX that so many characters have special meanings in certain circumstances.

If you insist, you can still author using $…$ and \[…\], and before processing do a global search-and-replace. But converting a leading $ to <m> and a trailing $ to </m> will drive you mad unless you are really good with regular expressions. So perhaps better to use \( and \) for inline mathematics and search-and-replace will go better. I count six keypresses for that, including the shifts for the parentheses, while it just takes me seven keypresses for the PreTeXt <m> element, when I use an editor that auto-completes elements with a two-key combination.

We realize change is hard—we used LaTeX for thirty years. But we believe the long-term advantages of PreTeXt markup are worth the short-term rearrangements.

TeX was first released in 1978. There was no Internet, no HTML, no Unicode, and no YouTube. There have been many attempts to convert TeX/LaTeX to more modern document formats. They are not hard to find—none is satisfactory. We know because we have spent many years trying to adapt them to our purposes.

Many laud LaTeX for its ability to separate content from presentation. The key word is ability. It is possible to use LaTeX in a purely semantic way. But it very rarely happens in practice. And we suspect that when it does, the result looks much like XML anyway, such as the use of many \begin{}/\end{} pairs. LaTeX allows authors enough freedom that it is impossible to accurately discern intent in a totally automated way.

By contrast, an XML vocabulary defined by a schema (i.e. PreTeXt) forces authors to communicate intent and denies authors the opportunity to micro-manage presentation. The result is automated conversions to many useful output formats with no extra effort from the author, including future conversions to formats not yet imagined. And XSL, once understood, is a robust and powerful tool for the sorts of text-manipulation tasks necessary.

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.

When you process XML, the less-than character, <, is a signal that the name of an opening or closing tag is coming next. How do you prevent this if you really need the character, especially for something like computer code? Answer: you use the “escaped” version, <. The ampersand is known as an escape character. It is a signal to the processor to escape from its usual rules. “But,” I hear you say, “we just gave the ampersand character a special meaning, now how do I get that character when I need to say ‘I went to the A&P store.’?” Simple—there is an escaped version, &.

So think of < and & as being the characters < and &. End of story. These two concessions should “work” throughout your PreTeXt source and in every conversion. Every markup language needs, and uses, an escape character, but XML and PreTeXt have you covered and really only need these two (infrequent) exceptions.

It is worth repeating: think of the escaped versions of the characters as actually being the characters themselves. That is the way the XML processor sees them and uses them. For more, see Section 3.14, Section 3.16, Subsubsection 4.1.4.2, Section 4.4, and Subsection 4.29.4.

Postscript: XML has the escaped characters &gt, &apos, and &quot for >, ', and " (respectively). But they are rarely (never?) necessary within PreTeXt.

Extra-credit homework: think about how some of the above was authored and then look at the source to grade your own work.

Use shorter titles? Read too about the @width hint for list items within Section 4.11.

Or convert your list to an <ol> or <ul>. The titles will now render more like their own paragraphs.

There are subtle and minor variations and restrictions around the interpretation of LaTeX syntax by LaTeX itself and the MathJax Javascript routines for rendering in a web page. Work backwards from Subsection 4.9.19 for details.

See Subsection 4.21.1 for an explanation.

See Subsection 4.21.1 for an explanation.

First, we know some aspects of processing are inefficient and therefore slow for large projects. We are working on it.

Your PreTeXt source is not a program, nor is it LaTeX, which can also be a program. So the idea of “commenting out” code, or mimicking conditional use of LaTeX’s \include{} command, are injurious to your PreTeXt source. Processing expects to see all of it. Some aspects of producing output demand it.

We have the notion of a version which can eliminate some (large) portions of your source in controlled ways (see Section 27.2). Processing tools, such as the PreTeXt-CLI and the pretext/pretext Python script support the notion of restricting some processing to a subtree of your source, without hiding parts of your source from the processor. See Section 47.10 for how to do this with the pretext/pretext Python script.