The PreTeXt Guide The PreTeXt Guide Robert A. Beezer University of Puget Sound David Farmer American Institute of Mathematics Alex Jordan Portland Community College Mitchel T. Keller Morningside College September 21, 2021 ©2013–2019 Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Docu- mentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”. Preface Introduction. This part is the place to begin if you are new to PreTeXt. Chapter 1 is the introduction, overview, and philosophy. Then Chapter 2 intends to get you started quickly by authoring a simple example and converting it to HTML and PDF output formats. Author’s Guide. This guide will help you author a PreTeXt document. So it serves as a description of the Pre- TeXt XML vocabulary, along with the mechanics of creating the source and common output formats. Chapter 3 is meant to be a short overview of the majority of PreTeXt’s features, which can be skimmed to get a sense of Pre- TeXt’s capabilities. Or it can be read quickly as you begin authoring and you can return as you need certain fea- tures. The roughly parallel Chapter 4 is much more comprehensive and is the first place to go for details not ad- dressed in the overview. Note that the Author’s Guide is not concerned with publishing your document, which is described in the Publisher’s Guide. Basic Reference. This part provides a quick overview of the minimal syntax for a variety of key PreTeXt features. Unlike the sample article, which is designed to demonstrate and stress test all aspects of PreTeXt, this guide will illustrate only the key elements of some of the most universally-used features of the language. In many cases, in addition to features not discussed, there may be alternative structures that are not given here. Publisher’s Guide. Even if you intend to distribute your document with an open license, and you are both author and publisher, it is still helpful and instructive to understand, and separate, the two different steps and roles. So visit this part of the Guide to learn how you can present, distribute, and maintain what you have authored. Developer’s Guide. This part provides advice, suggestions, and conventions for contributing to PreTeXt. For anything not answered here please use the pretext-dev¹ Google Group. Make a membership request and it will be processed quickly. Appendices. In addition to the usual items you might expect in the back matter, such as an open license, glos- sary, references, and an index, there are numerous more specialized additions, mostly describing the installation of, or effective use of, various technical tools that are independent of PreTeXt (but useful or necessary). ¹https://groups.google.com/forum/#!forum/pretext-dev iv Contents Preface iv I Introduction 1 Starting 2 2 Getting Started Tutorial 6 II Author's Guide 3 Overview of Features 12 4 Topics 23 5 Processing, Tools and Workflow 79 6 PreTeXt Vocabulary Specification 91 7 WeBWorK Exercises 95 8 Authoring Advice 101 9 Author FAQ: Frequently Asked Questions 103 III Basics Reference 10 About This Reference 108 v ☙ Contents ❧ vi 11 Basic Formatting 109 12 Document Structure 110 13 Mathematics 112 14 Lists 114 15 Blocks 116 16 Exercises 122 17 Worksheets 131 18 Renaming Elements 135 19 Figures and Friends 136 20 Tables 142 21 SageMath Content 145 22 Small, But Useful 147 23 Modular Source 150 IV Publisher's Guide 24 (∗) Producing a Book 152 25 Copyright and Licensing 154 26 Conversions, Generally 159 27 Conversion to Online HTML 163 28 Conversion to PDF and Print 169 29 Conversion to EPUB/Kindle 174 ☙ Contents ❧ vii 30 Conversion to Runestone 176 31 Conversion to Slides 178 32 (∗) Conversion to Jupyter Notebooks 180 33 Instructor's Version 181 34 Ancillaries 183 35 WeBWorK Exercises 187 36 Hosting Your Online Version 193 37 LATEX Fonts 195 38 LATEX Styles 200 39 (∗) Cover Design 206 40 Publisher File Reference 207 41 Print-On-Demand 214 42 Publisher FAQ: Frequently Asked Questions 216 V Developer's Guide 43 Processing with xsltproc 219 44 The pretext Script 226 45 Coding Conventions 232 46 Debugging 234 47 Git 236 ☙ Contents ❧ viii Appendices A Welcome to the PreTeXt Community 241 B Best Practices 244 C Python 245 D Text Editors, Spell Check 247 E Schema Tools 261 F Offline MathJax 264 G Revision Control: git 266 H Conversion from LATEX 267 I MacOS Installation Notes 268 J Windows Installation Notes 269 K Windows Subsystem for Linux 276 L Example List of Notation 278 M GNU Free Documentation License 279 Back Matter Glossary 285 References 288 Index 289 Part I Introduction 1 Chapter 1 Starting Welcome to the Author’s Guide for PreTeXt. You are likely eager to get started, but familiarizing yourself with this chapter should save you a lot of time in the long run. We will try to keep it short and at the end of early chapters we will guide you on where to go next. Not everything we say here will make sense on your first reading, so come back after your first few trial runs. When you are ready to seek further help, or ask questions, pleasereadthe Wel- come to the PreTeXt Community in Appendix A. 1.1 Philosophy PreTeXt is a markup language, which means that you explicitly specify the logical parts of your document and not how these parts should be displayed. This is very liberating for an author, since it frees you to concentrate on capturing your ideas to share with others, leaving the construction of the visual presentation to the software. As an example, you might specify the content of the title of a chapter to be Further Experiments, but you will not be concerned if a 36 point sans-serif font in black will be used for this title in the print version of your book, or a CSS class specifying 18 pixel height in blue is used for a title in an online web version of your book. You can just trust that a reasonable choice has been made for displaying a title of a chapter in a way that a reader will recog- nize it as a name for a chapter. (And if all that talk of fonts was unfamiliar, all the more reason to trust the design to software.) You are also freed from the technical details of presenting your ideas in the plethora of new formats available as a consequence of the advances in computers (including tablets and smartphones) and networks (global and wireless). Your output “just works” and the software keeps up with technical advances and the introduction of new formats, while you concentrate on the content of your book (or article, or report, or proposal, or …). If you have never used a markup language, it can be unfamiliar at first. Even if you have used a markup language before (such as HTML or basic LATEX) you will need to make a few adjustments. Most word-processors are WYSI- WYG (“what you see is what you get”). That approach is likely very helpful if you are designing the front page of a newspaper, but not if you are writing about the life-cycle of a salamander. In the old days, programs like troff and its predecessor, RUNOFF (1964), implemented simple markup languages to allow early computers to do limited text-formatting. Sometimes the old ways are the best ways. PreTeXt is what is called an XML application or an XML vocabulary (I prefer the latter). Authoring in XML might seem cumbersome at first, but you will eventually appreciate the long-run economies, so keep an open mind.And if you are already familiar with XML, realize we have been very careful to design this vocabulary with human au- thors foremost in our mind. Principles. The creation, design, development and maintenance of PreTeXt is guided by the following list of prin- ciples. They may not be fully understood on a first reading, but should be useful as you become more familiar with authoring texts with PreTeXt and should amplify some of the previous discussion. 2 1.2 ☙ Formatting Your Source ❧ 3 List 1.1.1 PreTeXt Principles 1. PreTeXt is a markup language that captures the structure of textbooks and research papers. 2. PreTeXt is human-readable and human-writable. 3. PreTeXt documents serve as a single source which can be easily converted to multiple other formats, cur- rent and future. 4. PreTeXt respects the good design practices which have been developed over the past centuries. 5. PreTeXt makes it easy for authors to implement features which are both common and reasonable. 6. PreTeXt supports online documents which make use of the full capabilities of the Web. 7. PreTeXt output is styled by selecting from a list of available templates, relieving the author of the bur- den involved in micromanaging the output format. 8. PreTeXt is free: the software is available at no cost, with an open license. The use of PreTeXt doesnot impose any constraints on documents prepared with the system. 9. PreTeXt is not a closed system: documents can be converted to LATEX and then developed using standard LATEX tools. 10. PreTeXt recognizes that scholarly documents involve the interaction of authors, publishers, scholars, in- structors, students, and readers, with each group having its own needs and goals.