Creating links to Racket docs for functions in user-scope packages
72 views
Skip to first unread message
Joel Dueck
Jul 12, 2020, 6:16:37 PM7/12/20
to Racket Users
Trying to generate URLs for linking into the Racket docs. I get the error below, but only when the package/identifier combo in question are installed in user scope, and only when using the `#:external-root-url` keyword argument:
> (define x (xref-binding->definition-tag (load-collections-xref) '(deta/query lookup) 0))
> x
'(def ((lib "deta/query.rkt") lookup))
;; works good:
> (xref-tag->path+anchor (load-collections-xref) x)
#<path:/Users/joel/Library/Racket/7.7/pkgs/deta-doc/doc/deta/index.html>
"(def._((lib._deta/query..rkt)._lookup))"
> (xref-tag->path+anchor (load-collections-xref) x #:external-root-url "http://docs.racket-lang.org/")
. . ../../../../../../Applications/Racket v7.7/collects/racket/private/kw.rkt:1393:47: path-element->string: contract violation
expected: path?
given: 'up
Is this a bug? Or is there a way to make this work for user-scope packages as well?
Matthew Flatt
Jul 13, 2020, 9:37:52 AM7/13/20
to Joel Dueck, Racket Users
It's currently not intended to work for packages installed in user
scope --- only for packages in the main installation --- although
probably it shouldn't report a path error for a user-scope package.
I'm not sure how difficult it would be to make redirection work on a
user-scope package's documentation. The function doesn't "just work"
for user-scope, because the location where documentation is rendered is
different for user-scope packages and installation-scope packages. It
might end up being about the same implementation effort to improve the
error message or to make the function work on user-scope packages,
though.
scope --- only for packages in the main installation --- although
probably it shouldn't report a path error for a user-scope package.
I'm not sure how difficult it would be to make redirection work on a
user-scope package's documentation. The function doesn't "just work"
for user-scope, because the location where documentation is rendered is
different for user-scope packages and installation-scope packages. It
might end up being about the same implementation effort to improve the
error message or to make the function work on user-scope packages,
though.
Joel Dueck
Jul 13, 2020, 12:02:17 PM7/13/20
to Racket Users
On Monday, July 13, 2020 at 8:37:52 AM UTC-5, Matthew Flatt wrote:
It might end up being about the same implementation effort to improve the
error message or to make the function work on user-scope packages
That was my sense as well...I will try taking a look at this, maybe I can contribute.
Joel Dueck
Jul 21, 2020, 12:25:03 PM7/21/20
to Racket Users
It looks like the problem might be in this function where it always constructs a path that is relative to (find-doc-dir).
Would it make sense instead to have it check the dest against all the paths returned by (get-doc-search-dirs) and just use the first one that matches? If so maybe I’ll try doing a pull request to that effect.
Sorry I’m tiptoeing here, I haven’t contributed to Scribble before.
Matthew Flatt
Jul 24, 2020, 12:15:54 PM7/24/20
to Joel Dueck, Racket Users
Hi Joel,
At Tue, 21 Jul 2020 09:25:03 -0700 (PDT), "'Joel Dueck' via Racket Users" wrote:
> It looks like the problem might be in this function
> <https://github.com/racket/scribble/blob/master/scribble-lib/scribble/html-rend
> er.rkt#L440-L459>
installed in user scope render documentation within the collections'
directories, and those directories are not included in the result of
`(get-doc-search-dirs)`.
A solution might use something like `path->pkg+subpath+collect+scope`,
where a 'user result for the scope triggers a different path
calculation. For user-scope packages, ocumentation is rendered within
the collection in a "doc" subdirectory, instead of in a common "doc"
directory. Probably the content of the individual "doc" directories
mirrors the main "doc" directory, in which case the relative-path
calculation would be the same, but I may have forgotten a difference.
Matthew
At Tue, 21 Jul 2020 09:25:03 -0700 (PDT), "'Joel Dueck' via Racket Users" wrote:
> It looks like the problem might be in this function
> er.rkt#L440-L459>
> where it always constructs a path that is relative to (find-doc-dir).
>
> Would it make sense instead to have it check the dest against all the paths
> returned by (get-doc-search-dirs) and just use the first one that matches?
> If so maybe I’ll try doing a pull request to that effect.
I don't think that specific approach is going to work. Packages
>
> Would it make sense instead to have it check the dest against all the paths
> returned by (get-doc-search-dirs) and just use the first one that matches?
> If so maybe I’ll try doing a pull request to that effect.
installed in user scope render documentation within the collections'
directories, and those directories are not included in the result of
`(get-doc-search-dirs)`.
A solution might use something like `path->pkg+subpath+collect+scope`,
where a 'user result for the scope triggers a different path
calculation. For user-scope packages, ocumentation is rendered within
the collection in a "doc" subdirectory, instead of in a common "doc"
directory. Probably the content of the individual "doc" directories
mirrors the main "doc" directory, in which case the relative-path
calculation would be the same, but I may have forgotten a difference.
Matthew
Joel Dueck
Jul 29, 2020, 10:27:15 AM7/29/20
to Racket Users
On Friday, July 24, 2020 at 11:15:54 AM UTC-5 Matthew Flatt wrote:
A solution might use something like `path->pkg+subpath+collect+scope`,
where a 'user result for the scope triggers a different path
calculation.
For my application, I was able to use this info to make a function that *seems* reliable for user-scope packages (at least, the ones I have tested with so far):
I will attempt something more robust (along the lines of your suggestion) for the pull request though.
Reply all
Reply to author
Forward
0 new messages