# HG changeset patch
# User Homutov Vladimir <vl@nginx.com>
# Date 1363600753 -14400
# Node ID 17d0c825f0984dcc245a4e127f03df774edca01b
# Parent  20a50f7bcbd6ac460fc1baa4e39f68833ee48446
Revised the userid module documentation.

 - added the "embedded variables" section;
 - documented the "$uid_reset" variable;
 - documented default parameters of "userid_expires", "userid_mark" and
   "userid_p3p" directives;
 - improved descriptions of "userid_mark" and "userid_service" directives.

diff --git a/xml/en/docs/http/ngx_http_userid_module.xml b/xml/en/docs/http/ngx_http_userid_module.xml
--- a/xml/en/docs/http/ngx_http_userid_module.xml
+++ b/xml/en/docs/http/ngx_http_userid_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_userid_module"
         link="/en/docs/http/ngx_http_userid_module.html"
         lang="en"
-        rev="2">
+        rev="3">
 
 <section id="summary">
 
@@ -18,7 +18,8 @@
 The <literal>ngx_http_userid_module</literal> module sets cookies
 suitable for client identification.
 Received and set cookies can be logged using the embedded variables
-<var>$uid_got</var> and <var>$uid_set</var>.
+<link id="var_uid_got">$uid_got</link> and
+<link id="var_uid_set">$uid_set</link>.
 This module is compatible with the
 <link url="http://www.lexa.ru/programs/mod-uid-eng.html">mod_uid</link>
 module for Apache.
@@ -105,35 +106,50 @@ The parameter <literal>none</literal> di
 
 
 <directive name="userid_expires">
-<syntax><value>time</value> | <literal>max</literal></syntax>
-<default/>
+<syntax><value>time</value> | <literal>max</literal> |
+    <literal>off</literal></syntax>
+<default>off</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
 Sets a time during which a browser should keep the cookie.
-The parameter <literal>max</literal> sets the time to
+The parameter <literal>max</literal> will cause the cookie to expire on
 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
 This is the maximum time understood by old browsers.
+The parameter <literal>off</literal> will cause the cookie to expire at
+the end of a browser session.
 </para>
 
 </directive>
 
 
 <directive name="userid_mark">
-<syntax><value>off | letter | digit | =</value></syntax>
+<syntax>
+    <value>letter</value> | <value>digit</value> |
+    <literal>=</literal> |
+    <literal>off</literal></syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
-Sets the first symbol of the cookie’s representation base64 tail
-(“<literal>==</literal>” by default) and resets all accepted cookies
-with another tail.
-It may be useful if it's required to add or change the P3P or the cookie expire
-time and leave the internally encoded value unchanged.
+If parameter is not <literal>off</literal>, enables the cookie marking
+mechanism and sets a character used as a mark.
+This mechanism allows to add or change
+<link id="userid_p3p"/> and/or cookie expiration time while
+preserving the client identifier.
+The mark can be any letter of the English alphabet (case-sensitive),
+digit, or the “<literal>=</literal>” character.
+</para>
+
+<para>
+If a mark is set, it is compared with the first padding symbol
+in the base64 representation of client identifier passed in a cookie.
+If they do not match, a cookie is resent with the specified mark,
+expiration time and a <header>P3P</header> header.
 </para>
 
 </directive>
@@ -154,8 +170,8 @@ Sets a cookie name.
 
 
 <directive name="userid_p3p">
-<syntax><value>string</value></syntax>
-<default/>
+<syntax><value>string</value> | <literal>none</literal></syntax>
+<default>none</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
@@ -163,6 +179,8 @@ Sets a cookie name.
 <para>
 Sets a value for the <header>P3P</header> header field that will be
 sent along with a cookie.
+If set to the special value <literal>none</literal>,
+the <header>P3P</header> header will not be sent in a response.
 </para>
 
 </directive>
@@ -190,13 +208,48 @@ Defines a path for which the cookie is s
 <context>location</context>
 
 <para>
-Identifies the service that set a cookie.
+If identifiers are issued by multiple servers (services),
+each service should be assigned its own <value>number</value>
+in order to ensure that client identifiers are unique.
 For version 1 cookies the default value is zero.
-For version 2 cookies the default value is an IP address of the server.
+For version 2 cookies this is the number composed from the last four
+octets of the server’s IP address.
 </para>
 
 </directive>
 
 </section>
 
+
+<section id="variables" name="Embedded variables">
+
+<para>
+The <literal>ngx_http_userid_module</literal> module
+supports the following embedded variables:
+<list type="tag">
+
+<tag-name id="var_uid_got"><var>$uid_got</var></tag-name>
+<tag-desc>
+The cookie name and received client identifier.
+</tag-desc>
+
+<tag-name id="var_uid_reset"><var>$uid_reset</var></tag-name>
+<tag-desc>
+If set to a non-empty string, and it is not “<literal>0</literal>”,
+client identifiers are reset.
+The special value “<literal>log</literal>” additionally leads to the output of
+messages about reset identifiers to the
+<link doc="../ngx_core_module.xml" id="error_log"/>.
+</tag-desc>
+
+<tag-name id="var_uid_set"><var>$uid_set</var></tag-name>
+<tag-desc>
+The cookie name and sent client identifier.
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
 </module>
diff --git a/xml/ru/docs/http/ngx_http_userid_module.xml b/xml/ru/docs/http/ngx_http_userid_module.xml
--- a/xml/ru/docs/http/ngx_http_userid_module.xml
+++ b/xml/ru/docs/http/ngx_http_userid_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_userid_module"
         link="/ru/docs/http/ngx_http_userid_module.html"
         lang="ru"
-        rev="2">
+        rev="3">
 
 <section id="summary">
 
@@ -18,7 +18,8 @@
 Модуль <literal>ngx_http_userid_module</literal> выдаёт куки
 для идентификации клиентов.
 Для записи в лог полученных и выданных кук можно использовать встроенные
-переменные <var>$uid_got</var> и <var>$uid_set</var>.
+переменные <link id="var_uid_got">$uid_got</link> и
+<link id="var_uid_set">$uid_set</link>.
 Модуль совместим с модулем
 <link url="http://www.lexa.ru/programs/mod-uid.html">mod_uid</link>
 для Apache.
@@ -105,33 +106,50 @@ userid_p3p     'policyref="/w3c/p3p.xml"
 
 
 <directive name="userid_expires">
-<syntax><value>время</value> | <literal>max</literal></syntax>
-<default/>
+<syntax><value>время</value> | <literal>max</literal> |
+    <literal>off</literal></syntax>
+<default>off</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
 Задаёт время, в течение которого браузер должен хранить куку.
-Параметр <literal>max</literal> задаёт время 31 декабря 2037 года 23:55:55 GMT.
+Параметр <literal>max</literal> устанавливает срок хранения куки до
+31 декабря 2037 года 23:55:55 GMT.
 Это максимальное время, которое понимают старые браузеры.
+Указание параметра <literal>off</literal> позволяет ограничить время
+действия куки сессией браузера.
 </para>
 
 </directive>
 
 
 <directive name="userid_mark">
-<syntax><value>off | буква | цифра | =</value></syntax>
+<syntax>
+    <value>буква</value> | <value>цифра</value> |
+    <literal>=</literal> |
+    <literal>off</literal></syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
-Задаёт первый символ хвоста base64 (по умолчанию “<literal>==</literal>”)
-представления куки и перевыдаёт все принятые куки, у которых этот хвост другой.
-Это полезно, если необходимо добавить или поменять P3P или время
-хранения куки, но при этом оставить неизменным закодированное внутри число.
+Если параметр не <literal>off</literal>, включает механизм маркировки кук
+и задаёт символ, используемый в качестве метки.
+Этот механизм позволяет добавить или изменить
+<link id="userid_p3p"/> и/или время хранения куки, но при этом оставить
+неизменным идентификатор клиента.
+Меткой может быть любая буква английского алфавита (с учётом регистра),
+цифра или знак “<literal>=</literal>”.
+</para>
+
+<para>
+Если метка задана, то она сравнивается с первым дополняющим символом
+в base64 представлении идентификатора клиента, передаваемом в куке.
+Если они не совпадают, то кука перепосылается с заданной меткой,
+временем хранения и заголовком <header>P3P</header>.
 </para>
 
 </directive>
@@ -152,15 +170,17 @@ userid_p3p     'policyref="/w3c/p3p.xml"
 
 
 <directive name="userid_p3p">
-<syntax><value>строка</value></syntax>
-<default/>
+<syntax><value>строка</value> | <literal>none</literal></syntax>
+<default>none</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
-Задаёт значение для поля заголовка <header>P3P</header>, который будет
+Задаёт значение для поля заголовка <header>P3P</header>, которое будет
 выдаваться вместе с кукой.
+Если задано специальное значение <literal>none</literal>,
+то в ответе не будет заголовка <header>P3P</header>.
 </para>
 
 </directive>
@@ -181,20 +201,55 @@ userid_p3p     'policyref="/w3c/p3p.xml"
 
 
 <directive name="userid_service">
-<syntax><value>число</value></syntax>
+<syntax><value>номер</value></syntax>
 <default>IP-адрес сервера</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
 
 <para>
-Задаёт номер сервиса, выдавшего куку.
-По умолчанию для куки первой версии используется ноль,
-а для второй — IP-адрес сервера.
+Если идентификаторы выдаются несколькими серверами (сервисами),
+то каждому сервису следует назначить свой собственный <value>номер</value>,
+для обеспечения уникальности выдаваемых идентификаторов клиентов.
+По умолчанию для кук первой версии используется ноль.
+Для кук второй версии это число, составленное из последних четырёх
+октетов IP-адреса сервера.
 </para>
 
 </directive>
 
 </section>
 
+
+<section id="variables" name="Встроенные переменные">
+
+<para>
+Модуль <literal>ngx_http_userid_module</literal>
+поддерживает следующие встроенные переменные:
+<list type="tag">
+
+<tag-name id="var_uid_got"><var>$uid_got</var></tag-name>
+<tag-desc>
+Имя куки и полученный идентификатор клиента.
+</tag-desc>
+
+<tag-name id="var_uid_reset"><var>$uid_reset</var></tag-name>
+<tag-desc>
+Если значением является непустая строка не равная “<literal>0</literal>”,
+то клиентские идентификаторы перевыдаются.
+Специальное значение “<literal>log</literal>” дополнительно приводит к выдаче
+сообщений о перевыданных идентификаторах в
+<link doc="../ngx_core_module.xml" id="error_log"/>.
+</tag-desc>
+
+<tag-name id="var_uid_set"><var>$uid_set</var></tag-name>
+<tag-desc>
+Имя куки и выданный идентификатор клиента.
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
 </module>