►Scribble: Racket Documentation Tool
▼4 Scribbling Documentation
►4.1 Getting Started with Documentation
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.7 Style Guide
4.1.7.1 Prose and Terminology
4.1.7.2 Typesetting Code
4.1.7.3 Typesetting Prose
4.1.7.4 Section Titles
  top← prev  up  next → 

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.

4.1.7 Style Guide
4.1.7.1 Prose and Terminology

In the descriptive body of defform, defproc, etc., do not start with “This ...” Instead, start with a sentence whose implicit subject is the form or value being described. Capitalize the first word. Thus, the description will often start with “Returns” or “Produces.” Refer to arguments and sub-forms by name.

Do not use the word “argument” to describe a sub-form in a syntactic form; use the term “sub-form” instead, reserving “argument” for values or expressions in a function call. Refer to libraries and languages as such, rather than as “modules” (even though the form to typeset a library or language name is called schememodname). Do not call an identifier (i.e., a syntactic element) a “variable” or a “symbol.” Do not use the word “expression” for a form that is a definition or might be a definition; use the word “form,” instead. Prefer “function” to “procedure.”

Avoid cut-and-paste for descriptive text. If two functions are similar, consider documenting them together with deftogether. To abstract a description, consider using explicit prose abstraction, such as “x is like y, except that ...,” instead of abstracting the source and instantiating it multiple times; often, a prose abstraction is clearer to the reader than a hidden abstraction in the document implementation.

4.1.7.2 Typesetting Code

Use id or a name that ends -id in defform to mean an identifier, not identifier, variable, name, or symbol. Similarly, use expr or something that ends -expr for an expression position within a syntactic form. Use body for a form (definition or expression) in an internal-definition position. Do not use expr for something that isn’t exactly an expression, id for something that isn’t exactly an identifier, etc.; instead, use defform/subs to define a new non-terminal.

Beware of using deftogether to define multiple variants of a syntactic form or procedure, because each defform or defproc creates a definition point, but each form or procedure should have a single definition point. (Scribble issues a warning when a binding has multiple definition points.) Instead, use defproc* or defform*.

Pay attention to the difference between identifiers and meta-variables when using scheme, especially outside of defproc or defform. Prefix a meta-variable with _; for example,

  @scheme[(rator-expr rand-expr ...)]

would be the wrong way to refer to the grammar of a function call, because it produces (rator-expr rand-expr ...), where rator-expr and rand-expr are typeset as variables. The correct description is

  @scheme[(_rator-expr _rand-expr ...)]

which produces (rator-expr rand-expr ...), where rator-expr and rand-expr are typeset as meta-variables. The defproc, defform, etc. forms greatly reduce this burden in descriptions, since they automatically set up meta-variable typesetting for non-literal identifiers. In defform, be sure to include literal identifiers (i.e., those not meant as variables, other than the form name being defined) in a #:literals clause.

To typeset an identifier with no particular interpretation – syntax, variable, meta-variable, etc. – use schemeidfont (e.g., as in rand-expr above). Otherwise, use litchar, not merely schemefont or verbatim, to refer to a specific sequence of characters.

When showing example evaluations, use the REPL-snapshot style:

  @interaction[

  (+ 1 2)

  ]

See also the scribble/eval library.

Use four dots, ...., in place of omitted code, since ... means repetition.

4.1.7.3 Typesetting Prose

Refrain from referring to documentation “above” or “below,” and instead have a hyperlink point to the right place.

In prose, use `` and '' quotation marks instead of ". Use --- for an em-dash, and do not include spaces on either side, though it will typeset as an en-dash and spaces in HTML output. Use American style for quotation marks and punctuation at the end of quotation marks (i.e., a sentence-terminating period goes inside the quotation marks). Of course, this rule does not apply for quotation marks that are part of code.

Do not use a citation reference (as created by cite) as a noun; use it as an annotation.

Do not start a sentence with a Scheme variable name, since it is normally lowercase. For example, use “The thing argument is...” instead of “thing is...”

4.1.7.4 Section Titles

Capitalize all words except articles (“the,” “a,” etc.), prepositions, and conjunctions that are not at the start of the title.

A manual title should normally start with a suitable keyword or key phrase (such as “Scribble” for this manual) that is in boldface. If the key word is primarily an executable name, use exec instead of bold. Optionally add further descriptive text in the title after a colon, where the text starting with the colon is not in boldface.

  top← prev  up  next →