{"size": 3722, "ext": "scrbl", "max_stars_repo_path": "scribble-doc/scribblings/scribble/doclang.scrbl", "max_stars_repo_name": "dannypsnl/scribble", "max_stars_repo_stars_event_min_datetime": "2015-01-11T18:19:42.000Z", "max_stars_repo_stars_event_max_datetime": "2022-03-31T08:45:52.000Z", "max_issues_repo_path": "scribble-doc/scribblings/scribble/doclang.scrbl", "max_issues_repo_name": "dannypsnl/scribble", "max_issues_repo_issues_event_min_datetime": "2015-03-24T20:53:21.000Z", "max_issues_repo_issues_event_max_datetime": "2022-02-20T22:51:57.000Z", "max_forks_repo_path": "scribble-doc/scribblings/scribble/doclang.scrbl", "max_forks_repo_name": "dannypsnl/scribble", "max_forks_repo_forks_event_min_datetime": "2015-03-09T12:23:06.000Z", "max_forks_repo_forks_event_max_datetime": "2022-03-07T15:00:13.000Z"}
{"max_stars_count": 161, "max_issues_count": 260, "max_forks_count": 103, "avg_line_length": 29.5396825397, "max_line_length": 99, "alphanum_fraction": 0.7278344976}
#lang scribble/manual
@(require "utils.rkt")

@title[#:tag "doclang"]{Document Language}

@defmodulelang[scribble/doclang2]{The @racketmodname[scribble/doclang2]
language provides everything from @racket[racket/base], except that it
replaces the @racket[#%module-begin] form.

The @racketmodname[scribble/doclang2] @racket[#%module-begin]
essentially packages the body of the module into a call to
@racket[decode], binds the result to @racket[doc], and exports
@racket[doc].

Any module-level form other than an expression (e.g., a
@racket[require] or @racket[define]) remains at the top level, and
the @racket[doc] binding is put at the end of the module. As usual, a
module-top-level @racket[begin] slices into the module top level.

For example:
@codeblock|{
#lang racket
(module example scribble/doclang2
  "hello world, this is"
  " an example document")
(require 'example)
doc
}|

The behavior of @racketmodname[scribble/doclang2] can be customized by
providing @racket[#:id], @racket[#:post-process], @racket[#:begin], and @racket[#:exprs]
arguments at the very beginning of the module.

@itemize[

@item{@racket[#:id] names the top-level documentation binding. By default, this
is @racket[doc].}

@item{@racket[#:post-process] processes the body of the module after
@racket[decode].  By default, this is @racket[values].}

@item{@racket[#:begin] prepends an additional sequence of expressions to the
beginning of the module's body outside of consideration for the document content.
For example, the default @racket[configure-runtime] submodule might be replaced
using @racket[#:begin], because using @racket[#:exprs] nests the replacement too
deeply to work as an override. By default, this is the empty sequence @racket[()].}

@item{@racket[#:exprs] prepends an additional sequence of expressions to the
beginning of the module's body, but after @racket[#:begin].  By default, this is the empty sequence
@racket[()].}

]

This example explicitly uses the defaults for all three keywords:

@codeblock|{
#lang racket
(module example scribble/doclang2
  #:id doc
  #:post-process values
  #:exprs ()
  "hello world, this is an example document")
(require 'example)
doc
}|


The next toy example uses a different name for the documentation binding, and
also adds an additional binding with a count of the parts in the document:

@codeblock|{
#lang racket
(module example scribble/doclang2
  #:id documentation
  #:post-process (lambda (decoded-doc)
                   (set! number-of-parts (length (part-parts decoded-doc)))
                   decoded-doc)
  #:exprs ((title "My first expression!"))

  (require scribble/core
           scribble/base)
  
  (define number-of-parts #f)
  (provide number-of-parts)
  (section "part 1")
  "hello world"
  (section "part 2")
  "this is another document")

(require 'example)
number-of-parts
documentation
}|


@history[#:changed "1.41" @elem{Added @racket[#:begin].}]}



@section{@racketmodname[scribble/doclang]}
@defmodulelang[scribble/doclang]{The @racketmodname[scribble/doclang] language
provides most of the same functionality as @racketmodname[scribble/doclang2], where the
configuration options are positional and mandatory.  The first three elements
in the @racket[#%module-begin]'s body must be the @racket[id],
@racket[post-process], and @racket[exprs] arguments.

Example:
@codeblock|{
#lang racket
(module* example scribble/doclang
  doc
  values
  ()
  (require scribble/base)
  (provide (all-defined-out))
  (define foo (para "hello again"))
  "hello world, this is an example document"
  (para "note the " (bold "structure")))

(module+ main
  (require (submod ".." example))
  (printf "I see doc is: ~s\n\n" doc)
  (printf "I see foo is: ~s" foo))
}|
}
