## Chapter10Author FAQ: Frequently Asked Questions

Technical questions first, followed by questions about markup.

1. ###### On my local machine, why is the not working?

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.

2. ###### How do I install xsltproc on Ubuntu or Debian Linux?

sudo apt-get install xsltproc

3. ###### How do I install pdf2svg?

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.

4. ###### 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.

5. ###### Can I create PreTeXt source in Microsoft Word or Google Docs?

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.

6. ###### 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 --xinclude switch on the command-line when you ran xsltproc. (See Section 5.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.)

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

8. ###### I have not updated in months, so I did a pull, and now I have a bunch of warnings. How do I catch up?

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.

9. ###### How do I put mathematics into my list labels?

First, realize that the way 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 @label attribute 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 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.

10. ###### 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 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.

11. ###### 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 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 31.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.

12. ###### Why do I have LaTeX errors?

If you have errors when you run pdflatex or xelatex, that is more likely to be caused by a problem with your 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 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 . 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.

13. ###### 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 6 and Appendix E.

14. ###### Why not LaTeX? Why PreTeXt?

was first released in 1978. There was no Internet, no HTML, no Unicode, and no YouTube. There have been many attempts to convert / 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 for its ability to separate content from presentation. The key word is ability. It is possible to use 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. 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.

15. ###### 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.

16. ###### I'm a little confused about the less-than character, the ampersand, and “escape characters” in general.

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, &lt;. 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, &amp;.

So think of &lt; and &amp; 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.13, Section 3.15, Subsubsection 4.1.4.2, Section 4.5, and Subsection 4.22.2.

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.

17. ###### The labels of my description list are long, and the formatting is really bad..

Use shorter label text? Read too about the @width hint for list items within Section 4.10.

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

18. ###### My math looks great in one output format (LaTeX or HTML) but is causing errors or looks bad in another output format (HTML or LaTeX). What's up?

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