Polyglot 2.0 Update

Last updated: home

A while back I posted an article introducing Polyglot, a Racket-powered tool I wrote to express web content using any language at a moment’s notice among prose. A lot has happened with Polyglot since then, but I do need to announce one major change for its users.

The documentation desperately needed an overhaul. As I’ve been adding to it, I’ve noticed errors that wouldn’t block users from adopting Polyglot, but would cause other problems. For example, there was a section that suggested that you could bundle CSS across a website using page-level postprocessing, but the code example did not aggregate styles across pages at all. I also noticed some gaps of information that I had to fill.

These errors were easy to make because the documentation became a mash-up of detailed reference material, a high-level guide, how-tos, and tutorials. All of these forms of documentation are necessary, but they require different modes of writing that should not mix together in one publication. They mixed, and all improvements I made to one mode of writing made the others suffer.

The good news is that this is expected for a flexible project, but I had to get ahead of any justified complaints from end-users. I split up the Polyglot documentation into a Guide and an API Reference for indexing on the Racket documentation site. How-Tos and Tutorials are not listed on the index, but are accessible from the Guide.

So why make a blog post about this?

Racket’s documentation is built via continuous integration. The documentation change is significant enough that any repeat visitors are going to hop onto online documentation in about 36 hours and wonder where the hell everything went. To find the new docs, just search for polyglot on the docs site. I left enough links lying around to get you to where you need to go.

There have been no functional changes to the code, so all Polyglot apps work as they did before. But when you click on an identifier that appears in search results for the polyglot collection, you will be directed to the API Reference, not the mixed-mode guide you were used to seeing.

For this reason the documentation change is large enough that you could call it a breaking change for readers. While I do not formally associate major version numbers to breaking changes, I release the new documentation as Polyglot 2.0 to hopefully attract users to relatively sane literature.

If you prefer the old documentation, you can still download a 1.x release of Polyglot and view their offline documentation using raco doc polyglot. Even so, I ask that you distance yourself from it because the 2.0 documentation will prevent a lot of headaches when you want to use more of Polyglot’s features.