[docs] xmldocs - docelic modified 4 files

[docs at icdevgroup.org]

User:      docelic
Date:      2004-10-28 19:41:19 GMT
Added:     refs     cgi.tag crypt.tag
Removed:   refs     cgi crypt
Log:
- Crypt and Cgi are both filters and tags, so the file rename must
  take place.

Revision  Changes    Path
1.1                  xmldocs/refs/cgi.tag


rev 1.1, prev_rev 1.0
Index: cgi.tag
===================================================================
__NAME__ purpose
get or set current value of the specified CGI input variable
__END__


__NAME__ see also
value
__END__


__NAME__ synopsis
<row>
	<entry>
			<arg choice='plain'>name</arg>
	</entry>
	<entry>Yes</entry><entry>Yes</entry>
	<entry></entry>
	<entry>Name of the CGI input variable.</entry>
</row>
<row>
	<entry>
			<arg choice='plain'>set</arg>
	</entry>
	<entry></entry><entry></entry>
	<entry>None.</entry>
	<entry>New value for a variable to set, instead of retrieving
	the current content.</entry>
</row>
<row>
	<entry>
			<arg choice='plain'>default</arg>
	</entry>
	<entry></entry><entry></entry>
	<entry>None.</entry>
	<entry>
	Text to return if the variable requested is missing or otherwise
	false.
	</entry>
</row>
<row>
	<entry>
			<arg choice='plain'>enable_html</arg>
	</entry>
	<entry></entry><entry></entry>
	<entry>0</entry>
	<entry>Allow HTML tags to appear in the output? By default, 
	All &lt; characters are replaced by &amp;lt;.
	</entry>
</row>
<row>
	<entry>
			<arg choice='plain'>keep</arg>
	</entry>
	<entry></entry><entry></entry>
	<entry>0</entry>
	<entry>
	Do apply filter for display, but do not modify the original
	CGI value itself (from the the <varname>$CGI::values</varname> hash)?
	</entry>
</row>
&ROW_FILTER_none;
&ROW_HIDE_0;
__END__


__NAME__ notes
This is one of often used Interchange tags.
__END__


__NAME__ description
The tag displays the value of a CGI variable submitted to a current page.
This is similar to the <tag>value</tag> tag, except that it displays 
transitory values that have been submitted with the current request.
In other words, the CGI values are reset on each request and you can
only access the values directly submitted to the current page.
</para><para>
For instance, if you invoke the page with &GET;
parameters, such as <literal>pagename?foo=bar</literal>,
then the value of the <literal>foo</literal> CGI variable will be
accessible using <code>[cgi foo]</code> in
&ITL; or <code>$CGI->{foo}</code> in embedded Perl.
__END__

__NAME__ notes
__END__

__NAME__ example
<example>
  <title>Accessing CGI variables</title>
	<para>
	Save the following content to a test page named say,
	<filename>cgitest.html</filename>, then visit 
	<literal><![CDATA[cgitest?foo=bar&toad=stool]]></literal> with your browser.
	</para>
  <programlisting>
<![CDATA[
Value of 'foo': [cgi foo]<br/>
Value of 'toad': [cgi name=toad]<br/>
]]>
  </programlisting>
</example>
__END__




1.1                  xmldocs/refs/crypt.tag


rev 1.1, prev_rev 1.0
Index: crypt.tag
===================================================================
__NAME__ purpose
encrypt a string exactly like the crypt(3) function in the C library
__END__


__NAME__ synopsis
<row>
	<entry>
		<group>
		<arg choice='plain'>value</arg>
		<arg choice='plain'>password</arg>
		</group>
	</entry>
	<entry>Yes</entry><entry>Yes</entry>
	<entry></entry>
	<entry>Text to encrypt.</entry>
</row>
<row>
	<entry>
		<group>
		<arg choice='plain'>salt</arg>
		<arg choice='plain'>crypted</arg>
		</group>
	</entry>
	<entry>Yes</entry><entry></entry>
	<entry>Random 2-character string</entry>
	<entry>Crypt salt. You usually
	want to leave it empty for the tag to generate the random salt itself.
	Specifying salt only makes sense for testing purposes, or when you're
	verifying the password, like you see in <xref linkend='crypt_examples'/>.
	</entry>
</row>
__END__


__NAME__ description
Encrypts a string exactly like the <function>crypt(3)</function>
function in the C library.
</para><para>
Note that crypt is intended to be a one-way function, much like breaking eggs to make an omelette. There is no (known) corresponding decrypt function. As a result, this function isn't all that useful for any cryptography.
</para><para>
This tag simply calls the Perl built-in <function>crypt()</function> function.
</para><para>
When verifying an existing encrypted string you should use the encrypted text as the salt (like <code>[crypt PLAIN CRYPTED]</code>) and compare that to CRYPTED (it should be equal). This allows your code to work with the standard crypt and with more exotic implementations.
</para><para>
When choosing a new salt, either let the tag generate a 2-character random string itself, or generate one yourself from the [./0-9A-Za-z] set. (working Perl code would be <code>join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]</code>.
</para><para>
The crypt function is unsuitable for encrypting large quantities of data, not least of all because you can't get the information back.
__END__


__NAME__ example
<example>
	<title>Crypt a string and verify it</title>
	<para>
	Note that this example is of little use in practice, but does show the
	components you can re-use:
	</para>
	<programlisting><![CDATA[
<p>
[seti salt][perl]join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64][/perl][/seti]
String "test" crypted with salt "[scratch salt]": [crypt value="test" salt="[scratch salt]"]
</p>

<p>
[seti crypted][crypt value="test" salt="[scratch salt]"][/seti]
Checking validity: [crypt value="test" salt="[scratch crypted]"]
</p>

<p>
[perl]
$Tag->crypt("test", $Scratch->{crypted}) eq $Scratch->{crypted} ?
  "Password matches." : "Password does not match."
[/perl]
</p>
	]]></programlisting>
</example>
__END__