simplify `pollen/setup` interface

info.rkt

@@ -1,7 +1,7 @@
 #lang info
 (define collection 'multi)
 
-(define version "0.9.912.58103")
+(define version "0.9.912.83987")
 (define deps '("base" "txexpr" "sugar" ("markdown" #:version "0.18") "htdp"
                "at-exp-lib" "html-lib" "rackjure" "web-server-lib" "scribble-text-lib" "rackunit-lib"
                "gui-lib"))

pollen/private/ts.rktd

@@ -1 +1 @@
-1454195303
+1454221187

pollen/scribblings/setup.scrbl

@@ -9,29 +9,10 @@
 
 @defmodule[pollen/setup]
 
-Global values that are used throughout the Pollen system.
 
-@section{Parameters}
+@section[#:tag "setup-overrides"]{How to override setup values}
 
-I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize]. 
+The values below can be changed by overriding them in your @racket["pollen.rkt"] source file:
-
-@defparam[setup:current-server-port port integer?]{
-A parameter that sets the HTTP port for the project server. Initialized to @racket[setup:default-project-server-port].}
-
-
-@defparam[setup:current-project-root port path?]{
-A parameter that holds the root directory of the current project (e.g., the directory where you launched @code{raco pollen start}).}
-
-@defparam[setup:current-server-extras-path dir path?]{
-A parameter that reports the path to the directory of support files for the project server. Initialized to @racket[#f], but set to a proper value when the server runs.}
-
-@defparam[setup:current-poly-target target symbol?]{
-A parameter that reports the current rendering target for @racket[poly] source files. Initialized to @racket['html].}
-
-
-@section[#:tag "setup-overrides"]{Setup overrides}
-
-These values can be changed by overriding them in your @racket["pollen.rkt"] source file:
 
 @itemlist[#:style 'ordered
 
@@ -42,9 +23,12 @@ These values can be changed by overriding them in your @racket["pollen.rkt"] sou
 @item{Assign it whatever value you like.}
 
 @item{Repeat as needed.}
+
+@item{(Don't forget to @racket[provide] the variables from within your @racket[setup] submodule.)}
+
  ]
 
-  When Pollen runs, these definitions will supersede those in @racket[pollen/setup].
+When Pollen runs, these definitions will supersede those in @racketmodname[pollen/setup].
 
 For instance, suppose you wanted the main export of every Pollen source file to be called @racket[van-halen] rather than @racket[doc], the extension of Pollen markup files to be @racket[.rock] rather than @racket[.pm], and the command character to be @litchar{🎸} instead of @litchar{◊}. Your @racket["pollen.rkt"] would look like this:
 
@@ -61,28 +45,22 @@ For instance, suppose you wanted the main export of every Pollen source file to
   (define command-char #\🎸))
 }]
 
-Though any of the values below can be overridden, it may not always be wise to do so. For instance, if you redefined @racket[setup:default-fallback-template-prefix], you would simply break the fallback-template mechanism, because it would look for files that don't exist. But we don't live in a nanny state, so you are entrusted to say what you mean and accept the consequences.
-
 Of course, you can restore the defaults simply by removing these defined values from @racket["pollen.rkt"].
 
-These values are each equipped with a corresponding @racket[setup:]@racket[_name] function that will return the value loaded from the @racket[setup] submodule (if @racket[_name] was defined there), otherwise it returns the original value for @racket[setup:]@racket[_name]. For instance, @racket[setup:default-command-char] will always be @litchar{◊}, but in the example above, @racket[setup:command-char] would return @litchar{🎸}. 
+Every @racket[(setup:_name)] function will resolve the current value of that variable: it will return the value from the @racket[setup] submodule (if @racket[_name] was defined there), otherwise it will return the default value (which is directly available from @racket[setup:default-]@racket[_name]). For instance, @racket[setup:default-command-char] will always be @litchar{◊}, but in the example above, @racket[(setup:command-char)] would return @litchar{🎸}. 
 
+@section{Values}
 
 @defoverridable[project-server-port integer?]{
-Determines the default HTTP port for the project server. Initialized to @racket[8080].}
+Determines the default HTTP port for the project server. Initialized to @val[setup:default-project-server-port].}
-
 
 @defoverridable[main-export symbol?]{The main X-expression exported from a compiled Pollen source file. Initialized to @racket[doc].}
 
 @defoverridable[meta-export symbol?]{The meta hashtable exported from a compiled Pollen source file. Initialized to @racket[metas].}
 
-@defoverridable[meta-tag-name symbol?]{Name of the tag used to mark metas within Pollen source.}
-
 @defoverridable[extension-escape-char char?]{Character for escaping output-file extensions within source-file names. Initialized to @racket[#\_].}
 
 
-
-
 @deftogether[(
 @defoverridable[preproc-source-ext symbol?]
 @defoverridable[markup-source-ext symbol?]
@@ -103,14 +81,9 @@ File extensions for Pollen source files, initialized to the following values:
 @(linebreak)@racket[setup:default-scribble-source-ext] = @code[(format "'~a" setup:default-scribble-source-ext)]
 
 
-@defoverridable[decodable-extensions (listof symbol?)]{File extensions that are eligible for decoding.}
-
-
 @defoverridable[main-pagetree string?]{Pagetree that Pollen dashboard loads by default in each directory. Initialized to @filepath{index.ptree}.}
 
 
-@defoverridable[pagetree-root-node symbol?]{Name of the root node in a decoded pagetree. It's ignored by the code, so its only role is to clue you in that you're looking at something that came out of the pagetree decoder. Initialized to @code{'pagetree-root}.}
-
 
 @defoverridable[main-root-node symbol?]{Name of the root node in a decoded @racket[doc]. Initialized to @code{'root}.}
 
@@ -127,11 +100,6 @@ File extensions for Pollen source files, initialized to the following values:
 @defoverridable[template-prefix string?]{Prefix of the default template. Initialized to @code{"template"}.}
 
 
-@defoverridable[fallback-template-prefix string?]{Used to generate the name of the fallback template (i.e., the template used to render a Pollen markup file when no other template can be found). Prefix is combined with the output suffix of the source file. Initialized to @code{"fallback"}.}
-
-
-@defoverridable[template-meta-key symbol?]{Meta key used to store a template name for that particular source file. Initialized to @racket['template].}
-
 @deftogether[(
 @(defoverridable newline string?)
 @(defoverridable linebreak-separator string?)
@@ -139,9 +107,6 @@ File extensions for Pollen source files, initialized to the following values:
 )]    
 Default separators used in decoding. The first two are initialized to @racket["\n"]; the third to @racket["\n\n"].
 
-@defoverridable[dashboard-css string?]{CSS file used for the dashboard. Initialized to @filepath{poldash.css}.}
-
-@defoverridable[paths-excluded-from-dashboard (listof path?)]{Paths not shown in the Pollen dashboard.}
 
 @defoverridable[render-cache-active boolean?]{Whether the render cache, which speeds up interactive sessions by reusing rendered versions of Pollen output files, is active. Default is active (@racket[#t]).}
 
@@ -151,7 +116,6 @@ Default separators used in decoding. The first two are initialized to @racket["\
 
 @defoverridable[unpublished-path? (path? . -> . boolean?)]{Predicate that determines whether a path is omitted from @secref{raco_pollen_publish} operations. If the predicate is @racket[#t], then the path is omitted. The default, therefore, is @racket[#f].}
 
-@defoverridable[here-path-key symbol?]{Key used to store the absolute path of the current source file in its @racket[metas] hashtable. Default is @racket['here-path].}
 
 @defoverridable[splicing-tag symbol?]{Key used to signal that an X-expression should be spliced into its containing X-expression. Default is @val[setup:default-splicing-tag].}