reading scribble include-section code

[Hendrik Boom]

I was reading Scribble's include-section code from
https://github.com/racket/scribble/blob/master/scribble-lib/scribble/base.rkt
and I can't figure out how this makes a section:

(define-syntax (include-section stx)
(syntax-case stx ()
[(_ mod)
(with-syntax ([doc-from-mod (datum->syntax #'mod 'doc)])
(unless (module-path? (syntax->datum #'mod))
(raise-syntax-error #f
"not a module path"
stx
#'mod))
#'(begin
(require (only-in mod [doc-from-mod doc]))
doc))]))

Could it be that *any* file read starting with #lang scribble/base
is implicitly wrapped with a @section wrapper of some sort?
Including, presumably, the top-level one presented on the comand line?

(This macro is giving my macro-understanding a real workout.)

(If that's not where I should find a current version of scribble,
someone please let me know)

-- hendrik

[Matthew Flatt]

At Fri, 29 Nov 2019 11:58:00 -0500, Hendrik Boom wrote:
> I was reading Scribble's include-section code from
> https://github.com/racket/scribble/blob/master/scribble-lib/scribble/base.rkt

> and I can't figure out how this makes a section: [...]

>
> Could it be that *any* file read starting with #lang scribble/base
> is implicitly wrapped with a @section wrapper of some sort?

Every `scribble/base` module provides a `doc` export. The value of
`doc` is a `part`.

When you use `section` in a Scribble document, that indicates to the
decoding layer (see `decode` from `scribble/decode`) that it should
create a nested `part`. So, in a way, every `scribble/base` document
has an implicit `section` --- at least, in the sense that both
`scribble/base` and `section` create parts.

Where `section` creates a part with a given title, using `title` in a
scribble document just creates a `title-decl` value. But the decoding
pass recognizes ` `title-decl` value to supply the title for `part`
that is exported as `doc`. That is, `scribble/base` sends all the
results of body expressions to `decode`, and that's where the `part`
for the module's `doc` export comes from.


Matthew