suzanne.soy/scribble-enhanced
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Scribble docs: split preprocessor variants into a separate manual

Browse Source 
original commit: ce31b5965c4680ca53cb85d6ec6731e2f949878f
This commit is contained in:
Matthew Flatt 2014-02-06 09:12:39 -07:00
parent b23fb873f5
commit e7adecfd59
5 changed files with 47 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/how-to-paper.scrbl
View File

@ -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")].

1
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
View File

@ -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))

26
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble-pp.scrbl Normal file
View File

@ -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[]

4
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/scribble.scrbl
View File

@ -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"]

29
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl
View File

@ -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