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.