revised help docs that conform to the PDDP template

svn path=/trunk/; revision=13942

1 files changed, 234 insertions, 185 deletions

diff --git a/doc/pddp/swap-help.pd b/doc/pddp/swap-help.pd
index b5d83c04..b6b106f4 100644
--- a/doc/pddp/swap-help.pd
+++ b/doc/pddp/swap-help.pd
@@ -1,185 +1,234 @@
-#N canvas 0 0 625 631 12;

-#X obj 104 572 pddp/pddplink http://puredata.info/dev/pddp -text pddp;

-#X obj 8 8 cnv 15 90 586 empty empty empty 20 12 0 14 -233017 -66577

-0;

-#X text 37 47 INLETS:;

-#X obj 54 18 swap;

-#X text 108 18 - SWAP TWO NUMBERS \, RESPECTING RIGHT-TO-LEFT ORDER

-;

-#X obj 285 470 swap;

-#X floatatom 175 429 5 0 0 0 - - -;

-#X floatatom 372 437 5 0 0 0 - - -;

-#X floatatom 312 497 5 0 0 0 - - -;

-#X floatatom 263 497 5 0 0 0 - - -;

-#X msg 243 427 42 7;

-#X obj 119 438 bng 15 250 50 0 empty empty "bang" 0 -6 0 8 -262144

--1 -1;

-#X msg 290 415 42 7 3 4;

-#X floatatom 506 491 5 0 0 0 - - -;

-#X floatatom 454 490 5 0 0 0 - - -;

-#X msg 454 436 bang;

-#X obj 454 460 swap 12;

-#X text 37 62 - LEFT:;

-#X text 28 263 - RIGHT:;

-#X text 104 63 Float - A float at the left inlet will send the number

-to the right outlet and then send the number at the right inlet to

-the left outlet.;

-#X text 104 117 Bang - A bang at the left inlet will force [swap] to

-send its values to the outlets \, in reverse order. The value from

-the left inlet will be sent to the right outlet then the value at the

-right inlet will be sent out the left outlet.;

-#X text 104 188 List - A list at the left inlet will update the values

-of both of [swap]'s inlets and send the numbers to the outlets in reverse

-order. Note that lists of 3 or more elements will be truncated.;

-#X text 104 264 Float - A float at the right inlet is stored for later

-use. It will be sent to the left outlet when a float or bang is received

-in the left inlet.;

-#X text 104 317 One - [swap] accepts a single float as a creation argument

-which initializes the first value to be sent out the left outlet.;

-#X text 104 370 Two - outputs the float values of the two inlets in

-reverse order when a float \, list \, or bang is received at the left

-inlet.;

-#X text 371 418 float;

-#X text 174 410 float;

-#X text 244 409 list;

-#X text 428 510 creation argument;

-#N canvas 59 0 397 246 Related_Objects 0;

-#X text 25 11 Native Pd Objects;

-#X text 23 92 Externals and other object libraries;

-#X obj 42 48 pack;

-#X obj 104 48 unpack;

-#X text 30 126 [split];

-#X restore 104 522 pd Related_Objects;

-#N canvas 60 0 581 620 More_Info 0;

-#X msg 38 54 42 7;

-#X obj 38 79 swap;

-#X floatatom 38 105 5 0 0 0 - - -;

-#X floatatom 97 105 5 0 0 0 - - -;

-#X obj 38 129 pack f f;

-#X obj 38 153 print;

-#N canvas 154 0 649 595 millers_note-off_parser 0;

-#X obj 27 18 notein;

-#X text 103 14 [notein] is an object which receives incoming MIDI data

-from a MIDI instrument. The three outlets are PITCH \, VELOCITY \,

-and MIDI CHANNEL from left to right. It is important to note however

-that the data is outputted from right to left. Which means that the

-first piece of information to be sent out the object is the MIDI CHANNEL.

-;

-#X obj 26 117 swap;

-#X obj 26 156 pack;

-#X obj 26 200 route 0;

-#X floatatom 26 228 5 0 0 0 - - -;

-#X text 102 117 Here \, [swap] is used to store the VELOCITY until

-the PITCH information comes from [notein]. The next step will pack

-the two together...but we have to ensure that [pack] receives the two

-numbers in the correct order: PITCH first \, then VELOCITY. This way

-\, using [route] we can determine whether or not this incoming MIDI

-data is a "note-off" signal (i.e. VELOCITY = 0).;

-#X obj 26 250 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1

--1;

-#X obj 46 312 notein;

-#X obj 47 352 pack;

-#X obj 47 377 route 0;

-#X floatatom 47 402 5 0 0 0 - - -;

-#X obj 47 420 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1

--1;

-#X text 122 308 The goal of the Miller's example at the bottom left

-\, is to retrieve "note-off" signals from [notein]. To do that \, we

-have to test the incoming data for pitches with a velocity of zero.

-To do that \, we are packing up the incoming PITCH and VELOCITY data

-and sending them to [route]...in effect we achieve the following:;

-#X text 98 420 IF velocity = 0 THEN "bang";

-#X text 127 445 In the example above \, the [pack] object will output

-a list as soon as the VELOCITY information comes from [notein]. As

-a result \, the list will be outputted from pack BEFORE the PITCH information

-is retrieved. [swap] is used to solve this problem by making sure that

-the VELOCITY and PITCH are both received before packing them up and

-sending them to the [route] object.;

-#X text 50 248 This will "bang" only when velocity = 0;

-#X text 22 282 THIS IS WHY THE ALTERNATIVE DOESN'T WORK?;

-#X connect 0 0 2 0;

-#X connect 0 1 2 1;

-#X connect 2 0 3 0;

-#X connect 2 1 3 1;

-#X connect 3 0 4 0;

-#X connect 4 0 5 0;

-#X connect 5 0 7 0;

-#X connect 8 0 9 1;

-#X connect 8 1 9 0;

-#X connect 9 0 10 0;

-#X connect 10 0 11 0;

-#X connect 11 0 12 0;

-#X restore 28 569 pd millers_note-off_parser;

-#X floatatom 44 319 5 0 0 0 - - -;

-#X floatatom 94 319 5 0 0 0 - - -;

-#X floatatom 143 319 5 0 0 0 - - -;

-#X floatatom 112 440 5 0 0 0 - - -;

-#X floatatom 161 440 5 0 0 0 - - -;

-#X floatatom 211 440 5 0 0 0 - - -;

-#X msg 37 243 2 2500 9 420;

-#X obj 43 289 unpack f f f f;

-#X floatatom 193 319 5 0 0 0 - - -;

-#X text 14 10 [swap] is most commonly used to change the order of a

-list. This trick is best suited for a PAIR of numbers.;

-#X obj 166 345 swap;

-#X obj 139 370 swap;

-#X obj 112 394 swap;

-#X obj 196 378 swap;

-#X obj 169 403 swap;

-#X obj 228 408 swap;

-#X floatatom 262 440 5 0 0 0 - - -;

-#X text 230 345 This could quickly become ridiculous!;

-#X msg 165 245 1 2 3 4;

-#X msg 254 258 0 200 3333 1111;

-#X text 14 477 In other settings \, the [swap] object is useful as

-a timing mechanism to ensure that two numbers arrive at their destination

-in a particular order. Miller Puckette provided an excellent example

-of [swap] used to build a 'note-off parser'.;

-#X text 14 185 Lists that are longer than two elements could be sorted

-this way \, but the structure quickly becomes unmanageable. It's probably

-better to find an alternative method.;

-#X connect 0 0 1 0;

-#X connect 1 0 2 0;

-#X connect 1 1 3 0;

-#X connect 2 0 4 0;

-#X connect 3 0 4 1;

-#X connect 4 0 5 0;

-#X connect 7 0 19 0;

-#X connect 8 0 18 0;

-#X connect 9 0 17 0;

-#X connect 13 0 14 0;

-#X connect 14 0 7 0;

-#X connect 14 1 8 0;

-#X connect 14 2 9 0;

-#X connect 14 3 15 0;

-#X connect 15 0 17 1;

-#X connect 17 0 18 1;

-#X connect 17 1 20 1;

-#X connect 18 0 19 1;

-#X connect 18 1 20 0;

-#X connect 19 0 10 0;

-#X connect 19 1 21 0;

-#X connect 20 0 21 1;

-#X connect 20 1 22 1;

-#X connect 21 0 11 0;

-#X connect 21 1 22 0;

-#X connect 22 0 12 0;

-#X connect 22 1 23 0;

-#X connect 25 0 14 0;

-#X connect 26 0 14 0;

-#X restore 104 547 pd More_Info;

-#X text 152 573 - Dave Sabine \, November 12 \, 2002;

-#X text 13 317 ARGUMENTS:;

-#X text 29 369 OUTLETS:;

-#X text 20 427 EXAMPLES:;

-#X text 21 522 SEE ALSO:;

-#X connect 5 0 9 0;

-#X connect 5 1 8 0;

-#X connect 6 0 5 0;

-#X connect 7 0 5 1;

-#X connect 10 0 5 0;

-#X connect 11 0 5 0;

-#X connect 12 0 5 0;

-#X connect 15 0 16 0;

-#X connect 16 0 14 0;

-#X connect 16 1 13 0;

+#N canvas 0 0 555 619 10;
+#X obj 0 595 cnv 15 552 21 empty \$0-pddp.cnv.footer empty 20 12 0
+14 -228856 -66577 0;
+#X obj 0 0 cnv 15 552 40 empty \$0-pddp.cnv.header swap 3 12 0 18 -204280
+-1 0;
+#X obj 0 230 cnv 3 550 3 empty \$0-pddp.cnv.inlets inlets 8 12 0 13
+-228856 -1 0;
+#N canvas 52 246 494 357 META 0;
+#X text 12 105 PLATFORM windows macosx gnulinux;
+#X text 12 205 LIBRARY internal;
+#X text 12 245 WEBSITE http://crca.ucsd.edu/~msp/;
+#X text 12 65 LICENSE SIBSD;
+#X text 12 225 AUTHOR Miller Puckette;
+#X text 12 305 HELP_PATCH_AUTHORS Dave Sabine \, November 12 \, 2002
+. Jonathan Wilkes revised the patch to conform to the PDDP template
+for Pd version 0.42.;
+#X text 12 5 GENRE help;
+#X text 12 45 KEYWORDS control float list bang;
+#X text 12 85 DESCRIPTION swap two numbers \, respecting right-to-left
+order;
+#X text 12 25 NAME swap;
+#X text 12 125 INLET_0 float list bang;
+#X text 12 145 INLET_1 float;
+#X text 12 165 OUTLET_0 float;
+#X text 12 185 OUTLET_1 float;
+#X text 12 265 RELEASE_DATE 1997;
+#X text 12 285 RELEASE_VERSION;
+#X restore 500 597 pd META;
+#X obj 0 425 cnv 3 550 3 empty \$0-pddp.cnv.outlets outlets 8 12 0
+13 -228856 -1 0;
+#X obj 0 485 cnv 3 550 3 empty \$0-pddp.cnv.argument arguments 8 12
+0 13 -228856 -1 0;
+#X obj 0 537 cnv 3 550 3 empty \$0-pddp.cnv.more_info more_info 8 12
+0 13 -228856 -1 0;
+#N canvas 86 455 428 136 Related_objects 0;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
+14 -204280 -1 0;
+#X text 8 2 [swap] Related Objects;
+#X text 20 69 Externals and other object libraries;
+#X obj 23 34 pack;
+#X obj 65 34 unpack;
+#X obj 20 89 pddp/helplink cyclone/split;
+#X restore 102 597 pd Related_objects;
+#X obj 78 239 cnv 17 3 135 empty \$0-pddp.cnv.let.0 0 5 9 0 16 -228856
+-162280 0;
+#X text 98 433 float;
+#X obj 78 434 cnv 17 3 17 empty \$0-pddp.cnv.let.0 0 5 9 0 16 -228856
+-162280 0;
+#X obj 78 380 cnv 17 3 35 empty \$0-pddp.cnv.let.1 1 5 9 0 16 -228856
+-162280 0;
+#X text 98 379 float;
+#X obj 493 3 swap;
+#X obj 465 20 pddp/pddplink http://wiki.puredata.info/en/swap -text
+pdpedia: swap;
+#X text 98 288 float;
+#X text 168 288 - a float at the left inlet will send the number to
+the right outlet and then send the number at the right inlet to the
+left outlet.;
+#X text 98 239 bang;
+#X text 168 239 - a bang at the left inlet will force [swap] to send
+its values to the outlets \, in reverse order. The value from the left
+inlet will be sent to the right outlet then the value at the right
+inlet will be sent out the left outlet.;
+#X text 98 329 list;
+#X text 168 329 - a list at the left inlet will update the values of
+both of [swap]'s inlets and send the numbers to the outlets in reverse
+order. Note that lists of 3 or more elements will be truncated.;
+#X text 167 379 - a float at the right inlet is stored for later use.
+It will be sent to the left outlet when a float or bang is received
+in the left inlet.;
+#X text 98 456 float;
+#X obj 78 457 cnv 17 3 17 empty \$0-pddp.cnv.let.1 1 5 9 0 16 -228856
+-162280 0;
+#X obj 78 152 swap;
+#X floatatom 106 79 5 0 0 0 - - -;
+#X floatatom 190 119 5 0 0 0 - - -;
+#X floatatom 118 179 5 0 0 0 - - -;
+#X floatatom 78 179 5 0 0 0 - - -;
+#X msg 149 78 42 7;
+#X obj 78 77 bng 15 250 50 0 empty empty empty 0 -6 0 10 -262144 -1
+-1;
+#X msg 191 78 42 7 3 4;
+#X floatatom 333 143 5 0 0 0 - - -;
+#X floatatom 294 142 5 0 0 0 - - -;
+#X msg 294 88 bang;
+#X obj 294 112 swap 12;
+#X text 188 102 float;
+#X text 103 60 float;
+#X text 150 60 list;
+#X text 286 162 creation argument;
+#N canvas 90 38 428 503 More_Info 0;
+#X msg 42 82 42 7;
+#X obj 42 107 swap;
+#X floatatom 42 133 5 0 0 0 - - -;
+#X floatatom 101 133 5 0 0 0 - - -;
+#X obj 42 157 pack f f;
+#X obj 42 181 print;
+#X floatatom 43 347 5 0 0 0 - - -;
+#X floatatom 93 347 5 0 0 0 - - -;
+#X floatatom 142 347 5 0 0 0 - - -;
+#X floatatom 111 468 5 0 0 0 - - -;
+#X floatatom 158 468 5 0 0 0 - - -;
+#X floatatom 212 468 5 0 0 0 - - -;
+#X msg 42 271 2 2500 9 420;
+#X obj 42 317 unpack f f f f;
+#X floatatom 192 347 5 0 0 0 - - -;
+#X text 18 38 [swap] is most commonly used to change the order of a
+list. This trick is best suited for a PAIR of numbers.;
+#X obj 165 373 swap;
+#X obj 138 398 swap;
+#X obj 111 422 swap;
+#X obj 195 406 swap;
+#X obj 168 431 swap;
+#X obj 227 436 swap;
+#X floatatom 263 468 5 0 0 0 - - -;
+#X text 199 373 This could quickly become ridiculous!;
+#X msg 140 271 1 2 3 4;
+#X msg 219 271 0 200 3333 1111;
+#X text 19 213 Lists that are longer than two elements could be sorted
+this way \, but the structure quickly becomes unmanageable. It's probably
+better to find an alternative method.;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
+14 -204280 -1 0;
+#X text 8 2 [swap] More Info;
+#X connect 0 0 1 0;
+#X connect 1 0 2 0;
+#X connect 1 1 3 0;
+#X connect 2 0 4 0;
+#X connect 3 0 4 1;
+#X connect 4 0 5 0;
+#X connect 6 0 18 0;
+#X connect 7 0 17 0;
+#X connect 8 0 16 0;
+#X connect 12 0 13 0;
+#X connect 13 0 6 0;
+#X connect 13 1 7 0;
+#X connect 13 2 8 0;
+#X connect 13 3 14 0;
+#X connect 14 0 16 1;
+#X connect 16 0 17 1;
+#X connect 16 1 19 1;
+#X connect 17 0 18 1;
+#X connect 17 1 19 0;
+#X connect 18 0 9 0;
+#X connect 18 1 20 0;
+#X connect 19 0 20 1;
+#X connect 19 1 21 1;
+#X connect 20 0 10 0;
+#X connect 20 1 21 0;
+#X connect 21 0 11 0;
+#X connect 21 1 22 0;
+#X connect 24 0 13 0;
+#X connect 25 0 13 0;
+#X restore 102 546 pd More_Info;
+#N canvas 70 19 444 592 Note-off_parser_using_swap 0;
+#X obj 0 346 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12
+0 14 -204280 -1 0;
+#X obj 21 109 notein;
+#X text 77 105 [notein] is an object which receives incoming MIDI data
+from a MIDI instrument. The three outlets are PITCH \, VELOCITY \,
+and MIDI CHANNEL from left to right. It is important to note however
+that the data is outputted from right to left. Which means that the
+first piece of information to be sent out the object is the MIDI CHANNEL.
+;
+#X obj 21 183 swap;
+#X obj 21 222 pack;
+#X obj 21 266 route 0;
+#X floatatom 21 294 5 0 0 0 - - -;
+#X text 76 183 Here \, [swap] is used to store the VELOCITY until the
+PITCH information comes from [notein]. The next step will pack the
+two together...but we have to ensure that [pack] receives the two numbers
+in the correct order: PITCH first \, then VELOCITY. This way \, using
+[route] we can determine whether or not this incoming MIDI data is
+a "note-off" signal (i.e. VELOCITY = 0).;
+#X obj 21 316 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X obj 21 386 notein;
+#X obj 22 426 pack;
+#X obj 22 451 route 0;
+#X floatatom 22 476 5 0 0 0 - - -;
+#X obj 22 497 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1
+-1;
+#X text 45 315 This will "bang" only when velocity = 0;
+#X text 18 37 In some settings \, the [swap] object is useful as a
+timing mechanism to ensure that two numbers arrive at their destination
+in a particular order. Miller Puckette has provided an excellent example
+of [swap] used to build a 'note-off parser':;
+#X obj 0 0 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
+14 -204280 -1 0;
+#X text 7 346 Why doesn't the alternative work?;
+#X text 77 382 The goal of the Miller's example above is to retrieve
+"note-off" signals from [notein]. To do that \, we have to test the
+incoming data for pitches with a velocity of zero. So we swap the values
+\, pack up the incoming VELOCITY and PITCH data \, and send them to
+[route]...in effect we achieve the following:;
+#X text 78 463 IF velocity = 0 THEN display the pitch and send a bang
+;
+#X text 77 485 With the [notein] object \, the VELOCITY information
+is sent before the PITCH information. (Remember that in Pd data is
+sent to the outlets in right-to-left order.) In the example at left
+\, the VELOCITY information triggers the output of [pack] BEFORE the
+PITCH information is retrieved. This is why [swap] is used-- it solves
+the problem by making sure that the VELOCITY and PITCH are both received
+before packing them up and sending them to the [route] object.;
+#X text 7 1 [swap] Note-off Parser;
+#X connect 1 0 3 0;
+#X connect 1 1 3 1;
+#X connect 3 0 4 0;
+#X connect 3 1 4 1;
+#X connect 4 0 5 0;
+#X connect 5 0 6 0;
+#X connect 6 0 8 0;
+#X connect 9 0 10 1;
+#X connect 9 1 10 0;
+#X connect 10 0 11 0;
+#X connect 11 0 12 0;
+#X connect 12 0 13 0;
+#X restore 102 568 pd Note-off_parser_using_swap;
+#X text 11 23 swap two numbers \, respecting right-to-left order;
+#X text 168 433 - outputs the value from the right inlet.;
+#X text 168 456 - outputs the value from the left inlet.;
+#X text 80 503 1) float;
+#X text 168 503 - initializes the value of the right inlet.;
+#X obj 4 597 pddp/pddplink pddp/help.pd -text help;
+#X connect 24 0 28 0;
+#X connect 24 1 27 0;
+#X connect 25 0 24 0;
+#X connect 26 0 24 1;
+#X connect 29 0 24 0;
+#X connect 30 0 24 0;
+#X connect 31 0 24 0;
+#X connect 34 0 35 0;
+#X connect 35 0 33 0;
+#X connect 35 1 32 0;