AtlatestRepositorysigil-doc
1
;;; (sd-p7 folio author) -- the folio-shaped author vocabulary, and the three2
;;; wrappers that install this language's content profile.3
;;;4
;;; HOW A DELEGATING LANGUAGE INSTALLS ITS PROFILE, and why it is exactly three5
;;; names.6
;;;7
;;; `(sigil doc private parser)` emits generated syntax that CALLS runtime8
;;; procedures by bare name. Those names resolve in the manuscript's own scope,9
;;; which the reader's prelude decides -- so a delegating language installs its10
;;; profile by binding those names to wrappers, and needs no change to sigil-doc11
;;; and no fork of the paragraph-run rules.12
;;;13
;;; The names are enumerated FROM THE PARSER rather than remembered, and14
;;; `test/gate-sd-p7.sh` re-derives the same set from `parser.sgl` and fails if15
;;; it has moved. The parser emits three author-runtime names:16
;;;17
;;; author-at every command and every root18
;;; author-normalize every command's result, and the hoisted19
;;; `#%sigil/doc-expression:N` lambdas20
;;; author-paragraph-run bare-prose runs21
;;;22
;;; CORRECTED after adversarial review. This header used to claim that the23
;;; second and third are emitted OUTSIDE any `author-at`, and that this is why24
;;; wrapping `author-at` alone is not enough. That was wrong, and it was25
;;; invented rather than read: `command-expression` splices a command's lowered26
;;; children INTO the expression `author-at` wraps, and a hoisted expression27
;;; lambda is only ever called from inside a root body. Every emission site runs28
;;; inside the root's `author-at`, so wrapping `author-at` alone WOULD be29
;;; sufficient. All three are wrapped here as defence in depth, which is a30
;;; different claim and a much weaker one.31
;;;32
;;; The site that genuinely has no wrapper is a `@(...)` form at the manuscript33
;;; TOP LEVEL: `parse-document-parts-with-profile` hoists it as raw syntax with34
;;; no `author-at` and no profile installed. Nothing there can build a node35
;;; today, because `author-location` raises outside an `author-at`.36
;;;37
;;; `author-flatten` is deliberately NOT in that list and deliberately not38
;;; wrapped here: it is called lexically from inside `(sigil doc author)`'s own39
;;; commands, so a prelude binding could never reach it. It consults the ambient40
;;; content profile itself, inside `(sigil doc private author-runtime)`. That is41
;;; the whole reason the profile is ambient rather than an extra argument.42
(define-library (sd-p7 folio author)43
(import (sigil core)44
(prefix (sigil doc private author-runtime) sd:)45
(sd-p7 folio model))46
(export author-at author-normalize author-paragraph-run47
note task milestone phase related)48
(begin49
;; Each wrapper installs the profile for the dynamic extent of the call it50
;; forwards. `sd:with-content-profile` is `dynamic-wind`-based, so a nested51
;; parse -- author code loading another manuscript -- restores the outer52
;; profile on the way out, on success and on failure alike.53
(define (author-at loc thunk)54
(sd:with-content-profile folio-content-profile55
(lambda () (sd:author-at loc thunk))))56
(define (author-normalize value loc command)57
(sd:with-content-profile folio-content-profile58
(lambda () (sd:author-normalize value loc command))))59
(define (author-paragraph-run values loc)60
(sd:with-content-profile folio-content-profile61
(lambda () (sd:author-paragraph-run values loc))))63
(define (children command values)64
(sd:author-flatten values (sd:author-location) command))66
(define (note id title . body)67
(make-note id title (children 'note body) (sd:author-location)))68
(define (task id title . body)69
(make-task id title (children 'task body) (sd:author-location)))70
(define (milestone id title . body)71
(make-milestone id title (children 'milestone body) (sd:author-location)))72
(define (phase id title . body)73
(make-phase id title (children 'phase body) (sd:author-location)))74
;; Written `@related["topics/x"]{}`. The empty-brace body is not optional75
;; decoration: a command with NO body at all opens a NAMED BLOCK that must76
;; be closed with `@end related`, so `@related["topics/x"]` inside a section77
;; swallows everything after it and fails at the enclosing `@end note`.78
;; Measured, not guessed -- it is how the first version of79
;; `sd-p7-folio-note.sgd` failed. `@anchor["start"]{}` in80
;; `test/fixtures/minimal.sgd` is the same idiom.81
(define (related target . body)82
(if (null? body)83
(make-related target 'mentions (sd:author-location))84
(error "related: body must be empty")))))