commit 532feda0483af7377829df63372ad59dbb913aed
parent 41c51bfdb444e2c07b121af23c5e4f398ace6717
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 20 Jun 2011 18:41:24 -0600
document `scribble' command-line use
original commit: 73f6a2b3929c6c55add6ea6e7e54ae9628f776c5
Diffstat:
4 files changed, 164 insertions(+), 24 deletions(-)
diff --git a/collects/scribble/run.rkt b/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)"
- (current-prefix-file file)]
+ #:multi
+ [("++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>"
- (current-redirect url)]
- [("--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)]
+ [("--prefix") file "use given .html/.tex prefix (for doctype/documentclass)"
+ (current-prefix-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"
- (current-style-extra-files (cons file (current-style-extra-files)))]
- [("++info-in") file "load format-specific link information from <file>"
- (current-info-input-files
- (cons file (current-info-input-files)))]
- [("++xref-in") module-path proc-id "load format-specific link information by"
+ [("--redirect-main") url "redirect main doc links to <url>"
+ (current-redirect-main url)]
+ [("--redirect") url "redirect external links to tag search via <url>"
+ (current-redirect url)]
+ [("++xref-in") module-path proc-id "load format-specific cross-ref info 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)]
diff --git a/collects/scribblings/scribble/how-to-paper.scrbl b/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}
- 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}
+ @commandline{scribble 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"].
diff --git a/collects/scribblings/scribble/running.scrbl b/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}.
+
diff --git a/collects/scribblings/scribble/scribble.scrbl b/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[]
