896ba2c60a
Fix two minor errata Closes #9 See merge request sane-project/standard!1 |
||
|---|---|---|
| _static/css | ||
| figs | ||
| .editorconfig | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| CHANGELOG.md | ||
| README.md | ||
| api.rst | ||
| conf.py | ||
| contact.rst | ||
| environment.rst | ||
| index.rst | ||
| introduction.rst | ||
| net.rst | ||
| preface.rst | ||
| requirements.txt | ||
| wordlist.txt | ||
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.