Newbie Trouble using Scribble Links

Hi, Racket Discourse.

I am busy preparing some documentation for a presentation that I have to do this afternoon, but I am banging my head against a wall trying to use Scribble section references and the like.

All I want to do is, include a reference/link to a .scrbl file which is in the same directory as the file from which the file is being referenced. So, for argument's sake I have two files main.scrbl and sub.scrbl where the sub file contains:

#lang scribble/base

@title[#:tag "example"]{Example Title}

This is some text.

and the main file contains:

#lang scribble/base

@seclink["example" #:doc '(lib "sub.scrbl")]

When I include a reference to a file such as shown in this cheatsheet, it works, but when I try and reference my file in the same manner, I get an output similar to

(part ("(lib mzlib/sub.scrbl)" "example"))

I assume that this implies something about the path not being specified correctly but I don't know.

I have messed around a bit but, honestly, I don't have enough time to troubleshoot this at length and I can't imagine that it would really be that hard--I am obviously missing something trivial. I haven't used the Scribble lang much up until now, but I would really like to get my team to use the tooling for our internal documentation.

If anyone would be so kind as to assist, I would be very grateful.

1 Like

Here is an example of how seclink is used in the manual of rosette.

First there is a main file that includes the other sections:

The chapters are given tags that begin with ch: (like you "example" tag).
You can see a seclink in action in:

Thanks for the quick reply @soegaard, I appreciate it.

When I do this, the rendered (I hope I'm using this term correctly) link is simply a red underlined string, like so:


I am using DrRacket's Scribble HTML button if that makes any difference.

Looking at the HTML, it seems like the generated link is somehow borked, with output:

<p>Is this correct <font class="badlink">link</font></p>.

Here is a full example:

I don't know whether it makes a difference that you are using the Scribble button in DrRacket.

Perhaps not important, but at least I could see the following by using the command line instead. When I run the command you provided, I get the following response:

[Output to main/index.html]
Warning: some cross references may be broken due to undefined tags:
(part "ch:seclink-example")

Where the output is the same.

What I do notice, however, is that if I include the section as you have done, using


the link works but it does not reference the other file, since it refers to the included section, I assume, which then also appears in the body of the rendered output below the link, instead of just the link to that file. Without the above, the link is "broken".

I might be confused about your goal then.

Are main.scrbl and sub.scrbl part of the same document?
[In my example they are.]

When main.scrbl is rendered should the link be to the raw file sub.scrbl or
to the rendered version of sub.scrbl?
[In my example, the link goes to a section in the rendered version of sub.scrbl].

Oh dear, I see from the output that I should be looking at the main/index.html file; I was mistakenly looking at the previously generated (using DrRacket) main.html.

Doing exactly as you have done, I apologize, I see that the rendered output is what I expect. This basically solves my issue, thank you.

Is the unexpected output from DrRacket the intended behaviour? See, e.g., the comparative outputs:

Your solution.

Using the same sources but DrRacket's Scribble HTML button.

In any event, thanks for the above.

Scribble files can be rendered as a single html file or as multiple html files.
The default is single, the option --htmls produces multiple html files.
I can't remember how the Scribble buttons in DrRacket work.

Cool, I will have a look at that; perhaps it might be possible to change the behaviour. I will go ahead and mark your reply above as the solution. And if I manage to modify the button, I will just add that here for posterity.

All the best, thanks, @soegaard.

1 Like