docs/prose-runs.md
Paragraph runs: inline commands in bare prose
#lang sigil/doc splits prose at blank lines into paragraphs. Since SD-P3 a paragraph may also contain commands, so ordinary prose no longer has to be wrapped in @p{…} to carry inline markup:
@section["Getting started" id: "start"]{
A paragraph that mentions @code{define} and links to @ref["start"]{the top}
without any wrapper at all.
A second paragraph, after a blank line.
}Both spellings remain legal and produce the same document tree. @p{…} is still the way to be explicit, and nothing about it changed.
The rule, exactly
A stretch of prose between blank lines is a run. Within a run:
- a command not at a block boundary — one with anything other than whitespace before it on its line — folds into the run;
- a command at a block boundary is a block child, exactly as before;
- a blank line closes the run, exactly as before.
@(…) author expressions follow the same boundary rule as commands.
A run is completed when its values exist, not while parsing, because the parser has no command vocabulary and cannot know whether @p, @code or @aside produces a block or an inline node:
| the run's values | result |
|---|---|
| all inline nodes | one paragraph spanning the run |
| no inline nodes | the values unchanged, as sibling block children |
| a mix | an error naming the manuscript line and column |
The middle row is why @tip{@p{…}} — where @p opens the body on the same line as the brace and so is not at a block boundary — keeps meaning exactly what it always meant.
BREAKING: a block command mid-line in bare prose no longer works
A folded command's own children are lowered as inline, which is what @code, @ref and @em need. A command that demands block children, such as @aside{…}, therefore fails inside its own constructor rather than reaching the table above:
Prose then @aside{a block} then more. <- make-admonition: child belongs to
the wrong semantic categoryThis spelling used to be accepted. Before SD-P3 the @aside was lifted out to block position, its children were lowered as blocks, and the result was three valid siblings: a paragraph, an admonition, and another paragraph. It is now an error, and that is a deliberate narrowing of the language — the review that asked for this change ruled that a block-valued command appearing mid-paragraph should become an author error.
No manuscript in the measured corpus writes it (all 21 non-boundary nodes across 74 documents are @code or @p). The workaround is either a blank line or an explicit @p{…} around the prose.
What it is NOT is a divergence between the two spellings: @p{Prose then @aside{a block} then more.} has always produced that same message, because @p also lowers its children inline. A test pins the two messages as equal, so the spellings cannot drift apart on diagnostics.
The same applies to prose between two block values on one line — @tip{@p{One} and @p{Two}} was three paragraphs before and is an error now.
Document escapes in bare prose
@@, @{, @}, @[ and @] are scanned as their own nodes, so a line containing one is several prose fragments. Those fragments now fold into a single paragraph, where before SD-P3 each became a separate paragraph:
Contact bob@@example.com now. before: three paragraphs; now: oneThe new behaviour matches @p{Contact bob@@example.com now.} exactly, which is the point, but it is a change on a manuscript with no command in it at all — so "bare prose with no commands is untouched" is true of the corpus and not true in general.
Known limitation: a command at the start of a wrapped line
A command that lands at the start of a line is a block child even when the surrounding lines are prose:
This paragraph mentions
@code{define} and continues here. <- @code is a BLOCK child; this failsRewrap the line, or wrap the paragraph in @p{…}, and it works.
This is deliberate, and the reason is that the same shape is how real documents write a block command between two paragraphs:
Intro prose.
@aside{An aside.}
More prose.Those are three siblings, and they must stay three siblings. A line break in Sigil Doc currently means two different things depending on what follows it, and nothing in the syntax distinguishes them — Markdown answers the same question with blank-line separation. That is a language decision rather than a parser detail, and it is filed as an open question rather than left implicit; see the sigil-doc plan.
What this changed for consumers of locations
A paragraph produced by folding a run is located at the run's span. Before SD-P3, an all-inline @item{…} or @cell{…} body was wrapped into a paragraph at runtime by (sigil doc author), which gave that paragraph the container's location. Those paragraphs are now narrower and address the prose itself.
Measured over 74 real manuscripts (the 10 in-repo plus the 64-document Guile Beginners conversion): 2,580 block-context nodes, 21 not at a block boundary, and this is the only observable difference in that corpus. Nothing else in the lowered output of the other 71 manuscripts changes by a single byte.
That is a statement about those documents, not a property of the change. The two shapes the corpus does not contain — a block command folded mid-line, and a document escape in bare prose — are described in the two sections above and do change.