documentation updates

scribblings/decode.scrbl

@@ -6,7 +6,7 @@
 @(my-eval `(require pollen pollen/decode pollen/decode/block xml))
 
 
-@section{Decode}
+@title{Decode}
 
 @defmodule[pollen/decode]
 
@@ -146,7 +146,7 @@ The @racket[_tags-to-exclude] argument is useful if you're decoding source that'
 #:exclude-tags '(style script))
 ]
 
-@subsection{Blocks}
+@section{Blocks}
 @defmodule[pollen/decode/block]
 
 Because it's convenient, Pollen categorizes tagged X-expressions into two categories: @italic{block} and @italic{inline}. Why is it convenient? When using @racket[decode], you often want to treat the two categories differently. Not that you have to. But this is how you can.
@@ -195,7 +195,7 @@ A parameter that defines the set of tags that @racket[decode] will treat as bloc
 @code[(format "~a" (dynamic-require 'css-tools/html 'block-tags))]}
 
 
-@subsection{Typography}
+@section{Typography}
 @defmodule[pollen/decode/typography]
 
 An assortment of typography & layout functions, designed to be used with @racket[decode]. These aren't hard to write. So if you like these, use them. If not, make your own.

scribblings/file.scrbl

@@ -5,7 +5,7 @@
 @(define my-eval (make-base-eval))
 @(my-eval `(require pollen pollen/file))
 
-@section{Files}
+@title{Files}
 
 @defmodule[pollen/file]
 

scribblings/module-reference.scrbl

@@ -0,0 +1,11 @@
+#lang scribble/manual
+
+@title[#:style 'toc]{Module reference}
+
+@local-table-of-contents[]
+
+@include-section["cache.scrbl"]
+@include-section["decode.scrbl"]
+@include-section["file.scrbl"]
+@include-section["ptree.scrbl"]
+@include-section["render.scrbl"]

scribblings/pollen.scrbl

@@ -0,0 +1,64 @@
+#lang scribble/manual
+
+@(require scribble/eval pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require pollen))
+
+
+@title{Pollen: the book is a program}
+
+@author[(author+email "Matthew Butterick" "mb@mbtype.com")]
+
+Pollen is a publishing system that helps authors create beautiful and functional web-based books. Pollen includes tools for writing, designing, programming, testing, and publishing.
+
+I used Pollen to create my book @link["http://practicaltypography.com"]{Butterick's Practical Typography}. Sure, go take a look. Is it better than the last digital book you encountered? Yes it is. Would you like your book to look like that? If so, keep reading.
+
+Pollen is built around two ideas. First, that digital books should be the best books we've ever had. (So far, they're not even close.) Second, that if digital books are software, an author shouldn't think of their book as merely data. The book is a program.
+
+Not that you need to be a programmer to use Pollen. On the contrary, the Pollen language is markup-based, so you can write & edit text naturally. But when you want to automate repetitive tasks, add cross-references, or pull in data from other sources, you can access a full programming language from within the text.
+
+That language is Racket. I chose Racket because while the idea for Pollen had been with me for several years, it simply wasn't possible to build it with other languages. So if it's unfamiliar to you, don't panic. It was unfamiliar to me. Once you see what you can do with Pollen & Racket, you may be persuaded. I was.
+
+Or, if you can find a better digital book-publishing tool, use that. Personally, I'm never going back to the way I used to work.
+
+@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}
+
+
+
+@section{Pollen source formats}
+
+@defmodulelang[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 @racket[pollen/markup].
+
+If the file extension is ``@(format ".~a" world:preproc-source-ext)'', the source is interpreted as @racket[pollen/pre] (``pre'' stands for ``preprocessor'').
+
+If the file extension is ``@(format ".~a" world:markdown-source-ext)'', the source is interpreted as @racket[pollen/markdown].
+
+@defmodulelang[pollen/markup]
+
+
+@defmodulelang[pollen/pre]
+
+@defmodulelang[pollen/markdown]
+
+@include-section["module-reference.scrbl"]
+
+
+@section{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/ptree.scrbl

@@ -1,11 +1,11 @@
 #lang scribble/manual
 
-@(require scribble/eval pollen/cache pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world pollen/ptree txexpr sugar pollen/decode xml))
+@(require scribble/eval pollen/cache pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world pollen/ptree txexpr pollen/decode))
 
 @(define my-eval (make-base-eval))
-@(my-eval `(require pollen pollen/ptree))
+@(my-eval `(require pollen pollen/ptree txexpr))
 
-@section{Ptrees}
+@title{Ptrees}
 
 @defmodule[pollen/ptree]
 
@@ -15,36 +15,174 @@ Books and other long documents are usually organized in a structured way — at
 
 @defproc[
 (ptree?
-[v any/c])
+[possible-ptree any/c])
 boolean?]
-Test whether @racket[_v] is a valid ptree: a @racket[txexpr?] whose elements are either @racket[pnode?] or @racket[ptree?]. Also, all the pnodes in a ptree must be unique. The root node is ignored.
+Test whether @racket[_possible-ptree] is a valid ptree. It must be a @racket[txexpr?] where all elements are @racket[pnode?] and unique within @racket[_possible-ptree] (not counting the root node).
 
 @examples[#:eval my-eval
 (ptree? '(root index.html))
 (ptree? '(root index.html index.html))
+(ptree? '(root index.html "index.html"))
 (define nested-pt '(root 1.html 2.html (3.html 3a.html 3b.html)))
 (ptree? nested-pt)
 (ptree? `(root index.html ,nested-pt (subsection.html more.html)))
 (ptree? `(root index.html ,nested-pt (subsection.html ,nested-pt)))
 ]
 
+@defproc[
+(validate-ptree
+[possible-ptree any/c])
+ptree?]
+Like @racket[ptree?], but raises a descriptive error if @racket[_possible-ptree] is invalid, and otherwise returns @racket[_possible-ptree] itself.
+
+@examples[#:eval my-eval
+(validate-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(validate-ptree `(root (,+ son.html daughter.html) uncle.html))
+(validate-ptree '(root (mama.html son.html son.html) mama.html))
+]
+
+
 @defproc[
 (pnode?
+[possible-pnode any/c])
+boolean?]
+Test whether @racket[_possible-pnode] is a valid pnode (short for ``ptree node''). A pnode can be any @racket[symbol?] that is not @racket[whitespace/nbsp?] Every leaf of a ptree is a pnode. In practice, your pnodes will likely be names of output files. 
+
+@margin-note{Pnodes are symbols (rather than strings) so that ptrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.}
+
+@examples[#:eval my-eval
+(map pnode? '(symbol index.html |   silly   |))
+(map pnode? '(9.999 "index.html" (p "Hello") |    |))
+]
+
+
+@defproc[
+(pnodeish?
 [v any/c])
 boolean?]
-Test whether @racket[_v] is a valid pnode. Every leaf of a ptree is a pnode. A pnode can be any @racket[stringish?] value that is both an @racket[xexpr?] and not @racket[whitespace/nbsp?] In practice, your pnodes will likely be names of output files.
+Return @racket[#t] if @racket[_v] can be converted with @racket[->pnode].
 
 @examples[#:eval my-eval
-(map pnode? (list 'symbol "string" "index.html" "\n\n ah! \n\n"))
-(map pnode? (list 9.999 (string->path "index.html") '(p "Hello") "\n\n"))
+(map pnodeish? '(9.999 "index.html" |    |))
 ]
 
 
+@defproc[
+(->pnode
+[v pnodeish?])
+pnode?]
+Convert @racket[_v] to a pnode.
+
+@examples[#:eval my-eval
+(map pnodeish? '(symbol 9.999 "index.html" |  silly  |))
+(map ->pnode '(symbol 9.999 "index.html" |  silly  |))
+]
+
+
+
+@section{Navigation}
+
 
 @defparam[current-ptree ptree ptree?
           #:value #f]{
-A parameter that defines the default ptree used by ptree navigation functions if another is not explicitly specified.}
+A parameter that defines the default ptree used by ptree navigation functions (e.g., @racket[parent], @racket[chidren], et al.) if another is not explicitly specified. Initialized to @racket[#f].}
+
+
+@defproc[
+(parent
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f pnode?)]
+Find the parent pnode of @racket[_p] within @racket[_ptree]. Return @racket[#f] if there isn't one.
+
+@examples[#:eval my-eval
+(current-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(parent 'son.html)
+(parent "mama.html")
+(parent (parent 'son.html))
+(parent (parent (parent 'son.html)))
+]
+
+@defproc[
+(children
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f pnode?)]
+Find the child pnodes of @racket[_p] within @racket[_ptree]. Return @racket[#f] if there aren't any.
+
+@examples[#:eval my-eval
+(current-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(children 'mama.html)
+(children 'uncle.html)
+(children 'root)
+(map children (children 'root))
+]
+
+
+@defproc[
+(siblings
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f pnode?)]
+Find the sibling pnodes of @racket[_p] within @racket[_ptree]. The list will include @racket[_p] itself. But the function will still return @racket[#f] if @racket[_ptree] is @racket[#f].
+
+@examples[#:eval my-eval
+(current-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(siblings 'son.html)
+(siblings 'daughter.html)
+(siblings 'mama.html)
+]
+
+
+@deftogether[(
+
+@defproc[
+(previous
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f pnode?)]
+
+@defproc[
+(previous*
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f (listof pnode?))]
+)]
+Return the pnode immediately before @racket[_p]. For @racket[previous*], return all the pnodes before @racket[_p], in sequence. In both cases, return @racket[#f] if there aren't any pnodes. The root node is ignored.
+
+@examples[#:eval my-eval
+(current-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(previous 'daughter.html)
+(previous 'son.html)
+(previous (previous 'daughter.html))
+(previous 'mama.html)
+(previous* 'daughter.html)
+(previous* 'uncle.html)
+]
+
+@deftogether[(
+
+@defproc[
+(next
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f pnode?)]
+
+@defproc[
+(next*
+[p (or/c #f pnodeish?)]
+[ptree ptree? (current-ptree)])
+(or/c #f (listof pnode?))]
+)]
+Return the pnode immediately after @racket[_p]. For @racket[next*], return all the pnodes after @racket[_p], in sequence. In both cases, return @racket[#f] if there aren't any pnodes. The root node is ignored.
+
+@examples[#:eval my-eval
+(current-ptree '(root (mama.html son.html daughter.html) uncle.html))
+(next 'son.html)
+(next 'daughter.html)
+(next (next 'son.html))
+(next 'uncle.html)
+(next* 'mama.html)
+(next* 'daughter.html)
+]
 
-@defparam[current-url-context dir path?
-          #:value world:current-project-root]{
-A parameter that defines the default directory used to resolve @racket[pnode->url]. Initialized to the root directory of the current project.}

scribblings/render.scrbl

@@ -5,7 +5,7 @@
 @(define my-eval (make-base-eval))
 @(my-eval `(require pollen))
 
-@section{Rendering}
+@title{Rendering}
 
 @defmodule[pollen/render]