% language=us runpath=texruns:manuals/luametafun

\environment luametafun-style

\startcomponent luametafun-text

\startchapter[title={Text}]

\startsection[title={Typesetting text}]

The \METAFUN\ \type {textext} command normally can do the job of typesetting a
text snippet quite well.

\startbuffer
\startMPcode
    fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
    draw textext("\bf This is text A") withcolor "white" ;
\stopMPcode
\stopbuffer

\typebuffer[option=TEX]

We get:

\startlinecorrection
\getbuffer
\stoplinecorrection

You can use regular \CONTEXT\ commands, so this is valid:

\startbuffer
\startMPcode
    fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
    draw textext("\framed{\bf This is text A}") withcolor "white" ;
\stopMPcode
\stopbuffer

\typebuffer[option=TEX]

Of course you can as well draw a frame in \METAPOST\ but the \type {\framed}
command has more options, like alignments.

\startlinecorrection
\getbuffer
\stoplinecorrection

Here is a variant using the \METAFUN\ interface:

\startbuffer
\startMPcode
    fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
    draw lmt_text [
        text  = "This is text A",
        color = "white",
        style = "bold"
    ] ;
\stopMPcode
\stopbuffer

\typebuffer[option=TEX]

The outcome is more or less the same:

\startlinecorrection
\getbuffer
\stoplinecorrection

Here is another example. The \type {format} option is actually why this command
is provided.

\startbuffer
\startMPcode
    fill fullcircle xyscaled (8cm,1cm) withcolor "darkred" ;
    draw lmt_text [
        text   = decimal 123.45678,
        color  = "white",
        style  = "bold",
        format = "@0.3F",
    ] ;
\stopMPcode
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection
\getbuffer
\stoplinecorrection

The following parameters can be set:

\starttabulate[|T|T|T|p|]
\FL
\BC name     \BC type    \BC default \BC comment \NC \NR
\ML
\NC offset   \NC numeric \NC 0       \NC \NC \NR
\NC strut    \NC string  \NC auto    \NC adapts the dimensions to the font (\type {yes} uses the the default strut) \NC \NR
\NC style    \NC string  \NC         \NC \NC \NR
\NC color    \NC string  \NC         \NC \NC \NR
\NC text     \NC string  \NC         \NC \NC \NR
\NC anchor   \NC string  \NC         \NC one of these \type {lft}, \type {urt} like anchors \NC \NR
\NC format   \NC string  \NC         \NC a format specifier using \type {@} instead of a percent sign \NC \NR
\NC position \NC pair    \NC origin  \NC \NC \NR
\NC trace    \NC boolean \NC false   \NC \NC \NR
\LL
\stoptabulate

The next example demonstrates the positioning options:

\startbuffer
\startMPcode
    fill fullcircle xyscaled (8cm,1cm) withcolor "darkblue" ;
    fill fullcircle scaled .5mm withcolor "white" ;
    draw lmt_text [
        text     = "left",
        color    = "white",
        style    = "bold",
        anchor   = "lft",
        position = (-1mm,2mm),
    ] ;
    draw lmt_text [
        text   = "right",
        color  = "white",
        style  = "bold",
        anchor = "rt",
        offset = 3mm,
    ] ;
\stopMPcode
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection
\getbuffer
\stoplinecorrection

\stopsection

\startsection[title=Strings]

Those familiar with \TEX\ probably know that there's something called catcodes.
These are properties that you assign to characters and that gives them some
meaning, like regular letters, other characters, spaces, but also escape
character (the backslash) or math shift (the dollar). Control over catcodes is
what makes for instance verbatim possible.

We show a few possibilities and start by defining a macro:

\startbuffer
\def\foo{x}
\stopbuffer

\typebuffer[option=TEX] \getbuffer

\startbuffer
\framed\bgroup
    \startMPcode
        interim catcoderegime := vrbcatcoderegime ;
        draw textext("stream $\string\foo$") withcolor "darkred" ;
    \stopMPcode
\egroup
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\framed\bgroup
    \startMPcode
        draw textext("stream $\foo$") withcolor "darkblue" ;
    \stopMPcode
\egroup
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\framed\bgroup
    \startMPcode
        interim catcoderegime := vrbcatcoderegime ;
        draw textext(stream "!" $\string\foo$) withcolor "darkgreen" ;
    \stopMPcode
\egroup
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\framed\bgroup
    \startMPcode
        draw textext(stream "!" $\foo$) withcolor "darkyellow" ;
    \stopMPcode
\egroup
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection \getbuffer \stoplinecorrection

\startbuffer
\framed\bgroup
    \startMPcode
        draw textext(\btx stream "!" $\string\foo$\etx) withcolor "darkgreen" ;
    \stopMPcode
\egroup
\stopbuffer

\typebuffer[option=TEX]

\startlinecorrection \getbuffer \stoplinecorrection

The \type {vrbcatcodesregime} switches to a verbatim catcode regime so the dollars
remain dollars. But because we do expand control sequences we have to put \type
{\string} in front.

The (expandable) \type {\btx} and \type {\etx} commands are aliases for the
control characters \type {0x02} and \type {0x03}. These are valid string fences
in \LUAMETATEX's \METAPOST\ and thereby permit embedding of the double quotes.

\stopsection

\stopchapter

\stopcomponent
