[docs] xmldocs - docelic modified 13 files

docs at icdevgroup.org docs at icdevgroup.org
Tue Dec 21 19:14:21 EST 2004


User:      docelic
Date:      2004-12-22 00:14:21 GMT
Modified:  bin      refs-autogen
Modified:  docbook  item-skel.onefile
Modified:  glossary ITL ad configuration
Modified:  refs     DirectoryIndex
Added:     glossary CGI
Added:     refs     alpha.filter alphanumeric.filter backslash.filter
Added:              bold.filter cgi.filter
Removed:   glossary cgi-var
Log:
- bin/refs-autogen: removed "Filter Type" section from filter refentry pages.
  (type of filter is indicated in title and description already).

- docbook/item-skel.onefile: updated the template to current practice

- glossary/ITL: added one more part from ictags-more.txt (the section on
  quoting of looping subtags)

- glossary/*, refs/DirectoryIndex: little fixes

- refs/*.filter: documented few filters to see how it plays out.
  Also prepared the ground to test online examples on them.

Revision  Changes    Path
1.77      +3 -1      xmldocs/bin/refs-autogen


rev 1.77, prev_rev 1.76
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.76
retrieving revision 1.77
diff -u -r1.76 -r1.77
--- refs-autogen	17 Dec 2004 13:39:23 -0000	1.76
+++ refs-autogen	22 Dec 2004 00:14:20 -0000	1.77
@@ -46,7 +46,7 @@
 my $last_path; # Last version we want docs generated for (say, 5.2.0).
 my $compounds = 1; # Summarize similar symbol groups to single page?
 
-my @page_order = (qw/purpose default structure synopsis description online example notes bugs/, "symbol type", "source", "author", "copyright", "see also", "directive type", "filter type");
+my @page_order = (qw/purpose default structure synopsis description online example notes bugs/, "symbol type", "source", "author", "copyright", "see also", "directive type");
 
 unless ( GetOptions ( 
 	"verbosedb|dumpdb|d!" => \$dumpdb,
@@ -1115,10 +1115,12 @@
 <para>$ag{"description"}</para>
 </refsect1>
 
+<!--
 <refsect1 id='$ag{"name"}_type'>
 <title>FILTER TYPE</title>
 <para>$ag{"filter type"}</para>
 </refsect1>
+-->
 
 <refsect1 id='$ag{"name"}_examples'>
 <title>EXAMPLES</title>



1.4       +1 -6      xmldocs/docbook/item-skel.onefile


rev 1.4, prev_rev 1.3
Index: item-skel.onefile
===================================================================
RCS file: /var/cvs/xmldocs/docbook/item-skel.onefile,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- item-skel.onefile	29 Nov 2004 19:51:09 -0000	1.3
+++ item-skel.onefile	22 Dec 2004 00:14:20 -0000	1.4
@@ -96,14 +96,9 @@
    how simple and obvious you think it is.
    It should consist of a title (no XML in it), description (inside <para>)
    and code example (inside <programlisting>).
-__NAME__ example
-<example>
-  <title></title>
-	<para>
-	</para>
+__NAME__ example: 
 <programlisting>
 </programlisting>
-</example>
 __END__
 
 



1.4       +88 -12    xmldocs/glossary/ITL


rev 1.4, prev_rev 1.3
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ITL	15 Dec 2004 14:24:00 -0000	1.3
+++ ITL	22 Dec 2004 00:14:20 -0000	1.4
@@ -10,7 +10,8 @@
 functions and can be just as powerful as the built-in tags.
 </para>
 
-<section>Tag Syntax</section>
+<section>
+<title>Basics</title>
 
 <para>
 &glos-ITL; tags are similar to HTML, in that they accept
@@ -41,9 +42,11 @@
 useful only if some content is provided in their <emphasis>body</emphasis>
 (the place between the opening and corresponding ending tag).
 </para>
+</section>
 
 
-<section>Standard Syntax</section>
+<section>
+<title>Standard Syntax</title>
 
 <para>
 We've covered the most basic syntax above. If you need to pass parameters
@@ -84,13 +87,17 @@
 always choose between the dash <emphasis role='bold'>and</emphasis>
 underscore</emphasis>! The two forms are interchangeable, except that you
 must be consistent with tag markers; an ending tag must match the opening tag.
-<code>[item-list]...[/item-list]</code> is okay, 
+Both <code>[item-list]...[/item-list]</code> or
+<code>[item_list]...[/item_list]</code> are fine, but
 <code>[item-list]...[/item_list]</code> is
 <emphasis role='bold'>not</emphasis>.
 </para>
 </important>
+</section>
 
-<section>HTML Comments</section>
+
+<section>
+<title>HTML Comments</title>
 
 <para>
 &glos-ITL; also allows you to use <literal>&lt;!--[</literal> and 
@@ -138,8 +145,12 @@
 trouble as you're supposed to be consistent in your syntax anyway.
 <!-- TODO there's more theoretical stuff in APPENDICES in ictags -->
 </para>
+</section>
+
+
+<section>
+<title>Named and Positional Parameters</title>
 
-<section>Named and Positional Parameters</section>
 
 <para>
 There are two styles of supplying parameters to a tag:
@@ -201,8 +212,12 @@
   </para></listitem>
 </itemizedlist>
 </para>
+</section>
+
+
+<section>
+<title>Argument Interpolation</title>
 
-<section>Argument Interpolation</section>
 
 <para>
 When ITL tags are <emphasis>expanded</emphasis>, for example when 
@@ -229,9 +244,54 @@
 quoted; only <arg choice='plain'>arg</arg> did because it
 contained a whitespace.
 </para>
+</section>
+
 
+<section>
+<title>Deeper look at argument quoting</title>
+
+<para>
+The question is &mdash; exactly when can you omit the quotes around
+argument values? First answer is trivial; never omit the quotes and you'll
+never run into trouble.
+</para>
+<para>
+To quote values, you can use double quotes (<literal>"</literal>),
+single quotes (<literal>'</literal>) and 
+pipes (<literal>|</literal>). Pipes have the additional functionality of
+removing leading and trailing whitespace, but generally you can use 
+them in combination to do three levels of quoting with ITL; for 
+more deeply nested constructs, use direct &PERL; code.
+</para>
+<para>
+The above trivial answer to the quoting problem, however, is not the best
+you can get in terms of speed or 
+style. In general, looping <emphasis>subtags</emphasis> (covered some lines
+below) do not need quotes because they are parsed in a separate pass, before
+the general parser takes on.
+</para><para>
+Here's an example that would work properly with quotes omitted. (Pay attention
+to <code>[item-field url]</code> which, at first sight, looks like it is
+invalid because it is not quoted and contains a space.)
+<programlisting>
+[item-list]
+[page [item-field url]]detailed info[/page] on [item-description]
+[/item-list]
+</programlisting>
+</para>
+
+<para>
+<code>[page [value mypage]]</code>, however, would <emphasis>not</emphasis>
+work, because the &tag-value; tag shown is not one of the looping subtags
+which receive special treatment.
+</para>
+
+</section>
+
+
+<section>
+<title>Universal Attributes</title>
 
-<section>Universal Attributes</section>
 
 <para>
 Universal attributes apply to all tags, although tags might specify
@@ -243,7 +303,7 @@
 We will explain <arg choice='plain'>interpolate</arg> and 
 <arg choice='plain'>reparse</arg> attributes here. <emphasis role='bold'>
 It is very important to remember that the behavior of the
-<arg choice='plain'>interpolate</arg> attribute (unfortunately) differs
+<arg choice='plain'>interpolate</arg> attribute (unfortunately) differs,
 depending on whether a tag is stand-alone or a container. In addition,
 the <arg choice='plain'>reparse</arg> attribute is only used with
 container tags (because its function is performed by
@@ -356,18 +416,25 @@
 </para><para> <sbr/><sbr/>
 The <arg choice='plain'>send</arg> attribute is deprecated.
 </para>
+</section>
 
 
-<section>Tag-specific Attributes</section>
+<section>
+<title>Tag-specific Attributes</title>
+
 
 <para>
 Each tag may accept additional arguments which vary from tag to
 tag. For each tag individually, you need to consult the 
 appropriate reference page to learn tag-specific parameters and attributes.
 </para>
+</section>
+
 
 
-<section>Attribute Arrays and Hashes</section>
+<section>
+<title>Attribute Arrays and Hashes</title>
+
 
 <para>
 Some tags allow you to pass a &PERL; &glos-array; or &glos-hash; as the
@@ -408,9 +475,11 @@
 properly. See the documentation for the specific tag before passing
 it an attribute array or hash value.
 </para>
+</section>
 
 
-<section>Perl calls</section>
+<section>
+<title>Perl calls</title>
 
 <para>
 You can simply ignore this section if you don't know the &PERL; 
@@ -444,9 +513,12 @@
 $Tag->routine( { entry => $hashref } );
 ]]></programlisting>
 </para>
+</section>
+
 
+<section>
+<title>Looping Tags and Sub-tags</title>
 
-<section>Looping Tags and Sub-tags</section>
 
 <para>
 Certain tags can only appear in a special context, usually nested within
@@ -651,3 +723,7 @@
 <!-- TODO put somewhere
 PREFIX-field"]PREFIX-field (Optimization note- one query per field if you use this; we optimize around this if only one products table) 
 -->
+</para>
+</section>
+
+<para>



1.5       +1 -1      xmldocs/glossary/ad


rev 1.5, prev_rev 1.4
Index: ad
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ad,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ad	15 Dec 2004 14:24:00 -0000	1.4
+++ ad	22 Dec 2004 00:14:20 -0000	1.5
@@ -13,7 +13,7 @@
 </para><para>
 Voluntary ad unit guidelines as suggested by the
 <ulink url="http://www.iab.net/standards/adunits.asp">Interactive
-Advertising Bureau</ulink> (in ascending order):
+Advertising Bureau</ulink> (specified in pixels, in ascending order):
 </para>
 
 <itemizedlist>



1.3       +5 -5      xmldocs/glossary/configuration


rev 1.3, prev_rev 1.2
Index: configuration
===================================================================
RCS file: /var/cvs/xmldocs/glossary/configuration,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- configuration	15 Dec 2004 14:24:00 -0000	1.2
+++ configuration	22 Dec 2004 00:14:20 -0000	1.3
@@ -1,8 +1,8 @@
 &IC; supports multiple catalogs, and therefore splits its configuration
-into two pieces. One is global, &gcf;, and affects every catalog running
-under that &IC; server.
-The other, &ccf;, is specific to an individual catalog, and has no effect
-on other catalogs.
+into two pieces. One is global, specified in &gcf;, and affects every
+catalog running under the same &IC; server installation.
+The other &mdash; catalog part, is specified in each catalog's
+&glos-CATROOT;/&ccf;, and has no effect on other catalogs.
 </para><para>
 Configuration directives are normally specified with the directive as the
 first word on the line, with its value or values following. Capitalization
@@ -97,5 +97,5 @@
 ifndef ORDERS_TO
   #Needs to go somewhere....
   MailOrderTo  webmaster@&def-domain;
-  endif
+endif
 </programlisting>



1.1                  xmldocs/glossary/CGI


rev 1.1, prev_rev 1.0
Index: CGI
===================================================================
Interchange server runs as a daemon on an Unix system, and is typically
accessed over a communication socket by a web server daemon. In turn,
the web server is accessed by a client using a web browser.
</para>
<para>
Users can send data back to the web server (and thus, indirectly,
to the Interchange process it contacts) by submitting HTML forms.
</para>
<para>
For the form submission to be meaningful, it must carry some data, which
is organized in <literal>
<replaceable>key</replaceable>=<replaceable>value</replaceable>
</literal> pairs. The submission happens according to the CGI
(Common Gateway Interface) specification.
</para><para>
Those submitted keys (and their associated values) are, now obviously, called
"CGI variables".
</para>
<para>
CGI variables in &IC; are accessible using the &tag-cgi; tag, but
<emphasis role='bold'>only</emphasis>
on a page directly following the form submission. In other words, you can't
use &tag-cgi; to retrieve a variable submitted at arbitrary past time during
an user session - that is possible only using &tag-value;.
</para>
<para>
As CGI variables contain user-supplied data, they are obviously of
great concern from a security standpoint.
<!-- TODO what to read on the topic -->
<!-- TODO: IC functionality to deal with CGI data security .. filters etc. -->



1.2       +1 -1      xmldocs/refs/DirectoryIndex


rev 1.2, prev_rev 1.1
Index: DirectoryIndex
===================================================================
RCS file: /var/cvs/xmldocs/refs/DirectoryIndex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DirectoryIndex	17 Dec 2004 22:02:52 -0000	1.1
+++ DirectoryIndex	22 Dec 2004 00:14:21 -0000	1.2
@@ -22,7 +22,7 @@
 (In other words, this directive won't help you make 
 <literal>http://&def-hostname;/</literal> show
 <literal>http://&def-hostname;/index.html</literal> -
-see the &SpecialPage; for that).
+see the &conf-SpecialPage; for that).
 __END__
 
 __NAME__ notes



1.1                  xmldocs/refs/alpha.filter


rev 1.1, prev_rev 1.0
Index: alpha.filter
===================================================================
__NAME__ purpose
eliminate non-alpha characters
__END__

__NAME__ see also
alphanumeric
__END__


__NAME__ description
The filter eliminates any non-alpha characters (that is, anything that's not
in <literal>a-zA-Z</literal> range).
__END__


__NAME__ notes
For more information on &PERL; Regular Expressions, pattern matching and
character classes, see
<citerefentry><refentrytitle>perlre</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
__END__


__NAME__ online: Filter example
<programlisting>
[filter alpha]** Hello, World! **[/filter]
</programlisting>
__END__




1.1                  xmldocs/refs/alphanumeric.filter


rev 1.1, prev_rev 1.0
Index: alphanumeric.filter
===================================================================
__NAME__ purpose
eliminate non-alphanumeric characters
__END__


__NAME__ see also
alpha
__END__


__NAME__ description
The filter eliminates any non-alphanumeric characters
(that is, anything that's not in <literal>a-zA-Z0-9</literal> range).
__END__


__NAME__ notes
For more information on &PERL; Regular Expressions, pattern matching and
character classes, see
<citerefentry><refentrytitle>perlre</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
__END__


__NAME__ online: Filter example
<programlisting>
[filter alphanumeric]** Test 2: Hello, World! **[/filter]
</programlisting>
__END__




1.1                  xmldocs/refs/backslash.filter


rev 1.1, prev_rev 1.0
Index: backslash.filter
===================================================================
__NAME__ purpose
eliminate backslashes
__END__


__NAME__ see also
__END__


__NAME__ description
The filter eliminates backslashes.
__END__


__NAME__ notes
For more information on &PERL; Regular Expressions, pattern matching and
character classes, see
<citerefentry><refentrytitle>perlre</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
__END__


__NAME__ online: Filter example
<programlisting>
[filter backslash]The filter will remove all of those: \\\\ \\\\[/filter]
</programlisting>
__END__




1.1                  xmldocs/refs/bold.filter


rev 1.1, prev_rev 1.0
Index: bold.filter
===================================================================
__NAME__ purpose
enclose input in HTML &lt;b&gt; (bold) tag
__END__


__NAME__ see also
__END__


__NAME__ description
The filter encloses input data in &glos-HTML; &lt;b&gt;
(<emphasis role='bold'>bold</emphasis>) tag.
__END__


__NAME__ online: Filter example
<programlisting>
"[filter bold]To Boldly Go Where No One Has Gone Before![/filter]"
  -- Star Trek
</programlisting>
__END__




1.1                  xmldocs/refs/cgi.filter


rev 1.1, prev_rev 1.0
Index: cgi.filter
===================================================================
__NAME__ purpose
expand to value of the CGI variable specified in body
__END__


__NAME__ description
The filter expands to the value of a &glos-CGI; variable.
Name of the variable is specified in filter body.
__END__


__NAME__ online: Filter example
<programlisting>
[cgi name=online_cgi_test set="TEST VALUE" hide=1]

My test value is [filter cgi]online_cgi_test[/filter]
</programlisting>
__END__









More information about the docs mailing list