@include-section should have the same load order as @section

[sorpaas]

If I have a main.scrbl, written:

@fn-a[]

@section{A section}
@fn-b[]

fn-a would be called first, and then fn-b.

However, if I extract the section to a file, so I have two files:

;;; main.scrbl
@fn-a[]

@include-section{section.scrbl}

;;; section.scrbl
@title{A section}
@fn-b[]

fn-b would be called first, and then fn-a.

However, they really should be called in the same order. In main.scrbl I might have something that modify a racket parameter (pinning the timezone in gregor, for example), and I would want those parameters get reflected in all sections.

I have a draft code that uses dynamic-require to solve this problem. However, I don't know whether it's general enough to be merged here:

(define (include-section* stx mod)
  (let* ([stx-path (syntax-source stx)]
         [mod-path (simplify-path (build-path stx-path 'up mod))])
    (dynamic-require `(file ,(path->string mod-path)) 'doc)))

(wrap-with-syntax include-section include-section*)

Where wrap-with-syntax is:

(define-syntax (wrap-with-syntax stx)
  (syntax-case stx ()
    [(_ name func)
     #'(define-syntax (name stx)
         (syntax-case stx () [(_ . t) #`(func (syntax #,stx) . t)]))]))

[mflatt]

I don't think imposing an order here is going to work out. Importing another section into a Scribble document is meant to correspond to a require at the module level, giving it various nice interactions with tools, such as raco make. More generally, documents are meant to be constructed functionality as much as possible.

To the degree that side effects are needed, the intent is to encapsulate the effects in the collect and resolve passes (and the traverse pass, if needed). Those passes are defined to have a specific order to facilitate the use of side effects.

[sorpaas]

@mflatt However that won't solve the Racket parameter setting issue. For example, I might have:

@require[gregor]
@current-timezone{America/New_York}

@section{A section}
@task[#:scheduled (moment ...)]{...}

That works correctly. While:

;;; main.scrbl
@require[gregor]
@current-timezone{America/New_York}

@include-section{section.scrbl}

;;; section.scrbl
@require[gregor]

@title{A section}
@task[#:scheduled (moment ...)]{...}

That does not work, while a normal user would expect they print out the same result.