This PR has only a token commit, and it's meant for discussion and refinement of some changes that are already in place. The changes are already in place because they started out as small adjustments and snowballed into a larger set of changes, and because the adjustments span so many packages and services, and because it was trial and error to figure out what works.

Some things to try first

Go to one of the snapshot sites from https://snapshot.racket-lang.org/ and click "Documentation" at the top. As you navigate documentation, you'll see "Racket language family" at the top right. Search for something like "list", and you'll see Racket results before HtDP results. But if you click "navigating at Racket" at the top left and then pick "HtDP", you'll get the opposite order and convention for reporting search results.

Go to the Rhombus snapshot page at https://users.cs.utah.edu/plt/rhombus-snapshots/ and click "Documentation" there. You correctly anticipate that "Rhombus language family" is at the top right. Note that the page lists all documentation, not just Rhombus documentation, but the list is organized differently compared to the Racket starting page. Search for something like "list", and you'll see Rhombus results before Racket results. Browse a Racket document, and then click "top" in the navigation panel at the top left of the page, and you'll end up back at the Rhombus documentation listing. If you click the top-right language-family link to switch to Racket mode, then "top" goes to the familiar Racket listing, instead.

If you have a very recent Racket build (via Git or a snapshot), in DrRacket, use #lang htdp/isl, and note that the "Help" menu starts with a "HtDP Documentation" item instead of "Racket Documentation". Searching with F1 priorities HtDP in search results (but does not show only HtDP results).

Language family

A language family here is intended as a documentation concept. Pinning down what "language family" means is specifically a topic for discussion here.

The original goal was to enable Racket- and Rhombus-specific views of documentation so that neither got too much in the way of the other. "Racket" can be special, because it's the foundation and the name of the ecosystem, but "Rhombus" should not be special, and a new mechanism should generalize to other languages or language families (whatever that might mean).

Specifically, the intent is to make a distinction between "Racket" and "Rhombus", but not to completely separate them. For the foreseeable future, a Rhombus user will want see what functionality is available from Racket libraries; in the long run, a Racket user might take advantage of a Rhombus library. So, each language family should have its own entry point in the documentation—a Rhombus user sees an introduction and roadmap that is suitable for Rhombus., for example—and searching documentation should provide results most useful to the language family, but "Racket" exists as a concept in Rhombus, and languages like "Rhombus" exist as a concept in Racket.

Along those lines, the intent is that a language-family choice affects how documentation is shown, not whether documentation is shown. When prioritizing search results, exact binding matches are currently still listed before non-exact matches, independent of language family. A documentation search can be configured (e.g., through the gear icon below the box on the main search page) to show results only for a given language family or for a given language, but that kind of filtering is not currently performed by default.

As soon as you have a mechanism aimed at Rhombus, though, then it looks useful for slightly different goals, such as organizing HtDP versus Racket documentation. The distinction between the HtDP Beginner Student Language and Racket is in some ways like the distinction between Rhombus and Racket, and in some ways it's not. It's good to have HtDP documentation not interfere with Racket uses, for example. Then again, probably HtDP users should see less of Racket than Rhombus users. And is "HtDP" as a language family the right idea, or do HtDP users really need a language-specific view in the sense of Beginner Student Language and Intermediate Student Language?

That leaves "language family" as difficult to define. So far, a language family means something like "languages especially meant to be used together and where you want to prioritize their search results together", but that doesn't help much for deciding when to create a language family. For example, I originally expected Shplait to just be in the Rhombus language family as far as documentation is concerned, but having it be a separate language family seems to make search results nicer from both Rhombus and Shplait perspectives. But should Plait and plai-typed be their own families for the same reason? Does "language family" become a less useful concept if there are too many or them?

These questions may be unaswerable in the abstract, and we may just have to keep experimenting. Meanwhile, there may be things in the implementation that can be done better.

Implementation: What's old

The concept of language family for documentation has been in place for a while, at least to sort and display search results. For example, searching for list at the current https://docs.racket-lang.org with annotate some results as "HtDP", "Rhombus, or (more recently) "Zuo". (Why are the "HtDP" results in the middle of Racket results currently? I think it's a bug that's now fixed.)

This use of a language family does not require that the language family is explicitly declared anywhere. The search interface simply reflect the language families that it discovers recorded in index entries.

Implementation: What's new

A language-family configuration can now affect the way that documentation is traversed, at least as far as "top" and "up" links go. Also, there's new support to generate a full-document listing that is oriented to a language family (such as Rhombus), and an individual document can control how it is listed in specific language families and how it should be listed by default.

How tools work

A collection's "info.rkt" can define language-family to declare a list of language families. That declaration is used to populate the documentation page that lets a user pick a language family, and it can be used more generally to map a language name to a documentation configuration.

Here's the declaration for Racket:

 (define language-family
   (list (hash 'fam "Racket"
                'describe-doc '(lib "scribblings/guide/guide.scrbl")
                ;; relative order in family-choice list:
                'order 100)))

For Rhombus:

 (define language-family
   (list (hash 'fam "Rhombus"
               ;; for "top" navigation and starting doc:
               'famroot "rhombus"
               'describe-doc '(lib "rhombus/scribblings/guide/rhombus-guide.scrbl"))))

For HtDP:

 (define language-family
   (list (hash 'fam "HtDP"
               ;; as both starting doc and description doc:
               'doc '(lib "scribblings/htdp-langs/htdp-langs.scrbl")
               'order -100)))

A #lang module language can tell DrRacket and other programming environments what language family should be used via 'documentation-family. The setup/language-family module provides get-language-families, but DrRacket just uses perform-search (newly extended to accept a family name) or the new send-language-family-page function alongside send-main-page.

The raco docs tool now accepts a -f/--family argument to select a family. At the moment, it looks for an exact match to a family name, but I may have changed it to best-match by the time you read this.

How documents work

(Most of this is not new.) A document written with #lang scribble/manual doesn't declare any particular language, so it gets "Racket" by default. A scribblings entry in "info.rkt" can specify a language family externally, and that's how some documentation gets the "HtDP" family.

A document written with #lang rhombus/scribble/manual gets "Rhombus" as its default language family. That can be overridden by a scribblings entry in "info.rkt".

More precisely, individual sections within a document (and individual index entries) have a language family, so that supports a document that mixes or bridges language families. Only the language family for a document's main part will affect how it is presented in a documentation listing.

How browsing supports a language-family choice

A document has a language family. Let's call the current configuration for how documents are viewed the navigation language family, or navigation family for short.

The navigation family is recorded in a "fam" query parameter in the URL. Existing mechanisms in Scribble-generated HTML carry query parameters along as a user follows documentation links (and, unlike cookies or local storage, that works file with "file://" URLs). Using query parameters makes also works for external links; for example, the Rhombus snapshot "Documentation" link points into documentation to the Rhombus page, and it includes "?fam=Rhombus&famroot=rhombus" to put navigation in Rhombus mode.

The "famroot" query parameter affects the "top" navigation link for all documents (and "up", if you go up enough). That's intended to be used only to point to a document that has a list of all documentation. The "HtDP" language family is meant to just use the Racket listsing, so it doesn't use "famroot".

Every document's language family is rendered at the top right of the document. (The layout is intended t obe unobtrusive for Racketeers who do not care about language families.) If the navigation family matches a document's language family, the language family is hyperlinked to a page for chosing a navigation family. Otherwise, "navigating as" is shown and hyperlinked to the page for choosing. A few documents (such as the search page) have no language family of their own, so they always have just "navigating as".

From the Scribble perspective, a document has to opt into showing a language family, so non-documentation rendered with Scribble should not be affected. The raco setup step for building documentation opts each document into showing the language family.

Overall, query parameters are consulted by the links to select a navigation family, the "top"/"up" nagivation links, and the search page. Those build on the JavaScript layers already in place for Scribbled documentation.

Everything should work right when installed in installation scope or use scope or a mixture. The user-scope main page and search page now set a query parameter to record the user-scope entry point, instead of using a cookie or local storage. This restores some old behavior: after starting on a user-scope documentaiton page and navigating to an installation-scope page, using the top-left search box on the installation-scope page should bounce back to user scope like it's supposed to.