document `scribble' command-line use

original commit: 73f6a2b3929c6c55add6ea6e7e54ae9628f776c5

collects/scribble/run.rkt

@@ -56,25 +56,22 @@
     (current-dest-directory dir)]
    [("--dest-name") name "write output as <name>"
     (current-dest-name name)]
-   [("--prefix") file "use given .html/.tex prefix (for doctype/documentclass)"
+   #:multi
-    (current-prefix-file file)]
+   [("++style") file "add given .css/.tex file after others"
+    (current-style-extra-files (cons file (current-style-extra-files)))]
+   #:once-each
    [("--style") file "use given base .css/.tex file"
     (current-style-file file)]
-   [("--redirect") url "redirect external links to tag search via <url>"
+   [("--prefix") file "use given .html/.tex prefix (for doctype/documentclass)"
-    (current-redirect url)]
+    (current-prefix-file file)]
-   [("--redirect-main") url "redirect main doc links to <url>"
-    (current-redirect-main url)]
-   [("--info-out") file "write format-specific link information to <file>"
-    (current-info-output-file file)]
    #:multi
    [("++extra") file "add given file"
     (current-extra-files (cons file (current-extra-files)))]
-   [("++style") file "add given .css/.tex file after others"
+   [("--redirect-main") url "redirect main doc links to <url>"
-    (current-style-extra-files (cons file (current-style-extra-files)))]
+    (current-redirect-main url)]
-   [("++info-in") file "load format-specific link information from <file>"
+   [("--redirect") url "redirect external links to tag search via <url>"
-    (current-info-input-files
+    (current-redirect url)]
-     (cons file (current-info-input-files)))]
+   [("++xref-in") module-path proc-id "load format-specific cross-ref info by"
-   [("++xref-in") module-path proc-id "load format-specific link information by"
     "calling <proc-id> as exported by <module-path>"
     (let ([mod (read-one module-path)]
           [id (read-one proc-id)])
@@ -86,6 +83,11 @@
          'scribble "bad procedure identifier for ++ref-in: ~s" proc-id))
       (current-xref-input-modules
        (cons (cons mod id) (current-xref-input-modules))))]
+   [("--info-out") file "write format-specific cross-ref info to <file>"
+    (current-info-output-file file)]
+   [("++info-in") file "load format-specific cross-ref info from <file>"
+    (current-info-input-files
+     (cons file (current-info-input-files)))]
    #:once-each
    [("--quiet") "suppress output-file reporting"
     (current-quiet #t)]

collects/scribblings/scribble/how-to-paper.scrbl

@@ -41,15 +41,7 @@ for the kind of document that you want as output:
        @itemize[
 
          @item{Run
-                @commandline{scribble --pdf mouse.scrbl}
+               @commandline{scribble mouse.scrbl}
-               to generate PDF as @filepath{mouse.pdf}. This will
-               work only if you have @exec{pdflatex} installed.
-               If you'd like to see the intermediate Latex, try
-                @commandline{scribble --latex mouse.scrbl}
-               to generate @filepath{mouse.tex}.}
-
-         @item{Run
-               @commandline{scribble --html mouse.scrbl}
               to generate HTML as @filepath{mouse.html}.  You may
               notice that the apostrophe in ``he's'' turned into a
               curly apostrophe.}
@@ -60,8 +52,19 @@ for the kind of document that you want as output:
               Sub-sections (which we add next) will appear as separate
               HTML files in the @filepath{mouse} directory.}
 
+         @item{Run
+                @commandline{scribble --pdf mouse.scrbl}
+               to generate PDF as @filepath{mouse.pdf}. This will
+               work only if you have @exec{pdflatex} installed.
+               If you'd like to see the intermediate Latex, try
+                @commandline{scribble --latex mouse.scrbl}
+               to generate @filepath{mouse.tex}.}
+
           ]
 
+See @secref["running"] for more information on the @exec{scribble}
+command-line tool.
+
 @section{Multiple Sections}
 
 Add more text to @filepath{mouse.scrbl} so that it looks like this:
@@ -604,5 +607,5 @@ Racket, continue with @secref["reader"] and then
 @secref["generic-prose"].  Move on to @secref["internals"] when you
 need more power.
 
-If you are interested in text preprocessing, contiue with
+If you are interested in text preprocessing, continue with
 @secref["reader"], but then skip to @secref["preprocessor"].

collects/scribblings/scribble/running.scrbl

@@ -0,0 +1,134 @@
+#lang scribble/manual
+@(require "utils.rkt"
+          (for-label setup/xref))
+
+@(define fn (italic "fn"))
+
+@title[#:tag "running"]{Running @exec{scribble}}
+
+The @exec{scribble} command-line tool (also available as @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{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{text} --- plain text in a single file
+       @filepath{@|fn|.txt}, 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).
+
+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
+@secref["xref-flags"] for information on references that cross
+documents that are built separately.
+
+@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 to 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, the 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).
+
+@subsection[#: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, format-specific cross-reference information needs
+to be saved and loaded explicitly.
+
+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
+@DPFlag{xref-in} flag loads cross-reference information by calling a
+specified module's function; in particular, the
+@racketmodname[setup/xref] module provides
+@racket[load-collections-xref] to load cross-reference information for
+all installed documentation. Thus,
+
+@commandline{scribble ++xref-in setup/xref load-collections-xref mine.scrbl}
+
+renders @filepath{mine.scrbl} to @filepath{mine.html} with
+cross-reference links to the Racket installation's documentation.
+
+The @DFlag{redirect-main} flag 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} flag is similar to @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}.
+

collects/scribblings/scribble/scribble.scrbl

@@ -28,5 +28,6 @@ starting with the @filepath{scribble.scrbl} file.
 @include-section["lp.scrbl"]
 @include-section["preprocessor.scrbl"]
 @include-section["internals.scrbl"]
+@include-section["running.scrbl"]
 
 @index-section[]