add docs

svn path=/trunk/externals/tclpd/; revision=12335

4 files changed, 124 insertions, 4 deletions

diff --git a/AUTHORS b/AUTHORS
new file mode 100644
index 0000000..03b00a3
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,7 @@
+Authors of tclpd.
+
+Federico Ferri <mescalinum@gmail.com>
+
+I'd like to thank also Mathieu Bouchard for sharing its knowledge and giving
+advices, thus contributing to this project.
+
diff --git a/COPYING b/COPYING
index 2128a66..f47bd6d 100644
--- a/COPYING
+++ b/COPYING
@@ -55,7 +55,7 @@ patent must be licensed for everyone's free use or not licensed at all.
 

   The precise terms and conditions for copying, distribution and

 modification follow.

-

+

 		    GNU GENERAL PUBLIC LICENSE

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

 

@@ -110,7 +110,7 @@ above, provided that you also meet all of these conditions:
     License.  (Exception: if the Program itself is interactive but

     does not normally print such an announcement, your work based on

     the Program is not required to print an announcement.)

-

+

 These requirements apply to the modified work as a whole.  If

 identifiable sections of that work are not derived from the Program,

 and can be reasonably considered independent and separate works in

@@ -168,7 +168,7 @@ access to copy from a designated place, then offering equivalent
 access to copy the source code from the same place counts as

 distribution of the source code, even though third parties are not

 compelled to copy the source along with the object code.

-

+

   4. You may not copy, modify, sublicense, or distribute the Program

 except as expressly provided under this License.  Any attempt

 otherwise to copy, modify, sublicense or distribute the Program is

@@ -225,7 +225,7 @@ impose that choice.
 

 This section is intended to make thoroughly clear what is believed to

 be a consequence of the rest of this License.

-

+

   8. If the distribution and/or use of the Program is restricted in

 certain countries either by patents or by copyrighted interfaces, the

 original copyright holder who places the Program under this License

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..3083f1a
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1 @@
+See README
diff --git a/README b/README
new file mode 100644
index 0000000..0276171
--- /dev/null
+++ b/README
@@ -0,0 +1,112 @@
+
+ Tcl for Pd
+ ==========
+
+This library allows to to write externals for Pd using the Tcl language.
+
+It is based on the standard API of PD (defined in m_pd.h, plus some other
+private header files, like g_canvas.h, s_stuff.h, ...).
+
+Also a library of Tcl helper functions is provided. It is not mandatory to use
+it (moreover: it requires Tcl 8.5, while the tclpd external alone requires only
+Tcl 8.4), but it is a syntactic sugar and can simplify a lot the code.
+Using it is as simple as sourcing pdlib.tcl in your Tcl external.
+
+Anyway, disregarding any approach chosen to develop Tcl externals, a general
+knowledge of Pd internals (atoms, symbols, symbol table, inlets, objects) is
+strongly required. (Pd-External-HOWTO is always a good reading)
+
+
+ Compiling and installing
+ ========================
+
+To compile tclpd, simply type:
+
+  make clean all
+
+To compile it with debug enabled:
+
+  make DEBUG=1 clean all
+
+Requirements are pd >= 0.39, swig, c++ compiler.
+To install tclpd, simply copy it to /usr/lib/pd/extra (or where you installed
+pure-data).
+
+
+ Writing GUI externals
+ =====================
+
+Pd is split into two processes: pd (the core) and pd-gui.
+A simple pd external just runs in the core. A simple Tcl externals still runs
+in the core, because tclpd creates a Tcl interpreter for that.
+
+Instead, pd-gui has its own Tcl interpreter. In order to to GUI things (i.e.
+draw on the canvas, or react to mouse events), the core process needs to
+communicate with the pd-gui process (generally sending Tk commands, or calling
+procedures defined in the pd-gui interp.
+This is done with the sys_gui() function, if using the plain API.
+
+Also pdlib.tcl provide means to simplify this task, with the guiproc function,
+which defines procedures directly into the pd-gui interpreter.
+
+As a counterexample, I'd like to cite tot/toxy/widget externals, which you may
+be familiar with.
+Such externals run in the pd-gui process. That was fine for writing simple gui
+externals, that don't need to react to any message.
+But, for instance, you cannot do a metronome or anything which is timing
+accurate, or heavy IO, as that is not the purpose of the gui process.
+Tclpd instead, by running in the core process, allows that.
+
+
+ Data conversion between Tcl <=> Pd
+ ==================================
+
+In pd exists 'atoms'. An atom is a float, a symbol, a list item, and such.
+Tcl does not have data types. In Tcl everything is a string, also numbers and
+lists. Just when something needs to be read as number, then evaluation comes
+in.
+This leads to loss of information about atom types. Imagine a
+symbol '456' comes into tclpd, you won't know anymore if "456"
+is a symbol or a float.
+
+Here a little convention comes in: in tclpd an atom gets converted into a
+two-item list, where first item is atom type, and second item is its value.
+
+Some examples of this conversion:
+
+ Pd:  456
+ Tcl: {float 456}
+
+ Pd:  symbol foo
+ Tcl: {symbol foo}
+
+ Pd:  list cat dog 123 456 weee
+ Tcl: {{symbol cat} {symbol dog} {float 123} {float 456} {symbol wee}}
+
+
+ Examples
+ ========
+
+I provided small examples.
+after loading pd with option '-lib tcl', just type the filename
+(minus the .tcl extension) to load the Tcl externals examples.
+
+actually there is one simple example: list_change (behaves like
+[change] object, but work with lists only)
+
+examples make use of pdlib.tcl. It's still possible to port the example to use
+only the plain Pd api. Contributions are welcome.
+
+
+ Authors
+ =======
+
+Please refer to AUTHORS file found in tclpd package.
+
+
+ License
+ =======
+
+Please refer to COPYING file found in tclpd package.
+
+