Pollen users cannot easily retrieve the doc from their files without reiterating a bunch of code already used inside of Pollen. So, I documented the existing function ->source-path and provided, contracted and documented get-doc and get-metas.
Pollen users cannot easily retrieve the `doc` from their files without reiterating a bunch of code already used inside of Pollen. So, I documented the existing function `->source-path` and provided, contracted and documented `get-doc` and `get-metas`.
Re “Pollen users cannot easily retrieve the doc from their files,” what is the specific difficulty you’ve run into?
As I see it, doc and metas are exports from a source file, so they can (and IMO should) be retrieved with something from the require family, such as Racket’s dynamic-require or Pollen’s cached-require. In fact, get-doc and get-metas rely on cached-require, which is why I’ve heretofore thought of them as just glue between select and cached-require.
I’m not opposed to making things easier. But I just want to make the improvement to the interface at the highest-leverage location.
Re “Pollen users cannot easily retrieve the `doc` from their files,” what is the specific difficulty you’ve run into?
As I see it, `doc` and `metas` are exports from a source file, so they can (and IMO should) be retrieved with something from the `require` family, such as Racket’s `dynamic-require` or Pollen’s [`cached-require`](http://pkg-build.racket-lang.org/doc/pollen/Cache.html?q=cached-require#%28def._cache._%28%28lib._pollen%2Fcache..rkt%29._cached-require%29%29). In fact, `get-doc` and `get-metas` rely on `cached-require`, which is why I’ve heretofore thought of them as just glue between `select` and `cached-require`.
I’m not opposed to making things easier. But I just want to make the improvement to the interface at the highest-leverage location.
I will try to clarify my the problem I encountered.
It started when I was writing my implementation for an RSS feed. I was using select to pull out a summary from a file. Soon, I discovered, this was not built for my exact use case. So, I wanted to write my own function to search a document called.
Using racket to search an X-expression was easy, and now there is even support for it in txexpr. From there all I need was to pull in a file's doc. That was surprisingly hard to do. Yes, cached-require worked, but it felt like something was missing.
With select and friends, I had a nice interface to pull grab part of a doc or a meta while referencing a document with a txexpr, pagenode or input/output relative/complete path. But, to add that to my own function, use something like findf-txexpr on a file, or just get the whole doc because I want it I had to rewrite a solution to a problem already solved within Pollen.
You do make a good point. Maybe the better, higher level solution is more similar to ->source-file. Something to provide an easy interface to reference a Pollen file.
However, it feels odd to me that the answer of how to get a 'p from a file's doc is the intuitive (select 'p file). But, if they then asked about getting the doc from that same file it requires a discussion about input vs ouput filepaths vs pagenodes, world:current-*-export, and sending the user over to a separate docs for cached-require.
I do think you are right that they should be accessed like other Racket exports with a require, but I feel like these functions provide a very useful and intuitive abstraction. I think that is one of Pollen greatest strengths. It provides intuitive interfaces and abstractions for dealing with and writing documents, but then allows the user to decide their own functionality.
Really all I was after was getting the entirety of a documents first paragraph. The solutions I found were to reiterate functions already within Pollen, ask for my very specific function to be merged, or expose Pollen's internal abstraction. I think the last is the highest-leverage solution.
I will try to clarify my the problem I encountered.
It started when I was writing my implementation for an RSS feed. I was using `select` to pull out a summary from a file. Soon, I discovered, this was not built for my exact use case. So, I wanted to write my own function to search a document called.
Using racket to search an X-expression was easy, and now there is even support for it in `txexpr`. From there all I need was to pull in a file's `doc`. That was surprisingly hard to do. Yes, `cached-require` worked, but it felt like something was missing.
With `select` and friends, I had a nice interface to pull grab part of a `doc` or a `meta` while referencing a document with a txexpr, pagenode or input/output relative/complete path. But, to add that to my own function, use something like `findf-txexpr` on a file, or just get the whole `doc` because I want it I had to rewrite a solution to a problem already solved within Pollen.
You do make a good point. Maybe the better, higher level solution is more similar to `->source-file`. Something to provide an easy interface to reference a Pollen file.
However, it feels odd to me that the answer of how to get a `'p` from a file's doc is the intuitive `(select 'p file)`. But, if they then asked about getting the `doc` from that same file it requires a discussion about input vs ouput filepaths vs pagenodes, `world:current-*-export`, and sending the user over to a separate docs for `cached-require`.
I do think you are right that they _should_ be accessed like other Racket exports with a `require`, but I feel like these functions provide a very useful and intuitive abstraction. I think that is one of Pollen greatest strengths. It provides intuitive interfaces and abstractions for dealing with and writing documents, but then allows the user to decide their own functionality.
Really all I was after was getting the entirety of a documents first paragraph. The solutions I found were to reiterate functions already within Pollen, ask for my very specific function to be merged, or expose Pollen's internal abstraction. I think the last is the highest-leverage solution.
We could also abstract a little further and wrap a require more explicitly. I couldn't think of a good name and don't know if it should go inside of template, but I would be happy to rebase the commit with something like this:
(define+provide/contract(source-requirepagenode-or-pathkey#:require-proc[require-proccached-require])(->*((or/cpagenode?pathish?)coerce/symbol?)(#:require-procprocedure?)any/c)(definesource-path(->source-path(cond[(pagenode?pagenode-or-path)(build-path(world:current-project-root)(symbol->stringpagenode-or-path))][elsepagenode-or-path])))(ifsource-path(require-procsource-pathkey)(error(format"source-require: no source found for '~a' in directory ~a"pagenode-or-path(current-directory)))))
We could also abstract a little further and wrap a require more explicitly. I couldn't think of a good name and don't know if it should go inside of template, but I would be happy to rebase the commit with something like this:
``` racket
(define+provide/contract (source-require pagenode-or-path key #:require-proc [require-proc cached-require])
(->* ((or/c pagenode? pathish?) coerce/symbol?) (#:require-proc procedure?) any/c)
(define source-path (->source-path (cond
[(pagenode? pagenode-or-path) (build-path (world:current-project-root) (symbol->string pagenode-or-path))]
[else pagenode-or-path])))
(if source-path
(require-proc source-path key)
(error (format "source-require: no source found for '~a' in directory ~a" pagenode-or-path (current-directory)))))
```
However, it feels odd to me that the answer of how to get a 'p from a file's doc is the intuitive (select 'p file). But, if they then asked about getting the doc from that same file it requires a discussion about input vs ouput filepaths vs pagenodes, world:current-*-export, and sending the user over to a separate docs for cached-require.
OK, I am persuaded by this argument. There should not be a discontinuity in the interface between one task and a closely related task.
I made some adjustments to your PR, but get-doc, get-metas, and get-source have now been added. Thanks.
> However, it feels odd to me that the answer of how to get a 'p from a file's doc is the intuitive (select 'p file). But, if they then asked about getting the doc from that same file it requires a discussion about input vs ouput filepaths vs pagenodes, world:current-*-export, and sending the user over to a separate docs for cached-require.
OK, I am persuaded by this argument. There should not be a discontinuity in the interface between one task and a closely related task.
I made some adjustments to your PR, but `get-doc`, `get-metas`, and `get-source` have now been added. Thanks.
Please reopen this pull request to perform a merge.
Pollen users cannot easily retrieve the
docfrom their files without reiterating a bunch of code already used inside of Pollen. So, I documented the existing function->source-pathand provided, contracted and documentedget-docandget-metas.Re “Pollen users cannot easily retrieve the
docfrom their files,” what is the specific difficulty you’ve run into?As I see it,
docandmetasare exports from a source file, so they can (and IMO should) be retrieved with something from therequirefamily, such as Racket’sdynamic-requireor Pollen’scached-require. In fact,get-docandget-metasrely oncached-require, which is why I’ve heretofore thought of them as just glue betweenselectandcached-require.I’m not opposed to making things easier. But I just want to make the improvement to the interface at the highest-leverage location.
I will try to clarify my the problem I encountered.
It started when I was writing my implementation for an RSS feed. I was using
selectto pull out a summary from a file. Soon, I discovered, this was not built for my exact use case. So, I wanted to write my own function to search a document called.Using racket to search an X-expression was easy, and now there is even support for it in
txexpr. From there all I need was to pull in a file'sdoc. That was surprisingly hard to do. Yes,cached-requireworked, but it felt like something was missing.With
selectand friends, I had a nice interface to pull grab part of adocor ametawhile referencing a document with a txexpr, pagenode or input/output relative/complete path. But, to add that to my own function, use something likefindf-txexpron a file, or just get the wholedocbecause I want it I had to rewrite a solution to a problem already solved within Pollen.You do make a good point. Maybe the better, higher level solution is more similar to
->source-file. Something to provide an easy interface to reference a Pollen file.However, it feels odd to me that the answer of how to get a
'pfrom a file's doc is the intuitive(select 'p file). But, if they then asked about getting thedocfrom that same file it requires a discussion about input vs ouput filepaths vs pagenodes,world:current-*-export, and sending the user over to a separate docs forcached-require.I do think you are right that they should be accessed like other Racket exports with a
require, but I feel like these functions provide a very useful and intuitive abstraction. I think that is one of Pollen greatest strengths. It provides intuitive interfaces and abstractions for dealing with and writing documents, but then allows the user to decide their own functionality.Really all I was after was getting the entirety of a documents first paragraph. The solutions I found were to reiterate functions already within Pollen, ask for my very specific function to be merged, or expose Pollen's internal abstraction. I think the last is the highest-leverage solution.
We could also abstract a little further and wrap a require more explicitly. I couldn't think of a good name and don't know if it should go inside of template, but I would be happy to rebase the commit with something like this:
OK, I am persuaded by this argument. There should not be a discontinuity in the interface between one task and a closely related task.
I made some adjustments to your PR, but
get-doc,get-metas, andget-sourcehave now been added. Thanks.Step 1:
From your project repository, check out a new branch and test the changes.Step 2:
Merge the changes and update on Gitea.