From 6ec8cf47c320d66390389d476a646178a71f37d3 Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Tue, 29 Apr 2014 18:52:12 -0700 Subject: [PATCH] updates --- command.rkt | 3 + raco.rkt | 1 + scribblings/command.scrbl | 4 +- scribblings/formats.scrbl | 154 +++++++++++++++++++++++++++++++++ scribblings/installation.scrbl | 17 ++++ scribblings/license.scrbl | 13 +++ scribblings/pollen.scrbl | 44 ++-------- scribblings/raco.scrbl | 88 +++++++++++++++++++ scribblings/server.scrbl | 12 +++ world.rkt | 3 +- 10 files changed, 297 insertions(+), 42 deletions(-) create mode 100644 scribblings/formats.scrbl create mode 100644 scribblings/installation.scrbl create mode 100644 scribblings/license.scrbl create mode 100644 scribblings/raco.scrbl create mode 100644 scribblings/server.scrbl diff --git a/command.rkt b/command.rkt index 9ca9ad8..f503878 100644 --- a/command.rkt +++ b/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 diff --git a/raco.rkt b/raco.rkt index 0d5db40..f828131 100644 --- a/raco.rkt +++ b/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)] diff --git a/scribblings/command.scrbl b/scribblings/command.scrbl index 4c0d8ba..54d7d68 100644 --- a/scribblings/command.scrbl +++ b/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: - -[insert] \ No newline at end of file +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. \ No newline at end of file diff --git a/scribblings/formats.scrbl b/scribblings/formats.scrbl new file mode 100644 index 0000000..b701ffb --- /dev/null +++ b/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. diff --git a/scribblings/installation.scrbl b/scribblings/installation.scrbl new file mode 100644 index 0000000..c72180e --- /dev/null +++ b/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} diff --git a/scribblings/license.scrbl b/scribblings/license.scrbl new file mode 100644 index 0000000..d219277 --- /dev/null +++ b/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. diff --git a/scribblings/pollen.scrbl b/scribblings/pollen.scrbl index 7ca5b97..835a914 100644 --- a/scribblings/pollen.scrbl +++ b/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"] - -@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["installation.scrbl"] @include-section["quick.scrbl"] +@include-section["raco.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["formats.scrbl"] @include-section["command.scrbl"] -@include-section["module-reference.scrbl"] - - -@section{License & source code} +@;include-section["server.scrbl"] -This module is licensed under the LGPL. - -Source repository at @link["http://github.com/mbutterick/pollen"]{http://github.com/mbutterick/pollen}. Suggestions & corrections welcome. +@include-section["module-reference.scrbl"] +@include-section["license.scrbl"] diff --git a/scribblings/raco.scrbl b/scribblings/raco.scrbl new file mode 100644 index 0000000..6180af1 --- /dev/null +++ b/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. + + + + diff --git a/scribblings/server.scrbl b/scribblings/server.scrbl new file mode 100644 index 0000000..4762482 --- /dev/null +++ b/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} + + + diff --git a/world.rkt b/world.rkt index c98a591..40e8274 100644 --- a/world.rkt +++ b/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")