PreTeXt + GIT training materials

[Dan Baker]

(posted on behalf of Will Haynes)

We need to get all authors set up with the tools necessary to use PreTeXt.    Here’s what everyone needs:

XML Editor:  PreText files are text files so you will want to edit them with a text editor, not a word processor, and PreText files are XML documents, which means that the text is marked up with tags like <chapter> or <example> or <p> for paragraph, much like HTML.  XML is very particular about the tags so your editor should be XML aware in order to help you type them in the right places, and warn you if you have them out of place.  I use OxygenXML which is $99 for educational use.   Atom (https://atom.io) is a free alternative. 

PreTeXt Schema:  The Pretext Schema is an XML document which describes the correct XML syntax of a PreTeXt document.  Your editor refers to this schema to know what tags are allowed where and to help you produce valid documents.

XSLT files:  XSLT files describe the transformation which turns a valid PreTeXt document into a webpage, ebook, or pdf.  The preTeXt team provides and continually improves the schema and XSLT files.

XSLT Processor:   An XSLT processor is a command-line tool which applies an XSLT stylesheet to a one or more PreTeXt files to convert them into webpages, ebooks and pdf files.  The recommended processor is xsltproc, which is free.

Version Control System:   A version control system is a tool which tracks files and manages revisions and coordinates contributions by multiple authors.  We will be using Git as our version control system.  Git is free. 

TO DO:

1. Fill out the skills form found here:  https://goo.gl/forms/EcRpC1xlZE9Nfbir2
   
2. Set up your computer for preTeXt development, and try to produce the sample documents.
1. You will need to install Git if you don’t already have it.  Instructions are here:  https://git-scm.org
2. Follow the Quickstart directions on the PreTeXt website:  https://pretextbook.org/quickstart.html. 
3.   If you run into problems getting set up, we need to get them straightened out first thing.  
3. Once the GitHub account is set up, we can start experimenting with collaborative editing using Git.   The process is described in Git for Authors https://pretextbook.org/gfa/html/.

Feel free to follow up with questions/comments related to this post.

[Dan Baker]

We had a snow day here in Northern Colorado so I found some extra time to get to know Git. I think my two biggest breakthroughs have been:

1. Using a GUI interface (instead of the command line Git Bash) to use Git. I've initally been using SmartGit. Command line vs GUI is a personal choice, but I'm more a visual person and also benefit from not having to remember all the commands.
2. Getting familiar with the basic workflow (based on Ch 1-3 of https://pretextbook.org/gfa/html/git-for-authors.html)
1. cloning from the definitive repository (GitHub) to my local machine, 
2. working from branches, 
3. always updating my local master (from the definitive @ GitHub)*** (key step) 
4. (if changes exist from #3) rebase working branches to tip of local updated master (I believe SmartGit calls this the 'Rebase HEAD to' (as opposed to 'to HEAD'), then
5. merge branches into my local master and 
6. finally pushing local improved master to the definitive

Feel free to add your own breakthroughs on Git or the other topics Will outlined above.

Dan