at main
1 folder
67 files
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Geometry drawings: devices, measurement layouts and the FDTD domain (#385)
* Geometry drawings: devices, measurement layouts and the FDTD domain
Extends the to-scale geometry API from the materials batch to the
devices and set-ups around them:
- Reactive silencers: side cuts of the expansion chamber (plain and
with extended tubes), the side-branch Helmholtz resonator (cavity
drawn as its equal-volume cube, volume annotated) and the
quarter-wave stub, using equivalent circular diameters 2 sqrt(S/pi).
ReactiveSilencerResult retains its constructor geometry and gains
plot_geometry().
- Image-source room plan: ImageSourceResult.plot_geometry() draws the
mirror-room lattice with images coloured by reflection order (low
orders on top), source and receiver marked.
- Barrier section: direct and diffracted paths over ground with the
path-length difference annotated; BarrierInsertionLoss retains the
five distances/heights and the optional thickness.
- Microphone position arrays: plot_microphone_positions() is the
library's first 3-D drawing (numbered points on a wireframe
hemisphere or sphere with the reflecting plane), fed directly by
measurement_positions()/precision_positions().
- Wall apertures: slit or circular section to scale with transmitted
wavefronts; ApertureTransmissionResult retains width/radius/depth.
- Baffled piston with its normalised far-field lobe at a chosen
frequency (RadiatingPistonResult.plot_geometry()).
- Plenum chamber: the box honours the line of sight r and its angle
exactly; outlet mouth to scale, wall area annotated.
- FDTD domain preview: FDTD2D.plot_geometry() draws the configured
domain before any time stepping (obstacles, sponge layers, impedance
and rigid edges, sources, optional probes); the solver now records
sponge_width, sponge_sides and edge_impedance as public read-only
configuration.
Six new public plot_*_geometry functions, 40 generated SVG variants
embedded in seven guides (EN/ES and the GitHub mirrors) with runnable
snippets, curated table and generated API pages updated, and 14 new
tests (retention round-trips, refusal paths, validation before any
figure is created, 3-D smoke).
* Address review: probes and frequency-index validation, immutable edge record
- plot_fdtd_domain validates probes before any figure exists.
- RadiatingPistonResult.plot_geometry bounds-checks frequency_index
with a descriptive ValueError.
- FDTD2D.edge_impedance is a MappingProxyType over a private copy.
- Plenum kwargs docstring matches where they are forwarded; the FDTD
preview prose no longer claims source-in-obstacle catching (the
solver already rejects that at add_source).
* Address static analysis: shared constants, extracted helpers, flat calls
- Silencer kinds, axis labels, legend placement and repeated messages
hoisted into module constants; identical EN/ES strings dropped from
the translation table.
- plot_silencer_geometry split into per-kind validators (and its
artist kwargs removed, matching the geometry-dict entry point);
_draw_hr_cavity and the FDTD sponge/edge painters extracted.
- Aperture opening computed without a nested conditional; exception
tests build their arrays outside pytest.raises.
- Regenerated API pages for the touched docstrings.
* Split the side-branch dimension resolution out of the drawing routine
Keeps _draw_branch_silencer under the cognitive-complexity threshold;
drawing output unchanged.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Geometry drawings: to-scale device cross-sections for materials (#381)
* Geometry drawings: to-scale device cross-sections for materials
New rendering module with drafting primitives (dimension lines with
extension leaders, material fills, microphone/loudspeaker symbols,
cross-section emblems) and six to-scale drawings:
- Layered absorber stack (porous/air/perforated/MPP/membrane), with
each layer dimensioned and the hole pattern of perforated plates
drawn at its real pitch.
- Square-section Helmholtz resonator.
- One period of the slit metamaterial absorber (slow-sound panel).
- QRD well profile from qrd_well_depths.
- ISO 10534-2 impedance tube and ASTM E2611 transmission tube: side
views at true scale with microphone positions, sample, termination,
cross-section emblem and the plane-wave working range.
API: layer dataclasses and HelmholtzResonator gain .plot();
LayeredAbsorberResult, SlitResonatorAbsorberResult,
DiffuserPolarResponse, ImpedanceTubeResult and TransferMatrix gain
.plot_geometry() with the defining geometry retained on the result
(trailing optional fields, backward compatible); six public
plot_*_geometry functions cover design-time drawing before any
computation. All drawings are bilingual and validate inputs before
touching matplotlib.
24 generated SVG variants, guide embeds (EN/ES and the GitHub
mirrors) with runnable snippets, curated API table rows and generated
API pages, and 16 new tests (smoke, retention round-trips, to-scale
checks, refusal paths for hand-built results).
* Address review: QRD pitch, sequence contract, language and bounds validation
- The drawn N = 7 QRD keeps the published 3.6 m total width: an 85.7 mm
pitch split into an 80.7 mm well plus a 5 mm fin (figure, snippets and
alt texts updated).
- plot_absorber_stack and plot_slit_absorber_geometry normalise any
Sequence, matching their advertised contracts.
- The six module-level renderers validate language and reject
non-positive diameter/sample_thickness before creating any figure;
layer-type dispatch moved ahead of axes creation.
- DiffuserPolarResponse docstring: well_width/periods are always
retained by the predictor; only depths distinguishes the
explicit-reflection path.
* Address static analysis: float comparisons, literal hoist, flat conditionals
- _dim: tolerance-based checks instead of float equality for the span
and the offset.
- Incident-sound label computed once per arrow.
- Tube emblem shape extracted from the nested conditional.
- Exception tests build their fixtures outside pytest.raises.
- Regenerated API page for the DiffuserPolarResponse docstring.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Make the documentation reachable and describe what it actually covers (#368)
* Make the documentation reachable and describe what it actually covers
The site was built to be cited and was hard to reach. Two things were doing
most of the damage: the machine-readable layer still described the fractional
octave filter bank the project began as, and the two strongest pieces of
evidence it owns were not published on it at all.
Evidence
- /reference/conformance/ renders the numerical report itself, every table,
instead of describing it and linking to GitHub. /reference/errata/ publishes
the registry of defects found in published standards. Both are transplanted
from their source documents by make site-reports, with a CI drift gate, in
both languages.
- An About page names who maintains the library, with the ORCID, Scholar,
ResearchGate and GitHub identities as visible links rather than only inside
JSON-LD, and carries a citation block with the Zenodo DOI.
- A /guides/ hub and a reference glossary of 120 quantities, each with its
symbol, unit, defining standard and implementing guide, marked up as a
DefinedTermSet.
Scope
- The SoftwareApplication and WebSite descriptions, featureList and keywords
are derived from the nine documented areas, so they follow the landing page
instead of contradicting the meta description on the same page.
- llms.txt is generated from the documentation tree. The hand-kept list named
42 of 221 English pages and the generator now fails if a page cannot be
placed. The full text is also published one file per area, since the single
file is far past what most clients will read.
- The conformance counts are imported from the generated report, and a check
fails the build if any page states a different number.
Structured data
- One @graph per page instead of a script per node, so the @id references
resolve for a plain JSON-LD processor and not only for Google.
- Breadcrumbs come from the navigation tree: 414 of 442 pages were naming
grouping prefixes that are not routes, with machine-titlecased labels in
both locales.
- datePublished is the commit that added a page, not the one that last touched
it. Guides are dual-typed as LearningResource, the generated API pages use
APIReference, and each page links its counterpart in the other language.
- Each page's typed bibliography reaches the structured data, with one stable
id per work so a standard is a single entity cited by many pages.
Extraction
- KaTeX no longer serializes the TeX source alongside the rendered formula, so
L_eq stops extracting as LeqL_{eq}Leq.
- A clean markdown copy of every page sits beside its HTML, advertised with
link rel=alternate: 31 kB against 388 kB for one guide.
- Figures declare their intrinsic size, and a theme pair no longer downloads
the palette the reader will not see.
- Every guide now states which clauses it covers and which it does not, which
the landing page already claimed of all of them and eight of sixty-six did.
* Serve the documentation media from the site instead of hotlinking
Every figure, animation and example fiche was loaded from
raw.githubusercontent.com. That host is not a CDN, it caches for five minutes
against the Pages origin's ten, it is rate limited, GitHub asks people not to
use it as an asset host, and the URLs were pinned to main, so renaming a
figure silently broke every published page that showed it.
A prebuild step stages the media from .github/images and .github/reports into
the site. SVG is copied verbatim, since it is the figure pipeline's own output
and re-encoding it is not wanted. The rasters go through the image step that
already existed, 36 MB down to 21.7 MB. The WebM animations are copied as they
are. The GIFs are skipped: they exist only so the markdown mirror on GitHub
has something it can play, and the site uses the WebM. The example PDFs come
along too, 1.7 MB, so that nothing is left pointing off-origin and the
preconnect to a third host could go.
The rewrite happens in two places because the references are authored two
ways. The components go through mediaUrl. Around a hundred more are
hand-written img pairs inside markdown, mostly on the theory pages, and remark
keeps those as unparsed raw nodes that never become elements, so a rehype pass
rewrites them as text. That is also why the staged path is stable rather than
content-hashed: a hash is not something a text rewrite can resolve, and Pages
serves everything with the same max-age either way.
docs/ and the README keep their absolute URLs on purpose. GitHub renders those
directly and has no build step to rewrite anything.
Verified on the built site: no page references raw.githubusercontent.com for
media any more, 451 pages, html-validate clean, i18n parity at 105 pages, and
pa11y WCAG2AA reporting 0 errors across 54 URLs.
Spanish docs: UNE terminology, decimal commas, localized snippets and theory figures (#365)
* Normalize Spanish docs prose to UNE acoustic terminology
Sweep the Spanish pages for the non-UNE forms "presion sonora",
"potencia sonora" and "intensidad sonora" and normalize the prose to
the wording used by the official Spanish editions of the standards:
"presion acustica" (UNE-EN ISO 16283-2:2016, UNE-EN ISO 10052:2005,
UNE-EN ISO 3746:2011, UNE-ISO 226:2013), "potencia acustica"
(UNE-EN ISO 3746:2011, UNE-EN ISO 4871:2010, UNE-EN ISO 9614-1:2010),
"intensidad acustica" (UNE-EN 61043:1999, UNE-EN ISO 9614-1:2010) and
"nivel de presion acustica de impactos" (UNE-EN ISO 12354-2:2018,
UNE-EN ISO 717-2:2013). 92 replacements across 32 pages, prose only:
code snippets keep the labels they share with the generated figures.
Rename the intensity guide to "Intensidad acustica (p-p)" and the
structure-borne power guide to "Potencia acustica estructural de
equipos (EN 15657)", updating every cross-link text and the theory
anchor intensidad-sonora-iec-61043 accordingly. The API sidebar group
label becomes "Potencia acustica e intensidad" via api_taxonomy.py
with the generated sidebar regenerated.
* Use decimal commas in Spanish docs prose quantities
Sweep every Spanish page for decimal points leaking into prose numbers
and switch them to the comma the locale convention calls for: the
rotorcraft validation prose (fourteen tolerances such as 0,08 dB(A) and
0,5 s), the insulation-prediction worked example (53,6 dB / 53,8 dB),
the tone-audibility Annex E tone (137,3 Hz), the Mackenzie check value
(1550,744 m/s), the EPNL, loudness and absorption fiche descriptions
(98,3 EPNdB; 8,2 sonos and 70,4 fonios; 0,60 y 0,55), the junction
constants table and the third-octave band-edge table in the signal
analysis theory page. Code snippets, inline code, math, clause numbers
and quoted source text keep their points.
* Pass language="es" in Spanish figure-reproduction snippets
The <details> blocks under each localized figure in the Spanish guides
are meant to reproduce the _es variant shown on the page, but 82 of the
one-line result .plot() calls omitted the language="es" argument and
would render English axis labels instead. Add the argument across 33
guides, matching the pattern the intensity field-indicators snippet
already used. The three lab-insulation results whose plot() does not
take a language argument (lab airborne, lab impact and the
element-normalized intensity difference) are left as they were.
* Extend the UNE terminology sweep to sound absorption
Normalize "absorción sonora" to "absorción acústica" across the
Spanish pages (36 occurrences in 14 pages, including the EN 12354-6
guide title and the theory headings), the wording of UNE-EN ISO
3746:2011 and of the equivalent absorption area in UNE-EN ISO
10140-3:2011, UNE-EN ISO 12354-2:2018 and UNE-EN ISO 16283-2:2016, and
the same term the accredited report strings already use. Also restore
the accent in the theory index anchor to the renamed intensity heading,
since heading slugs keep accented characters.
* Theory pages: illustrate each section family with existing result figures
The seven theory pages carried no figures at all. Embed sixteen of the
existing generated figures (light and dark variants, Spanish variants on
the Spanish mirrors) where the concept matches the prose: weighting
curves, time integration and the p-p intensity estimator in the signal
analysis page; equal-loudness contours, the specific-loudness pattern
and the hearing-threshold panels in perception; NC/RC rating, the
Schroeder decay and the ISO 717-1 shifted reference in rooms and
buildings; the Lden profile, ISO 9613-1 absorption and the three sound
power routes in environment and transport; the scattering coefficient
and ISO 11654 rating in materials and surfaces; and the Wk weighting and
the resonator mobility triplet in vibration. Each embed reuses the alt
text of the guide that owns the figure and adds a one-line caption.
Also give the wave-simulation section hub the reading-order paragraph
its siblings already have, linking the closed-form pages the FDTD solver
cross-checks, in both languages.
* Address review findings from the Spanish locale sweeps
Second pass fixes flagged by review: five terminology occurrences the
line-based sweep missed because the noun and adjective were split by a
line wrap or emphasis markup (sound-power, rotorcraft-noise and two
section hubs); six Spanish pages that still embedded the English figure
variant although the _es variant exists (junction-transmission,
aircraft-noise airport contour, miso-coherence,
objective-intelligibility, psychoacoustic-annoyance twice); and 19 more
language="es" arguments on figure-reproduction plot calls the first
pass missed, chained-call receivers such as room.noise_criterion(spl)
.plot() and the axes-creating first call of the two-profile
atmospheric-refraction snippet among them. The lab-insulation plot
wrappers forward keyword arguments to the rating plot, so the three
calls excluded earlier now take the argument too. All Spanish python
fences re-checked to compile and EN/ES parity re-verified.
* Carry the UNE terminology into the generated-asset Spanish strings
Apply the same evidence-based decisions to every Spanish string source
that feeds generated assets: the translation tables of
generate_graphs.py and generate_diagrams.py, the _STRINGS tables of the
plot modules and the report i18n values. 35 strings change: "presión
acústica" (UNE-EN ISO 16283-2:2016, 10052:2005, 3746:2011),
"potencia acústica" (UNE-EN ISO 3746:2011, 4871:2010, 9614-1:2010),
"intensidad acústica" (UNE-EN 61043:1999, 9614-1:2010), "absorción
acústica" (UNE-EN ISO 3746:2011) and "nivel de presión acústica de
impactos" (UNE-EN ISO 12354-2:2018). Strings the UNE editions keep are
untouched: "emisión sonora", "exposición sonora", "campo sonoro",
"fuente sonora". Only Spanish values change; the English keys stay.
The two plot-i18n test assertions that pin the axis label follow, and
the eight Spanish doc fences that deliberately mirrored the old figure
labels now mirror the new ones.
* Regenerate the Spanish figure variants with the UNE terminology
make graphs after the string-source change: 48 files, all of them _es
or _es_dark variants (24 figure/diagram pairs), picking up "presión
acústica", "potencia acústica", "intensidad acústica", "absorción
acústica" and "nivel de presión acústica de impactos" in titles and
axis labels. The English variants are untouched. The committed example
fiches need no regeneration: every example in generate_reports.py
renders in English, so no changed Spanish report string reaches them.
* Align the intensity-fiche Spanish assertions with the UNE terminology