@include-section should have the same load order as @section
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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