Skip to content

Restructure the documentation, and draw the symbols so they scan - #2

Merged
smnandre merged 1 commit into
ateliersvg:mainfrom
smnandre:docs/restructure-and-figures
Aug 13, 2026
Merged

smnandre merged 1 commit into
ateliersvg:mainfrom
smnandre:docs/restructure-and-figures

Conversation

@smnandre

Copy link
Copy Markdown
Contributor

Two commits, kept apart because they answer different questions, but shipped
together because the second only touches files the first creates.

Restructure the documentation

Rewrites the README around what the package does rather than around its class
list, drops the "See also" blocks that repeated the navigation, and adds
installation.md, options.md and renderers.md. Two figures per symbology,
both referenced from docs/code/<slug>.md: the canonical symbol, and one option
that changes what the reader sees. An option only earns a figure where it is
legible as a picture, so a scale change gets a sentence and a quiet zone, a bar
width ratio or an error correction level gets a drawing.

Draw the example symbols dark on a light ground

The figures were drawn in currentColor on a transparent ground so they would
inherit whatever page they landed on. That inverts them wherever the page is
dark: the documentation site on its dark theme, and GitHub on its dark theme,
which is where these same files are read.

A symbol is defined by its reflectance. A decoder finds it by that polarity,
locking onto the finder patterns of a matrix code or the guard bars of a linear
one. Inverted, it looks like a barcode and does not scan, so a page showing one
to say "this package encodes barcodes" was showing a drawing of one.

The QR figures also take the four-module quiet zone ISO/IEC 18004 requires,
where they had two. The DataMatrix figures keep theirs: ISO/IEC 16022 asks for
one module, which they already clear, and widening it would only shrink the
symbol inside the same box.

Verified by sampling the rasterised output on the module grid rather than by
eye: quiet zone clear on all four sides, the three finder patterns exact to the
module, timing pattern alternating.

Regenerated with tools/barcode/generate-examples.php, which now carries the
reason in its header so the next person does not restore currentColor.

The figures were drawn in currentColor on a transparent ground so they would
inherit whatever page they landed on. That inverts them wherever the page is
dark: the documentation site on its dark theme, and GitHub on its dark theme,
which is where these same files are read.

A symbol is defined by its reflectance. A decoder finds it by that polarity,
locking onto the finder patterns of a matrix code or the guard bars of a linear
one. Inverted, it looks like a barcode and does not scan, so a page showing one
to say "this package encodes barcodes" was showing a drawing of one.

The QR figures also take the four-module quiet zone ISO/IEC 18004 requires,
where they had two. The DataMatrix figures keep theirs: ISO/IEC 16022 asks for
one module, which they already clear.

Regenerated with tools/barcode/generate-examples.php. Verified by sampling the
raster on the module grid: quiet zone clear, three finder patterns exact,
timing pattern alternating.
@smnandre
smnandre merged commit 0c121bb into ateliersvg:main Aug 13, 2026
5 checks passed
@smnandre
smnandre deleted the docs/restructure-and-figures branch August 13, 2026 18:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant