How to set up definitions (as in LaTeX) in scribble?

Questions & Answers
1

I am trying to use scribble to write a technical document, with "defined terms". I would like in one place to be able to make a definition and give it a tag, and then refer to that tag elsewhere (perhaps in the same doc, perhaps from another doc).

So something like this:

@definition[#:tag "partition"]{A @dt{disk partition} is a separated part of physical memory, defined in the partition table.}
... elsewhere
See @defref["partition"] for more details.

I am completely new to scribble and racket, but I have read parts of the documentation. I can see that section and secref resemble what I want, and that I'll probably need a new "tag type" (like 'part is used for sections). But I'm struggling to understand how to actually extend scribble in this way. I get that I probably need to define a new function, but how do I "hook in" to the tagging system?

1 Like
2

Would elemtag and elemref do what you want?

3

Is the tech form sufficient? Along with deftech? See 4.2.7 Links

4

Thank you both. tech seems like exactly what I need! I'm a bit confused by the syntax. I can get it working just fine within a single document. I tried calling it from another file with

@tech[doc: '(lib "the-other-file.scrbl")]{field}

and it just renders with a "badlink" but no error. I get the same if I just put #:doc "the-other-file.scrbl". I could only find this cheat sheet to see how it works: Scribble Cheatsheet

I also noticed that I didn't get any warning when the ref was missing (if I made a typo). I do get a warning when I use secref with a section that

5

See

[

7 Running scribble
docs.racket-lang.org

](https://docs.racket-lang.org/scribble/running.html#%28part._xref-flags%29)

It may help.

6

You should only need #:doc if the definition of the term is in a different Scribble document, not if it is merely in a different file that ends up in the same document, e.g. via include-section.

7

| LiberalArtist
March 26 |

  • | - |

danielittlewood:

Thank you both. tech seems like exactly what I need! I'm a bit confused by the syntax. I can get it working just fine within a single document. I tried calling it from another file with

@tech[doc: '(lib "the-other-file.scrbl")]{field}

and it just renders with a "badlink" but no error. I get the same if I just put #:doc "the-other-file.scrbl".

You should only need #:doc if the definition of the term is in a different Scribble document, not if it is merely in a different file that ends up in the same document, e.g. via include-section.

Indeed, the distinction between document and file-on-disk is not unique to Scribble, but it did confuse me at first. When do I need special work for cross-references? When not? Depends on the document :slight_smile: