Skip to main content

The PreTeXt Guide

Section 32.3 The Author Interface

Subsection 32.3.1 Author Interface Basics

The author interface is a web-based interface that allows you to manage your book on Runestone Academy. It is designed to be easy to use and provides a number of features to help you manage your book.
The author interface is available at author.runestone.academy. You can log in with your Runestone account. Once you have logged in you will see a list of your books. You can click on the book title to to edit metadata about your book. The author interface is also where you can build a new version of your book, see some analytics about your book, and publish your book to the Runestone Academy servers. You can even get an anonymized data set from a large sample of the classes using your book.
The author interface lets you pull changes from github and rebuild your book.
Figure 32.3.1. The author interface main page
The main page of the author interface gives you access to all of the different functions. Clicking on the build button pulls the latest source from github and builds your book. If you have a large book this can take a few minutes. When the build is complete you deploy your book to the runestone servers. You will see the build status change at the bottom of the page. If there is a failure for any reason you can usually see the cause by clicking the button to view the latest log.
Another feature of the author interface is to provide you with some analytics. This page shows you the number of students that have enrolled in a course using your book year to date. It also shows you usage patterns for the book by the week of the course. You can click on any of the shaded cells to drill down and see how students are viewing the sections of each chapter.
An impact report for Foundations of Python Programming
Figure 32.3.2. Some example analytics for your book
The Analytics are in their early stages so we encourage you to contact us with ideas for what kinds of data you would find useful.
If you click on the book’s identifier you will be able to edit metadata about the book. This is reflected in our library page so you can change the shelf section or update the blurb that describes your book to an audience. The Available for courses and Visible to Everyone in the Library checkboxes allow you to control the visibility of your book. If you are in the early stages of development you probably do not want others to see the book, but you can always view it via a direct link. When you are ready to make your book available to the world you can check the Visible to Everyone box and your book will appear in the Runestone Library. When you are ready to let others create a course around your book you can check the Available for Courses box. This will allow others to create a course using your book as the textbook. You can always change these settings later.
Editing metatdata about a book
Figure 32.3.3. Editing a book’s metadata

Subsection 32.3.2 Advanced Author Interface

The author interface also provides a number of advanced features to address the following scenarios:
  • Your repository and your <document-id> do not match.
  • Your repository is structured so that your project.ptx file is not in the root of your repository.
  • You have a single repository with more than one book.
  • You want to produce multiple books from a single repository using the PreTeXt versions feature.
If your repository name and your document-id do not match you will need to fill out the the path to an existing repo field so that it matches what you checked out from github.
If your repository is structured so that your project.ptx file is not in the root of your repository you will need to configure the path to the project.ptx file. This is done by filling in the field for the path to the project.ptx file. This should be a relative path from the root of your repository to the project.ptx file.
If you have a single repository with more than one book you will need to do the following steps.
  1. Create a new book for book number 1 on the main author page using the Github URL to your repository.
  2. Make sure you have a target in your project.ptx file for this book and it is configured to use the publication file you created for Runestone.
  3. Edit the metadata for your book in case any of the other advanced configuration situtations apply.
  4. To create book number 2 on the main author page use the existing repo field. This should be /books/<your-repo-name>. Leave the Github URL field blank.
  5. Depending on how your repository is structured you may need to make sure you have a second target for the second book with a different output folder configured and a different document-id. Alternatively you may have an entirely separate project.ptx file for the second book in a different folder of your repository. In this case you need to fill in the field for the path to the project.ptx file.
If you have a single repository and want to build two books using different versions then the process is the same as above, but you will need to have a second publisher file with the appropriate version information so that you will get a different output. This includes using the @component on the <document-id> element. This will allow you to have two different books in the same repository with different document-ids.