Hyperlinks inside a scribble single file

Questions & Answers
1

I have a problem with my scribble docs for math-quiz. It is a very simple (single) file (my first attempt at this), and contains just a few sections and subsections. Nothing fancy.
This all works, except after I introduced several hyperlinks from inside one section to another section inside the same file. For some reason I can't figure out, these links are hard-coded to my local math-quiz path, and when installed as a Racket package on another computer, these links don't work.
For example:

@section[#:tag "gapesa"]{GAPESA Exercises}
... section text...

From another section ...
@(secref "gapesa")...

This works only on my working copy of math-quiz package, but when installed on another computer, or as another user, it still uses the same path as on my local package.

Any way to fix this?

2

How are they installing the package?

Is the documentation actually being rebuilt as part of that process?

3

@joeld
See GitHub - hrvoje064/math-quiz-jasna: math-quiz for grade 1,2,3, ... elementary school. Written in Racket

@hrvoje064
I can't spot anything unusual in the info file.
Are you using DrRacket to make the executable?

4

I notice that rendered HTML files are included in the scribblings directory of the repo, and these files include the problematic machine-specific file:// paths. (It would be better to exclude all .css .js and .html files in that folder from version control.)

So the hunch which prompted my initial question is probably correct: whatever process is being used to copy these files and “install” them on the other computers is not rebuilding the docs locally the way a normal raco pkg install would.

5

No, I was doing that (using DrRacket to make the executable) before I installed math-quiz as a package on Racket package server. Now, I'm just updating my local source files, and pushing them to GitHub. And as far as I can see (when I update the math-quiz program on my daughter's windows computer), the package being updated from Racket server is being rebuilt locally. That is everything but these 3 hyperlinks I mentioned in original post.
I have one menu entry in math-quiz program to update the program (using the DrRacket Package Management window), so I can follow what goes on during updating.
What I find very confusing is that apart from these 3 links in scribble file (that are not updated), all the others are updated correctly. I mean, every section, and subsection declaration is a link, and I can check them just hovering the mouse over the section name on the gray area on the left, and it shows correct runtime path, all except these 3 secref links.

6

A couple of things:

  1. Usually, a Racket package should not distribute HTML files with the repository. You should remove every file under https://github.com/hrvoje064/math-quiz-jasna/tree/main/scribblings except math-quiz.scrbl.
  2. When you install a package, Racket will automatically render Scribble source to HTML for you. Where it stores these HTML files could vary depending on how Racket is installed. For example, mine is stored at /Users/sorawee/projects/racket/racket/doc/math-quiz/index.html (although the locally cloned package is at /Users/sorawee/projects/math-quiz-jasna/). To view the documentation, use the command raco docs. The links in the rendered HTML are all correct. https://docs.racket-lang.org/math-quiz/index.html is also rendered just fine.
  3. (define scribblings '(("scribblings/math-quiz.scrbl") ())) in info.rkt is malformed. You should change it to (define scribblings '(("scribblings/math-quiz.scrbl" ()))).
7

It would be good to find the code that reads the scribblings key (I’d guess in the racket-index package) and have it report an error during raco setup.

2 Likes
8

So what you are saying is that I should actually commit only the math-quiz.scrbl file to GitHub? I suppose that also means that before doing that, I have to delete all the other files in scribblings folder on GitHub repo.
Okay, I'll try that, but still there's this question; why do only these 3 secref links fail, when all the other links (section, subsection) work correctly?

9

Thanks. (for all 3 :rofl:).
I guess I left all those files there, because I did not know how the package installation really works.
Another reason was that if these files are not there (at least HTML) than downloading the source zip file from GitHub directly, without installing it as a racket package, will not work. That is, running the main.rkt file directly from DrRacket will work, but the HTML docs will not work.
Although, that's probably not a valid reason, because I still keep the text docs in the program, and these work no matter how the program is installed.

10

I think we talked past each other. Let me try again.

So what you are saying is that I should actually commit only the math-quiz.scrbl file to GitHub? I suppose that also means that before doing that, I have to delete all the other files in scribblings folder on GitHub repo.

Yes and yes.

(Slightly off-topic: you might find the command raco pkg new helpful for your new projects in the future, since it will generate a .gitignore file that prevents you from checking in some of the compiled files)

Okay, I’ll try that, but still there’s this question; why do only these 3 secref links fail, when all the other links (section, subsection) work correctly?

I assume that you generate the HTML by using the “Scribble HTML” button in DrRacket. Is that correct?

The thing is, currently the generated HTML file with this method will use the absolute filesystem path on your system when resolving some links. That is why these 3 secref links failed. These HTMLs only work on your computer, and are not always appropriate for distribution to other systems.

Instead, you can simply distribute the Scribble source file. When people install your package (by using the package manager or the raco pkg install command), the Scribble file will be locally compiled to HTML on the user’s system automatically. When the user clicks "View documentation" or runs raco docs, they will get correct HTML with correct links on their system.

And again, you will find that https://docs.racket-lang.org/math-quiz/index.html is already correct. The 3 secref links work when the Scribble file is rendered as a part of package setup.

I do think, though, that it would be nice to improve Scribble. What you want is totally reasonable, and Scribble should be able to support that. In particular, @shhyou might have more thoughts on generating relative links. It is actually already possible for Scribble to generate relative paths, but the condition for that is pretty limited. IIUC, he experimented with relaxing the condition in https://github.com/racket/scribble/pull/315.

11

@LiberalArtist
and have it report an error during raco setup.

Actually, raco setup does report this error, I just wasn't looking at it. Too many lines to follow carefully.

12

@sorawee

(Slightly off-topic: you might find the command raco pkg new helpful for your new projects in the future, since it will generate a .gitignore file that prevents you from checking in some of the compiled files)

Thanks. I did try raco pkg new, but decided not to use it for math-quiz, as math-quiz is a long running program, so I was afraid it would mess up my existing files.
Anyway I did notice that .gitignore file. Unfortunately, at that time I didn't even know what that is!

13

@sorawee

I do think, though, that it would be nice to improve Scribble. What you want is totally reasonable, and Scribble should be able to support that. In particular, @shhyou might have more thoughts on generating relative links. It is actually already possible for Scribble to generate relative paths, but the condition for that is pretty limited. IIUC, he experimented with relaxing the condition in...

Yes, and I now really have a valid reason for this. You might remember, that when I started this program I was originally posting it as a binary only package on Jasna's Math Quiz by hrvoje064 . Now, after following your advice, and that source package on pkgs.racket-lang.org works, I tried to fix the binary only distribution as well.
Unfortunately this does not work. If I follow the same recipe (keeping only math-quiz.scrbl in scribbling directory), I get nothing. So, to get something at least, I must populate (before compiling for distribution) scribblings directory with all the other files, including the math-quiz.html. Then everything works, but for these 3 local secref links, which are hardwired to my home directory.
Actually, I did find the way to fix it (although I knew even before I started that this is useless). I used (system (format "scribble ~a" path-to-math-quiz.scrbl)) that is to run first time user starts the program. This actually works (although all the files, including math-quiz.html end up in bin folder and not where scrbl file is). But of course this works only if user has Racket installed, and that defeats the purpose of binary distribution.

14

A temporary fix would be to generate the html-files as you did originally,
and the post-process the results with a small search/replace script
to fix the offending urls.

Far from an elegant solution, but one that works until a better solution shows up.

15

@soegaard OK, I'll try that. Thanks.

16

I was under the impression that you want people to use your package via the package server. I see now that you want them to download the file from your website directly.

FWIW, if you run the Scribble command with the --dest argument, relative links will be mostly used in the generated HTML under the specified directory. But you also want to provide --redirect-main http://docs.racket-lang.org/ so that cross-ref links to stuff like require are not local to your computer.

Something like:

scribble +m --dest html --redirect-main http://docs.racket-lang.org/ scribblings/math-quiz.scrbl

(Also thanks to Alexis whose new package made me realize the importance of --dest.)

17

Yes, you were under the right impression, the preferred use now is via the package server. This is not only simpler but allows for menu click package update, which binary distribution does not allow.
However, since I started this with binary distribution only, and that site is still alive, I wanted to fix that one as well. And thanks to @soegaard advice, it now is. Really, it was much simpler than I imagined it would be. I just have to make sure that my home path does not change :rofl: