This is the file `README.phantoms' of dednat4.
Author:     Eduardo Ochs <eduardoochs@gmail.com>
Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
Version:    2008jun27
This file is in the Public Domain.
See: http://angg.twu.net/dednat4.html
     http://angg.twu.net/dednat4/README.phantoms.html
     http://angg.twu.net/dednat4/README.phantoms
     (find-dn4ex "edrxmain41.tex")
     (find-dn4ex "edrx08.sty" "experimental.lua")
     (find-dn4 "experimental.lua")



Most of the functions in the file "experimental.lua" - that you can
load with a line like '%L require "experimental"' in the .tex file -
are concerned with tricks involving "phantom nodes".



Midpoints
=========

To draw a diagram like the triangle below,

%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
%D 2D
%D (( A FA |-> A GA |->
%D    FA GA -> .plabel= b TA
%D    A FA GA midpoint
%D      |->
%D ))
%D enddiagram

we use the word "midpoint" to create a "phantom node" halfway between
FA and GA, and then we draw an arrow from A to this phantom node.

If we insert a line like "%L PP(ds)" between "midpoint" and "|->" we
can see how this phantom node is represented internally: by running
dednat4.lua on the file with the "%L PP(ds)" line we get something
like this:

  {1={"TeX"="\\phantom{O}", "noden"=5, "x"=120, "y"=125},
   2={"noden"=1, "tag"="A", "x"=120, "y"=100}, ...
  }

A phantom node doesn't have a "tag" field, so it's impossible to refer
to it by name; it is possible to access the node "A" as 'nodes["A"]'
and as 'nodes[1]', but that phantom node can only be accessed as
'nodes[5]'.

The generated .dnt file will contain something like this:

  \defdiag{T:F->G}{
    \morphism(300,0)/|->/<-300,-375>[{A}`{FA};{}]
    \morphism(300,0)/|->/<300,-375>[{A}`{GA};{}]
    \morphism(0,-375)|b|/->/<600,0>[{FA}`{GA};{TA}]
    \morphism(300,0)/|->/<0,-375>[{A}`{\phantom{O}};{}]
  }

We can redefine "\phantom" temporarily to make the phantom nodes
visible. For example:

$$\diag{T:F->G}
  \qquad
  \def\red#1{{\color{red}#1}}
  \def\phantom{\red}
  \diag{T:F->G}
$$



Harrownodes and varrownodes
===========================

To draw a diagram like the one below, with an arrow pointing from the
left wall of the square to the right wall,

%D diagram harrowdemo
%D 2Dx     100       +40
%D 2D  100 A |-----> FA
%D 2D	   |          -
%D 2D	 f |   |->    | Ff
%D 2D	   v          v
%D 2D  +30 B |-----> FB
%D 2D
%D ((  A FA |->
%D     A  B -> .plabel= l f
%D    FA FB -> .plabel= r Ff
%D     B FB |->
%D    A FB harrownodes nil 20 nil |->
%D ))
%D enddiagram
%D
$$\diag{harrowdemo}$$

we need something better than just:

  A B midpoint FA FB midpoint |->

which would draw an arrow between phantom nodes placed halfway between
A and B and FA and FB.

Here's how the key line, "A FB harrownodes nil 20 nil |->", works.
"harrownodes" takes the two nodes at the top of the stack - A and FB -
and regards them as the opposite corners of a rectangle; it takes the
mean of their "y" coordinates, (100+130)/2 = 115, and uses their "x"
coordinates - 100 and 140 - and the "hints", nil 20 nil, to produce
two phantom nodes in a horizontal line at the middle of the rectangle.
Let's call this horizontal line the "reference line".

The given corners - A and FB - are at (100,100) and (140,130); they
are projected on the reference line, and they become (100,115) and
(140,115); we will call these new nodes the "reference nodes". The "x"
coordinates for the two phantom nodes will be calculated from just the
"x" coordinates of the projected reference nodes, and from the hints.
In this case, the hints mean:

  nil - no extra space at the left
  20 - the (horizontal) distance between the two phantom nodes
  nil - no extra space at the right

The calculation is done by the function "splitdist". It receives
arguments x1 (=100), x2 (=140), dx0 (=nil), dx1 (=20), and dx2 (=nil),
and it returns as results px1 (=110) and px2 (=130). Note that px2-px1
= dx1 = 20, and that (px1+px2)/2 = 120, the midpoint of x1 and x2. If
the hints dx0 or dx2 (or both) were non-nil, they would be used to
shift the midpoint toward x2 or towards x1. The details can be found
at the source, at:

  (find-dn4 "experimental.lua" "splitdist")

(Actually, I use these extra hints so little myself that I don't think
that it's important to explain them now...)

Variations:

varrownodes is like harrownodes, but the phantom nodes are obtained by
projecting the original corners on a vertical line instead of on a
horizontal line.

dharrownodes does not project the original corners - the phantom nodes
are created in the line between the two original corners (and the
reference nodes have the same coordinates as the original corners).
The "h" in the name of this word indicates that the hints are used to
calculate the horizontal coordinates of the phantom nodes from the
horizontal coordinates of the reference nodes - their vertical
coordinates are calculated afterwards, to make them lie on the line
that joins the reference nodes.

dvarrownodes is like dharrownodes, but the hints refer to the vertical
coordinates; the vertical coordinates of the phantom nodes are
calculated first, and their horizontal coordinates are adjusted
afterwards to make them lie on the right line.


Relative phantom nodes
======================

  (find-dn4 "experimental.lua")