AtlatestRepositorysigil-doc
1
# Paragraph runs: inline commands in bare prose3
`#lang sigil/doc` splits prose at blank lines into paragraphs. Since SD-P3 a4
paragraph may also contain commands, so ordinary prose no longer has to be5
wrapped in `@p{…}` to carry inline markup:7
```text8
@section["Getting started" id: "start"]{9
A paragraph that mentions @code{define} and links to @ref["start"]{the top}10
without any wrapper at all.12
A second paragraph, after a blank line.13
}14
```16
Both spellings remain legal and produce the same document tree. `@p{…}` is still17
the way to be explicit, and nothing about it changed.19
## The rule, exactly21
A stretch of prose between blank lines is a **run**. Within a run:23
- a command **not at a block boundary** — one with anything other than24
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.30
A run is completed when its values exist, not while parsing, because the parser31
has no command vocabulary and cannot know whether `@p`, `@code` or `@aside`32
produces 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 |40
The middle row is why `@tip{@p{…}}` — where `@p` opens the body on the same line41
as the brace and so is *not* at a block boundary — keeps meaning exactly what it42
always meant.44
### BREAKING: a block command mid-line in bare prose no longer works46
A folded command's own children are lowered as **inline**, which is what47
`@code`, `@ref` and `@em` need. A command that demands *block* children, such as48
`@aside{…}`, therefore fails inside its own constructor rather than reaching the49
table above:51
```text52
Prose then @aside{a block} then more. <- make-admonition: child belongs to53
the wrong semantic category54
```56
**This spelling used to be accepted.** Before SD-P3 the `@aside` was lifted out57
to block position, its children were lowered as blocks, and the result was three58
valid siblings: a paragraph, an admonition, and another paragraph. It is now an59
error, and that is a deliberate narrowing of the language — the review that60
asked for this change ruled that a block-valued command appearing mid-paragraph61
should become an author error.63
No manuscript in the measured corpus writes it (all 21 non-boundary nodes across64
74 documents are `@code` or `@p`). The workaround is either a blank line or an65
explicit `@p{…}` around the prose.67
What it is NOT is a divergence between the two spellings: `@p{Prose then68
@aside{a block} then more.}` has always produced that same message, because `@p`69
also lowers its children inline. A test pins the two messages as equal, so the70
spellings cannot drift apart on diagnostics.72
The 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 prose77
`@@`, `@{`, `@}`, `@[` and `@]` are scanned as their own nodes, so a line78
containing one is several prose fragments. Those fragments now fold into a79
single paragraph, where before SD-P3 each became a **separate paragraph**:81
```text82
Contact bob@@example.com now. before: three paragraphs; now: one83
```85
The new behaviour matches `@p{Contact bob@@example.com now.}` exactly, which is86
the point, but it is a change on a manuscript with no command in it at all — so87
"bare prose with no commands is untouched" is true of the corpus and not true in88
general.90
## Known limitation: a command at the start of a wrapped line92
A command that lands at the **start of a line** is a block child even when the93
surrounding lines are prose:95
```text96
This paragraph mentions97
@code{define} and continues here. <- @code is a BLOCK child; this fails98
```100
Rewrap the line, or wrap the paragraph in `@p{…}`, and it works.102
This is deliberate, and the reason is that the same shape is how real documents103
write a block command between two paragraphs:105
```text106
Intro prose.107
@aside{An aside.}108
More prose.109
```111
Those are three siblings, and they must stay three siblings. A line break in112
Sigil Doc currently means two different things depending on what follows it, and113
nothing in the syntax distinguishes them — Markdown answers the same question114
with blank-line separation. That is a language decision rather than a parser115
detail, and it is filed as an open question rather than left implicit; see the116
`sigil-doc` plan.118
## What this changed for consumers of locations120
A paragraph produced by folding a run is located at the **run's** span. Before121
SD-P3, an all-inline `@item{…}` or `@cell{…}` body was wrapped into a paragraph122
at runtime by `(sigil doc author)`, which gave that paragraph the **container's**123
location. Those paragraphs are now narrower and address the prose itself.125
Measured over 74 real manuscripts (the 10 in-repo plus the 64-document Guile126
Beginners conversion): 2,580 block-context nodes, 21 not at a block boundary, and127
this is the only observable difference **in that corpus**. Nothing else in the128
lowered output of the other 71 manuscripts changes by a single byte.130
That is a statement about those documents, not a property of the change. The two131
shapes the corpus does not contain — a block command folded mid-line, and a132
document escape in bare prose — are described in the two sections above and do133
change.