From e7adecfd59afcf2645c115e536519c0d927d8fda Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 6 Feb 2014 09:12:39 -0700
Subject: [PATCH] Scribble docs: split preprocessor variants into a separate
manual
original commit: ce31b5965c4680ca53cb85d6ec6731e2f949878f
---
.../scribblings/scribble/how-to-paper.scrbl | 6 ++--
.../scribblings/scribble/info.rkt | 1 +
.../scribblings/scribble/scribble-pp.scrbl | 26 +++++++++++++++++
.../scribblings/scribble/scribble.scrbl | 4 +--
.../scribblings/scribble/text.scrbl | 29 ++++++++++---------
5 files changed, 47 insertions(+), 19 deletions(-)
create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble-pp.scrbl
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to-paper.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to-paper.scrbl
index 341b6e14..a15d190b 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to-paper.scrbl
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to-paper.scrbl
@@ -577,7 +577,8 @@ the @hash-lang[] line that starts the document. The
@racket[decode] operation. The @racketmodname[scribble/text] language,
however, acts more like a plain-text generator and preprocessor, and it
does not perform any such decoding rules. (For more on
-@racketmodname[scribble/text], see @secref["text"].)
+@racketmodname[scribble/text], see @other-doc['(lib
+"scribblings/scribble/scribble-pp.scrbl")].)
@margin-note{More precisely, languages like
@racketmodname[scribble/base] apply @racket[decode] only after
@@ -677,4 +678,5 @@ Racket, continue with @secref["reader"] and then
need more power.
If you are interested in text generation and preprocessing, continue
-with @secref["reader"], but then skip to @secref["text"].
+with @secref["reader"], but then switch to
+@other-doc['(lib "scribblings/scribble/scribble-pp.scrbl")].
\ No newline at end of file
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
index e8aa9ab8..2df098de 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
@@ -1,6 +1,7 @@
#lang info
(define scribblings '(("scribble.scrbl" (multi-page) (racket-core -24))
+ ("scribble-pp.scrbl" (multi-page) (tool))
("demo-s1.scrbl" (keep-style no-search) (omit-start))
("demo-m1.scrbl" (multi-page keep-style no-search) (omit-start))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble-pp.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble-pp.scrbl
new file mode 100644
index 00000000..7cde8eec
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble-pp.scrbl
@@ -0,0 +1,26 @@
+#lang scribble/manual
+@(require "utils.rkt")
+
+@title{Scribble as Preprocessor}
+
+@author["Matthew Flatt" "Eli Barzilay"]
+
+@section-index["Preprocessor"]
+
+The @racketmodname[scribble/text] and @racketmodname[scribble/html]
+languages act as ``preprocessor'' languages for generating text or
+HTML. These preprocessor languages use the same @"@" syntax as the
+main Scribble tool (see @other-doc['(lib
+"scribblings/scribble/scribble.scrbl")]), but instead of working in
+terms of a document abstraction that can be rendered to text and HTML
+(and other formats), the preprocessor languages work in a way that is
+more specific to the target formats.
+
+@table-of-contents[]
+
+@; ------------------------------------------------------------------------
+
+@include-section["text.scrbl"]
+@include-section["html.scrbl"]
+
+@index-section[]
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble.scrbl
index adce341d..b23116db 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble.scrbl
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble.scrbl
@@ -1,5 +1,5 @@
#lang scribble/manual
-@(require scribble/bnf "utils.rkt")
+@(require "utils.rkt")
@title{Scribble: The Racket Documentation Tool}
@@ -26,8 +26,6 @@ starting with the @filepath{scribble.scrbl} file.
@include-section["generic.scrbl"]
@include-section["plt.scrbl"]
@include-section["lp.scrbl"]
-@include-section["text.scrbl"]
-@include-section["html.scrbl"]
@include-section["internals.scrbl"]
@include-section["running.scrbl"]
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl
index 57c699bb..118ed0e9 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl
@@ -10,6 +10,8 @@
@initialize-tests
@(define (tech/r s) @tech[s #:doc '(lib "scribblings/reference/reference.scrbl")])
+@(define scribble-doc '(lib "scribblings/scribble/scribble.scrbl"))
+@(define @-form @tech[#:doc scribble-doc]{@"@"-forms})
@(define-syntax-rule (def-rkt t-id)
(begin
@@ -21,7 +23,6 @@
#:style (make-style #f (list (make-tex-addition "shaded.tex")
(make-css-addition "shaded.css")))
]{Text Generation}
-@section-index["Preprocessor"]
@defmodulelang[scribble/text]{The @racketmodname[scribble/text]
language provides everything from @racket[racket/base],
@@ -33,9 +34,9 @@ preprocessor language:
@itemize[
@item{The language uses @racket[read-syntax-inside] to read the body
- of the module, similar to @secref["docreader"]. This means that
+ of the module, similar to @secref[#:doc scribble-doc "docreader"]. This means that
by default, all text is read in as Racket strings; and
- @seclink["reader"]|{@-forms}| can be used to use Racket
+ @seclink[#:doc scribble-doc "reader"]|{@-forms}| can be used to use Racket
functions and expression escapes.}
@item{Values of expressions are printed with a custom @racket[output]
@@ -77,7 +78,7 @@ part shows the source input, and the right part the printed result.)
feature on top of feature, but
blah blah blah.}-|
-Using @seclink["reader"]|{@-forms}|, we can define and use Racket
+Using @seclink[#:doc scribble-doc "reader"]|{@-forms}|, we can define and use Racket
functions.
@example|-{#lang scribble/text
@@ -114,7 +115,7 @@ convenient conditional output.
You have 3 errors in your code,
I fixed 1 error.}-|
-Using the scribble @seclink["reader"]|{@-forms}| syntax, you can write
+Using the scribble @seclink[#:doc scribble-doc "reader"]|{@-forms}| syntax, you can write
functions more conveniently too.
@example|-{#lang scribble/text
@@ -277,14 +278,14 @@ The separator can be set to any value.
@section{Defining Functions and More}
(Note: most of the tips in this section are applicable to any code
-that uses the Scribble @tech{@"@"-form} syntax.)
+that uses the Scribble @|@-form| syntax.)
Because the Scribble reader is uniform, you can use it in place of any
expression where it is more convenient. (By convention, we use a
plain S-expression syntax when we want a Racket expression escape, and
-an @tech{@"@"-form} for expressions that render as text, which, in the
+an @|@-form| for expressions that render as text, which, in the
@racket[scribble/text] language, is any value-producing expression.)
-For example, you can use an @tech{@"@"-form} for a function that you define.
+For example, you can use an @|@-form| for a function that you define.
@example|-{#lang scribble/text
@(define @bold[text] @list{*@|text|*})
@@ -298,7 +299,7 @@ will need to accept a variable number of arguments. In fact, this
leads to a common problem: what if we want to write a function that
consumes a number of ``text arguments'' rathen than a single
``rest-like'' body? The common solution for this is to provide the
-separate text arguments in the S-expression part of an @tech{@"@"-form}.
+separate text arguments in the S-expression part of an @|@-form|.
@example|-{#lang scribble/text
@(define (choose 1st 2nd)
@@ -310,7 +311,7 @@ separate text arguments in the S-expression part of an @tech{@"@"-form}.
Either you're with us, or against us.
}-|
-You can even use @tech{@"@"-forms} with a Racket quote or quasiquote as the
+You can even use @|@-form|s with a Racket quote or quasiquote as the
``head'' part to make it shorter, or use a macro to get grouping of
sub-parts without dealing with quotes.
@@ -337,7 +338,7 @@ sub-parts without dealing with quotes.
Yet another solution is to look at the text values and split the input
arguments based on a specific token. Using @racket[match] can make it
-convenient --- you can even specify the patterns with @tech{@"@"-forms}.
+convenient --- you can even specify the patterns with @|@-form|s.
@example|-{#lang scribble/text
@(require racket/match)
@@ -487,7 +488,7 @@ is the indentation of the output. This can be crucial in some cases, if
you're generating code for an indentation-sensitive language (e.g.,
Haskell, Python, or C preprocessor directives). To get a better
understanding of how the pieces interact, you may want to review how the
-@seclink["reader"]|{Scribble reader}| section, but also remember that
+@seclink[#:doc scribble-doc "reader"]|{Scribble reader}| section, but also remember that
you can use quoted forms to see how some form is read.
@example|-{#lang scribble/text
@@ -983,7 +984,7 @@ trivial: the source text is still source code in a module, so you can
more
}-|
-Note that the @seclink["at-exp-lang"]{@racket[at-exp] language} can
+Note that the @seclink[#:doc scribble-doc "at-exp-lang"]{@racket[at-exp] language} can
often be useful here, since such files need to deal with texts. Using
it, it is easy to include a lot of textual content.
@@ -1018,7 +1019,7 @@ it, it is easy to include a lot of textual content.
}-|
Of course, the extreme side of this will be to put all of your content
-in a plain Racket module, using @tech{@"@"-forms} for convenience. However,
+in a plain Racket module, using @|@-form|s for convenience. However,
there is no need to use the text language in this case; instead, you can
@racket[(require scribble/text)], which will get all of the bindings
that are available in the @racket[scribble/text] language. Using