getting-started doc improvements, and small change to raise-syntax-error

svn: r13607

collects/scribblings/guide/info.ss

@@ -1,5 +1,5 @@
 #lang setup/infotab
 
-(define scribblings '(("guide.scrbl" (multi-page) (getting-started))))
+(define scribblings '(("guide.scrbl" (multi-page) (getting-started -10))))
 
 (define compile-omit-paths '("contracts-examples"))

collects/scribblings/main/config.ss

@@ -26,7 +26,7 @@
 
 ;; Section definitions for manuals that appear on the start page.
 (define manual-sections
-  '((getting-started "Getting Started")
+  '((getting-started (link "Getting Started" (lib "scribblings/main/getting-started.scrbl")))
     (language        "Languages")
     (tool            "Tools")
     (gui-library     "GUI and Graphics Libraries")

collects/scribblings/main/getting-started.scrbl

@@ -0,0 +1,44 @@
+#lang scribble/doc
+@(require scribble/manual)
+
+@title{Getting Started with PLT Scheme}
+
+If you are new to programming or if you have the patience to work
+through a textbook:
+
+@itemize[
+
+ @item{@italic{@link["http:///www.htdp.org/"]{How to
+       Design Programs}} is the best place to start.}
+
+ @item{@other-manual['(lib "web-server/scribblings/tutorial/continue.scrbl")]
+       introduces you to the Module language and building web applications.}
+
+ @item{@other-manual['(lib "scribblings/guide/guide.scrbl")] describes
+       the rest of the PLT Scheme language, which is much bigger than
+       the learning-oriented languages of the textbook. Since you
+       learned functional programming from the textbook, you'll be
+       able to skim chapters 1 and 2 of the Guide.}
+
+]
+
+
+If you're already a programmer and you're in more of a hurry:
+
+@itemize[
+
+ @item{@other-manual['(lib "scribblings/quick/quick.scrbl")] gives you
+       a taste of PLT Scheme.}
+
+ @item{@other-manual['(lib "scribblings/more/more.scrbl")] dives much
+       deeper and much faster. If it's too much, just skip to the
+       Guide.}
+
+ @item{@other-manual['(lib "scribblings/guide/guide.scrbl")] starts
+       with a tutorial on Scheme based, and then it describes the rest
+       of the PLT Scheme language.}
+
+]
+
+Of course, you should feel free to mix and match the above two tracks,
+since there is information in each that is not in the other.

collects/scribblings/main/info.ss

@@ -9,6 +9,7 @@
     ("master-index.scrbl" (depends-all-main no-depend-on) (omit))
     ("user/search.scrbl"       (user-doc depends-all no-depend-on) (omit))
     ("user/master-index.scrbl" (user-doc depends-all no-depend-on) (omit))
+    ("getting-started.scrbl" () (omit))
     ("license.scrbl" () (omit))
     ("acks.scrbl"    () (omit))
     ("release.scrbl" () (omit))))

collects/scribblings/main/private/manuals.ss

@@ -80,12 +80,29 @@
                      s)))
                 infos
                 recs)]
+         [docs (cons
+                ;; Add HtDP
+                (list
+                 ;; Category
+                 'getting-started
+                 ;; Priority
+                 7
+                 ;; Priority label (not used):
+                 ""
+                 ;; Path
+                 '(url "http://www.htdp.org/")
+                 ;; Spec
+                 (italic (link #:underline? #f "http://www.htdp.org/" "How to Design Programs")))
+                docs)]
          [plain-line
           (lambda content
             (list (make-flow (list (make-paragraph content)))))]
          [line
           (lambda (spec)
-            (plain-line (hspace 2) (other-manual spec #:underline? #f)))])
+            (plain-line (hspace 2) 
+                        (if (element? spec)
+                            spec
+                            (other-manual spec #:underline? #f))))])
     (define (contents renderer part resolve-info)
       (make-table
        #f
@@ -96,7 +113,10 @@
                                docs)])
              (list*
               (plain-line (hspace 1))
-              (plain-line (sec-label sec))
+              (plain-line (let ([s (sec-label sec)])
+                            (if (and (list? s) (eq? 'link (car s)))
+                                (seclink "top" #:doc (caddr s) #:underline? #f (cadr s))
+                                s)))
               (add-sections
                (sec-cat sec)
                (lambda (str)

collects/scribblings/more/info.ss

@@ -1,3 +1,3 @@
 #lang setup/infotab
 
-(define scribblings '(("more.scrbl" () (getting-started 5))))
+(define scribblings '(("more.scrbl" () (getting-started 3))))

collects/scribblings/quick/quick.scrbl

@@ -582,9 +582,16 @@ threads. That is, instead of a ``minimalist'' language---which is the
 way that Scheme is often described---PLT Scheme offers a rich language
 with an extensive set of libraries and tools.
 
-To continue touring PLT Scheme, but from a systems-oriented
+If you are new to programming or if you have the patience to work
-perspective instead of pictures, your next stop is @other-manual['(lib
+through a textbook, we recommend reading
-"scribblings/more/more.scrbl")].
+@italic{@link["http://www.htdp.org/"]{How to Design Programs}}. If you
+have already read it, or if you want to see where the book will take
+you, then see @other-manual['(lib
+"web-server/scribblings/tutorial/continue.scrbl")].
+
+For experienced programmers, to continue touring PLT Scheme from a
+systems-oriented perspective instead of pictures, your next stop is
+@other-manual['(lib "scribblings/more/more.scrbl")].
 
 To instead start learning about the full PLT Scheme language and tools
 in depth, move on to @other-manual['(lib "guide.scrbl"

collects/scribblings/reference/exns.scrbl

@@ -150,21 +150,24 @@ is provided; it is described in more detail below. The
 @scheme[message] is used as the main body of the error message.
 
 The optional @scheme[expr] argument is the erroneous source syntax
-object or S-expression. The optional @scheme[sub-expr] argument is a
+object or S-expression (but the expression @scheme[#f] cannot be
-syntax object or S-expression within @scheme[expr] that more precisely
+represented by itself; it must be wrapped as a @tech{syntax
-locates the error.  Both may appear in the generated error-message
+object}). The optional @scheme[sub-expr] argument is a syntax object
-text if @scheme[error-print-source-location] is @scheme[#t]. Source
+or S-expression (again, @scheme[#f] cannot represent itself) within
-location information in the error-message text is similarly extracted
+@scheme[expr] that more precisely locates the error.  Both may appear
-from @scheme[sub-expr] or @scheme[expr] when at least one is a syntax
+in the generated error-message text if
+@scheme[error-print-source-location] is @scheme[#t]. Source location
+information in the error-message text is similarly extracted from
+@scheme[sub-expr] or @scheme[expr] when at least one is a syntax
 object and @scheme[error-print-source-location] is @scheme[#t].
 
-If @scheme[sub-expr] is provided, it is used (in syntax form) for the
+If @scheme[sub-expr] is provided and not @scheme[#f], it is used (in
-@scheme[exprs] field of the generated exception record, else the
+syntax form) for the @scheme[exprs] field of the generated exception
-@scheme[expr] is used if provided. In either case, the syntax object
+record, else the @scheme[expr] is used if provided and not
-is @scheme[cons]ed onto @scheme[extra-sources] to produce the
+@scheme[#f]. In either case, the syntax object is @scheme[cons]ed onto
-@scheme[exprs] field, or @scheme[extra-sources] is used directly for
+@scheme[extra-sources] to produce the @scheme[exprs] field, or
-@scheme[exprs] if neither @scheme[expr] nor @scheme[sub-expr] is
+@scheme[extra-sources] is used directly for @scheme[exprs] if neither
-provided.
+@scheme[expr] nor @scheme[sub-expr] is provided and not @scheme[#f].
 
 The form name used in the generated error message is determined
 through a combination of the @scheme[name], @scheme[expr], and

collects/scribblings/reference/hashes.scrbl

@@ -282,11 +282,10 @@ caveat above about concurrent modification.
 @defproc[(hash-count [hash hash?])
          exact-nonnegative-integer?]{
 
-Returns the number of keys mapped by @scheme[hash]. If
+Returns the number of keys mapped by @scheme[hash]. If @scheme[hash]
-@scheme[hash] is not created with @scheme['weak], then the
+is not created with @scheme['weak], then the result is computed in
-result is computed in constant time and atomically. If
+constant time and atomically. If @scheme[hash] is created with
-@scheme[hash] is created with @scheme['weak], see the caveat
+@scheme['weak], see the @concurrency-caveat[] above.}
-above about concurrent modification.}
 
 
 @defproc[(hash-iterate-first [hash hash?])
@@ -342,24 +341,24 @@ key-comparison mode, and same key-holding strength as @scheme[hash].}
 
 Returns an exact integer; for any two @scheme[eq?] values, the
 returned integer is the same. Furthermore, for the result integer
-@scheme[k] and any other exact integer @scheme[j], @scheme[(= k j)]
+@scheme[_k] and any other exact integer @scheme[_j], @scheme[(= _k _j)]
-implies @scheme[(eq? k j)].}
+implies @scheme[(eq? _k _j)].}
 
 
 @defproc[(eqv-hash-code [v any/c]) exact-integer?]{
 
 Returns an exact integer; for any two @scheme[eqv?] values, the
 returned integer is the same. Furthermore, for the result integer
-@scheme[k] and any other exact integer @scheme[j], @scheme[(= k j)]
+@scheme[_k] and any other exact integer @scheme[_j], @scheme[(= _k _j)]
-implies @scheme[(eq? k j)].}
+implies @scheme[(eq? _k _j)].}
 
 
 @defproc[(equal-hash-code [v any/c]) exact-integer?]{
 
 Returns an exact integer; for any two @scheme[equal?] values, the
 returned integer is the same.  Furthermore, for the result integer
-@scheme[k] and any other exact integer @scheme[j], @scheme[(= k j)]
+@scheme[_k] and any other exact integer @scheme[_j], @scheme[(= _k _j)]
-implies @scheme[(eq? k j)]. A has code is computed even when
+implies @scheme[(eq? _k _j)]. A has code is computed even when
 @scheme[v] contains a cycle through pairs, vectors, boxes, and/or
 inspectable structure fields. See also @scheme[prop:equal+hash].}
 

collects/web-server/info.ss

@@ -2,7 +2,7 @@
 
 (define scribblings
   '(("scribblings/web-server.scrbl" (multi-page) (tool))
-    ("scribblings/tutorial/continue.scrbl" () (getting-started))))
+    ("scribblings/tutorial/continue.scrbl" () (getting-started 5))))
 
 (define mzscheme-launcher-libraries '("main.ss"))
 (define mzscheme-launcher-names     '("PLT Web Server"))

collects/web-server/scribblings/tutorial/continue.scrbl

@@ -16,8 +16,10 @@ up a web server, how to generate dynamic web content, and how to
 interact with the user.
 
 The target audience for this tutorial are students who've gone through
-the design and use of structures in @link["http://htdp.org/"]{How to Design Programs}, with some 
+the design and use of structures in
-higher-order functions, @scheme[local], and a minor bit of mutation.
+@italic{@link["http://www.htdp.org/"]{How to Design Programs}}, with
+some higher-order functions, @scheme[local], and a minor bit of
+mutation.
 
 @section{Getting Started}
 

src/mzscheme/src/error.c

@@ -2045,8 +2045,8 @@ static Scheme_Object *raise_syntax_error(int argc, Scheme_Object *argv[])
   }
 
   scheme_wrong_syntax_with_more_sources(who,
-                                        (argc > 3) ? argv[3] : NULL,
+                                        ((argc > 3) && !SCHEME_FALSEP(argv[3])) ? argv[3] : NULL,
-                                        (argc > 2) ? argv[2] : NULL,
+                                        ((argc > 2) && !SCHEME_FALSEP(argv[2])) ? argv[2] : NULL,
                                         extra_sources,
                                         "%T", str);