This is the file `README.interact' of dednat4.
Author:     Eduardo Ochs <eduardoochs@gmail.com>
Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
Version:    2008jul05
This file is in the Public Domain.
See: http://angg.twu.net/dednat4.html
     http://angg.twu.net/dednat4/README.interact.html
     http://angg.twu.net/dednat4/README.interact
     (find-dn4 "Makefile")



There are two ways to understand the internals of dednat4
"interactively". One way - more obvious, and not so interactive - is
to add small snippets of Lua code to a TeX file and run dednat4 on it.
For example:

rm -Rv /tmp/dn4test/
mkdir  /tmp/dn4test/
cd     /tmp/dn4test/
cat > ee.tex <<'%%%'
%L require "experimental"    -- for "midpoint"
%D diagram T:F->G
%D 2Dx    100   +20  +20
%D 2D 100       A
%D 2D         / - \  
%D 2D        /  |  \
%D 2D       v   v   v
%D 2D +25 FA ------> GA
%D 2D          TA
%L PP(nodes)                 -- Lua code: dump the table `nodes'
%D (( A FA -> A GA ->
%L    PP(ds)                 -- Lua code: dump the table `ds'
%D    FA GA -> .plabel= b TA
%D    A FA GA midpoint |->
%D ))
%D enddiagram
$$\diag{T:F->G}$$
%%%

Then if we run:

  ~/dednat4/dednat4 ee.tex

we get this output, modulo some line breaks that I added by hand to
make it nicer:

  {1={"noden"=1, "tag"="A", "x"=120, "y"=100},
   2={"noden"=2, "tag"="FA", "x"=100, "y"=125},
   3={"noden"=3, "tag"="------>", "x"=120, "y"=125},
   4={"noden"=4, "tag"="GA", "x"=140, "y"=125},
   "------>"={"noden"=3, "tag"="------>", "x"=120, "y"=125},
   "A"={"noden"=1, "tag"="A", "x"=120, "y"=100},
   "FA"={"noden"=2, "tag"="FA", "x"=100, "y"=125},
   "GA"={"noden"=4, "tag"="GA", "x"=140, "y"=125}}
  {1={"arrown"=2, "from"=1, "shape"="->", "to"=4},
   2={"noden"=4, "tag"="GA", "x"=140, "y"=125},
   3={"noden"=1, "tag"="A", "x"=120, "y"=100},
   4={"arrown"=1, "from"=1, "shape"="->", "to"=2},
   5={"noden"=2, "tag"="FA", "x"=100, "y"=125},
   6={"noden"=1, "tag"="A", "x"=120, "y"=100}}

The "PP" function is defined in edrxlib.lua. See:
  (find-dn4 "edrxlib.lua" "PP")
  <http://angg.twu.net/dednat4/edrxlib.lua.html#PP>

If we are editing that file "ee.tex" in Emacs, then the following
eev-ism can be used instead of running dednat4 by hand on a shell: put
the sexp hyperlink below somewhere in ee.tex, and execute it with M-e.

  % (find-sh "~/dednat4/dednat4 ee.tex")



Running dednat4 from the Lua command line
=========================================

When dednat4.lua sees that it has been called with no command-line
arguments at all - not even arg[0], that usually says where the
dednat4 script was read from - it deduces that it has been invoked
from a Lua interpreter in interactive mode, and behaves in a special
way. For example:


/home/edrx/dednat4(edrx:de)# lua51
Lua 5.1.3  Copyright (C) 1994-2008 Lua.org, PUC-Rio
> dofile "dednat4.lua"
Loaded: dednat4.lua
> 
> dolinenumbers = nil
> mytostringk = mytostringk2
> 
> dofs "diagram miniadj2"
> dofs "2Dx      100   140 "
> dofs "2D  140 a^L <= a   "
> dofs "2D       -     -   "
> dofs "2D       |     |   "
> dofs "2D       v     v   "
> dofs "2D  100  b => b^R  "
> dofs "(( a^L a <=   a^L b |->   a b^R |->"
> 
> printf("xs = %s\n", mytostring(xs))
xs = {9=100, 15=140}
> for i=1,#nodes  do printf("nodes[%d] = %s\n",  i, mytostring(nodes[i]))  end
nodes[1] = {noden=1, tag="a^L", x=100, y=140}
nodes[2] = {noden=2, tag="a", x=140, y=140}
nodes[3] = {noden=3, tag="b", x=100, y=100}
nodes[4] = {noden=4, tag="b^R", x=140, y=100}
> for i=1,#arrows do printf("arrows[%d] = %s\n", i, mytostring(arrows[i])) end
arrows[1] = {arrown=1, from=1, shape="<=", to=2}
arrows[2] = {arrown=2, from=1, shape="|->", to=3}
arrows[3] = {arrown=3, from=2, shape="|->", to=4}
> for i=1,#ds     do printf("ds[%d] = %s\n",     i, mytostring(ds[i]))     end
ds[1] = {arrown=3, from=2, shape="|->", to=4}
ds[2] = {noden=4, tag="b^R", x=140, y=100}
ds[3] = {noden=2, tag="a", x=140, y=140}
ds[4] = {arrown=2, from=1, shape="|->", to=3}
ds[5] = {noden=3, tag="b", x=100, y=100}
ds[6] = {noden=1, tag="a^L", x=100, y=140}
ds[7] = {arrown=1, from=1, shape="<=", to=2}
ds[8] = {noden=2, tag="a", x=140, y=140}
ds[9] = {noden=1, tag="a^L", x=100, y=140}
> for i=1,#depths do printf("depths[%d] = %s\n", i, mytostring(depths[i])) end
depths[1] = 0
> PP(keys(nodes))
 {1=1, 2=2, 3=3, 4=4, 5="a^L", 6="b^R", 7="a", 8="b"}
> 
> dofs "   b b^R => ))"
> dofs "enddiagram"
\defdiag{miniadj2}{
  \morphism(0,-600)/<=/<600,0>[{a^L}`{a};{}]
  \morphism(0,-600)/|->/<0,600>[{a^L}`{b};{}]
  \morphism(600,-600)/|->/<0,600>[{a}`{b^R};{}]
  \morphism(0,0)/=>/<600,0>[{b}`{b^R};{}]
}
> 


[I need to write much more about this...]


The elements of ds are stored in the wrong order
================================================

Note: due to a bad design decision the elements of ds are "in the
wrong order" - to push a new element we move the old elements from the
positions 1..n to 2..n+1, and then we set ds[1] to the new element...
this simplifies accessing the elements at the top of the stack, but
complicates all the rest - especially "@" and operations with the
array "depths".



See:
  (find-es "dednat" "eepitch-dednat4")