HTML and PDF versions can be found at
Go to file
Ralph Little 896ba2c60a Merge branch 'fix-errata' into 'master'
Fix two minor errata

Closes #9

See merge request sane-project/standard!1
2023-10-15 04:52:55 +00:00
_static/css Tweak styling of content and tables 2019-11-30 11:30:11 +09:00
figs Apply "Remove *.eps figures" 2020-01-31 20:38:31 +09:00
.editorconfig .editorconfig: trim trailing whitespace 2019-10-14 13:40:37 +09:00
.gitignore Add GitLab CI configuration 2019-11-30 11:32:17 +09:00
.gitlab-ci.yml Fix CI test jobs for SANE standard 2023-10-13 04:42:40 +00:00 Add a list of per version changes to the standard 2020-02-10 10:38:47 +09:00 Add a check for broken or redirecting external links 2020-02-15 11:53:20 +09:00
api.rst Allow member `desc` to be valid for group options 2023-10-13 15:12:55 +09:00 Add author names (based on info from sane-backends/AUTHORS). 2020-03-05 21:13:18 +09:00
contact.rst Drop www. prefix from the SANE home page's URL 2020-02-15 15:38:45 +09:00
environment.rst Fix missing quote in markup 2020-07-12 17:30:05 +09:00
index.rst Fix unexpanded numref 2020-04-19 16:39:01 +09:00
introduction.rst Split document on chapter level 2019-11-30 11:32:14 +09:00
net.rst Fix CI test jobs for SANE standard 2023-10-13 04:42:40 +00:00
preface.rst Fix spelling issues 2020-02-15 17:50:53 +09:00
requirements.txt Add spell checking support 2020-02-15 17:11:52 +09:00
wordlist.txt Fix spelling issues 2020-02-15 17:50:53 +09:00

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

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.