[docs] xmldocs - docelic modified 2 files

[docs at icdevgroup.org]

User:      docelic
Date:      2004-09-26 19:52:19 GMT
Added:     refs     crypt values-space
Log:
- two new items documented

Revision  Changes    Path
1.1                  xmldocs/refs/crypt


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


__NAME__ synopsis
<row>
	<entry>
		<group choice='plain'>
		<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 choice='plain'>
		<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 (random two characters that make potential
	attacker's dictionary too large to pre-compile it). 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__





1.1                  xmldocs/refs/values-space


rev 1.1, prev_rev 1.0
Index: values-space
===================================================================
__NAME__ purpose
switch between value namespaces
__END__


__NAME__ synopsis2
<row>
	<entry>name</entry>
	<entry>Yes</entry><entry></entry>
	<entry><literal></literal></entry>
	<entry>Switch namespace. Empty value (<code>name=""</code>) switches
	back to the main namespace.</entry>
</row>
<row>
	<entry>copy-all</entry>
	<entry></entry><entry></entry>
	<entry>0</entry>
	<entry>
	Copy all values from the current
	namespace to the new one, and switch to it.
	(Nested data structures are not dereferenced).
	</entry>
</row>
<row>
	<entry>copy</entry>
	<entry></entry><entry></entry>
	<entry></entry>
	<entry>
	Copy only the specified space-separated values.
	</entry>
</row>
<row>
	<entry>clear</entry>
	<entry></entry><entry></entry>
	<entry>0</entry>
	<entry>
	Clear all values in the target namespace and switch to it.
	</entry>
</row>
<row>
	<entry>show</entry>
	<entry></entry><entry></entry>
	<entry>0</entry>
	<entry>
	Return name of the current namespace, then switch to a new one.
	</entry>
</row>
__END__


__NAME__ see also
value, value-extended
__END__


__NAME__ description
This tag switches the values namespace for the duration of the page.
To switch back to the default namespace, use
<code>[values-space name='']</code>.
</para><para>
The current namespace is kept in the <varname>$Vend::ValuesSpace</varname>
variable.
__END__


__NAME__ example
<example>
	<title>Switch and display namespaces</title>
	<programlisting>
Current namespace is: [values-space] <sbr/>
Switching to namespace 'basket': [values-space basket] <sbr/>
Switching [values-space name=checkout show=1 clear=1] to clear [values-space] <sbr/>

	</programlisting>
</example>
__END__