bkyk8rc3zvpnsf5inmcqq4n3k98cv6hj-my-site-hyper-literate-git.test.suzanne.soy-0.0.1

running.scrbl (10378B)

---

 #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 (not user-scope 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), and it can generate
 redirected linked for documentation that is installed in user scope.
 The URL @tt{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 @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.}]