PreTeXt Author’s Guide PreTeXt Author’s Guide Robert A. Beezer University of Puget Sound DRAFT June 28, 2019 DRAFT ©2013–2016 Robert A. Beezer Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation 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 This guide will help you author a PreTeXt document. So it serves as a description of the PreTeXt xml vocabulary, along with the mechanics of creating the source and common output formats. Note that this is different than publishing your document, which is described in the PreTeXt 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. v Contents Preface v 1 Start Here 1 1.1 Philosophy..............................................1 1.2 Formatting Your Source.......................................2 1.3 Where Next?.............................................3 2 A Careful, Quick, Minimal Example4 2.1 Authoring...............................................4 2.2 Setup.................................................5 2.3 Processing...............................................5 2.4 Extending the Minimal Example..................................6 2.5 Where Next?.............................................8 3 Overview of Features 9 3.1 Structure...............................................9 3.2 Paragraphs..............................................9 3.3 Cross-References........................................... 10 3.4 Titles................................................. 10 3.5 Mathematics............................................. 11 3.6 Images................................................. 11 3.7 Lists.................................................. 12 3.8 Exercises............................................... 12 3.9 Worksheets.............................................. 13 3.10 References............................................... 13 3.11 Figures and Tables.......................................... 13 3.12 Programs and Consoles....................................... 13 3.13 Special Characters.......................................... 14 3.14 Verbatim and Literal Text...................................... 14 3.15 Sage.................................................. 14 3.16 Side-by-Side Panels.......................................... 15 3.17 Mathematical Results........................................ 15 3.18 Front Matter............................................. 15 3.19 Back Matter.............................................. 15 3.20 Index and Notation Entries..................................... 15 3.21 WeBWorK Exercises......................................... 16 3.22 URLs and External References................................... 16 3.23 Video................................................. 16 3.24 Scientific Units............................................ 16 3.25 Accessibility.............................................. 17 vi CONTENTS vii 4 Processing, Tools and Workflow 18 4.1 Basic Processing........................................... 18 4.2 Modular Source Files......................................... 18 4.3 Verifying your Source........................................ 19 4.4 Customizations, String Parameters................................. 20 4.5 Customizations, Thin XSL Stylesheets............................... 20 4.6 Images and the mbx Script...................................... 21 4.7 Author Tools............................................. 21 4.8 Keeping Your Source Up-to-Date.................................. 22 4.9 File Management........................................... 24 4.10 Testing HTML Output Locally................................... 25 4.11 Doctesting Sage Code........................................ 26 4.12 Building Output in CoCalc..................................... 26 5 PreTeXt Vocabulary Specification 27 5.1 RELAX-NG Schema......................................... 27 5.2 Schematron Rules........................................... 28 5.3 Versions of the Schema........................................ 28 5.4 Reading RELAX-NG Compact Syntax............................... 29 5.5 Validation............................................... 29 5.6 Schema Browser........................................... 30 5.7 Editor Support for Schema..................................... 30 6 (∗) Topics 31 6.1 Paragraphs.............................................. 31 6.2 (∗) Exercises, Inline and Divisional................................. 39 6.3 (∗) Worksheets............................................ 39 6.4 (∗) Lists of Works Cited (References)................................ 39 6.5 Verbatim and Literal Text...................................... 39 6.6 Cross-References and Citations................................... 40 6.7 Divisions................................................ 44 6.8 Mathematics............................................. 44 6.9 Lists.................................................. 48 6.10 Exercises and their Solutions.................................... 52 6.11 Images................................................. 53 6.12 (∗) Tables and Tabulars....................................... 55 6.13 (∗) Program Listings......................................... 55 6.14 Side-by-Side Panels.......................................... 55 6.15 (∗) Front and Back Matter..................................... 56 6.16 Index................................................. 56 6.17 (∗) Notation.............................................. 59 6.18 (∗) Automatic Lists.......................................... 59 6.19 URLs and External References................................... 59 6.20 Video................................................. 60 6.21 (∗) Music............................................... 63 6.22 (∗) Units of Measure......................................... 63 6.23 Unicode Characters.......................................... 63 6.24 (∗) Testing Sage Examples...................................... 64 6.25 Xinclude Modularization....................................... 64 6.26 Accessibility.............................................. 65 7 Authoring Advice 68 7.1 Writing Your Student-Friendly Math Textbook.......................... 68 CONTENTS viii 8 The mbx Script 70 8.1 Running mbx ............................................. 70 8.2 Example Use............................................. 70 8.3 Strategy................................................ 71 8.4 Debugging Image Generation.................................... 71 8.5 Restricting the Scope......................................... 71 8.6 Configuring External Helper Programs............................... 72 8.7 Output................................................ 72 8.8 mbx Capabilities............................................ 72 8.9 mbx on Windows........................................... 72 8.10 Python requests Library...................................... 73 9 WeBWorK Exercises 74 9.1 WeBWorK Problems......................................... 74 A Welcome to the PreTeXt Community 78 A.1 Help and Support........................................... 78 A.2 Feature Requests and Reporting Problems............................. 79 A.3 Contributing............................................. 79 A.4 Personal Email............................................ 79 B FAQ: Frequently Asked Questions 81 Glossary 85 C Best Practices 88 D Conversion from LATEX 89 E Text Editors, Spell Check 90 E.1 Sublime Text............................................. 90 E.2 Aspell................................................. 97 E.3 emacs................................................. 98 E.4 XML Copy Editor.......................................... 98 E.5 vi, vim................................................. 98 F Schema Tools 99 F.1 Jing and Trang............................................ 99 F.2 Schematron.............................................. 101 G Revision Control: git 102 H Windows Installation Notes 103 H.1 Setup................................................. 103 H.2 Installing xsltproc.......................................... 105 H.3 Installing git............................................. 107 H.4 Installing Anaconda......................................... 108 H.5 Installing ImageMagick....................................... 108 H.6 Installing Ghostscript........................................ 109 H.7 Installing pdf2svg .......................................... 109 H.8 Installing jing............................................. 110 H.9 What’s Missing............................................ 111 I Windows Subsystem for Linux 112 CONTENTS ix J The PreTeXt Vagrant box 114 K GNU Free Documentation License 117 References 123 Index 124 Chapter 1 Start Here 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, please read the Welcome to