racket / racket/scribble

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

Open
#86 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Racket
Stars
250
Forks
102
Avg merge
11d 11h
Merged PRs (30d)
1

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the evaluation behavior of @section and @include-section using the main.scrbl and section.scrbl examples in the issue. Read the proposed dynamic-require implementation and wrap-with-syntax helper first; done means included sections observe parameter changes made earlier in the main document and preserve the same call order as inline sections.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.