sane-project-standard/README.md

SANE Standard

Converted from the original LaTeX version, this is the SANE Standard in reStructuredText format, for use with Sphinx. You can find the latest published version at

https://sane-project.gitlab.io/standard/

where you can also find links to HTML and PDF exports for all tagged versions and branches.

Building A Single Version

You can build HTML and PDF versions of the SANE Standard with one of

sphinx-build -M html . _build/
sphinx-build -M latexpdf . build/

This assumes an environment where not only the requirements are installed but also Sphinx itself and, for PDF output, a number of LaTeX related packages. For an example setup, please refer to the Dockerfile for the image used by this project's CI. While the example is Debian specific, it should be helpful in getting started on another distribution, if so inclined. Of course, using the Docker image that is used in CI is another option.

Building All Tagged Versions

The CI setup for this project publishes HTML and PDF versions for all tagged versions. You can create all these versions locally too.

In addition to everything that is needed to build the latest version, you will need to install the sphinx-versions Python package. If you installed everything listed in requirements.txt, you are all set.

The build itself is done with

CI=true sphinx-versioning build -P sane-standard.pdf . public/

Of course, all this can be found back in the .gitlab-ci.yml file as well.

How Did This All Come About

The SANE Standard was first released as part of sane-1.0.1. It was maintained in LaTeX format in two files, doc/sane.tex and doc/net.tex, and a small number of images created with xfig and kept below docs/figs/. When the sane package was split into two packages, sane-backends and sane-frontends, the SANE Standard ended up in the former. It was infrequently edited over time and occasionally the version was bumped (see the Changelog for details).

The SANE Project's website included an HTML and printable version of the SANE Standard. The printable version started out as a PostScript document but in the summer of 2016 a PDF version was added. There were a few problems with how the SANE Standard was maintained on the website however.

For one thing, all of the HTML, PostScript and PDF versions required manual updates whenever the SANE Standard changed. Second, the tool used to convert to HTML was no longer functional/available. Third, the HTML version looked extremely twentieth century or retro, if you wish, and was cumbersome to navigate.

In the fall of 2019, @paddy-hack set out to convert the SANE Standard to reStructuredText for use with Sphinx. He reconstructed the standard's commit history in a git repository of its own (in the latex-master and latex-draft-2 branches) and diligently worked his way through all commits converting one at a time (on the master and draft-2 branches). While taking utmost care to stay true to the LaTeX revisions and neither introduce nor fix mistakes, discrepancies in the reStructuredText version are to blame solely on @paddy-hack. The project was finally made public mid February 2020, after being interrupted by preparations for and release of sane-backends-1.0.29.