2021-03-05 11:16:00

10 files changed, 331 insertions, 25 deletions

diff --git a/doc/context/scripts/mkiv/context.html b/doc/context/scripts/mkiv/context.html
index 808da3209..682b8621f 100644
--- a/doc/context/scripts/mkiv/context.html
+++ b/doc/context/scripts/mkiv/context.html
@@ -76,6 +76,8 @@
         <tr><th>--arrange</th><td></td><td>run extra imposition pass, given that the style sets up imposition</td></tr>
         <tr><th>--noarrange</th><td></td><td>ignore imposition specifications in the style</td></tr>
         <tr><th/><td/><td/></tr>
+        <tr><th>--pages</th><td></td><td>report pagenumbers of names pages and list references (--page=... or --page=...)</td></tr>
+        <tr><th/><td/><td/></tr>
         <tr><th>--jit</th><td></td><td>use luajittex with jit turned off (only use the faster virtual machine)</td></tr>
         <tr><th>--jiton</th><td></td><td>use luajittex with jit turned on (in most cases not faster, even slower)</td></tr>
         <tr><th/><td/><td/></tr>
diff --git a/doc/context/scripts/mkiv/context.man b/doc/context/scripts/mkiv/context.man
index 99c0c42aa..7d9e949bb 100644
--- a/doc/context/scripts/mkiv/context.man
+++ b/doc/context/scripts/mkiv/context.man
@@ -101,6 +101,9 @@ run extra imposition pass, given that the style sets up imposition
 .B --noarrange
 ignore imposition specifications in the style
 .TP
+.B --pages
+report pagenumbers of names pages and list references (--page=... or --page=...)
+.TP
 .B --jit
 use luajittex with jit turned off (only use the faster virtual machine)
 .TP
diff --git a/doc/context/scripts/mkiv/context.xml b/doc/context/scripts/mkiv/context.xml
index 40751c613..98a75244b 100644
--- a/doc/context/scripts/mkiv/context.xml
+++ b/doc/context/scripts/mkiv/context.xml
@@ -112,6 +112,11 @@
                 </flag>
             </subcategory>
             <subcategory>
+                <flag name="pages">
+                    <short>report pagenumbers of names pages and list references (<ref name="page"/>=... or <ref name="page"/>=...)</short>
+                </flag>
+            </subcategory>
+            <subcategory>
                 <flag name="jit">
                     <short>use luajittex with jit turned off (only use the faster virtual machine)</short>
                 </flag>
diff --git a/doc/context/scripts/mkiv/mtx-context.html b/doc/context/scripts/mkiv/mtx-context.html
index 808da3209..682b8621f 100644
--- a/doc/context/scripts/mkiv/mtx-context.html
+++ b/doc/context/scripts/mkiv/mtx-context.html
@@ -76,6 +76,8 @@
         <tr><th>--arrange</th><td></td><td>run extra imposition pass, given that the style sets up imposition</td></tr>
         <tr><th>--noarrange</th><td></td><td>ignore imposition specifications in the style</td></tr>
         <tr><th/><td/><td/></tr>
+        <tr><th>--pages</th><td></td><td>report pagenumbers of names pages and list references (--page=... or --page=...)</td></tr>
+        <tr><th/><td/><td/></tr>
         <tr><th>--jit</th><td></td><td>use luajittex with jit turned off (only use the faster virtual machine)</td></tr>
         <tr><th>--jiton</th><td></td><td>use luajittex with jit turned on (in most cases not faster, even slower)</td></tr>
         <tr><th/><td/><td/></tr>
diff --git a/doc/context/scripts/mkiv/mtx-context.man b/doc/context/scripts/mkiv/mtx-context.man
index 99c0c42aa..7d9e949bb 100644
--- a/doc/context/scripts/mkiv/mtx-context.man
+++ b/doc/context/scripts/mkiv/mtx-context.man
@@ -101,6 +101,9 @@ run extra imposition pass, given that the style sets up imposition
 .B --noarrange
 ignore imposition specifications in the style
 .TP
+.B --pages
+report pagenumbers of names pages and list references (--page=... or --page=...)
+.TP
 .B --jit
 use luajittex with jit turned off (only use the faster virtual machine)
 .TP
diff --git a/doc/context/scripts/mkiv/mtx-context.xml b/doc/context/scripts/mkiv/mtx-context.xml
index 40751c613..98a75244b 100644
--- a/doc/context/scripts/mkiv/mtx-context.xml
+++ b/doc/context/scripts/mkiv/mtx-context.xml
@@ -112,6 +112,11 @@
                 </flag>
             </subcategory>
             <subcategory>
+                <flag name="pages">
+                    <short>report pagenumbers of names pages and list references (<ref name="page"/>=... or <ref name="page"/>=...)</short>
+                </flag>
+            </subcategory>
+            <subcategory>
                 <flag name="jit">
                     <short>use luajittex with jit turned off (only use the faster virtual machine)</short>
                 </flag>
diff --git a/doc/context/sources/general/manuals/metafun/metafun-basics.tex b/doc/context/sources/general/manuals/metafun/metafun-basics.tex
index 92d2f2c07..479f39602 100644
--- a/doc/context/sources/general/manuals/metafun/metafun-basics.tex
+++ b/doc/context/sources/general/manuals/metafun/metafun-basics.tex
@@ -51,8 +51,8 @@ wish, your comments, your grocery list, whatever. Comments in \METAPOST, prefixe
 by a percent sign, as in \typ {% Let's draw a circle}, are ignored by the
 interpreter, but useful reminders for the programmer.
 
-If the file is saved as \type {yourfile.mp}, then the file is processed by
-\METAPOST\ by issuing the following command:
+Traditionally, if the file is saved as \type {yourfile.mp}, then the file is
+processed by \METAPOST\ by issuing the following command:
 
 \starttyping
 mpost yourfile
@@ -88,7 +88,7 @@ If you have installed \CONTEXT, somewhere on your system there resides a file
 following line at the top of your file:
 
 \starttyping
-input mp-tool ; % or input metafun ;
+input metafun ;
 \stoptyping
 
 By loading this file, the resulting graphic will provide a high resolution
@@ -96,10 +96,44 @@ bounding box, which enables more accurate placement. The file also sets the \typ
 {prologues := 1} so that viewers like \GHOSTVIEW\ can refresh the file when it is
 changed.
 
+{\bf However!} When you use \METAPOST\ in \CONTEXT, you will not run the
+mentioned program at all: you embed your graphic in the document and we will
+discuss this later. You can still use separate files but then you process them as
+follows:
+
+\starttyping
+mtxrun --script metapost somefile.mp
+\stoptyping
+
+Alternatively you can wrap the individual pictures in a \TEX\ file, say \type
+{yourfile.tex}:
+
+\starttyping
+\starttext
+    \startMPpage
+        % code
+    \stopMPpage
+    \startMPpage
+        % code
+    \stopMPpage
+\stoptext
+\stoptyping
+
+and then run:
+
+\starttyping
+context somefile.tex
+\stoptyping
+
+after which you can use the resulting \PDF\ file (if it has more pages you just
+filter the page from that file).
+
 Next we will introduce some more \METAPOST\ commands. From now on, we will omit
 the encapsulating \type {beginfig} and \type {endfig} macros. If you want to
 process these examples yourself, you should add those commands yourself, or if
-you use \CONTEXT\ you don't need them at all.
+you use \CONTEXT\ you don't need them at all. You can for instance wrap them in a
+\type {\startMPpage} \unknown\ \type {\stopMPpage} environment if you want to
+play around.
 
 \startbuffer
 pickup pencircle scaled .5cm ;
@@ -3377,7 +3411,43 @@ context("%3!texexp!",     10.4698E30,"@2.3f","@2i")
 
 \typebuffer
 
-This gives: \inlinebuffer .
+This gives: \inlinebuffer . In \in {figure} [fig:formatters] we see some more
+formatters.
+
+\startbuffer
+for i=1 upto 12 :
+    draw
+        thefmttext("\letterpercent 3!date!","month,space,year",2019,i)
+        shifted (0,i *cm / 2);
+    draw
+        thefmttext("@3!date!","month,space,year",2019,i)
+        shifted (4cm,i *cm / 2);
+endfor ;
+
+for i=1 upto 20 :
+    draw
+        thefmttext(decimal i)
+        shifted (1cm,-i/2*cm);
+    draw
+        thefmttext("@!month!",i)
+        shifted (4cm,-i/2*cm);
+    draw
+        thefmttext("@!weekday!",i)
+        shifted (7cm,-i/2*cm);
+    draw
+        thefmttext("@!monthshort!",i)
+        shifted (10cm,-i/2*cm);
+    draw
+        thefmttext("@3!dayoftheweek!",i,1,2018)
+        shifted (13cm,-i/2*cm);
+endfor ;
+\stopbuffer
+
+\typebuffer
+
+\startplacefigure[title=formatters,reference=fig:formatters]
+    \framed{\scale[width=.8\textwidth]{\processMPbuffer}}
+\stopplacefigure
 
 \stopsection
 
@@ -3660,6 +3730,149 @@ We could have said \type {-- hide(a := a shifted point i of p) a} because the
 
 \stopsection
 
+\startsection[title=External files]
+
+You can put code in an external file and load that one when needed. The low level
+command is \type {input}:
+
+\starttyping
+input myfile ;
+input myfile.mp ;
+input myfile.mpiv ;
+input myfile.mpxl ;
+input "myfile.mpxl" ;
+\stoptyping
+
+In \CONTEXT\ we have modules and their name starts with \type {mp-} and the
+suffix can depend on what version you use (\type {mpii}, \type {mpiv}, \type
+{mpxl}) but that will be dealt with automatically.
+
+\starttyping
+loadmodule("mine") ;
+\stoptyping
+
+This will locate \type {mp-mine} with the proper suffix and often a module will
+be set up to be loaded only once. For loading files \LUAMETAFUN\ provides:
+
+\starttyping
+loadfile("somefile.mp") ;
+\stoptyping
+
+Which is a bit more robust than the \type {input} commands that is kind of fuzzy
+because it takes a sequence of tokens or a string. When you embed code in a
+document source there are some environments that permit loading of definitions
+and extensions.
+
+\starttyping
+\startMPdefinitions
+   % code passed to the library directly
+\stopMPdefinitions
+
+\startMPextensions
+   % code passed to the library but via tex (expansion step)
+\stopMPextensions
+\stoptyping
+
+\stopsection
+
+\startsection[title=Instances]
+
+The library supports several numbering models. The default is \type {scaled} that
+uses integers that represent a (relatively small) float. Although you can go up
+to 32K it's wise to stay below 4096. The \type {double} number model supports 64
+bit floating point and the \type {decimal} model arbitrary precision. In \LUATEX\
+there is also \type {binary} for arbitrary precision but in \LUAMETATEX\ that
+model is not provided.
+
+You can use different models and instances alongside. In \MKIV\ and \LMTX\ we have
+a few predefined. The \type {metafun} instance is the default. Here we show the
+ones that use \METAFUN:
+
+\starttyping[style=\ttx]
+\defineMPinstance[metafun]   [format=metafun,extensions=yes,initializations=yes]
+\defineMPinstance[minifun]   [format=minifun,extensions=yes,initializations=yes]
+\defineMPinstance[extrafun]  [format=metafun,extensions=yes,initializations=yes]
+\defineMPinstance[lessfun]   [format=metafun]
+\defineMPinstance[doublefun] [format=metafun,extensions=yes,initializations=yes,method=double]
+\defineMPinstance[decimalfun][format=metafun,extensions=yes,initializations=yes,method=decimal]
+\defineMPinstance[mprun]     [format=metafun,extensions=yes,initializations=yes]
+\defineMPinstance[simplefun] [format=metafun,method=double] % for internal usage
+\stoptyping
+
+All instances will load additional definitions btu extensions (expanded
+definitions) and initializations (before each graphic) are optional.
+
+\starttyping
+\startMPdefinitions
+\stopMPdefinitions
+
+\startMPextensions
+\stopMPextensions
+
+\startMPinitializations
+\stopMPinitializations
+\stoptyping
+
+You can search the sources of manuals and test suite for examples of usage, but here are
+some:
+
+\startbuffer
+\defineMPinstance[foo][definitions=yes]
+\defineMPinstance[bar][definitions=yes]
+
+\startMPdefinitions{foo}
+    vardef p = image (
+        draw fullsquare scaled 1cm withcolor "darkgreen" ;
+        draw textext("1") ;
+    )
+    enddef ;
+\stopMPdefinitions
+
+\startMPdefinitions{bar}
+    vardef p = image (
+        draw (fullsquare rotated 45) scaled 1cm withcolor "darkyellow" ;
+        draw textext("2") ;
+    )
+    enddef ;
+\stopMPdefinitions
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We use both as:
+
+\startbuffer[demo-1]
+\startMPcode{foo}
+    draw p ;
+    draw image (
+        draw fullcircle scaled 1cm withcolor "darkblue" ;
+        draw textext("3") withcolor "darkred" ;
+    ) ;
+    draw p ;
+\stopMPcode
+\stopbuffer
+
+\startbuffer[demo-2]
+\startMPcode{bar}
+    draw p ;
+    draw image (
+        draw fullcircle scaled 1cm withcolor "darkblue" ;
+        draw textext("4") withcolor "darkred" ;
+    ) ;
+\stopMPcode
+\stopbuffer
+
+\typebuffer[demo-1,demo-2]
+
+\startlinecorrection
+\startcombination[nx=2,ny=1]
+    {\getbuffer[demo-1]} {foo}
+    {\getbuffer[demo-2]} {bar}
+\stopcombination
+\stoplinecorrection
+
+\stopsection
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/metafun/metafun-debugging.tex b/doc/context/sources/general/manuals/metafun/metafun-debugging.tex
index de863aea0..f8957b5d8 100644
--- a/doc/context/sources/general/manuals/metafun/metafun-debugging.tex
+++ b/doc/context/sources/general/manuals/metafun/metafun-debugging.tex
@@ -375,6 +375,80 @@ When we overlay these three we get. The envelope only returns the outer curve.
 \stopoverlay
 \stoplinecorrection
 
+We show a few nore examples and let it to the user to come up with applications
+for this feature. We start by defining a scaled pen that we apply to a simple
+path that has three point.
+
+\startbuffer
+pen whateverpen ; whateverpen := makepen(fullcircle xyscaled(1/20,1/40));
+
+path p ; p := (origin .. (1,1/2) .. (1,1/4)) scaled 10 ;
+path q ; q := envelope whateverpen of p ;
+
+draw              p withpen pencircle xyscaled(1/2,1/4)
+                    withcolor "darkgreen"   withtransparency (1,.5) ;
+drawpoints        p withpen pencircle scaled 1
+                    withcolor "darkgray"    withtransparency (1,.5) ;
+drawcontrolpoints p withpen pencircle scaled 1/2
+                    withcolor "darkmagenta" withtransparency (1,.5) ;
+
+currentpicture := currentpicture shifted (-20,0) ;
+
+draw              p withpen pencircle xyscaled(1/2,1/4)
+                    withcolor "darkgreen"   withtransparency (1,.5) ;
+draw              q withpen pencircle scaled 1/5
+                    withcolor "darkblue"    withtransparency (1,.5) ;
+drawpoints        q withpen pencircle scaled 1
+                    withcolor "darkgray"    withtransparency (1,.5) ;
+drawcontrolpoints q withpen pencircle scaled 1/2
+                    withcolor "darkyellow"  withtransparency (1,.5) ;
+draw              q withpen pencircle scaled 1/50
+                    withcolor "white" ;
+
+currentpicture := currentpicture ysized 2cm ;
+\stopbuffer
+
+\typebuffer
+
+On the left we see the path drawn with a circular pen. The points and control
+points are also shown. The path is repeated on the right but there it gets the
+envelope overlayed. We show the points and control points of the envelope: they
+nearly overlap but that depends of course on the used pen.
+
+\startlinecorrection[blank]
+    \processMPbuffer
+\stoplinecorrection
+
+In order to illustrate that the envelope is an outline we blow up a piece of
+this image:
+
+\startlinecorrection[blank]
+    \scale[height=3cm]{\clip[nx=10,ny=20,x=9,y=7]{\processMPbuffer}}
+\stoplinecorrection
+
+Without further explanation we let you ponder the results of the following code.
+
+\startbuffer
+drawoptions(withcolor "darkred") ;
+draw (envelope pensquare of (up--left)) ;
+draw (up--left) shifted (4,0) withpen pensquare ;
+draw fullcircle shifted (8,0) ;
+draw (envelope pensquare of fullcircle) shifted (12,0) ;
+draw (fullcircle) shifted (16,0) withpen pensquare ;
+draw (fullcircle) shifted (20,0) withpen pencircle ;
+currentpicture := currentpicture xsized TextWidth ;
+\stopbuffer
+
+\typebuffer
+
+The efficiency of the output of each draw differs a lot because circles are made
+from eight points and because a transformed pen results in two paths. Normally
+that is not something you have to loose sleep over.
+
+\startlinecorrection[blank]
+    \processMPbuffer
+\stoplinecorrection
+
 \stopsection
 
 \startsection[title=Performance]
diff --git a/doc/context/sources/general/manuals/metafun/metafun-environment.tex b/doc/context/sources/general/manuals/metafun/metafun-environment.tex
index 20b6920f9..57875008d 100644
--- a/doc/context/sources/general/manuals/metafun/metafun-environment.tex
+++ b/doc/context/sources/general/manuals/metafun/metafun-environment.tex
@@ -342,7 +342,7 @@
 
 \startbuffer[shape-a]
 \startuniqueMPgraphic{meta:hash}{linewidth,linecolor,angle,gap}
-  if unknown context_back : input mp-back ; fi ;
+  loadmodule("back") ;
   some_hash ( OverlayWidth, OverlayHeight ,
               \MPvar{linewidth}, \MPvar{linecolor} ,
               \MPvar{angle}, \MPvar{gap} ) ;
@@ -369,7 +369,7 @@
 
 \startbuffer[symb-a]
 \startuniqueMPgraphic{meta:button}{type,size,linecolor,fillcolor}
-  if unknown context_butt : input mp-butt ; fi ;
+  loadmodule("butt") ;
   some_button ( \MPvar{type},
                 \MPvar{size},
                 \MPvar{linecolor},
diff --git a/doc/context/sources/general/manuals/metafun/metafun-text-lmtx.tex b/doc/context/sources/general/manuals/metafun/metafun-text-lmtx.tex
index bd84f08ec..abdca3c3a 100644
--- a/doc/context/sources/general/manuals/metafun/metafun-text-lmtx.tex
+++ b/doc/context/sources/general/manuals/metafun/metafun-text-lmtx.tex
@@ -1295,7 +1295,7 @@ being an invisible character with maximum dimensions. Variables like \type
 can save variables.
 
 \startbuffer
-\startuseMPgraphic{test 1}
+\startuseMPgraphic{shapetest-1}
   begingroup ;
     save p ; path p ; p := fullcircle scaled 6cm ;
     lmt_parshape [
@@ -1319,7 +1319,7 @@ The second shape is a diamond. This is a rather useless shape, unless the text
 suits the small lines at the top and bottom.
 
 \startbuffer
-\startuseMPgraphic{test 2}
+\startuseMPgraphic{shapetest-2}
   begingroup ;
     save p ; path p ; p := fullsquare rotated 45 scaled 5cm ;
     lmt_parshape [
@@ -1338,7 +1338,7 @@ The third and fourth shape demonstrate that providing a suitable offset is not
 always trivial.
 
 \startbuffer
-\startuseMPgraphic{test 3}
+\startuseMPgraphic{shapetest-3}
   begingroup ;
     save w, h, p ; path p ; w := h := 6cm ;
     p := (.5w,h) -- (   0,  h) -- (0,0) -- (w,0) &
@@ -1360,14 +1360,15 @@ a path, \METAPOST\ is able to calculate the right dimensions and offsets. This i
 needed, since we need these later on.
 
 \startbuffer
-\startuseMPgraphic{test 4}
+\startuseMPgraphic{shapetest-4}
   begingroup ;
-    save d, p, q ; path p, q ; d := BodyFontSize/2;
+    save d, p, q, shape ; path p, q ; d := BodyFontSize/2;
     vardef shape(expr w, h, o) =
         (o,o) -- (w-o,o) & (w-o,o) .. (.75w-o,.5h) ..
         (w-2o,h-o) & (w-2o,h-o) -- (o,h-o) -- cycle
     enddef ;
-    p := shape(6cm, 6cm, d) ; q := shape(6cm, 6cm, 0) ;
+    p := shape(6cm, 6cm, d) ;
+    q := shape(6cm, 6cm, 0) ;
     lmt_parshape [
         path       = p,
         offsetpath = q,
@@ -1386,10 +1387,10 @@ Since we also want these graphics as backgrounds, we define them as overlays. If
 you don't want to show the graphic, you may omit this step.
 
 \startbuffer
-\defineoverlay[test 1][\useMPgraphic{test 1}]
-\defineoverlay[test 2][\useMPgraphic{test 2}]
-\defineoverlay[test 3][\useMPgraphic{test 3}]
-\defineoverlay[test 4][\useMPgraphic{test 4}]
+\defineoverlay[shapetest-1][\useMPgraphic{shapetest-1}]
+\defineoverlay[shapetest-2][\useMPgraphic{shapetest-2}]
+\defineoverlay[shapetest-3][\useMPgraphic{shapetest-3}]
+\defineoverlay[shapetest-4][\useMPgraphic{shapetest-4}]
 \stopbuffer
 
 \typebuffer \getbuffer
@@ -1399,7 +1400,7 @@ Themas, Questing for the Essence of Mind and Pattern}. Watch how we pass a list
 of shapes.
 
 \startbuffer[text]
-\startshapetext[test 1,test 2,test 3,test 4]
+\startshapetext[shapetest-1,shapetest-2,shapetest-3,shapetest-4]
   \forgetall % as it says
   \setupalign[verytolerant,stretch,normal]%
   \samplefile{douglas}% Douglas R. Hofstadter
@@ -1409,17 +1410,15 @@ of shapes.
 \typebuffer[text]
 
 Finally we combine text and shapes. Since we also want a background, we use \type
-{\framed}. The macros \type {\parwidth} and \type {\parheight} are automatically
-set to the current shape dimensions. The normal result is shown in \in {figure}
-[fig:shapes].
+{\framed}. The normal result is shown in \in {figure} [fig:shapes].
 
 \startbuffer[shapes]
 \startbuffer
 \startcombination[2*2]
-  {\framed[offset=overlay,frame=off,background=test 1]{\getshapetext}} {test 1}
-  {\framed[offset=overlay,frame=off,background=test 2]{\getshapetext}} {test 2}
-  {\framed[offset=overlay,frame=off,background=test 3]{\getshapetext}} {test 3}
-  {\framed[offset=overlay,frame=off,background=test 4]{\getshapetext}} {test 4}
+  {\framed[offset=overlay,frame=off,background=shapetest-1]{\getshapetext}} {shapetest-1}
+  {\framed[offset=overlay,frame=off,background=shapetest-2]{\getshapetext}} {shapetest-2}
+  {\framed[offset=overlay,frame=off,background=shapetest-3]{\getshapetext}} {shapetest-3}
+  {\framed[offset=overlay,frame=off,background=shapetest-4]{\getshapetext}} {shapetest-4}
 \stopcombination
 \stopbuffer
 \stopbuffer