updates

command.rkt

@@ -2,6 +2,9 @@
 (require pollen/world)
 (provide (all-defined-out))
 
+(define (handle-test)
+  `(displayln "raco pollen is installed correctly"))
+
 (define (handle-help)
   `(displayln (format "Pollen commands:
 help                  show this message

raco.rkt

@@ -27,6 +27,7 @@
 (define-syntax (select-syntax-for-command stx)
   (datum->syntax stx 
                  (case arg-command-name
+                   [("test" "xyzzy") (handle-test)]
                    [(#f "help") (handle-help)]
                    [("start") (handle-start first-arg-or-current-dir port-arg)]
                    [("render") (handle-render first-arg-or-current-dir rest-args)]

scribblings/command.scrbl

@@ -628,6 +628,4 @@ The answer is to use a @italic{rest argument} in the function, which takes the `
 
 @section{Further reading}
 
-The Pollen language is a variant of Racket's own text-processing language, called Scribble. So many things that are true about Scribble are also true about Pollen. For the sake of clarity & brevity, I've omitted them from this summary. But if you want the full story:
+The Pollen language is a variant of Racket's own text-processing language, called Scribble. So many things that are true about Scribble are also true about Pollen. For the sake of clarity & brevity, I've omitted them from this summary. But if you want the full story, see @secref["reader" #:doc '(lib "scribblings/scribble/scribble.scrbl")] in the Scribble documentation.
-
-[insert]

scribblings/formats.scrbl

@@ -0,0 +1,154 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world sugar pollen/pagetree))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen pollen/file))
+
+
+@title{File formats}
+
+
+@section{Source formats}
+
+@defmodulelang*[(pollen/pre pollen/markdown pollen/markup pollen/pagetree)]
+
+
+The Pollen language is divided into variants, or @italic{dialects}, that are tailored to suit each of the core source formats.
+
+These dialects can be invoked one of two ways: either by invoking a specific dialect in the first line of the file (also known as the @litchar{#lang} line), or by using the generic @litchar{#lang pollen} as the first line, and then the correct dialect will be automatically selected based on the source file extension.
+
+If the @litchar{#lang} line specifies a dialect different from the one specified by the file extension, the @litchar{#lang} line will take precedence. 
+
+
+For ease of use, the behavior of the Pollen language departs from the standard Racket language in several ways. The differences are noted below.
+
+@subsection{Command syntax using ◊}
+
+Commands must start with the special lozenge character @litchar{◊}. Other material is interpreted as plain text. See @secref["◊ command overview"] for more.
+
+@bold{How is this different from Racket?} In Racket, everything is a command, and plain text must be quoted.
+
+@subsection{Any command is valid}
+
+There are no undefined commands in Pollen. If a command has not already been defined, it's treated as a tag function. See @secref["◊ command overview"] for more.
+
+@bold{How is this different from Racket?} In Racket, if you try to treat an identifier as a function before defining it with @racket[define], you'll get an error.
+
+
+@subsection{Standard exports}
+
+By default, every Pollen source file exports two symbols, which you can access by using the source file with @racket[require]:
+
+@racket['doc] contains the output of the file. The type of output depends on the source format (documented below).
+
+@racket['metas] is a hash of key–value pairs with extra information that is extracted from the source. These @racket['metas] will always contain the key @racket['here-path], which returns a string representation of the full path to the source file. Beyond that, the only @racket['metas] are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).
+
+@bold{How is this different from Racket?} In Racket, you must explicitly @racket[define] and then @racket[provide] any values you want to export.
+
+@subsection{Custom exports}
+
+Any value or function that is defined within the source file using @racket[define] is automatically exported.
+
+@bold{How is this different from Racket?} In Racket, you must explicitly @racket[provide] any values you want to export. Unlike Racket, every Pollen source file impliedly uses @racket[(provide (all-defined-out))].
+
+
+@subsection{The @code{@(format "~a" world:project-require)} file}
+
+If a file called @code{@(format "~a" world:project-require)} exists in the same directory with a source file, it's automatically imported when the source file is compiled.
+
+@bold{How is this different from Racket?} In Racket, you must explicitly import files using @racket[require].
+
+@subsection{Preprocessor (@(format ".~a" world:preproc-source-ext) extension)}
+
+Invoke the preprocessor dialect by using @code{#lang pollen/pre} as the first line of your source file, or by using @code{#lang pollen} with a file extension of @code{@(format ".~a" world:preproc-source-ext)}. These forms are equivalent:
+
+
+@racketmod[#:file "sample.css.pp" pollen
+_...source...
+]
+
+@racketmod[#:file "sample.css" pollen/pre
+_...source...
+]
+
+When no dialect is explicitly specified by either the @litchar{#lang} line or the file extension, Pollen will default to using the preprocessor dialect. For instance:
+
+@racketmod[#:file "test.yyz" pollen
+_...source...
+]
+
+Of course, you're better off specifying the preprocessor dialect explicitly rather than relying on this default behavior.
+
+The output of the preprocessor dialect, provided by @racket['doc], is plain text.
+
+
+
+@subsection{Markdown (@(format ".~a" world:markdown-source-ext) extension)}
+
+Invoke the Markdown dialect by using @code{#lang pollen/markdown} as the first line of your source file, or by using @code{#lang pollen} with a file extension of @code{@(format ".~a" world:markdown-source-ext)}. These forms are equivalent:
+
+
+@racketmod[#:file "sample.txt.pmd" pollen
+_...source...
+]
+
+@racketmod[#:file "sample.txt" pollen/markdown
+_...source...
+]
+
+The output of the Markdown dialect, provided by @racket['doc], is a tagged X-expression.
+
+
+@subsection{Markup (@(format ".~a" world:markup-source-ext) extension)}
+
+Invoke the Pollen markup dialect by using @code{#lang pollen/markup} as the first line of your source file, or by using @code{#lang pollen} with a file extension of @code{@(format ".~a" world:markup-source-ext)}. These forms are equivalent:
+
+
+@racketmod[#:file "about.html.pm" pollen
+_...source...
+]
+
+@racketmod[#:file "about.html" pollen/markup
+_...source...
+]
+
+The output of the Pollen markup dialect, provided by @racket['doc], is a tagged X-expression.
+
+@subsection{Pagetree  (@(format ".~a" world:pagetree-source-ext) extension)}
+
+
+Invoke the pagetree dialect by using @code{#lang pollen/ptree} as the first line of your source file, or by using @code{#lang pollen} with a file extension of @code{@(format ".~a" world:pagetree-source-ext)}. These forms are equivalent:
+
+
+@racketmod[#:file "main.ptree" pollen
+_...source...
+]
+
+@racketmod[#:file "main.rkt" pollen/ptree
+_...source...
+]
+
+
+
+The output of the pagetree dialect, provided by @racket['doc], is a @racket[pagetree?] that is checked for correctness using @racket[validate-pagetree].
+
+
+
+
+@section{Utility formats}
+
+These aren't source formats because they don't contain a @litchar{#lang pollen} line. But for convenience, they get special handling by the Pollen project server.
+
+
+
+@subsection{Scribble  (@(format ".~a" world:scribble-source-ext) extension)}
+
+Scribble files are recognized by the project server and can be compiled and previewed in single-page mode.
+
+
+@subsection{Null (@(format ".~a" world:null-source-ext) extension)}
+
+Files with the null extension are simply rendered as a copy of the file without the extension, so @code{index.html.p} becomes @code{index.html}. 
+
+This can be useful you're managing your project with git. Most likely you'll want to ignore @code{*.html} and other file types that are frequently regenerated by the project server. But if you have isolated static files — for instance, a @code{index.html} that doesn't have source associated with it — they'll be ignored too. You can cure this problem by appending the null extension to these static files, so they'll be tracked in your source system without actually being source files.

scribblings/installation.scrbl

@@ -0,0 +1,17 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world sugar))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen pollen/file))
+
+
+@title{Installation}
+
+Install Racket, which includes DrRacket.
+
+Install Pollen from the command line:
+@verbatim{raco pkg install pollen}
+
+After that, you can update the package from the command line:
+@verbatim{raco pkg update pollen}

scribblings/license.scrbl

@@ -0,0 +1,13 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world sugar))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen pollen/file))
+
+
+@title{License & source code}
+
+This module is licensed under the LGPL.
+
+Source repository at @link["http://github.com/mbutterick/pollen"]{http://github.com/mbutterick/pollen}. Suggestions & corrections welcome.

scribblings/pollen.scrbl

@@ -40,50 +40,18 @@ Or, if you can find a better digital-publishing tool, use that. But I'm never go
 
 @include-section["acknowledgments.scrbl"]
 
-
+@include-section["installation.scrbl"]
-@section{Installation}
-
-Install Racket, which includes DrRacket.
-
-Install Pollen from the command line:
-@verbatim{raco pkg install pollen}
-
-After that, you can update the package from the command line:
-@verbatim{raco pkg update pollen}
-
-
 
 @include-section["quick.scrbl"]
 
+@include-section["raco.scrbl"]
 
-
+@include-section["formats.scrbl"]
-@section{Source formats}
-
-[pollen]
-
-This puts Pollen into automatic mode, where the source file is interpreted according to the file extension. 
-
-If the file extension is ``@(format ".~a" world:markup-source-ext)'', the source is interpreted as [pollen/markup].
-
-If the file extension is ``@(format ".~a" world:preproc-source-ext)'', the source is interpreted as [pollen/pre] (``pre'' stands for ``preprocessor'').
-
-If the file extension is ``@(format ".~a" world:markdown-source-ext)'', the source is interpreted as [pollen/markdown].
-
-[pollen/markup]
-
-
-[pollen/pre]
-
-[pollen/markdown]
 
 @include-section["command.scrbl"]
 
-@include-section["module-reference.scrbl"]
+@;include-section["server.scrbl"]
-
-
-@section{License & source code}
 
-This module is licensed under the LGPL.
+@include-section["module-reference.scrbl"]
-
-Source repository at @link["http://github.com/mbutterick/pollen"]{http://github.com/mbutterick/pollen}. Suggestions & corrections welcome.
 
+@include-section["license.scrbl"]

scribblings/raco.scrbl

@@ -0,0 +1,88 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/render pollen/world (for-label racket pollen/world))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen pollen/file))
+
+
+@title{Using @exec{raco pollen}}
+
+
+Racket provides centralized command-line options through @racket[raco] (short for @code{racket command}, see @other-doc['(lib "scribblings/raco/raco.scrbl")]). 
+
+Once you install Pollen, you can access the following Pollen-specific commands through @racket[raco] using the subcommand @exec{raco pollen}.
+
+@section{Making sure @racket[raco pollen] works}
+
+Open a terminal window and type:
+
+@verbatim{
+> raco pollen test}
+
+If @racket[raco pollen] is installed correctly, you'll see:
+
+@verbatim{raco pollen is installed correctly}
+
+But if you get:
+
+@verbatim{raco: Unrecognized command: pollen}
+
+You'll need to fix the problem before proceeding, most likely by reinstalling Pollen (see @racket[Installation]).
+
+@section{@racket[raco pollen]}
+
+Same as @racket[raco pollen help].
+
+@section{@racket[raco pollen help]}
+
+Displays a list of available commands.
+
+
+@section{@racket[raco pollen start]}
+
+Starts the project server from the current directory using the default port, which is the value of the parameter @racket[world:current-server-port] (by default, port @(format "~a" world:default-port)).
+
+This command can be invoked with two optional arguments.
+
+@racket[raco pollen start _path] will start the project server in @racket[_path] rather than the current directory.
+
+@verbatim{
+> raco pollen start ~/path/to/project/}
+
+@racket[raco pollen start _path _port] will start the project server in @racket[_path] using @racket[_port] rather than @racket[world:current-server-port]. This is useful if you want to have multiple project servers running simultaneously.
+
+@verbatim{
+> raco pollen start ~/path/to/project/
+> raco pollen start ~/path/to/project/scribblings 8088}
+
+If you want to start in the current directory but with a different port, use @litchar{.} as the path:
+
+@verbatim{
+> raco pollen start . 8088}
+
+@section{@racket[raco pollen render]}
+
+Renders all preprocessor source files and then all pagetree files found in the current directory.
+
+This command can be invoked with extra arguments.
+
+@racket[raco pollen render _directory] will render the preprocessor source files and pagetree files in the specified directory.
+
+Alternatively, the command can take a variable number of path arguments. @racket[raco pollen render _path...] will render only the paths specified in @racket[_path...]. Consistent with the usual command-line idiom, this can be a single path, a list of paths, or a pattern:
+
+@verbatim{
+> raco pollen render foo.html.pm
+> raco pollen render foo.html.pm bar.html.pm zam.css.pp
+> raco pollen render *.html.pm}
+
+
+@section{@racket[raco pollen clone]}
+
+Makes a copy of the project directory on the desktop, and removes any source files or other Pollen-related files.
+
+@racket[raco pollen clobe _directory-path] will perform the same copying and filtering, but using @racket[_directory-path] as the destination rather than the desktop.
+
+
+
+

scribblings/server.scrbl

@@ -0,0 +1,12 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/render pollen/world (for-label racket pollen/world))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen pollen/file))
+
+
+@title{The project server}
+
+
+

world.rkt

@@ -46,7 +46,8 @@
 
 (define current-project-root (make-parameter (current-directory)))
 
-(define current-server-port (make-parameter 8080))
+(define default-port 8080)
+(define current-server-port (make-parameter default-port))
 
 (define dashboard-css "poldash.css")