AtlatestRepositorysigil-doc

sigil-doc / tree / test / sd-p7 / folioauthor.sgl

1;;; (sd-p7 folio author) -- the folio-shaped author vocabulary, and the three
2;;; wrappers that install this language's content profile.
3;;;
4;;; HOW A DELEGATING LANGUAGE INSTALLS ITS PROFILE, and why it is exactly three
5;;; names.
6;;;
7;;; `(sigil doc private parser)` emits generated syntax that CALLS runtime
8;;; 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 its
10;;; profile by binding those names to wrappers, and needs no change to sigil-doc
11;;; and no fork of the paragraph-run rules.
12;;;
13;;; The names are enumerated FROM THE PARSER rather than remembered, and
14;;; `test/gate-sd-p7.sh` re-derives the same set from `parser.sgl` and fails if
15;;; it has moved. The parser emits three author-runtime names:
16;;;
17;;; author-at every command and every root
18;;; author-normalize every command's result, and the hoisted
19;;; `#%sigil/doc-expression:N` lambdas
20;;; author-paragraph-run bare-prose runs
21;;;
22;;; CORRECTED after adversarial review. This header used to claim that the
23;;; second and third are emitted OUTSIDE any `author-at`, and that this is why
24;;; wrapping `author-at` alone is not enough. That was wrong, and it was
25;;; invented rather than read: `command-expression` splices a command's lowered
26;;; children INTO the expression `author-at` wraps, and a hoisted expression
27;;; lambda is only ever called from inside a root body. Every emission site runs
28;;; inside the root's `author-at`, so wrapping `author-at` alone WOULD be
29;;; sufficient. All three are wrapped here as defence in depth, which is a
30;;; different claim and a much weaker one.
31;;;
32;;; The site that genuinely has no wrapper is a `@(...)` form at the manuscript
33;;; TOP LEVEL: `parse-document-parts-with-profile` hoists it as raw syntax with
34;;; no `author-at` and no profile installed. Nothing there can build a node
35;;; today, because `author-location` raises outside an `author-at`.
36;;;
37;;; `author-flatten` is deliberately NOT in that list and deliberately not
38;;; wrapped here: it is called lexically from inside `(sigil doc author)`'s own
39;;; commands, so a prelude binding could never reach it. It consults the ambient
40;;; content profile itself, inside `(sigil doc private author-runtime)`. That is
41;;; 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-run
47 note task milestone phase related)
48 (begin
49 ;; Each wrapper installs the profile for the dynamic extent of the call it
50 ;; forwards. `sd:with-content-profile` is `dynamic-wind`-based, so a nested
51 ;; parse -- author code loading another manuscript -- restores the outer
52 ;; profile on the way out, on success and on failure alike.
53 (define (author-at loc thunk)
54 (sd:with-content-profile folio-content-profile
55 (lambda () (sd:author-at loc thunk))))
56 (define (author-normalize value loc command)
57 (sd:with-content-profile folio-content-profile
58 (lambda () (sd:author-normalize value loc command))))
59 (define (author-paragraph-run values loc)
60 (sd:with-content-profile folio-content-profile
61 (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 optional
75 ;; decoration: a command with NO body at all opens a NAMED BLOCK that must
76 ;; be closed with `@end related`, so `@related["topics/x"]` inside a section
77 ;; swallows everything after it and fails at the enclosing `@end note`.
78 ;; Measured, not guessed -- it is how the first version of
79 ;; `sd-p7-folio-note.sgd` failed. `@anchor["start"]{}` in
80 ;; `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")))))