[interchange-docs] xmldocs - docelic modified glossary/ITL

docs at icdevgroup.org docs at icdevgroup.org
Mon Jun 18 14:57:38 EDT 2007

User:      docelic
Date:      2007-06-18 18:57:37 GMT
Modified:  glossary ITL
* Add few sentences related to interpolate_itl_references pragma and its

Revision  Changes    Path
1.22      +40 -8     xmldocs/glossary/ITL

rev 1.22, prev_rev 1.21
Index: ITL
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- ITL	25 Feb 2007 11:06:54 -0000	1.21
+++ ITL	18 Jun 2007 18:57:37 -0000	1.22
@@ -261,15 +261,15 @@
 If you want to use one tag's output as another tag's input, you
 cannot use positional syntax and you must double-quote the
-argument. For example, this will not work:
+argument. For example, this <emphasis role='bold'>WILL NOT</emphasis> work:
 [page scan se=[scratch <replaceable>variable_name</replaceable>]]
-Actually, the above example is in a really bad shape. To make it work, we
-need to switch to named syntax and properly quote arguments containing
+Actually, the above code is in a really bad shape. To make it work, we
+need to do two things: switch to named syntax, and properly quote arguments
+containing whitespace:
 [page href=scan arg="se=[scratch <replaceable>variable_name</replaceable>]"]
@@ -279,6 +279,23 @@
 quoted; only <arg choice='plain'>arg</arg> did because it
 contained a whitespace.
+As you can implicitly see from the above example, attribute values
+are normally interpolated (in other words,
+<literal>se=[scratch variable_name]</literal> was expanded to
+before being passed as value to <literal>arg=</literal>.
+However, when the attributes are of complex types (array or hash
+references), their values <emphasis role='bold'>are not</emphasis>
+&glos-interpolate;d. The interpolation is controlled by the
+&pragma-interpolate_itl_references; pragma, and more about this whole
+concept can be learned below in <xref linkend="itl_arrays_and_hashes"/>.
@@ -620,7 +637,7 @@
+<section id="itl_arrays_and_hashes">
 <title>Attribute Arrays and Hashes</title>
@@ -643,7 +660,7 @@
-Here is an example of an attribute array:
+Here is an example of an array-based attribute:
@@ -657,8 +674,9 @@
-It is up to each individual tag to handle an array or hash value
-properly. See the documentation for the specific tag before passing
+<emphasis role='bold'>It is up to each individual tag to handle an
+array or hash value properly</emphasis>.
+See the documentation for the specific tag before passing
 it an attribute array or hash value.
 The &tag-page; tag, for example, would treat a search specification array
 (the structure we've shown above) as a joined search (one of different
@@ -692,6 +710,20 @@
 $Tag->ROUTINE( { entry => $hashref } );
+Pay attention to the fact that with array- or hash-based attributes,
+their values <emphasis role='bold'>are not interpolated</emphasis>.
+It means that, at places where scalar options
+<emphasis role='bold'>are</emphasis> interpolated (such as
+<code>[tag option='[time]']</code>, resulting in &tag-time; expanding to
+the current time), reference-based attributes are not (such as
+<code>[tag my.option='[time]']</code>, which would result in literal
+"<literal>[time]</literal>" being passed to the attribute "my.option".
+Interpolation of reference-based attributes can be enabled by
+setting the &pragma-interpolate_itl_references; pragma.

More information about the docs mailing list