How to View Edits

(Significant portions of the text in this post were adapted from a 2021 article by Evon for Lidar Magazine)

The LAS specification’s raw format is a set of text files encoded with mostly Markdown formatting and a sprinkling of LaTeX. By storing the raw format as text instead of binary (such as the Microsoft Word *.docx format) we can leverage the power of Git and GitHub to show line-by-line differences and merge multiple versions together with minimal effort.

Despite the convenience of maintaining plain text files, however, a static and versioned PDF is far easier to read, reference and cite when one is using the specification for development, contracting, and standards. Therefore, we need some sort of automated system for conveniently converting the plain text files into PDFs, preferably with zero manual effort and minimal maintenance.

This repo leverages GitHub Actions to create a virtual machine configured in the scripts folder and run Sphinx every time a new commit is made to the official ASPRSorg GitHub repository:

A few minutes later, a draft PDF is available directly on GitHub Actions as a downloadable attachment called an Artifact:

These PDFs are temporary objects that stay available for 60 days, after which they disappear. They can be recreated on-demand by rerunning the GitHub Action:

By following these steps you can easily visualize the incremental changes that you've made to the specification before final publication.