added -x flag to plt-help, improved man pages

svn: r8048

collects/help/help.ss

@@ -5,9 +5,18 @@
          setup/dirs
          scheme/cmdline)
 
+(define exact-search? #f)
+
 (command-line
+ #:once-any (["--exact" "-x"] "Go directly to the first exact hit for the search term" (set! exact-search? #t))
  #:args search-term
  (cond
+   [exact-search?
+    (when (null? search-term)
+      (error 'plt-help "expected a search term after -x or --exact"))
+    (unless (null? (cdr search-term))
+      (error 'plt-help "expected a single search term, got ~s" search-term))
+    (send-exact-results (car search-term))]
    [(null? search-term)
     (let ([dest-path (build-path (find-doc-dir) "start" "index.html")])
       (send-url (format "file://~a" (path->string dest-path))))]

collects/help/search.ss

@@ -9,10 +9,61 @@
          scribble/manual
          (prefix-in scheme: scribble/scheme)
          net/sendurl
+         net/uri-codec
          mzlib/contract)
 
 (provide/contract
- [generate-search-results (-> (listof string?) void?)])
+ [generate-search-results (-> (listof string?) void?)]
+ [send-exact-results (-> string? void?)])
+
+;; if there is exactly one exact match for this search key, go directly
+;; to that place. Otherwise, go to a page that lists all of the matches.
+(define (send-exact-results search-key)
+  (let* ([file (next-search-results-file)]
+         [exact-search-regexp (regexp (format "^~a$" (regexp-quote search-key #f)))]
+         [x (load-collections-xref)]
+         [index (xref-index x)]
+         [len (length index)]
+         [exact-matches (filter (has-match (list exact-search-regexp)) index)])
+    (cond
+      [(or (null? exact-matches)
+           (not (null? (cdr exact-matches))))
+       (generate-search-results (list search-key))]
+      [else
+       (let ([match (car exact-matches)])
+         (let-values ([(path tag) (xref-tag->path+anchor x (entry-tag match))])
+           (send-url (format "file://~a~a" 
+                             (path->string path) 
+                             (if tag (string-append "#" (uri-encode tag)) "")))))])))
+
+(define (generate-search-results search-keys)
+  (let ([file (next-search-results-file)]
+        [search-regexps (map (λ (x) (regexp (regexp-quote x #f))) search-keys)]
+        [exact-search-regexps (map (λ (x) (regexp (format "^~a$" (regexp-quote x #f)))) search-keys)]
+        [search-key-string
+         (cond
+           [(null? search-keys) ""]
+           [else
+            (apply
+             string-append
+             (car search-keys)
+             (map (λ (x) (format ", or ~a" x))
+                  (cdr search-keys)))])])
+    (let ([x (load-collections-xref)])
+      (xref-render
+       x
+       (decode `(,(title (format "Search results for ~a" search-key-string))
+                 ,@(let* ([index (xref-index x)]
+                          [len (length index)]
+                          [matching-entries (filter (has-match search-regexps) index)]
+                          [exact-matches (filter (has-match exact-search-regexps) matching-entries)]
+                          [inexact-matches (filter (compose not (has-match exact-search-regexps))  matching-entries)])
+                     (append
+                      (build-itemization "Exact matches" exact-matches)
+                      (build-itemization "Containing matches" inexact-matches)))))
+       file)
+      (send-url (format "file://~a" (path->string file)))
+      (void))))
 
 (define (make-extra-content desc)
   ;; Use `desc' to provide more details on the link:
@@ -56,35 +107,6 @@
                 (append (cdr search-results-files) 
                         (list (car search-results-files))))))
 
-(define (generate-search-results search-keys)
-  (let ([file (next-search-results-file)]
-        [search-regexps (map (λ (x) (regexp (regexp-quote x #f))) search-keys)]
-        [exact-search-regexps (map (λ (x) (regexp (format "^~a$" (regexp-quote x #f)))) search-keys)]
-        [search-key-string
-         (cond
-           [(null? search-keys) ""]
-           [else
-            (apply
-             string-append
-             (car search-keys)
-             (map (λ (x) (format ", or ~a" x))
-                  (cdr search-keys)))])])
-    (let ([x (load-collections-xref)])
-      (xref-render
-       x
-       (decode `(,(title (format "Search results for ~a" search-key-string))
-                 ,@(let* ([index (xref-index x)]
-                          [len (length index)]
-                          [matching-entries (filter (has-match search-regexps) index)]
-                          [exact-matches (filter (has-match exact-search-regexps) matching-entries)]
-                          [inexact-matches (filter (compose not (has-match exact-search-regexps))  matching-entries)])
-                     (append
-                      (build-itemization "Exact matches" exact-matches)
-                      (build-itemization "Containing matches" inexact-matches)))))
-       file)
-      (send-url (format "file://~a" (path->string file)))
-      (void))))
-
 ;; has-match : (listof regexp) -> entry -> boolean
 (define ((has-match search-regexps) entry)
   (ormap (λ (str) 

man/man1/drscheme.1

@@ -83,7 +83,7 @@ the on-line documentation has been installed locally.
 .SH BUGS
 Submit bug reports via
 .ce 1
-help-desk (encouraged),
+drscheme (encouraged),
 or via the web
 .ce 1
 http://bugs.plt-scheme.org/ (discouraged)
@@ -94,6 +94,6 @@ bugs@plt-scheme.org (discouraged)
 .I DrScheme
 was implemented by PLT.
 .SH SEE ALSO
-.BR help-desk(1),
+.BR plt-help(1),
 .BR mred(1),
 .BR mzscheme(1)

man/man1/mred.1

@@ -373,6 +373,6 @@ Robert Bruce Findler (robby@plt-scheme.org), and
 John Clements (clements@plt-scheme.org), based on
 MzScheme.
 .SH SEE ALSO
-.BR help-desk(1),
+.BR plt-help(1),
 .BR mzscheme(1),
 .BR drscheme(1)

man/man1/mzscheme.1

@@ -263,6 +263,6 @@ It uses the conservative garbage collector implemented by Hans
 Boehm and extended by John Ellis. MzScheme was originally based 
 on libscheme, written by Brent Benson.
 .SH SEE ALSO
-.BR help-desk(1),
+.BR plt-help(1),
 .BR drscheme(1),
 .BR mred(1)

man/man1/plt-help.1

@@ -1,24 +1,24 @@
 .\" dummy line
-.TH HELP-DESK 1 "May 2006"
+.TH PLT-Help 1 "May 2006"
 .UC 4
 .SH NAME
-help-desk \- The PLT Scheme documentation center
+plt-help \- The PLT Scheme documentation center
 .SH SYNOPSIS
-.B help-desk
+.B plt-help
-.I term ...
+.I [-x --exact] term ...
 .SH DESCRIPTION
-.I Help Desk 
+.I PLT Help 
 searches for term in the PLT Scheme documentation and opens an html document in a web browser with the results of the search.
 .PP
 For further information on
-.I Help Desk,
+.I PLT Help,
 please consult the on-line
 documentation and other information available at
 .PP
 .ce 1
 http://www.drscheme.org/
 .SH FILES
-.I Help Desk
+.I PLT Help
 looks for its libraries using the environment variable
 PLTCOLLECTS.  If this variable is not defined,
 the installation directory is found automatically.