hyper-literate/scribble-doc/scribblings/scribble/running.scrbl

#lang scribble/manual
@(require "utils.rkt"
          scribble/bnf
          (for-label setup/xref))

@(define fn (italic "fn"))

@title[#:tag "running"]{Running @exec{scribble}}

The @exec{scribble} command-line tool (also available as @as-index{@exec{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:

@itemlist[

 @item{@DFlag{html} --- a single HTML page @filepath{@|fn|.html},
       plus CSS sources and needed image files; this mode is the
       default if no format is specified}

 @item{@DFlag{htmls} --- multiple HTML pages (and associated files) in
       a @filepath{@|fn|} directory, starting with
       @filepath{@|fn|/index.html}}

 @item{@DFlag{html-tree} @nonterm{n} --- HTML pages in a directory
       tree up to @nonterm{n} layers deep; a tree of depth @exec{0} is
       equivalent to using @DFlag{html}, and a tree of depth @exec{1}
       is equivalent to using @DFlag{htmls}}

 @item{@DFlag{latex} --- LaTeX source @filepath{@|fn|.tex}, plus
       any needed additional files (such as non-standard class files)
       needed to run @exec{latex} or @exec{pdflatex}}

 @item{@DFlag{pdf} --- PDF @filepath{@|fn|.pdf} that is generated
       via @exec{pdflatex}}

 @item{@DFlag{xelatex} --- PDF @filepath{@|fn|.pdf} that is generated
       via @exec{xelatex}}

 @item{@DFlag{dvipdf} --- PDF @filepath{@|fn|.pdf} that is generated
       via @exec{latex}, @exec{dvips}, and @exec{pstopdf}}

 @item{@DFlag{latex-section} @nonterm{n} --- LaTeX source
       @filepath{@|fn|.tex} plus additional @filepath{.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 @tt{1} for @nonterm{n} to make the rendered
       document a section, @tt{2} for a subsection, etc.}

 @item{@DFlag{text} --- plain text in a single file
       @filepath{@|fn|.txt}, with non-ASCII content encoded as UTF-8}

 @item{@DFlag{markdown} --- Markdown text in a single file
       @filepath{@|fn|.md}, with non-ASCII content encoded as UTF-8}

]

Use @DFlag{dest-name} to specify a @|fn| other than the default name,
but only when a single source file is provided. Use the @DFlag{dest}
flag to specify a destination directory (for any number of source
files). Use @DFlag{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 @racket[doc]
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{submodule}
that exports @racket[doc] as a @racket[part], or it should directly
export @racket[doc] as a @racket[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 @DFlag{doc-binding} to
access an alternate exported name in place of @racket[doc].

When multiple documents are rendered at the same time, cross-reference
information in one document is visible to the other documents. See
@secref["xref-flags"] for information on references that cross
documents that are built separately.

@history[#:changed "1.4" @elem{Added @DFlag{dvipdf}.}
         #:changed "1.18" @elem{Added @DFlag{doc-binding}.}
         #:changed "1.19" @elem{Added @DFlag{xelatex}.}]

@section{Extra and Format-Specific Files}

Use the @DFlag{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 @filepath{.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 @racket[css-addition] or
@racket[tex-addition] style property so that the support is included
automatically; see @secref["config"] for more information.

In rare cases, use the @DFlag{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
@filepath{scribble.css} in the @filepath{scribble} collection. For
Latex (or PDF) output, the style file should be a @filepath{.tex} file
to substitute for @filepath{scribble.tex} in the @filepath{scribble}
collection. The @DFlag{style} flag is rarely useful, because the
content of @filepath{scribble.css} or @filepath{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 @DFlag{prefix} to specify an alternate format-specific start of
the output file. For HTML output, the starting file specifies the
@tt{DOCTYPE} declaration of each output HTML file as a substitute for
@filepath{scribble-prefix.html} in the @filepath{scribble}
collection. For Latex (or PDF) output (but not Latex-section output), the starting file specifies
the @ltx{documentclass} declaration and initial @ltx{usepackage}
declarations as a substitute for @filepath{scribble-prefix.tex} in the
@filepath{scribble} collection. See also @racket[html-defaults],
@racket[latex-defaults], and @secref["config"].

For any output form, use the @DPFlag{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 @racket[image] (which copies
the file automatically).

@section[#:tag "xref-flags"]{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 @PFlag{m} or @DPFlag{main-xref-in} flag loads cross-reference
information for all installed documentation, so

@commandline{scribble +m mine.scrbl}

renders @filepath{mine.scrbl} to @filepath{mine.html} with
cross-reference links to the Racket installation's documentation.
(The @filepath{racket-index} package must be installed to use
@PFlag{m}/@DPFlag{main-xref-in}.)

The @DPFlag{xref-in} flag loads cross-reference information by calling
a specified module's function. The @racketmodname[setup/xref] module
provides @racket[load-collections-xref] to load cross-reference
information for all installed documentation, and @PFlag{m} or
@DPFlag{main-xref-in} is just a shorthand for @exec{++xref-in
setup/xref load-collections-xref}.

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

The @DFlag{redirect} flag is like @DFlag{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 @DFlag{info-out} to save information from a
document build and use @DPFlag{info-in} to load previously saved
information. For example, if @filepath{c.scrbl} refers to information
in @filepath{a.scrbl} and @filepath{b.scrbl}, then

@commandline{scribble --info-out a.sxref a.scrbl}
@commandline{scribble --info-out b.sxref b.scrbl}
@commandline{scribble ++info-in a.sxref ++info-in b.sxref c.scrbl}

builds @filepath{c.html} with cross-reference links into
@filepath{a.html} and @filepath{b.html}.


@section{Selecting an Image Format}

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

Use @DPFlag{convert} @nonterm{fmt} multiple times to specify multiple
preferred formats, where a @nonterm{fmt} earlier in the command line
take precedence over @nonterm{fmt}s specified later.

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

@history[#:changed "1.4" @elem{Added @DPFlag{convert} support.}]

@section{Passing Command-Line Arguments to Documents}

When @exec{scribble} loads and renders a document module, by default
it sets @racket[current-command-line-arguments] to an empty vector.
Use the @DPFlag{arg} flag (any number of times) to add a string to
@racket[current-command-line-arguments].

For example,

@commandline{scribble ++arg --mode ++arg fast turtle.scrbl}

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

@history[#:changed "1.1" @elem{Added the empty-vector default and @DPFlag{arg} flag.}]