docs: revise language-family handling

Simplify language-family handling by having a `#lang` report just a
family name, and `help/search` takes care of the rest based on
`language-family` definitions in "info.rkt" files.

Author: mflatt

drracket-core-lib/drracket/private/app.rkt

@@ -246,11 +246,10 @@
                            [label (string-constant help-desk)]
                            [parent button-panel]
                            [callback (λ (x y)
-                                       (define-values (query-table sub)
-                                         (drracket:frame:try-to-find-a-query-table-and-sub
+                                       (define fam
+                                         (drracket:frame:try-to-find-a-language-family
                                           (drracket:frame:try-to-find-an-irl)))
-                                       (help-desk:help-desk #:query-table query-table
-                                                            #:sub sub))])])
+                                       (help-desk:help-desk #:language-family fam))])])
     (send docs-button focus))
   (send button-panel stretchable-height #f)
   (send button-panel set-alignment 'center 'center)

drracket-core-lib/drracket/private/frame.rkt

@@ -771,11 +771,9 @@
       (define lang-name
         (cond
           [irl
-           (define ht
-             (call-read-language irl
-                                 'documentation-language-family
-                                 (hash)))
-           (hash-ref ht 'doc-language-name default-lang-name)]
+           (call-read-language irl
+                               'documentation-language-family
+                               "Racket")]
           [else default-lang-name]))
       (format (string-constant x-documentation) lang-name))
     (new menu-item%
@@ -786,9 +784,8 @@
             (send menu-item set-label (get-menu-item-label)))]
          [callback (λ (item evt)
                      (define irl (maybe-get-irl))
-                     (define ht (call-read-language irl 'documentation-language-family (hash)))
-                     (help:help-desk #:sub (hash-ref ht 'doc-path "index.html")
-                                     #:query-table (hash-ref ht 'doc-query (hash)))
+                     (define fam (call-read-language irl 'documentation-language-family "Racket"))
+                     (help:help-desk #:language-family fam)
                      #t)]))
 
   (define (drracket-help-menu:after-about menu dlg-parent)
@@ -822,16 +819,12 @@
     (and drr-frame
          (send (send (send drr-frame get-current-tab) get-defs) get-irl)))
 
-  ;; (or/c #f irl) -> (values hash string)
-  (define (try-to-find-a-query-table-and-sub irl)
-    (define ht
-      (if irl
-          (call-read-language irl
-                              'documentation-language-family
-                              (hash))
-          (hash)))
-    (values (hash-ref ht 'doc-query (hash))
-            (hash-ref ht 'doc-path "index.html"))))
+  ;; (or/c #f irl) -> string
+  (define (try-to-find-a-language-family irl)
+    (and irl
+         (call-read-language irl
+                             'documentation-language-family
+                             #f))))
 
 
 (require (submod "." add-racket-to-path)

drracket-core-lib/drracket/private/help-desk.rkt

@@ -149,10 +149,12 @@
   (equal? choice 1))
 
 (define (help-desk [key #f] [context #f] [parent #f]
-                   #:sub [sub #f]
-                   #:query-table [query-table (hash)])
+                   #:language-family [language-family #f])
   (when key (maybe-try-to-materialize-docs parent))
-  (if key
-      (perform-search key context #:query-table query-table)
-      (send-main-page #:query-table query-table
-                      #:sub (or sub "index.html"))))
+  (cond
+    [key
+     (perform-search key context #:language-family language-family)]
+    [language-family
+     (send-language-family-page language-family)]
+    [else
+     (send-main-page)]))

drracket-core-lib/drracket/private/in-irl-namespace.rkt

@@ -245,16 +245,7 @@
                                                (-> read-only-text/c exact-integer?
                                                    string?)
                                                string?)))))]
-    [(documentation-language-family)
-     (hash/dc
-      [key symbol?]
-      [val (key)
-           (case key
-             [(doc-language-name) string?]
-             [(doc-path) path-string?]
-             [(doc-query) (hash/c symbol? string? #:immutable #t)]
-             [else any/c])]
-      #:immutable #t)]
+    [(documentation-language-family) string?]
     [else
      (error 'key->contract "unknown key")]))
 

drracket-core-lib/drracket/private/rep.rkt

@@ -191,8 +191,8 @@ TODO
             (send (send (send frame get-current-tab) get-defs) get-irl)]
            [else
             (drracket:frame:try-to-find-an-irl)]))
-       (define-values (query-table sub)
-         (drracket:frame:try-to-find-a-query-table-and-sub irl))
+       (define fam
+         (drracket:frame:try-to-find-a-language-family irl))
        (cond
          [(is-a? obj text%)
           (define start (send obj get-start-position))
@@ -202,7 +202,7 @@ TODO
                           (send obj get-text start end)))
           (cond
             [(or (not str) (equal? "" str))
-             (drracket:help-desk:help-desk #:query-table query-table #:sub sub)]
+             (drracket:help-desk:help-desk #:language-family fam)]
             [else
              (let* ([l (send obj get-canvas)]
                     [l (and l (send l get-top-level-window))]
@@ -217,11 +217,9 @@ TODO
                     [name (and l (send l get-language-name))])
                (drracket:help-desk:help-desk
                 str (and ctxt (list ctxt name)) frame
-                #:query-table query-table
-                #:sub sub))])]
+                #:language-family fam))])]
          [else
-          (drracket:help-desk:help-desk #:query-table query-table
-                                        #:sub sub)])))
+          (drracket:help-desk:help-desk #:language-family fam)])))
 
     ;; keep this in case people use it in their keymaps
     (add-drs-function "execute"  (λ (frame) (send frame execute-callback)))

drracket-core-lib/drracket/private/unit.rkt

@@ -233,11 +233,10 @@
                      (string-append short-str "...")))
                 menu
                 (λ x
-                  (define-values (query-table sub)
-                    (drracket:frame:try-to-find-a-query-table-and-sub irl))
+                  (define fam
+                    (drracket:frame:try-to-find-a-language-family irl))
                   (help-desk:help-desk str (list ctxt name)
-                                          #:query-table query-table
-                                          #:sub sub)))
+                                          #:language-family fam)))
               (void)))))))
 
   (define (filename->kind fn)

drracket-core-lib/drracket/tool-lib.rkt

@@ -933,17 +933,17 @@ all of the names in the tools library, for use defining keybindings
        ((or/c #f string?)
         (or/c #f string? (list/c string? string?))
         (or/c (is-a?/c frame%) (is-a?/c dialog%) #f)
-        #:sub string?)
+        #:language-family string?)
        any)
   (()
    ((search-key #f)
     (search-context #f)
     (parent #f)
-    (sub "index.html")))
+    (language-family #f)))
   @{if @racket[search-key] is a string, performs a search in the docs with
  @racket[search-key] and @racket[search-context].
- Otherwise, calls @racket[send-main-page] with @racket[sub] as the
-@racket[#:sub] keyword argument.
+ Otherwise, calls @racket[send-language-family-page]. The @racket[language-family]
+ argument is passed along in either case.
 
  The search may involve asking the user a question, in which case the
  dialog with the question uses @racket[parent] as its parent.

drracket-core/scribblings/tools/lang-tools.scrbl

@@ -585,45 +585,25 @@ find a prefix and extract the subsequent name:
 
  When a language's @racket[_get-info] procedure (accessed via @racket[read-language])
  responds to the @racket['documentation-language-family]
- key, the information it provides is used to find documentation
- for the @tech[#:doc '(lib "scribblings/raco/raco.scrbl")]{language family}
- that the language is a part of. The response to that key should be a
- @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{hash
-  table} with certain known keys, such that those keys have to
- have specific kinds of values attached to them, but is
- allowed to have extra keys that are unconstrained (for
- better forwards compatibility). This is the contract:
-
- @racketblock[
- (hash/dc
-  [key symbol?]
-  [val (key)
-   (case key
-     [(doc-language-name) string?]
-     [(doc-path) path-string?]
-     [(doc-query) (hash/c symbol? string? #:immutable #t)]
-     [else any/c])]
-  #:immutable #t)
- ]
+ key, the result is a string that names a language family. The
+ language family should be defined as @racketidfont{language-family} in
+ some collection's @filepath{info.rkt} file, and that definition
+ configures a documentation entry point, a navigation configuration,
+ and search precedence.
 
 DrRacket uses the contents of this hash in three ways:
  @itemlist[
  @item{
-   When typing “f1” (or right clicking) to search for
+   When typing f1 (or right clicking) to search for
    documentation in DrRacket, DrRacket calls
-   @racket[perform-search] and @racket[send-main-page] to
-   summon browser-based documentation. If
-   hash contains the @racket['doc-query] key, then the value
-   associated with that key is supplied as the
-   @racket[#:query-table] argument.}
- @item{If the hash maps the
-   @racket['doc-language-name] to a string, then DrRacket uses that
-   string in the first menu item in the @onscreen{Help} menu
+   @racket[perform-search] or @racket[send-language-family-page] to
+   summon browser-based documentation, and it passes
+   along the language family.}
+ @item{DrRacket uses the name in the first menu item in the @onscreen{Help} menu
    item, replacing the word “Racket” with the string in the hash.}
- @item{ When selecting that menu item, DrRacket visits the web
-   page named by the @racket['doc-path] key. Specifically,
-   DrRacket passes @racket['doc-path] as the @racket[#:sub]
-   argument to @racket[send-main-page].
+ @item{ When selecting that menu item, DrRacket visits the
+   documentation page the language family by passing it
+   along to @racket[send-language-family-page].
    }]
 }
 

drracket-plugin-lib/drracket/private/drsig.rkt

@@ -266,7 +266,7 @@
    add-keybindings-item
    planet-spec?
    try-to-find-an-irl
-   try-to-find-a-query-table-and-sub))
+   try-to-find-a-language-family))
 
 (define-signature drracket:program-cm^
   (frame%))