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.
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
@include-section{sub.scrbl}
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".
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:
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.
