doc improvements re metas

scribblings/cache.scrbl

@@ -19,7 +19,7 @@ The slowest part of a @racket[render] is parsing and decoding the source file. O
 (or/c txexpr? hash? integer?)]
 Similar to @racket[(dynamic-require _source-path _key)], except that it first tries to retrieve the requested value out of the cache. If it's not there, or out of date, @racket[dynamic-require] is used to update the value.
 
-The only keys supported are @racket['doc] and @racket['metas].
+The only keys supported are @racket[doc] and @racket[metas] (or more precisely, the values of @racket[world:current-main-export] and @racket[world:current-meta-export], which default to @racket[doc] and @racket[metas]).
 
 If you want the speed benefit of the cache, you should @bold{always} use @racket[cached-require] to get data from Pollen source files. That doesn't mean you can't still use functions like @racket[require], @racket[local-require], and @racket[dynamic-require]. They'll just be slower.
 

scribblings/command.scrbl

@@ -593,6 +593,58 @@ In this case, though there are two metas named @racket[dog] (and they use differ
 The @racket[metas] submodule is useful because it gives you access to the @racket[metas] hashtable @italic{without} compiling the rest of the file. So if you need to collect metas from a set of source files — for instance, page titles (for a table of contents) or categories — getting the metas through the submodule is likely to be faster.
 
 
+@;--------------------------------------------------------------------
+@subsubsection{Retrieving metas}
+
+The @racket[metas] hashtable is available immediately within the body of your source file. You can use @racket[hash-ref] to get values out of @racket[metas].
+
+@codeblock{
+#lang pollen
+◊(define-meta dog "Roxy")
+◊(hash-ref metas 'dog)
+}
+
+@terminal{
+Roxy
+}
+
+
+Because the metas are collected first, you can actually invoke a meta before you define it:
+
+@codeblock{
+#lang pollen
+◊(hash-ref metas 'dog)
+◊(define-meta dog "Roxy")
+◊(define-meta dog "Spooky")
+}
+
+@terminal{
+Spooky
+}
+
+This can be useful for setting up fields that you want to include in @racket[metas] but also have visible in the body of a document, like a title.
+
+@codeblock{
+#lang pollen/markup
+◊(define-meta title "The Amazing Truth")
+◊h1{◊(hash-ref metas 'title)}
+}
+
+The result of this file will be:
+
+@terminal{
+'(root (h1 "The Amazing Truth"))
+}
+
+And the metas:
+@terminal{
+> metas
+'#hash((title . "The Amazing Truth") (here-path . "unsaved-editor"))
+}
+You cannot, however, use @racket[hash-set!] or other similar functions, because @racket[metas] is an immutable hash.
+
+
+
 @;--------------------------------------------------------------------
 @subsubsection{Inserting a comment}
 

scribblings/formats.scrbl

@@ -40,9 +40,13 @@ There are no undefined commands in Pollen. If a command has not already been def
 
 By default, every Pollen source file exports two identifiers, 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).
+The main export, @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).
+The second export, @racket[metas], is a hashtable 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).
+
+Pollen source files also make the @racket[metas] hashtable available through a submodule, also called @racket[metas]. So rather than importing a source file with @racket[(require "source.html.pm")], you would @racket[(require (submod "source.html.pm" metas))]. Accessing the metas this way avoids fully compiling the source file, and thus will usually be faster.
+
+The names @racket[doc] and @racket[metas] can be changed for a project by overriding @racket[world:main-export] and @racket[world:meta-export].
 
 @margin-note{The Pollen rendering system relies on these two identifiers, but otherwise doesn't care how they're generated. Meaning, the code inside your Pollen source file could be @tt{#lang racket} or @tt{#lang whatever}. As long as you manually @racket[provide] those two identifiers and follow the usual file-naming convention, your source file will be usable.}
 

scribblings/render.scrbl

@@ -77,7 +77,7 @@ Note that @racket[_pagetree] or @racket[_pagetree_source] is used strictly as a
 Find a template file for @racket[_source-path], with the following priority:
 @itemlist[#:style 'ordered
 
-@item{If the metas for @racket[_source-path] have a key for @code[(format "~a" world:template-meta-key)], then use the value of this key.}
+@item{If the @racket[metas] for @racket[_source-path] have a key for @code[(format "~a" world:template-meta-key)], then use the value of this key.}
 
 @item{If this key doesn't exist, or if it points to a nonexistent file, look for a default template in the project directory with the name @code[(format "~a.[output extension]" world:default-template-prefix)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the output path would be @code["intro.html"], so the default template would be @code[(format "~a.html" world:default-template-prefix)].}