On this page:
4.1.1 Setting Up Library Documentation
4.1.2 Racket Typesetting and Hyperlinks
4.1.3 Section Hyperlinks
4.1.4 Defining Racket Bindings
4.1.5 Showing Racket Examples
4.1.6 Multi-Page Sections

4.1 Getting Started with Documentation

Although the scribble command-line utility generates output from a Scribble document, documentation of Racket libraries is normally built by raco setup. This chapter emphasizes the raco setup approach, which more automatically supports links across documents.

See Getting Started for information on using the scribble command-line utility.

4.1.1 Setting Up Library Documentation

To document a collection or PLaneT package:

4.1.2 Racket Typesetting and Hyperlinks

In the document source at the start of this chapter (Setting Up Library Documentation), the Racket expression (list 'testing 1 2 3) is typeset properly, but the list identifier is not hyperlinked to the usual definition. To cause list to be hyperlinked, add a require form like this:

  @(require (for-label racket))

This require with for-label declaration introduces a document-time binding for each export of the racket module. When the document is built, the racket form detects the binding for list, and so it generates a reference to the specification of list. The setup process detects the reference, and it finds the matching specification in the existing documentation, and ultimately directs the hyperlink to that specification.

Hyperlinks based on for-label and racket are the preferred mechanism for linking to information outside of a single document. Such links require no information about where and how a binding is documented elsewhere:

  #lang scribble/manual

  @(require (for-label racket))

  

  @title{My Library}

  

  See also @racket[list].

The racket form typesets a Racket expression for inline text, so it ignores the source formatting of the expression. The racketblock form, in contrast, typesets inset Racket code, and it preserves the expression’s formatting from the document source.

  #lang scribble/manual

  @(require (for-label racket))

  

  @title{My Library}

  

  Some example Racket code:

  

  @racketblock[

  (define (nobody-understands-me what)

    (list "When I think of all the"

          what

           "I've tried so hard to explain!"))

  (nobody-understands-me "glorble snop")

  ]

4.1.3 Section Hyperlinks

A section declaration in a document can include a #:tag argument that declares a hyperlink-target tag. The secref function generates a hyperlink, using the section name as the text of the hyperlink. Use seclink to create a hyperlink with text other than the section title.

The following example illustrates section hyperlinks:

  #lang scribble/manual

  @(require (for-label racket))

  

  

  @title{My Library}

  

  Welcome to my documentation: @racket[(list 'testing 1 2 3)].

  

  @table-of-contents[]

  

  

  @section[#:tag "chickens"]{Philadelphia Chickens}

  

  Dancing tonight!

  

  

  @section{Reprise}

  

  See @secref{chickens}.

Since the page is so short, the hyperlinks in the above example are more effective if you change the "info.rkt" file to add the 'multi-file flag:

  (define scribblings '(("manual.scrbl" (multi-page))))

A section can have a tag prefix that applies to all tags as seen from outside the section. Such a prefix is automatically given to each top-level document as processed by raco setup. Thus, referencing a section tag in a different document requires using a prefix, which is based on the target document’s main source file. The following example links to a section in the Racket reference manual:

  #lang scribble/manual

  @(require (for-label racket))

  @(define ref-src

     '(lib "scribblings/reference/reference.scrbl"))

  

  @title{My Library}

  

  See also @italic{@secref[#:doc ref-src]{pairs}}.

As mentioned in Racket Typesetting and Hyperlinks, however, cross-document references based on (require (for-label ....)) and racket are usually better than cross-document references using secref.

4.1.4 Defining Racket Bindings

Use defproc to document a procedure, defform to document a syntactic form, defstruct to document a structure type, etc. These forms provide consistent formatting of definitions, and they declare hyperlink targets for racket-based hyperlinks.

To document a my-helper procedure that is exported by "helper.rkt" in the "my-lib" collection that contains "manual.scrbl":

Adding these pieces to ""manual.scrbl"" gives us the following:

  #lang scribble/manual

  @(require (for-label racket

                       "helper.rkt"))

  

  @title{My Library}

  

  @defmodule[my-lib/helper]

  

  @defproc[(my-helper [lst list?])

           (listof

            (not/c (one-of/c 'cow)))]{

  

   Replaces each @racket['cow] in @racket[lst] with

   @racket['aardvark].}

In defproc, a contract is specified with each argument to the procedure. In this example, the contract for the lst argument is list?, which is the contract for a list. After the closing parenthesis that ends the argument sequence, the contract of the result must be given; in this case, my-helper guarantees a result that is a list where none of the elements are 'cow.

Some things to notice in this example and the documentation that it generates:

See defproc*, defform, etc. for more information on forms to document Racket bindings.

4.1.5 Showing Racket Examples

The examples form from scribble/eval helps you generate examples in your documentation. Warning: the examples form is especially likely to change or be replaced.

To use examples, the procedures to document must be suitable for use at documentation time; in fact, examples uses bindings introduced into the document source by require. Thus, to generate examples using my-helper from the previous section, "helper.rkt" must be imported both via require-for-label and require:

  #lang scribble/manual

  @(require scribble/eval    ; <--- added

            "helper.rkt"     ; <--- added

            (for-label racket

                       "helper.rkt"))

  

  @title{My Library}

  

  @defmodule[my-lib/helper]{The @racketmodname[my-lib/helper]

  module---now with extra cows!}

  

  @defproc[(my-helper [lst list?])

           (listof (not/c (one-of/c 'cow)))]{

  

   Replaces each @racket['cow] in @racket[lst] with

   @racket['aardvark].

  

   @examples[

     (my-helper '())

     (my-helper '(cows such remarkable cows))

   ]}

4.1.6 Multi-Page Sections

Setting the 'multi-page option (see Section Hyperlinks) causes each top-level section of a document to be rendered as a separate HTML page.

To push sub-sections onto separate pages, use the 'toc style for the enclosing section (as started by title, section, subsection, etc.) and use local-table-of-contents to generate hyperlinks to the sub-sections.

Revising "cows.scrbl" from the previous section:

  #lang scribble/manual

  

  @title[#:style '(toc)]{Cows}

  

  @local-table-of-contents[]

  

  @section[#:tag "singing"]{Singing}

  Wherever they go, it's a quite a show.

  

  @section{Dancing}

  See @secref["singing"].

To run this example, remember to change "info.rkt" to add the 'multi-page style. You may also want to add a call to table-of-contents in "manual.scrbl".

The difference between table-of-contents and local-table-of-contents is that the latter is ignored for Latex output.

When using local-table-of-contents, it often makes sense to include introductory text before the call of local-table-of-contents. When the introductory text is less important and when when local table of contents is short, putting the introductory text after the call of local-table-of-contents may be appropriate.