Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
This file:
  http://angg.twu.net/dednat5/README.html
                   (find-dn5 "README")
Author:  Eduardo Ochs <eduardoochs@gmail.com>
Version: 2012jun11
License: GPL3


Note: the old documentation, that tried to look like a traditional
README, is below, under the "--snip--"s. This draft-ish,
work-in-progress-ish stuff above the "--snip--"s, has plans to become
both a tutorial and a hands-on hackers guide when it grows up. By the
way, the inspiration for the style comes from the sandboxes at:

  http://angg.twu.net/eev-current/eev-intro.el.html
                       (find-eev "eev-intro.el")
  



The single-file version of dednat5
==================================
The utility "build.lua" glues all modules together in a single file,
"dednat5.lua":

  (find-dn5 "build.lua")
  (find-dn5 "dednat5.lua")

To rebuild it, run the `find-dn5sh' sexp below:

  (find-dn5sh "rm -v dednat5.lua; lua5.1 build.lua && chmod 755 dednat5.lua")

The Makefile can run build.lua too, but by default it will try to
download and compile lua5.1 too, which is bad (this needs to be
changed). See:

  (find-dn5 "Makefile" "dednat5.lua")



The REPL
========
...needs to be rewritten for the nth time, because its logic is too
ugly - but it works. See:

  (find-angg ".emacs" "dednat5")
  (find-dn5 "repl.lua")

* (eepitch-lua51)
* (eepitch-kill)
* (eepitch-lua51)
dofile "repl.lua"
repl()
= 2, 3, 4
= 2, 3 +
 4
= !!!
= (2 +
   3 +
   4)
= (2 +
   3
   + 4)
foo(bar)
print(2, 3)
print(2,
^C
^C
^D





The demos
=========
Dednat5 comes with a directory with several demos (a.k.a. tests):

  (find-dn5 "tests/")
  (find-dn5 "tests/Makefile")

**This one is missing**, and I need to recover it from backups:

  (find-dn5 "tests/Makefile" "testrepl")







LuaTeX
======
LuaTeX works only in utf-8 mode (ok, not really: it supports latin-1,
but with a hack that is hard to use), and I use glyphs with evil char
codes a lot, so at this moment I am not supporting LuaTeX - neither
using it myself. Maybe later.

  (find-es "luatex")







--snip--snip--


Some documentation
==================
The URL:

  http://angg.twu.net/dednat4.html
            (find-TH "dednat4")

has an overview of the previous version - dednat5 is a rewrite of
dednat4 - and has several nice figures and blocks of code; it also has
some sections about dednat5, so it's a good starting point. Please
start by reading it! The documentation of dednat5 is very preliminary
at the moment, to say the least... 8-\



The single-file version of dednat5
==================================
The utility "build.lua" glues all modules together in a single file,
"dednat5.lua":

  (find-dn5 "build.lua")
  (find-dn5 "dednat5.lua")

You only need the file dednat5.lua and the Lua interpreter to use
dednat5. This should make it easy to run dednat5 in M$ Windows, but I
know too little about W$ to try that myself.



Running it
==========
If you run, say,

  dednat5.lua foo.tex

this will produce a file foo.dnt; you can then run:

  latex foo.tex

and then you'll be done - but that "foo.tex" needs to be written
correctly for things to work. Such a "foo.tex" should have a line like

  \input foo.dnt

at some point between the "\documentclass" and the "\begin{document}";
it needs to be before "\begin{document}" because it contains lines
like:

  \usepackage{proof}   % For derivation trees ("%:" lines)

and "\usepackage" can't be used after "\begin{document}".
Here's an example of a ".tex" file and the corresponding ".dnt":

  (find-dn5 "tests/test1.tex")
  (find-dn5 "tests/test1.dnt")



LaTeX packages you'll need
==========================
You will need to have these latex packages installed:

  http://research.nii.ac.jp/~tatsuta/proof-sty.html
  http://www.dante.de/CTAN/help/Catalogue/entries/diagxy.html

In Debian "proof.sty" is in the package "texlive-math-extra" and
"diagxy.tex" is in "texlive-generic-extra". You will also need
MetaPost for one of the demos; it is in "texlive-metapost". So do:

  sudo apt-get install texlive-math-extra
  sudo apt-get install texlive-generic-extra
  sudo apt-get install texlive-metapost



The (basic) modules
===================
If you want to play with the individual modules of dednat5 then it is
better to fetch the tarball, from:

  http://angg.twu.net/dednat5/dednat5.tgz

Each module has a section containing tests, that are not copied to the
single-file version (dednat5.lua). (I need to document how to run the
tests...)

There are four low-level modules, all independent:
  (find-dn5 "common.lua")
  (find-dn5 "eoo.lua")
  (find-dn5 "parse.lua")
  (find-dn5 "prefixes.lua")

These modules control how the ".tex" file is read and processed, and
how the ".dnt" file is written:
  (find-dn5 "process.lua")
  (find-dn5 "preamble.lua")
  (find-dn5 "options.lua")

  (find-dn5 "treetex.lua")
  (find-dn5 "treesegs.lua")
  (find-dn5 "treehead.lua")

  (find-dn5 "diagstacks.lua")
  (find-dn5 "diagtex.lua")
  (find-dn5 "diagforth.lua")



The MetaPost module
===================
...is not a module yet. Take a look at:

  (find-dn5 "tests/test2.tex" "metapost-head")
  (find-dn5 "tests/test2.mp")

to see how the support for MetaPost (i.e., for "%M" lines) is
implemented in less than 10 lines of Lua. Producing the pdf is harder,
though:

  (find-dn5 "tests/Makefile" "test2")

To compare the input with the output, use these links:

  (find-dn5 "tests/test2.tex" "metapost-diagram")
  (find-dn5 "tests/test2.mp"  "metapost-diagram")
  http://angg.twu.net/dednat5/tests/test2.pdf

Here are some links about MetaPost:

  http://www.tug.org/metapost.html
  http://tex.loria.fr/prod-graph/zoonekynd/metapost/metapost.html






Extensions (some undocumented, some just planned)
=================================================
A way to put subdiagrams in nodes:
  (find-LATEX "2011ebl-slides.tex" "BOX")

Begriffsschrift notation:
  (find-dn5 "begriff.lua")
  (find-dn5 "tests/testbegr.tex")

A command-line interface (a REPL), for hacking and debugging:
  (find-dn5 "repl.lua")





Some Emacs tools
================
...that need to be ported from dednat4 to dednat5:
  (find-angg ".emacs-tex.el" "diagskel")
  (find-angg ".emacs-tex.el" "dednames")
  (find-dn4 "dednames.lua")

I am writing a minimal version of eev tailored to be used with
dednat5:

  (find-dn5 "dednat-eev.el")

but it is not ready yet.



If you are interested
=====================
...Then get in touch! Questions and encouragement will certainly make
me hurry up 8-). I'm <eduardoochs@gmail.com>, and if you don't mind
making your questions public then please use the eev mailing list:

  http://lists.gnu.org/archive/html/eev/       (archives)
  http://lists.nongnu.org/mailman/listinfo/eev (subscription)
  http://news.gmane.org/gmane.emacs.eev.devel  (gmane interface)

(I haven't even announced dednat5 there yet...)



Update
======

The current build.lua does not build a minimal dednat5.lua anymore -
it builds a huge beast with all the experimental modules built in!

It need



Notes for myself
================
* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
cd ~/dednat5/
# (find-dn5 "Makefile")
# (find-dn5 "tests/Makefile")
make S=$S tgz
touch preamble.lua
make S=$S tgz
make S=$S cleantests
make S=$S cleandednat5
make S=$S test

make S=$S veryveryclean
make S=$S test
make S=$S tgz

make S=$S veryveryclean
make S=$S tgz
make S=$S test

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
# (find-dn5 "Makefile")
# (find-dn5 "tests/Makefile")
cd ~/dednat5/
make veryveryclean
make S=$S LUA51_=$(which lua5.1) tgz
make S=$S LUA51_=$(which lua5.1) test
# (find-blogme3file "anggmake.lua" "dednat5.tgz")

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
rm -Rv /tmp/dn5/
mkdir  /tmp/dn5/
cd     /tmp/dn5/
tar -xvzf ~/dednat5/dednat5.tgz
make veryveryclean
make S=$S LUA51_=$(which lua5.1) tgz


# Announcements:
# http://article.gmane.org/gmane.comp.lang.lua.general/78408
# http://lua-users.org/lists/lua-l/2011-04/msg00926.html




-- Local Variables:
-- coding:             raw-text-unix
-- ee-anchor-format:   "«%s»"
-- End: