7 Running scribble

The scribble command-line tool (also available as raco scribble) runs a Scribble document and renders it to a specific format. Select a format with one of the following flags, where the output name fn is by default the document source name without its file suffix:

• --html — a single HTML page "fn.html", plus CSS sources and needed image files; this mode is the default if no format is specified

• --htmls — multiple HTML pages (and associated files) in a "fn" directory, starting with "fn/index.html"

• --html-tree ‹n› — HTML pages in a directory tree up to ‹n› layers deep; a tree of depth 0 is equivalent to using --html, and a tree of depth 1 is equivalent to using --htmls

• --latex — LaTeX source "fn.tex", plus any needed additional files (such as non-standard class files) needed to run latex or pdflatex

• --pdf — PDF "fn.pdf" that is generated via pdflatex

• --xelatex — PDF "fn.pdf" that is generated via xelatex

• --dvipdf — PDF "fn.pdf" that is generated via latex, dvips, and pstopdf

• --latex-section ‹n› — LaTeX source "fn.tex" plus additional ".tex" files to be included in the enclosing document’s preamble, where the enclosing document must use the UTF-8 input encoding and T1 font encoding; use 1 for ‹n› to make the rendered document a section, 2 for a subsection, etc.

• --text — plain text in a single file "fn.txt", with non-ASCII content encoded as UTF-8

• --markdown — Markdown text in a single file "fn.md", with non-ASCII content encoded as UTF-8

Use --dest-name to specify a fn other than the default name, but only when a single source file is provided. Use the --dest flag to specify a destination directory (for any number of source files). Use --dest-base to add a prefix to the name of each support file that is generated or copied to the destination.

After all flags, provide one or more document sources, where each source declares a module. The module should either have a doc submodule that exports doc as a part, or it should directly export doc as a part. (The submodule is tried first, and the main module is not directly loaded or evaluated if the submodule can be loaded on its own.) Use --doc-binding to access an alternate exported name in place of doc.

When multiple documents are rendered at the same time, cross-reference information in one document is visible to the other documents. See Handling Cross-References for information on references that cross documents that are built separately.

Changed in version 1.4: Added --dvipdf.
Changed in version 1.18: Added --doc-binding.
Changed in version 1.19: Added --xelatex.

7.1 Extra and Format-Specific Files

Use the --style flag to specify a format-specific file to adjust the output style file for certain formats. For HTML (single-page or multi-page) output, the style file should be a CSS file that is applied after all other CSS files, and that may therefore override some style properties. For Latex (or PDF) output, the style file should be a ".tex" file that can redefine Latex commands. When a particular Scribble function needs particular CSS or Latex support, however, a better option is to use a css-addition or tex-addition style property so that the support is included automatically; see Extending and Configuring Scribble Output for more information.

In rare cases, use the --style flag to specify a format-specific base style file. For HTML (single-page or multi-page) output, the style file should be a CSS file to substitute for "scribble.css" in the "scribble" collection. For Latex (or PDF) output, the style file should be a ".tex" file to substitute for "scribble.tex" in the "scribble" collection. The --style flag is rarely useful, because the content of "scribble.css" or "scribble.tex" is weakly specified; replacements must define all of the same styles, and the set of styles can change across versions of Racket.

Use --prefix to specify an alternate format-specific start of the output file. For HTML output, the starting file specifies the DOCTYPE declaration of each output HTML file as a substitute for "scribble-prefix.html" in the "scribble" collection. For Latex (or PDF) output (but not Latex-section output), the starting file specifies the \documentclass declaration and initial \usepackage declarations as a substitute for "scribble-prefix.tex" in the "scribble" collection. See also html-defaults, latex-defaults, and Extending and Configuring Scribble Output.

For any output form, use the ++extra flag to add a needed file to the build destination, such as an image file that is referenced in the generated output but not included via image (which copies the file automatically).

7.2 Handling Cross-References

Cross references within a document or documents rendered together are always resolved. When cross references span documents that are rendered separately, cross-reference information needs to be saved and loaded explicitly. Cross-reference information is format-specific, but HTML-format information is usable for Latex (or PDF) or text rendering.

A Racket installation includes HTML-format cross-reference information for all installed documentation. Each document’s information is in a separate file, so that loading all relevant files would be tedious. The +m or ++main-xref-in flag loads cross-reference information for all installed documentation, so

  scribble +m mine.scrbl

renders "mine.scrbl" to "mine.html" with cross-reference links to the Racket installation’s documentation. (The "racket-index" package must be installed to use +m/++main-xref-in.)

The ++xref-in flag loads cross-reference information by calling a specified module’s function. The setup/xref module provides load-collections-xref to load cross-reference information for all installed documentation, and +m or ++main-xref-in is just a shorthand for ++xref-in setup/xref load-collections-xref.

The --redirect-main flag for HTML output redirects links to the local installation’s documentation (not user-scope documentation) to a given URL, such as http://docs.racket-lang.org/. Beware that documentation links sometimes change (although Scribble generates HTML paths and anchors in a relatively stable way), so http://download.racket-lang.org/docs/version/html/ may be more reliable when building with an installation for version. The --redirect-main flag is ignored for non-HTML output.

The --redirect flag is like --redirect-main, except that it builds on the given URL to indicate a cross-reference tag that is more stable than an HTML path and anchor (in case the documentation for a function changes sections, for example), and it can generate redirected linked for documentation that is installed in user scope. The URL https://docs.racket-lang.org/local-redirect/index.html can work for these redirections.

For cross-references among documentation that is not part of the Racket installation, use --info-out to save information from a document build and use ++info-in to load previously saved information. For example, if "c.scrbl" refers to information in "a.scrbl" and "b.scrbl", then

builds "c.html" with cross-reference links into "a.html" and "b.html".

7.3 Selecting an Image Format

Use the ++convert ‹fmt› flag to select ‹fmt› as a preferred image format to use when rendering a document that includes values that can be converted to different image formats. The ‹fmt› argument can be pdf, ps, png, svg, or gif, but a renderer typically supports only a subset of those formats.

Use ++convert ‹fmt› multiple times to specify multiple preferred formats, where a ‹fmt› earlier in the command line take precedence over ‹fmt›s specified later.

For example, to generate Latex sources with images in Encapsulated PostScript format (so that the result works with latex instead of pdflatex), combine --latex with ++convert ps. To generate HTML pages with images converted to SVG format instead of PNG format, combine --html with ++convert svg.

Changed in version 1.4: Added ++convert support.

7.4 Passing Command-Line Arguments to Documents

When scribble loads and renders a document module, by default it sets current-command-line-arguments to an empty vector. Use the ++arg flag (any number of times) to add a string to current-command-line-arguments.

For example,

  scribble ++arg --mode ++arg fast turtle.scrbl

causes (current-command-line-arguments) to return '#("--mode" "fast") while "turtle.scrbl" is loaded and rendered, which could affect the content that "turtle.scrbl" generates if it uses current-command-line-arguments.

Changed in version 1.1: Added the empty-vector default and ++arg flag.