cleaned up a number of patches; renamed all to the standard -help.pd format; added some more ideas to the style guide; finished up lists_vs_anythings

svn path=/trunk/; revision=2841

1 files changed, 232 insertions, 0 deletions

diff --git a/doc/pddp/trigger-help.pd b/doc/pddp/trigger-help.pd
new file mode 100644
index 00000000..4f150485
--- /dev/null
+++ b/doc/pddp/trigger-help.pd
@@ -0,0 +1,232 @@
+#N canvas 145 60 985 628 10;
+#X obj 26 16 trigger;
+#X text 24 230 As I see it \, the [trigger] object serves two great
+purposes which aren't really related - but they might be on some level
+that I don't fully understand yet.;
+#X text 22 278 1 Sequence a series of bangs - or triggers for symbols
+and/or other messages. In the example below \, you should see that
+it is important that it is important that [metro] gets a tempo setting
+before it is started - but let's assume for a moment that you wanted
+to start the [metro] with only a single click.;
+#X obj 26 481 metro;
+#X msg 51 462 1000;
+#X obj 26 501 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X obj 26 404 tgl 15 0 empty empty On/Off 0 -6 0 7 -262144 -1 -1 0
+1;
+#X text 24 104 The [trigger] object can be abbreviated as "t" and the
+creation arguments can be abbreviated as follows:;
+#X obj 114 150 trigger float bang symbol list pointer anything;
+#X text 215 169 is the same as;
+#X obj 218 189 t f b s l p a;
+#X obj 26 422 t f b;
+#X text 27 526 This example is simple \, and may not be very practicle
+in most situations \, but it clearly shows how [trigger] can be used
+to create a simple sequence of events. It is important to note however
+that the messages sent from [trigger]'s outlets occur in ZERO time
+with no delay between the events...more at the top right of the page...
+;
+#X obj 484 94 t b b;
+#X msg 484 75 bang;
+#X obj 484 124 timer;
+#X floatatom 484 144 5 0 0 0 - - -;
+#X obj 456 34 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X obj 456 600 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X text 518 75 Click here.;
+#X text 524 141 Watch here.;
+#X text 476 163 Now \, to prove that I'm not crazy...click here >;
+#X obj 822 203 timer;
+#X floatatom 822 222 5 0 0 0 - - -;
+#X obj 847 182 delay 2000;
+#X text 597 89 any delay between the first bang and the second bang
+;
+#X text 598 105 from the trigger.;
+#X text 476 198 object to force a 2 second delay between the;
+#X text 599 75 In this case \, the [timer] object does not perceive
+;
+#X text 471 290 2 Click this subpatch to read about [trigger]'s second
+great purpose...;
+#N canvas 148 22 927 612 trigger_can_convert_data_types 0;
+#X msg 425 103 2.5;
+#X msg 523 103 bang;
+#X msg 465 103 23 64;
+#X msg 569 103 symbol dog;
+#X obj 425 228 trigger float bang symbol list anything;
+#X text 24 24 All sophisticated programming environments provide tools
+to convert data types. For instance \, Visual Basic has:;
+#X text 24 55 - VarType: to check the data type.;
+#X text 24 70 - CStr: to convert a variable to a string.;
+#X text 23 84 - CDate: to convert a variable to a date.;
+#X text 24 99 - isNumeric: to test whether the variable is a number.
+;
+#X text 22 113 - etc.;
+#X text 19 137 [trigger] is one object in Pd which can convert an incoming
+atom to a different type of atom.;
+#X text 422 30 In the example below \, you can see that this [trigger]
+has creation arguments which specify what data type the object should
+output through each outlet. Messages which are sent to the first outlet
+will be floats \; the second outlet will send bangs \; the third \,
+symbols \; etc.;
+#X text 19 172 To prove this \, click on each of the messages below
+and watch your terminal window for the output.;
+#X obj 20 239 t b;
+#X msg 20 210 bang;
+#X msg 57 210 1;
+#X floatatom 90 212 5 0 0 0 - - -;
+#X msg 132 211 symbol cat;
+#X msg 204 211 this is anything;
+#X obj 20 259 print all_messages_are_converted_to_bangs;
+#X text 20 292 Another example showing floats and symbols.;
+#X msg 20 308 bang;
+#X floatatom 90 310 5 0 0 0 - - -;
+#X msg 132 309 symbol cat;
+#X msg 206 319 this is anything;
+#X obj 20 337 t f s;
+#X msg 57 308 1 0;
+#X obj 45 387 print converted_to_symbols;
+#X obj 20 407 print converted_to_floats;
+#X text 62 338 Note that "this is anything" causes an error. That is
+because 'anythings' don't conform to floats \, symbols \, lists \,
+pointers. They can only be converted to "bang".;
+#X text 18 430 In the example above \, note that the trigger object
+does not split a list among the outlets like [unpack] does. Instead
+it sends all list elements through all outlets and converts them as
+necessary.;
+#X text 20 486 Also note that some messages don't convert as nicely
+as others. Hence \, the symbol "cat" converts to a ZERO when [trigger]
+converts that symbol into a float. Likewise \, all numbers will convert
+to a symbol called "float" when sent through [trigger]'s right-most
+outlet.;
+#X floatatom 425 248 5 0 0 0 - - -;
+#X obj 482 248 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X symbolatom 539 286 10 0 0 0 - - -;
+#X floatatom 594 162 5 0 0 0 - - -;
+#X obj 594 200 pack f s;
+#X msg 637 161 symbol earth;
+#X msg 652 181 symbol jupiter;
+#X obj 596 267 print a_list;
+#X floatatom 426 403 5 0 0 0 - - -;
+#X symbolatom 470 403 10 0 0 0 - - -;
+#X obj 514 421 print another_list;
+#X text 630 131 Click on all these.;
+#X obj 426 363 r anythings;
+#X text 425 303 Note how each of the messages sent to this trigger
+are converted appropriately for their receiving atoms boxes. Also note
+that "anythings" are sent to the example below.;
+#X text 430 447 I'e used the [route] object to show how "anythings"
+are converted as they pass through the above [trigger]. Note that all
+messages converted to floats are displayed here in the number box \,
+all symbols are displayed in the symbol box \, and all lists are printed
+to the terminal window.;
+#X obj 654 247 s anythings;
+#X obj 426 383 route float symbol list;
+#X msg 642 103 symbol cat;
+#X connect 0 0 4 0;
+#X connect 1 0 4 0;
+#X connect 2 0 4 0;
+#X connect 3 0 4 0;
+#X connect 4 0 33 0;
+#X connect 4 1 34 0;
+#X connect 4 2 35 0;
+#X connect 4 3 40 0;
+#X connect 4 4 48 0;
+#X connect 14 0 20 0;
+#X connect 15 0 14 0;
+#X connect 16 0 14 0;
+#X connect 17 0 14 0;
+#X connect 18 0 14 0;
+#X connect 19 0 14 0;
+#X connect 22 0 26 0;
+#X connect 23 0 26 0;
+#X connect 24 0 26 0;
+#X connect 25 0 26 0;
+#X connect 26 0 29 0;
+#X connect 26 1 28 0;
+#X connect 27 0 26 0;
+#X connect 36 0 37 0;
+#X connect 37 0 4 0;
+#X connect 38 0 37 1;
+#X connect 39 0 37 1;
+#X connect 45 0 49 0;
+#X connect 49 0 41 0;
+#X connect 49 1 42 0;
+#X connect 49 2 43 0;
+#X connect 50 0 4 0;
+#X restore 475 325 pd trigger_can_convert_data_types;
+#X obj 822 238 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X floatatom 902 164 5 0 0 0 - - -;
+#X text 477 246 at the top-right to clearly see "logical time";
+#X text 477 259 as measured by [timer].;
+#X text 509 554 This document was updated for Pd version 0.35 test
+26 by Dave Sabine as part of a project called pddp proposed by Krzysztof
+Czaja to build comprehensive documentation for Pd.;
+#X text 472 378 RELATED OBJECTS;
+#X obj 557 404 route;
+#X obj 477 404 unpack;
+#X obj 523 404 pack;
+#X obj 598 404 delay;
+#X obj 640 404 pipe;
+#X obj 675 404 float;
+#X obj 715 404 int;
+#X obj 744 404 symbol;
+#N canvas 0 22 456 306 related_objects_from_other_libraries 0;
+#X obj 31 36 exciter 200 200 8 0.1 1 1;
+#X text 26 77 These objects are offered in Pd only if you have downloaded
+and properly installed the appropriate library. These objects may or
+may not exist in a single library.;
+#X text 25 126 The best places to find information about Pd's libraries
+is:;
+#X text 22 148 www.puredata.org and click on "Downloads" then "Software"
+;
+#X text 24 163 or;
+#X text 24 178 iem.kug.ac.at/pdb/;
+#X restore 477 435 pd related_objects_from_other_libraries;
+#X obj 940 5 pddp;
+#X text 472 463 MORE INFO;
+#X obj 479 490 pddp_open all_about_data_types;
+#X obj 480 516 pddp_open all_about_lists_vs_anythings;
+#X obj 822 157 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X text 17 138 "float" = f;
+#X text 17 150 "bang" = b;
+#X text 16 162 "symbol" = s;
+#X text 17 176 "list" = l;
+#X text 17 204 "anything" = a;
+#X text 17 190 "pointer" = p;
+#X text 26 45 The [trigger] object outputs its input from right to
+left \, converting to the types indicated by its creation arguments.
+There is also a "pointer" argument type (see the [pointer] object.)
+;
+#X text 20 364 Click the toggle to set the tempo and start the [metro]
+simultaneously.;
+#X text 67 413 Triggers are sent from right to left...so our tempo
+messages gets sent to [metro] immediately before the numbers from the
+toggle to start and stop the [metro].;
+#X text 482 40 Below is a simple structure which will measure the "logical
+time" between "bangs" from the [trigger] object.;
+#X text 477 184 In this case \, I've simply patched a [delay];
+#X text 476 212 first and second "bangs" sent to the [timer].;
+#X text 477 232 You can reset the [delay] with the number box;
+#X text 86 15 - sequence messages in right-to-left order and convert
+data;
+#X text 503 15 types;
+#X connect 3 0 5 0;
+#X connect 4 0 3 1;
+#X connect 6 0 11 0;
+#X connect 11 0 3 0;
+#X connect 11 1 4 0;
+#X connect 13 0 15 1;
+#X connect 13 1 15 0;
+#X connect 14 0 13 0;
+#X connect 15 0 16 0;
+#X connect 17 0 18 0;
+#X connect 22 0 23 0;
+#X connect 23 0 31 0;
+#X connect 24 0 22 1;
+#X connect 32 0 24 1;
+#X connect 50 0 24 0;
+#X connect 50 0 22 0;