AtlatestRepositorysigil-doc
1# Paragraph runs: inline commands in bare prose
2
3`#lang sigil/doc` splits prose at blank lines into paragraphs. Since SD-P3 a
4paragraph may also contain commands, so ordinary prose no longer has to be
5wrapped in `@p{…}` to carry inline markup:
6
7```text
8@section["Getting started" id: "start"]{
9A paragraph that mentions @code{define} and links to @ref["start"]{the top}
10without any wrapper at all.
12A second paragraph, after a blank line.
14```
16Both spellings remain legal and produce the same document tree. `@p{…}` is still
17the way to be explicit, and nothing about it changed.
19## The rule, exactly
21A stretch of prose between blank lines is a **run**. Within a run:
23- a command **not at a block boundary** — one with anything other than
24 whitespace before it on its line — folds into the run;
25- a command **at a block boundary** is a block child, exactly as before;
26- a blank line closes the run, exactly as before.
28`@(…)` author expressions follow the same boundary rule as commands.
30A run is completed when its values exist, not while parsing, because the parser
31has no command vocabulary and cannot know whether `@p`, `@code` or `@aside`
32produces a block or an inline node:
34| the run's values | result |
35| --- | --- |
36| all inline nodes | one paragraph spanning the run |
37| no inline nodes | the values unchanged, as sibling block children |
38| a mix | an error naming the manuscript line and column |
40The middle row is why `@tip{@p{…}}` — where `@p` opens the body on the same line
41as the brace and so is *not* at a block boundary — keeps meaning exactly what it
42always meant.
44### BREAKING: a block command mid-line in bare prose no longer works
46A folded command's own children are lowered as **inline**, which is what
47`@code`, `@ref` and `@em` need. A command that demands *block* children, such as
48`@aside{…}`, therefore fails inside its own constructor rather than reaching the
49table above:
51```text
52Prose then @aside{a block} then more. <- make-admonition: child belongs to
53 the wrong semantic category
54```
56**This spelling used to be accepted.** Before SD-P3 the `@aside` was lifted out
57to block position, its children were lowered as blocks, and the result was three
58valid siblings: a paragraph, an admonition, and another paragraph. It is now an
59error, and that is a deliberate narrowing of the language — the review that
60asked for this change ruled that a block-valued command appearing mid-paragraph
61should become an author error.
63No manuscript in the measured corpus writes it (all 21 non-boundary nodes across
6474 documents are `@code` or `@p`). The workaround is either a blank line or an
65explicit `@p{…}` around the prose.
67What it is NOT is a divergence between the two spellings: `@p{Prose then
68@aside{a block} then more.}` has always produced that same message, because `@p`
69also lowers its children inline. A test pins the two messages as equal, so the
70spellings cannot drift apart on diagnostics.
72The same applies to prose between two block values on one line —
73`@tip{@p{One} and @p{Two}}` was three paragraphs before and is an error now.
75### Document escapes in bare prose
77`@@`, `@{`, `@}`, `@[` and `@]` are scanned as their own nodes, so a line
78containing one is several prose fragments. Those fragments now fold into a
79single paragraph, where before SD-P3 each became a **separate paragraph**:
81```text
82Contact bob@@example.com now. before: three paragraphs; now: one
83```
85The new behaviour matches `@p{Contact bob@@example.com now.}` exactly, which is
86the point, but it is a change on a manuscript with no command in it at all — so
87"bare prose with no commands is untouched" is true of the corpus and not true in
88general.
90## Known limitation: a command at the start of a wrapped line
92A command that lands at the **start of a line** is a block child even when the
93surrounding lines are prose:
95```text
96This paragraph mentions
97@code{define} and continues here. <- @code is a BLOCK child; this fails
98```
100Rewrap the line, or wrap the paragraph in `@p{…}`, and it works.
102This is deliberate, and the reason is that the same shape is how real documents
103write a block command between two paragraphs:
105```text
106Intro prose.
107@aside{An aside.}
108More prose.
109```
111Those are three siblings, and they must stay three siblings. A line break in
112Sigil Doc currently means two different things depending on what follows it, and
113nothing in the syntax distinguishes them — Markdown answers the same question
114with blank-line separation. That is a language decision rather than a parser
115detail, and it is filed as an open question rather than left implicit; see the
116`sigil-doc` plan.
118## What this changed for consumers of locations
120A paragraph produced by folding a run is located at the **run's** span. Before
121SD-P3, an all-inline `@item{…}` or `@cell{…}` body was wrapped into a paragraph
122at runtime by `(sigil doc author)`, which gave that paragraph the **container's**
123location. Those paragraphs are now narrower and address the prose itself.
125Measured over 74 real manuscripts (the 10 in-repo plus the 64-document Guile
126Beginners conversion): 2,580 block-context nodes, 21 not at a block boundary, and
127this is the only observable difference **in that corpus**. Nothing else in the
128lowered output of the other 71 manuscripts changes by a single byte.
130That is a statement about those documents, not a property of the change. The two
131shapes the corpus does not contain — a block command folded mid-line, and a
132document escape in bare prose — are described in the two sections above and do
133change.