[interchange-docs] xmldocs - docelic modified 3 files
docs at icdevgroup.org
docs at icdevgroup.org
Sun Feb 25 06:06:55 EST 2007
User: docelic
Date: 2007-02-25 11:06:55 GMT
Modified: glossary ITL
Modified: guides install.xml
Modified: refs SafeUntrap
Log:
* Polishing few items
Revision Changes Path
1.21 +33 -28 xmldocs/glossary/ITL
rev 1.21, prev_rev 1.20
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- ITL 2 Nov 2006 10:43:42 -0000 1.20
+++ ITL 25 Feb 2007 11:06:54 -0000 1.21
@@ -15,13 +15,12 @@
<para>
&glos-ITL; tags are similar to HTML, in that they accept
-parameters or attributes and that there are both
-<emphasis>standalone</emphasis> and <emphasis>container</emphasis> tags.
-</para><para>
-We will call an attribute a <emphasis>parameter</emphasis> if it may be
-called <emphasis>positionally</emphasis> or if it is required.
-</para><para>
-A standalone tag has no ending element, such as
+attributes and that there are both
+<emphasis>standalone</emphasis> (non-container) and
+<emphasis>container</emphasis> tags.
+</para>
+<para>
+A standalone tag has no ending element, such as &tag-value;:
<programlisting>
[value name]
@@ -30,7 +29,7 @@
The tag, as seen in the above example, will insert the user's name (provided
they supplied one in the first place).
</para><para>
-A container tag has both beginning and ending elements, such as
+A container tag has both beginning and ending elements, such as &tag-if;:
<programlisting>
[if value name]
@@ -41,8 +40,8 @@
In the above example, you can implicitly see that container tags are mostly
useful only if some content is provided in their <emphasis>body</emphasis>
(the place between the opening and corresponding ending tag).
-</para>
-<para>
+</para><para>
+
Additionally, container tags for which you do not provide any
<emphasis>body</emphasis> can be closed using "XML-style" syntax.
The following two lines are identical in effect:
@@ -53,9 +52,10 @@
</para>
<para>
Note, however, that <emphasis role='bold'>you can use "<literal>/]</literal>"
-only with tags for which you provide no parameters, or the parameters are named
-and quoted</emphasis>. Positional parameters "eat" everything (including
-the "<literal>/</literal>") up to the closing bracket.
+only with tags for which you provide no attributes, or the attributes are named
+and quoted</emphasis>. Positional attributes (<emphasis>parameters</emphasis>)
+"absorb" everything (including the "<literal>/</literal>") up to the closing
+bracket.
</para>
<para>
It's probably also useful to mention that there must be no whitespace
@@ -69,9 +69,8 @@
<title>Standard Syntax</title>
<para>
-We've covered the most basic syntax above. If you need to pass parameters
-or attributes (let's call them <emphasis>arguments</emphasis> when their
-nature is irrelevant) to the tag, you do that in the opening section.
+We've covered the most basic syntax above. If you need to pass
+attributes to the tag, you do that in the opening section.
If the tag is a container, then body text can additionally be specified
between the opening and closing marker:
@@ -177,10 +176,11 @@
<para>
-There are two styles of supplying parameters to a tag:
+There are two styles of supplying attributes to a tag:
<emphasis>named</emphasis> and <emphasis>positional</emphasis>.
+
</para><para>
-In the named style, you supply parameters using
+In the <emphasis>named</emphasis> style, you supply attributes using
<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
pairs, just as with HTML:
@@ -188,7 +188,7 @@
[value name=<replaceable>variable_name</replaceable>]
</programlisting>
-The positional-style tag that accomplishes the same thing but is more
+The positional-style tag that accomplishes the same thing, but is more
compact:
<!-- TODO: [tag pos1 ] makes pos1 in fact "pos1 " -->
@@ -204,10 +204,10 @@
each tag's SYNOPSIS reference section; try &tag-value; for example.
</para><para>
Additionally, <emphasis role='bold'>you cannot mix named and positional
-parameters in the same tag</emphasis>; use either all named, or all positional.
+attributes in the same tag</emphasis>; use either all named, or all positional.
<emphasis role='bold'>It seems I cannot stress this enough, this is a common
-beginners' mistake, especially when you copy/paste foreign code and combine
-with your own!</emphasis>
+beginners' mistake, especially when you copy/paste other people's code and
+combine with your own.</emphasis>
</para><para>
In any case, positional syntax is appropriate for simpler tags and
&IC; interprets positional arguments somewhat faster (but don't let your
@@ -215,13 +215,14 @@
<ulink url="http://www.thocp.net/biographies/dijkstra_edsger.htm">Edsger W. Dykstra</ulink>
once said, "Premature optimization is the root of all programming evil").
</para><para>
-In most cases, tag parameters specified in the positional fashion work
-the same as named parameters. However, <emphasis role='bold'>there are a few
-situations where you must use named parameters</emphasis>:
+In most cases, tag attributes specified in the positional fashion
+(<emphasis>parameters</emphasis>) work
+the same as named attributes. However, <emphasis role='bold'>there are a few
+situations where you must use named attributes</emphasis>:
<itemizedlist>
<listitem><para>
- When you want to specify a parameter that comes positionally after a
+ When you want to specify a parameter that, positionally, comes after a
parameter that you want to omit, e.g. omit the first parameter but specify
the second. The parser would have no way of knowing which is which, so
you must revert to named syntax. This rarely happens, though, because the
@@ -240,6 +241,10 @@
When you need to use the output of a tag as <emphasis>argument</emphasis> for
another tag.
</para></listitem>
+
+ <listitem><para>
+ When you are using looping subtags (Loop tags and subtags are explained below).
+ </para></listitem>
</itemizedlist>
</para>
</section>
@@ -326,8 +331,8 @@
<para>
You might wonder why unquoted tags are even allowed. The answer is
<emphasis>performance</emphasis>. If you have large lists of tags you can
-achieve significant speed-ups by using positional parameters. Parsing and
-disassembling named parameters takes some more CPU cycles.
+achieve significant speed-ups by using positional attributes. Parsing and
+disassembling named attributes takes some more CPU cycles.
</para>
</section>
1.8 +2 -2 xmldocs/guides/install.xml
rev 1.8, prev_rev 1.7
Index: install.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/install.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- install.xml 30 Jul 2006 20:40:03 -0000 1.7
+++ install.xml 25 Feb 2007 11:06:54 -0000 1.8
@@ -115,10 +115,10 @@
all distributions compile a threaded version. This problem has caused,
and is causing, endless problems for &IC; users. Run
<command>perl -V:usethreads</command> to quickly test your mileage.
- An answer of '<literal>UNKNOWN</literal>' is good, and the answer of
- '<literal>define</literal>' is not good.
+ The answer '<literal>define</literal>' is not good.
</para>
<para>
+ <emphasis role='bold'>However</emphasis>,
There should be no
problems with threaded Perl versions 5.8.5 or newer, although it means
an up-to-30% performance drop. For home installations and testing, both
1.5 +20 -2 xmldocs/refs/SafeUntrap
rev 1.5, prev_rev 1.4
Index: SafeUntrap
===================================================================
RCS file: /var/cvs/xmldocs/refs/SafeUntrap,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- SafeUntrap 6 Nov 2006 18:41:21 -0000 1.4
+++ SafeUntrap 25 Feb 2007 11:06:55 -0000 1.5
@@ -13,7 +13,7 @@
embedded &PERL; and conditional operations.
Define it as blank to prevent any operators but the default restrictive ones.
</para><para>
-For a complete discussion and the opcodes list, see
+For a complete discussion and the complete list of opcodes, see
<citerefentry><refentrytitle>Opcode</refentrytitle>
<manvolnum>3perl</manvolnum></citerefentry> manual page.
__END__
@@ -44,4 +44,22 @@
</programlisting>
__END__
-TODO: enabling all
+__NAME__ example: Allowing a group of file-related operations
+
+<programlisting>
+[set data_file]products/biglist.txt[/set]
+[calcn]-r $Scratch->{data_file};[/calcn]
+</programlisting>
+
+Adding <literal>:filesys_read</literal> to SafeUntrap solves this problem:
+
+<programlisting>
+SafeUntrap :filesys_read
+</programlisting>
+
+As said, see the
+<citerefentry><refentrytitle>Opcode</refentrytitle>
+<manvolnum>3perl</manvolnum></citerefentry> manual page for
+more information and the complete list of operation codes and groups.
+__END__
+
More information about the docs
mailing list