I’d like to be able to open the Racket glossary <https://github.com/sschwarzer/racket-glossary> with raco docs racket-glossary .
I installed the package with raco pkg install git+<https://github.com/sschwarzer/racket-glossary> and can list the package with raco pkg show -l
raco docs racket-glossary opens the Racket documentation search, but doesn’t find anything. The help for raco docs --help says the syntax is raco docs [ <option> ... ] [<search-terms>] ...
I guess normally search terms are defined implicitly when describing an API, but the Racket glossary doesn’t have an API. What’s the recommended way to define a search term so that raco docs works?
Or is there a better way to open the documentation?
The background is that I don’t want to publish the glossary as a package as long as it has so few entries, but I want to explain users how they can install and view the current version from Github.
Of course you can open the generated HTML documentation by opening the file in a webbrowser, but it would be easier to use raco docs instead of describing where the file can be found.
Two things:
• The keyword that you should use is either “Glossary of Racket concepts” or “glossary” (where “glossary” is the file name of your Scribble file) • If you want additional keyword, I think you can do that by using section-index.
Yes, I’d like something more specific than “glossary”, and the whole title is cumbersome to type. Thanks to your help, I created the index entry with @section-index{racket-glossary}
Now, raco docs racket-glossary opens the search results page with the “racket-glossary” term.
Is there a way to open the found page directly if there’s only one search hit?
AFAIK, no. Feel free to hack JS to improve it.
Thanks, but no thanks. :smile:
But thanks for section-index, of course. :slightly_smiling_face:
Another possibility is to rename your scribble file, in case that was not clear
No, it actually wasn’t clear. I thought the possibility of using glossary came from the word “Glossary” in the document title.
really?!?
I said, I thought that, I didn’t say it was actually the case.
When you changed the file name, did you update info.rkt as well?
My experiments so far were with the scribblings/glossary.scrbl filename. The info.rkt contains
#lang info
(define collection "racket-glossary")
(define deps '("base"))
(define build-deps '("scribble-lib" "racket-doc" "rackunit-lib"))
(define scribblings '(("scribblings/glossary.scrbl" ())))
(define pkg-desc "Glossary of Racket concepts")
(define version "0.1.0-dev")
(define pkg-authors '(sschwarzer))
(define license '(Apache-2.0 OR MIT))
ohhh!
Let me clear up something that I just realized
When you said “No, it actually wasn’t clear.“, I didn’t read carefully
When I saw the word “No”, I thought you meant “No, it doesn’t work”
I had added (edited) the word “clear” in after you were confused because I thought I wasn’t clear in my answer.
lolol
unclear-ception
My understanding is that glossary.scrbl as filename is specific enough because it’s in the racket-glossary collection (and therefore kind of “namespace”). I don’t want to hijack the “glossary” term for all the Racket documentation. :slightly_smiling_face: If needed, I’d change the file name from glossary.scrbl to racket-glossary.scrbl if you think it’s advisable.
yeah, all Scribble file names share one single namespace
I guess I should change it to racket-glossary.scrbl then!
A lot of people named the file “manual.scrbl” and there are a lot of conflicts
Another possibility, actually, is to adjust info.rkt
Adjust in which way?
The scribblings entry has a couple of options to adjust the name. I don’t recall exactly how to do it. You need to look it up
Then it’s probably more straightforward to change the file name, I guess?
Yeah, sure
Thanks a lot, will do. :+1: