Section 2.2 Example Projects
We are now ready to create our first PreTeXt project. First, let's run through the steps to start a new book, and see how to convert it to HTML and PDF. After that, we will create a very minimal article to explore the structure of a PreTeXt project.
Your First PreTeXt Book.
From a terminal, type:
This will create a new folder at your current location called new-pretext-project. The folder contains the source files for your project (the files you will edit to add content to your book), as well as a folder for assets (such as external images you might put in your book), a folder for publication files (which describe some customizations for your book) and a project.ptx file that tracks options for different output targets.
Next, change directories to the new-pretext-project. In the terminal:
Now we build a version for the web (HTML) with the following command:
Finally, we can view the results of our conversion using this command, which starts up a simple web server so we can see all content:
The output from this command will give a URL to click on (and might even open your browser to that location) that should show you the web output. When you are done viewing, return to the terminal and hit CTRL+C to terminate the server.
To build and then view something suitable for print (PDF), you would enter the following two lines:
pretext build print
pretext view print
If you are building on a local machine, the view command should open your pdf viewer; on CoCalc you will get a web link for the print version. You can also directly open the file located at output/print/main.pdf
A Minimal Example.
Let's back up and create a simpler project to explore. First rename the new-pretext-project folder you just created to something like book-example, either using your file manager or in the terminal by doing the following (assuming you were still inside that folder):
cd ..
mv new-pretext-project book-example
Now enter:
This creates another new-pretext-project, and you can follow the directions above to navigate to it, build, and view it.
Time to look at the source. Open the file main.ptx in the source folder of your project. Make sure this opens in a text editor, and that you see something like this:
<?xml version="1.0" encoding="UTF-8"?>
<pretext>
<article>
<title>Hello World!</title>
<p>This is a PreTeXt document.</p>
</article>
</pretext>
This illustrates the structure of all PreTeXt documents. In particular, notice:
The first line says that the text file you are looking at is an
XML file. This should go at the top of every pretext file, including any that you later import.
The next line and the last line of the document are the start and end of the <pretext> tags. Every pretext document needs these to wrap all of their contents.
Inside those, we have <article> tags, since this is an article (and not a book, which would have <book> tags instead).
Then, inside the article, we have a title (the text of the title is wrapped in the <title> tags), followed by a paragraph (in <p> tags).
Notice how every opening tag (no slash) has a paired closing tag (with a slash, plus the identical name). Think of these tags as defining a box that holds either text content or other boxes (defined by a pair of opening and closing tags).
In the next section we will expand this minimal example by adding some additional content.
