8 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"

• --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

• --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. 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.

8.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).

8.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 ++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 redirects links to the local installation’s 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 flag is similar to --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). No server currently exists to serve such tag requests, however.

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".