Revised and added to all_about help patches

svn path=/trunk/; revision=13941

1 files changed, 122 insertions, 85 deletions

diff --git a/doc/pddp/all_about_atom_conversion.pd b/doc/pddp/all_about_atom_conversion.pd
index ea1ec8fc..0daadcd5 100644
--- a/doc/pddp/all_about_atom_conversion.pd
+++ b/doc/pddp/all_about_atom_conversion.pd
@@ -1,88 +1,125 @@
-#N canvas 32 32 763 478 10;
-#X obj 4 2 cnv 15 750 20 empty empty all_about_atom_conversion 20 10
-1 18 -233017 -66577 0;
-#X obj 721 3 pddp/pddplink http://puredata.info/dev/pddp -text pddp
+#N canvas 0 0 448 248 10;
+#X obj 1 1 cnv 15 445 20 empty \$0-pddp.cnv.header atom_conversion
+20 10 1 18 -261106 -33289 0;
+#X obj 407 2 pddp/pddplink http://puredata.info/dev/pddp -text pddp
 ;
-#X obj 27 354 list2int;
-#X obj 91 353 l2i;
-#X obj 93 379 a2l;
-#X obj 26 380 any2list;
-#X obj 26 330 lister;
-#X obj 26 406 list2symbol;
-#X obj 26 427 symbol2list;
-#X obj 115 406 l2s;
-#X obj 115 426 s2l;
-#X obj 159 407 tosymbol;
-#X obj 159 426 fromsymbol;
-#X obj 508 290 glue;
-#X obj 569 317 pack;
-#X obj 568 291 list2symbol;
-#X obj 678 290 tosymbol;
-#X text 485 264 making "lists" from untyped inputs:;
-#X obj 444 290 repack;
-#X obj 27 308 list;
-#X obj 26 283 any;
-#X obj 55 283 pipe;
-#X text 439 66 a set that is not a "list" has an undefined type:;
-#X text 17 39 SPECIAL CASES OF "LISTS".;
-#X obj 473 420 pddp/pddplink all_about_data_types.pd -text all_about_data_types
+#X obj 43 80 pddp/pddplink all_about_messages.pd;
+#X obj 1 226 cnv 15 445 20 empty \$0-pddp.cnv.footer empty 20 12 0
+14 -233017 -33289 0;
+#N canvas 44 246 494 344 META 0;
+#X text 12 65 HELP_PATCH_AUTHORS Dave Sabine \, May 5 \, 2003 . Jonathan
+Wilkes revised the patch to conform to the PDDP template for Pd version
+0.42.;
+#X text 12 5 GENRE all_about_pd;
+#X text 12 25 KEYWORDS needs_work;
+#X text 12 45 DESCRIPTION how to convert Pd atoms;
+#X restore 392 228 pd META;
+#N canvas 14 133 428 105 Related_objects 0;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
+14 -261106 -33289 0;
+#X text 7 2 Atoms- Related Objects;
+#X floatatom 22 43 5 0 0 0 - - -;
+#X symbolatom 22 67 10 0 0 0 - - -;
+#X obj 105 42 makefilename;
+#X obj 200 60 pddp/helplink cyclone/fromsymbol;
+#X obj 200 80 pddp/helplink zexy/symbol2list;
+#X obj 311 59 pddp/helplink zexy/list2symbol;
+#X obj 311 79 pddp/helplink cyclone/tosymbol;
+#X obj 200 40 pddp/pddplink all_about_externals.pd -text _________
 ;
-#X obj 473 397 pddp/pddplink all_about_lists_vs_anythings.pd -text
-all_about_lists_vs_anythings;
-#X obj 454 155 bng 15 250 50 0 empty empty bang 0 20 1 9 -262144 -1
--1;
-#X obj 503 155 bng 15 250 50 0 empty empty float 0 21 1 9 -262144 -1
--1;
-#X obj 552 155 bng 15 250 50 0 empty empty symbol 0 21 1 9 -262144
--1 -1;
-#X msg 456 93 list this is a set with a cast;
-#X msg 463 112 this is a set withOUT a cast;
-#X obj 651 155 bng 15 250 50 0 empty empty list 0 21 1 9 -262144 -1
--1;
-#X obj 701 155 bng 15 250 50 0 empty empty UNDEFINED 0 21 1 9 -262144
--1 -1;
-#X obj 454 135 route bang float symbol pointer list;
-#X obj 602 155 bng 15 250 50 0 empty empty pointer 0 21 1 9 -262144
--1 -1;
-#X msg 20 63 list;
-#X symbolatom 42 129 10 0 0 0 - - -;
-#X msg 27 83 list 25;
-#X msg 34 103 list foo;
-#X text 97 104 A "list" of one "symbol" is converted to a "symbol"
+#X obj 200 40 pddp/pddplink all_about_externals.pd -text Externals
 ;
-#X text 82 83 A "list" of one "float" is converted to a "float";
-#X text 60 63 An empty "list" is converted to a "bang";
-#X obj 21 169 bng 15 250 50 0 empty empty bang 0 20 1 9 -262144 -1
--1;
-#X obj 70 169 bng 15 250 50 0 empty empty float 0 21 1 9 -262144 -1
--1;
-#X obj 119 169 bng 15 250 50 0 empty empty symbol 0 21 1 9 -262144
--1 -1;
-#X obj 218 169 bng 15 250 50 0 empty empty list 0 21 1 9 -262144 -1
--1;
-#X obj 268 169 bng 15 250 50 0 empty empty UNDEFINED 0 21 1 9 -262144
--1 -1;
-#X obj 21 149 route bang float symbol pointer list;
-#X obj 169 169 bng 15 250 50 0 empty empty pointer 0 21 1 9 -262144
--1 -1;
-#X text 13 233 There are many ways to store \, manipulate. and convert
-atoms and lists. Here is a sampling;
-#X connect 15 0 14 0;
-#X connect 29 0 33 0;
-#X connect 30 0 33 0;
-#X connect 33 0 26 0;
-#X connect 33 1 27 0;
-#X connect 33 2 28 0;
-#X connect 33 3 34 0;
-#X connect 33 4 31 0;
-#X connect 33 5 32 0;
-#X connect 35 0 47 0;
-#X connect 37 0 47 0;
-#X connect 38 0 36 0;
-#X connect 38 0 47 0;
-#X connect 47 0 42 0;
-#X connect 47 1 43 0;
-#X connect 47 2 44 0;
-#X connect 47 3 48 0;
-#X connect 47 4 45 0;
-#X connect 47 5 46 0;
+#X restore 103 228 pd Related_objects;
+#X obj 6 228 pddp/pddplink pddp/help.pd -text help;
+#X text 208 106 <- give some links to the manual;
+#X obj 43 65 pddp/pddplink all_about_atoms.pd;
+#X text 42 36 Converting between atom types in Pd can be tricky. Make
+sure you have read the following help patches first:;
+#N canvas 9 155 428 140 symbol-atom_to_float 0;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 20 10
+1 18 -261106 -33289 0;
+#X text 7 1 From a symbol-atom to a float;
+#X text 20 37 There are no standard objects to turn a symbol-atom into
+a float. There are two important externals for this \, however:;
+#X obj 20 70 pddp/helplink cyclone/fromsymbol;
+#X obj 20 90 pddp/helplink zexy/symbol2list;
+#X restore 43 149 pd symbol-atom_to_float;
+#N canvas 14 48 428 554 float_to_symbol-atom 0;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 20 10
+1 18 -261106 -33289 0;
+#X text 7 1 Changing a float to a symbol-atom;
+#X obj 45 163 hsl 128 15 0 127 0 0 empty 123 empty -2 -8 0 10 -262144
+-1 -1 0 1;
+#X text 19 79 For example \, you can enter a number for the "receive-symbol"
+of the so-called IEMGUIS like the slider below. Since receive-names
+need to be symbol-atoms \, the GUI automatically converts "123" to
+a symbol-atom after you click "Ok" or "Apply" in the "Properties" dialogue.
+;
+#X text 181 158 <- hslider with receive-symbol "123";
+#X msg 42 353 symbol 123;
+#X obj 42 375 print empty_symbol;
+#X msg 151 457 123;
+#X text 192 456 <- try it;
+#X obj 151 479 makefilename %d;
+#X text 255 479 <- outputs "symbol 123" \,;
+#X text 255 494 where "123" is a real;
+#X text 255 509 symbol-atom;
+#X obj 130 503 send;
+#X floatatom 93 479 5 0 0 0 - - -;
+#X text 19 395 The [makefilename] object will do the trick \, however.
+It always outputs a symbol message (remember that a symbol message
+must have a symbol-atom as an element) \, and so it can convert an
+incoming float to a symbol-atom:;
+#X text 19 494 Also see:;
+#X obj 20 514 pddp/helplink zexy/list2symbol;
+#X obj 20 529 pddp/helplink cyclone/tosymbol;
+#X text 19 36 Problem: some objects in Pd expect certain atom types
+and will complain with an error if they receive the wrong type. Other
+objects will silently make the conversion for you.;
+#X text 19 183 Note that there's no visible difference between the
+float "123" and the symbol-atom "123"-- the only difference is in how
+these character are understood by Pd. If I want to send a value to
+the slider using [send] \, there is a problem because [send] doesn't
+do any atom conversion-- if you try to create [send 123] you'll get
+an error.;
+#X text 19 267 However \, you can send a symbol message to the right
+inlet of [send] to specify the send-name. You might think that using
+a symbol message will convert the number to a symbol-atom. Unfortunately
+\, that doesn't work either-- the message box silently ignores the
+float and outputs an empty symbol:;
+#X connect 5 0 6 0;
+#X connect 7 0 9 0;
+#X connect 9 0 13 1;
+#X connect 14 0 13 0;
+#X restore 43 106 pd float_to_symbol-atom;
+#N canvas 22 133 428 426 multiple_atoms_to_one_symbol-atom 0;
+#X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 20 10
+1 18 -261106 -33289 0;
+#X text 7 1 Concatenate multiple atoms;
+#X msg 42 98 list one 2 3;
+#X msg 140 98 1 2 3;
+#X msg 42 131 symbol \$1\$2\$3;
+#X symbolatom 42 158 10 0 0 0 - - -;
+#X text 19 36 Dollarsign variables can be used to join several atoms
+together to form one atom. The result is always a symbol-atom.;
+#X text 139 131 \$1\$2\$3 is always a symbol-atom \,;
+#X text 139 148 so we can safely use it build a;
+#X text 139 165 symbol message.;
+#X obj 42 277 makefilename Program%cFiles;
+#X symbolatom 42 301 0 0 0 0 - - -;
+#X msg 42 250 32;
+#X obj 41 352 pddp/helplink zexy/list2symbol;
+#X obj 41 372 pddp/helplink cyclone/tosymbol;
+#X text 19 196 There are also times when you may need to create a symbol-atom
+that contains spaces in it. Use the %c argument with [makefilename].
+;
+#X text 19 335 For more complex constructions \, see:;
+#X connect 2 0 4 0;
+#X connect 3 0 4 0;
+#X connect 4 0 5 0;
+#X connect 10 0 11 0;
+#X connect 12 0 10 0;
+#X restore 43 128 pd multiple_atoms_to_one_symbol-atom;
+#X text 42 171 See also:;
+#X obj 43 187 pddp/pddplink all_about_message_conversion.pd;
+#X obj 43 202 pddp/pddplink all_about_symbol_construction.pd;