add 'no-navigation style property and revise "PLT root" strategy

Author: mflatt

scribble-doc/scribblings/scribble/base.scrbl

@@ -91,7 +91,11 @@ path, it is converted to a string using
 @racket[module-path-prefix->string]. Similarly, if @racket[tag-prefix]
 is a hash table with @racket['tag-prefix] mapped to a module path,
 then it is replaced with a hash table where @racket['tag-prefix] is
-mapped to a string.
+mapped to a string. When @racket[tag-prefix] as a hash table is
+used for the main part in a document rendered by @exec{raco setup},
+@exec{raco setup} uses some keys to configure the document's
+rendering; see @racket[scribblings] in @secref[#:doc '(lib
+"scribblings/raco/raco.scrbl") "setup-info"] for more information.
 
 The @racket[vers] argument is propagated to the @racket[title-decl]
 structure. Use @racket[""] as @racket[vers] to suppress version
@@ -729,7 +733,8 @@ the section hyperlink's resolution in HTML is potentially delayed; see
          element?]{
 
 Like @racket[secref] for the document's implicit @racket["top"]
-tag. Use this function to refer to a whole manual instead of
+tag that @exec{raco setup} adds to every document that it renders.
+Use this function to refer to a whole manual instead of
 @racket[secref], in case a special style in the future is used for
 manual titles.
 

scribble-doc/scribblings/scribble/core.scrbl

@@ -370,7 +370,9 @@ each key in the table, the value in the table is merged with the
 context from enclosing parts. A value is merged by adding the key and
 value to the accumulation if the key is not yet present, or by
 @racket[cons]ing the new value to the context's current value when the
-key is present. Use @racket[current-part-context-accumulation] during
+key is present. For example, the key @racket['index-extras] is used
+to merge with an @racket[index-desc] within a discovered @racket[index-element].
+Use @racket[current-part-context-accumulation] during
 the @techlink{collect pass} or @techlink{resolve pass} to retrieve the
 value that has been accumulated from enclosing parts.
 
@@ -390,7 +392,11 @@ The @racket[tag-prefix] field determines the optional @techlink{tag
 prefix} for the part and/or @techlink{part context} accumulation. When
 @racket[tag-prefix] is a hash table, the value associated with the
 @racket['tag-prefix] key is used as the tag prefix when the value
-is a string.
+is a string. When @racket[tag-prefix] as a hash table is
+used for the main part in a document rendered by @exec{raco setup},
+@exec{raco setup} uses recognizes some keys to configure the document's
+rendering; see @racket[scribblings] in @secref[#:doc '(lib
+"scribblings/raco/raco.scrbl") "setup-info"] for more information.
 
 The @racket[tags] indicates a list of @techlink{tags} that each link
 to the section. Normally, @racket[tags] should be a non-empty list, so
@@ -480,6 +486,11 @@ The recognized @tech{style properties} are as follows:
        document, causes the HTML output to not include an ``on this 
        page'' margin box.}
 
+ @item{@indexed-racket['no-navigation] --- As a @tech{style property}
+       for the main part of a rendered page, causes the HTML output to
+       not include ``top,'' ``up,'', ``prev,'' and ``next'' controls
+       if they would otherwise apply.}
+
  @item{@indexed-racket['no-header-controls] --- Suppresses link and
        link-information icons (if any) as part of a section header in
        HTML output.}
@@ -590,7 +601,8 @@ The @racket[parts] field contains sub-parts.
          #:changed "1.27" @elem{Added @racket['no-toc+aux] support.}
          #:changed "1.54" @elem{Changed @racket[tag-prefix] field to allow a
                                 @tech{part context} hash table.}
-         #:changed "1.57" @elem{Added @racket['no-header-controls] support.}]}
+         #:changed "1.57" @elem{Added @racket['no-header-controls] support.}
+         #:changed "1.59" @elem{Added @racket['no-navigation] support.}]}
 
 
 @defstruct[paragraph ([style style?] [content content?])]{

scribble-lib/scribble/html-render.rkt

@@ -239,7 +239,7 @@
          [placeholder ,emptylabel]
          [title "Enter a search string to search the manuals"]
          [onkeypress ,(format "return DoSearchKey(event, this, ~s, ~s);"
-                              (version) top-path)])))))
+                              (get-installation-name) top-path)])))))
 (define search-box (make-search-box "../"))
 (define top-search-box (make-search-box ""))
 
@@ -290,6 +290,7 @@
                 ;; user start page). If it's a path, then it's also
                 ;; used for the "top" link on the page.
                 [up-path #f]
+                [search-up-path up-path]
                 [script-path #f]
                 [script-file #f]
                 [search-box? #f])
@@ -1029,7 +1030,7 @@
          "up" (if (path? up-path)
                   (url->string* (path->url up-path))
                   "../index.html")
-         `[onclick . ,(format "return GotoPLTRoot(\"~a\");" (version))]))
+         `[onclick . ,(format "return GotoPLTRoot(\"~a\");" (get-installation-name))]))
       (define tocset-toggle
         (make-element "tocsettoggle"
                       (list
@@ -1041,14 +1042,15 @@
                                          '([title . "show/hide table of contents"]
                                            [onclick . "TocsetToggle();"]))))
                         "contents"))))
+      (define no-nav? (and (memq 'no-navigation (style-properties (part-style d))) #t))
       (define navleft
         `(span ([class "navleft"])
            ,@(if search-box?
-                 (list (if up-path search-box top-search-box))
+                 (list (if search-up-path search-box top-search-box))
                  (list `(div ([class "nosearchform"]))))
            ,@(render
               sep-element
-              (and up-path (make-element top-link top-content))
+              (and up-path (not no-nav?) (make-element top-link top-content))
               tocset-toggle
               ;; sep-element
               ;; (make-element
@@ -1060,7 +1062,7 @@
               ;;   (make-link-element #f index-content (car (part-tags/nonempty index))))
               )))
       (define navright
-        (if (not (or parent up-path next))
+        (if (or (not (or parent up-path next)) no-nav?)
           ""
           `(span ([class "navright"])
              ,@(render

scribble-lib/scribble/scribble-common.js

@@ -2,6 +2,8 @@
 
 // Page Parameters ------------------------------------------------------------
 
+var plt_root_as_query = false;
+
 function GetURL() {
   return new URL(location);
 }
@@ -19,16 +21,20 @@ function GetPageArg(key, def) {
 }
 
 function MergePageArgsIntoLink(a) {
-  if (GetPageArgs().size === 0 || !a.dataset.pltdoc) return;
+  if ((GetPageArgs().size === 0 || !a.dataset.pltdoc) && !plt_root_as_query) return;
   a.href = MergePageArgsIntoUrl(a.href);
 }
 
 function MergePageArgsIntoUrl(href) {
   const url = new URL(href, window.location.href);
   for (const [key, val] of GetPageArgs()) {
+    if (key[0] == "q") continue; // use "q" to mean "don't propagate automatcially"
     if (url.searchParams.has(key)) continue;
     url.searchParams.append(key, val)
   }
+  if (plt_root_as_query && !url.searchParams.has("PLT_Root")) {
+      url.searchParams.append("PLT_Root", plt_root_as_query);
+  }
   return url.href;
 }
 
@@ -72,28 +78,52 @@ function SetCookie(key, val) {
 
 // note that this always stores a directory name, ending with a "/"
 function SetPLTRoot(ver, relative) {
-  var root = location.protocol + "//" + location.host
-           + NormalizePath(location.pathname.replace(/[^\/]*$/, relative));
-  SetCookie("PLT_Root."+ver, root);
+    var root = location.protocol + "//" + location.host
+        + NormalizePath(location.pathname.replace(/[^\/]*$/, relative));
+    if (location.protocol == "file:") {
+        // local storage or cookies are not going to work in modern browsers,
+        // so add a query parameter to all URLs
+        plt_root_as_query=root
+    } else {
+        SetCookie("PLT_Root."+ver, root);
+    }
 }
 
 // adding index.html works because of the above
 function GotoPLTRoot(ver, relative) {
+  var famroot = (GetPageArg("fam", false) ? GetPageArg("famroot", false) : false)
   var u = GetRootPath(ver);
-  if (u == null) return true; // no cookie: use plain up link
+  if (u == null) {
+    // no cookie: use plain up link
+    if (famroot) {
+        location = MergePageArgsIntoUrl("../" + famroot + "/index.html");
+        return false;
+    }
+    return true;
+  }
   // the relative path is optional, default goes to the toplevel start page
   if (!relative) relative = "index.html";
-  location = u + relative;
+  if (relative == "index.html" && famroot) {
+      relative = famroot + "/index.html";
+  }
+  location = MergePageArgsIntoUrl(u + relative);
   return false;
 }
 
 function GetRootPath(ver) {
     var u = GetCookie("PLT_Root."+ver, null);
     if (u != null)
         return u;
+
+    // via query argument? (especially for `file://` URLs)
+    u = GetPageArg("PLT_Root", null)
+    if (u != null)
+        return u;
+
     // use root specified by local-redirect wrapper, if present
     if (typeof user_doc_root != "undefined")
         return user_doc_root;
+
     return null;
 }