I, too, do not understand the

\definetextbackground

\starttextbackground

\stoptextbackground

commands, even though I tried looking at "details.pdf" (and core-pgr.tex).

My particular problem is rather classic, that of illustrating examples, set off from the main text.

I first used

\defineframedtext [example]

[width=fit,background=screen,backgroundscreen=0.7]

\startexample

...

\stopexample

and this is appropriate if the example is short enough to fit on one page.

However, a long example (many paragraphs) that spans more than one page

runs off the bottom.

Textbackground seems more appropriate, so I tried

\definetextbackground [example]

[location=paragraph,backgroundcolor=middlegray,frame=off]

\definestartstop [example]

[before={\starttextbackground[example]},after=\stoptextbackground]

but this does not work. I tried other variants (such as adding state=start, ...) with no success.

Does anyone have suggestions on where to look for further documentation or examples of use?

Thanks.