From da6ce95acf0d78830ccba89e4767b1f5546f8bb0 Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Mon, 27 May 2019 11:17:06 -0700 Subject: [PATCH] explain 'here-path better --- pollen/private/ts.rktd | 2 +- pollen/scribblings/command.scrbl | 4 ++-- pollen/scribblings/core.scrbl | 7 ++++++- pollen/scribblings/formats.scrbl | 2 +- pollen/scribblings/setup.scrbl | 2 ++ 5 files changed, 12 insertions(+), 5 deletions(-) diff --git a/pollen/private/ts.rktd b/pollen/private/ts.rktd index 3a92ff4..e774d99 100644 --- a/pollen/private/ts.rktd +++ b/pollen/private/ts.rktd @@ -1 +1 @@ -1558741359 +1558981026 diff --git a/pollen/scribblings/command.scrbl b/pollen/scribblings/command.scrbl index 889355d..eb66aba 100644 --- a/pollen/scribblings/command.scrbl +++ b/pollen/scribblings/command.scrbl @@ -1,5 +1,5 @@ #lang scribble/manual -@(require scribble/bnf scribble/eval "utils.rkt" "mb-tools.rkt" +@(require scribble/bnf scribble/eval "utils.rkt" "mb-tools.rkt" pollen/setup (for-syntax racket/base) (for-label rackunit pollen/core pollen/setup pollen/cache pollen/tag pollen/render pollen/template (only-in scribble/reader use-at-readtable))) @@ -612,7 +612,7 @@ Second, the metas are collected into a hash table that is exported with the name '#hasheq((dog . "Roxy") (cat . "Chopper") (here-path . "unsaved-editor")) } -The only key that's automatically defined in every meta table is @id{'here-path}, which is the absolute path to the source file. (In this case, because the file hasn't been saved, you'll see the @val{unsaved-editor} name instead.) +The only key that's automatically defined in every meta table is @racket['#,(setup:here-path-key)], which is the absolute path to the source file. (In this case, because the file hasn't been saved, you'll see the @val{unsaved-editor} name instead.) Still, you can override this too: diff --git a/pollen/scribblings/core.scrbl b/pollen/scribblings/core.scrbl index 235aed1..7e53156 100644 --- a/pollen/scribblings/core.scrbl +++ b/pollen/scribblings/core.scrbl @@ -16,12 +16,17 @@ These functions are automatically imported into every Pollen source file (meanin @section{Metas} +The only key that's automatically defined in every meta table is @racket['#,(setup:here-path-key)], which holds the absolute path to the source file. For instance, you could retrieve this value with @racket[(select-from-metas '#,(setup:here-path-key) metas)]. You can use something other than @racket['#,(setup:here-path-key)] as the key by overriding @racket[setup:here-path-key]. + +For a full introduction to metas, see @secref["Inserting_metas"]. + + @defform[(define-meta name value)] Add @racket[_value] to the metas of the current document, using @racket[_name] as the key. You can retrieve a meta value — even in the same document where you define it — with @racket[(select-from-metas _name metas)]. -For an introduction to metas, see @secref["Inserting_metas"]. + @section{Splicing} diff --git a/pollen/scribblings/formats.scrbl b/pollen/scribblings/formats.scrbl index 4bc31a3..1656f5d 100644 --- a/pollen/scribblings/formats.scrbl +++ b/pollen/scribblings/formats.scrbl @@ -45,7 +45,7 @@ By default, every Pollen source file exports two identifiers: @itemlist[ @item{@id{doc} contains the output of the file. The type of output depends on the source format (about which, more below).} -@item{@id{metas} is a hashtable of key–value pairs with extra information that is extracted from the source. These @id{metas} will always contain the key @id{'here-path}, which returns a string representation of the full path to the source file. Beyond that, the only @id{metas} are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).} +@item{@id{metas} is a hashtable of key–value pairs with extra information that is extracted from the source. These @id{metas} will always contain the key @racket['#,(setup:here-path-key)], which returns a string representation of the full path to the source file. Beyond that, the only @id{metas} are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).} ] As usual, you can use @racket[require], @racket[local-require], or @racket[dynamic-require] to retrieve these values. But within a Pollen project, the faster way is to use @racket[get-doc] and @racket[get-metas]. diff --git a/pollen/scribblings/setup.scrbl b/pollen/scribblings/setup.scrbl index 9e17e4e..e0aa119 100644 --- a/pollen/scribblings/setup.scrbl +++ b/pollen/scribblings/setup.scrbl @@ -159,6 +159,8 @@ If the cache can't find a certain file on the watchlist, no error will arise. Th @history[#:added "2.0"]} +@defoverridable[here-path-key 'symbol]{Key used to store the path of the source file in its metas table. No idea why you'd want to change this.} + @section{Parameters}