Repository navigation
docs: modernize README and website - #337
Merged
Merged
Conversation
trans
commented
Sep 27, 2026
trans
left a comment
Member
Author
There was a problem hiding this comment.
Reviewed the README, docs/build.rb, the _src templates, the generated pages and atom.xml. It reads well, and the facts check out. One real issue and a couple of small ones.
What I verified
- README examples: all run on current
mainand produce what the README shows:to_ranges→[1..3, 6..7],snakecase→"ruby_facets",average→2.0, andrequire 'facets/ostruct'loads OpenStruct with the extensions. - Guide examples:
dashcase→"ruby-facets",Range.intersection(1..10, 5..15)→5..10, andfacets/time/stamploads. - Release facts on the site and feed match
HISTORY.md: 3.2.2 on 2026-06-15, 3.2.1 on 2026-06-14 (load fix, OpenDSL, PIC), and 3.2.0 on 2026-04-01 (Ruby 3.1+,to_ranges,dashcase). - The builder reproduces the committed HTML exactly: rerunning it leaves no diff.
- No broken local links in any generated page.
atom.xmlparses, and itsnews.html#facets-3-2-xanchors all exist.
Issue: docs/build.rb crashes outside a UTF-8 locale
On a system without a UTF-8 locale (plain C/POSIX, common in containers and minimal CI images) the build fails:
(erb):28: incompatible character encodings: ASCII-8BIT and US-ASCII (Encoding::CompatibilityError)
The templates contain non-ASCII characters (←, ·, ↗), and File.read uses the locale's default encoding. With LANG=C.UTF-8 it works. A one-line fix near the top:
Encoding.default_external = Encoding::UTF_8Alternatively, pass encoding: 'UTF-8' to the File.read calls.
Smaller points
- Orphaned archive post:
posts/2008-03-24-release-2-4.htmlis built (it's in thearchivehash), but nothing links to it.news.htmllists the other five archive posts and skips 2.4. - Start year (FYI): the README and site say Facets began in 2005, which matches
LICENSE.txtand the 1.0.0 entry (2005-12-04). The old.indexmetadata recorded a creation date of 2004-12-16, so the pre-1.0 work may date to late 2004. Your call. - Optional:
docs/README.mdsays the Brite-era files (.page,.post,brite.yml,assets/layouts/) are kept for reference. Since #335 removed the other leftover tooling files, these could go too, but keeping them is reasonable.
Generated by Claude Code
trans
pushed a commit
that referenced
this pull request
Sep 27, 2026
Facets took its name in version 0.5.0 on 2004-12-23 (see work/HISTORY-0.rdoc), and the old .index metadata recorded 2004-12-16; 1.0 followed in December 2005. The README, site and LICENSE said 2005. They now say 2004. The news page's archive section gains the short origin story from work/HISTORY-0.rdoc: TomsLib (2002), Succ (2003), A.B.C. and Raspberry (2004), then Ruby Facets (December 2004). The README and the contribute page mention the 2002 roots in a phrase. Also from the #337 review: - docs/build.rb sets UTF-8 as the default external encoding, so it no longer crashes outside a UTF-8 locale. - news.html links the 2.4 release post, which was built but not linked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E2Njj4j1r9twkVcXsMySLW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mainbut still unreleased, includinglib/rails.Checks
ruby docs/build.rbmaingit diff --check