[Sync-En] filters: document the role of the zlib window parameter (#1316)

Author: lacatoire

appendices/filters.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 3f1dbc451b313fb1ec8058f24c1beccf55fce316 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 82b5e0afeb38142e91fbba05f06b46c3129420ba Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no Maintainer: Marqitos -->
 <appendix xml:id="filters" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Lista de filtros estándar</title>
@@ -54,8 +54,8 @@
 <?php
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'string.rot13');
-fwrite($fp, "Ceci est un test.\n");
-/* muestra :  Prpv rfg ha grfg.   */
+fwrite($fp, "Esto es una prueba.\n");
+/* Muestra:  Rfgb rf han cehron.   */
 ?>
 ]]>
     </programlisting>
@@ -75,8 +75,8 @@ fwrite($fp, "Ceci est un test.\n");
 <?php
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'string.toupper');
-fwrite($fp, "Ceci est un test.\n");
-/* muestra :  CECI EST UN TEST.   */
+fwrite($fp, "Esto es una prueba.\n");
+/* Muestra:  ESTO ES UNA PRUEBA.   */
 ?>
 ]]>
     </programlisting>
@@ -96,8 +96,8 @@ fwrite($fp, "Ceci est un test.\n");
 <?php
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'string.tolower');
-fwrite($fp, "Ceci est un test.\n");
-/* muestra :  ceci est un test.   */
+fwrite($fp, "Esto es una prueba.\n");
+/* Muestra:  esto es una prueba.   */
 ?>
 ]]>
     </programlisting>
@@ -121,16 +121,16 @@ fwrite($fp, "Ceci est un test.\n");
 <![CDATA[
 <?php
 $fp = fopen('php://output', 'w');
-stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<strong><em><span>");
-fwrite($fp, "<strong>Ce texte en gras</strong> finit par être agrandi <h1>en un titre 1</h1>\n");
+stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<b><i><u>");
+fwrite($fp, "<b>texto en negrita</b> ampliado a un <h1>encabezado de nivel 1</h1>\n");
 fclose($fp);
-/* muestra :  Ce texte en gras finit par être agrandi en un titre 1   */
+/* Muestra:  texto en negrita ampliado a un encabezado de nivel 1   */
 
 $fp = fopen('php://output', 'w');
-stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, array('strong','em','span'));
-fwrite($fp, "<strong>Ce texte en gras</strong> finit par être agrandi <h1>en un titre 1</h1>\n");
+stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, array('b','i','u'));
+fwrite($fp, "<b>texto en negrita</b> ampliado a un <h1>encabezado de nivel 1</h1>\n");
 fclose($fp);
-/* muestra :  Ce texte en gras finit par être agrandi en un titre 1   */
+/* Muestra:  texto en negrita ampliado a un encabezado de nivel 1   */
 ?>
 ]]>
     </programlisting>
@@ -174,22 +174,22 @@ $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'convert.base64-encode');
 fwrite($fp, "This is a test.\n");
 fclose($fp);
-/* muestra :  VGhpcyBpcyBhIHRlc3QuCg==  */
+/* Muestra:  VGhpcyBpcyBhIHRlc3QuCg==  */
 
 $param = array('line-length' => 8, 'line-break-chars' => "\r\n");
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'convert.base64-encode', STREAM_FILTER_WRITE, $param);
 fwrite($fp, "This is a test.\n");
 fclose($fp);
-/* muestra :  VGhpcyBp
-           :  cyBhIHRl
-           :  c3QuCg==  */
+/* Muestra:  VGhpcyBp
+          :  cyBhIHRl
+          :  c3QuCg==  */
 
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'convert.base64-decode');
 fwrite($fp, "VGhpcyBpcyBhIHRlc3QuCg==");
 fclose($fp);
-/* muestra :  This is a test.  */
+/* Muestra:  This is a test.  */
 ?>
 ]]>
     </programlisting>
@@ -223,7 +223,7 @@ fclose($fp);
 $fp = fopen('php://output', 'w');
 stream_filter_append($fp, 'convert.quoted-printable-encode');
 fwrite($fp, "This is a test.\n");
-/* muestra :  =This is a test.=0A  */
+/* Muestra:  =This is a test.=0A  */
 ?>
 ]]>
     </programlisting>
@@ -282,7 +282,7 @@ fclose($fp);
 
   <section xml:id="filters.compression.zlib">
    <title>zlib.deflate y zlib.inflate</title>
-   <simpara>
+   <para>
     <literal>zlib.deflate</literal> (compresión) y
     <literal>zlib.inflate</literal> (descompresión) son las implementaciones
     de los métodos de compresión presentados en la
@@ -296,18 +296,135 @@ fclose($fp);
     0, que representa la ausencia de compresión, y -1, que representa el nivel por defecto de zlib:
     actualmente, 6.
 
-    <parameter>window</parameter> es el tamaño del buffer de memoria, en base 2.
-    Los valores superiores, hasta 15, es decir, 32768 bytes, dan mejores
-    compresiones, y los valores inferiores, hasta 9, es decir, 512 bytes,
-    ocupan menos espacio en memoria. Por defecto,
+    <parameter>window</parameter> es el logaritmo en base 2 del tamaño de la
+    ventana de compresión. Los valores superiores, hasta 15, es decir, 32768 bytes,
+    dan una mejor compresión a costa de más memoria, y los valores inferiores,
+    hasta 9, es decir, 512 bytes, dan una compresión menor ocupando menos
+    espacio en memoria. Por defecto,
     <parameter>window</parameter> vale actualmente <literal>15</literal>.
 
-    <parameter>memory</parameter> es una indicación del nivel de memoria
-    necesario.
+    El filtro <literal>zlib.deflate</literal> implementa los métodos de
+    compresión <literal>DEFLATE</literal>, <literal>ZLIB</literal> y
+    <literal>GZIP</literal> según el valor del parámetro
+    <parameter>window</parameter>.
+
+    Los 4 bits inferiores del parámetro window fijan el tamaño del
+    «búfer de historial» interno utilizado, siendo el logaritmo en base 2 de su
+    tamaño, en un rango de 8 a 15. El significado de los demás bits del
+    parámetro window puede fijarse como se describe a continuación.
+
+    <itemizedlist>
+     <listitem>
+      <simpara>
+       <literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>)
+       es un algoritmo de compresión sin tratar, sin encabezado ni suma de
+       verificación. Se aplica cuando el parámetro window se fija en el rango
+       de -9 a -15. Este algoritmo de compresión es la base de todos los
+       formatos generados por el filtro <literal>zlib.deflate</literal>.
+       Las funciones correspondientes que operan directamente sobre strings son
+       <function>gzdeflate</function> y <function>gzinflate</function>.
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+       <literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>)
+       aplica el algoritmo <literal>DEFLATE</literal> y añade un encabezado de
+       2 bytes y un tráiler de 4 bytes que contiene la suma de verificación
+       Adler32 de los datos sin comprimir, en orden de bytes big-endian:
+       <literal><![CDATA[ZLIB = ZLIBHEADER(2B)  DEFLATE  ADLER32(4B)]]></literal>
+
+       El encabezado de 2 bytes, leído como un número de 16 bits sin signo en
+       orden big-endian, debe ser múltiplo de 31.
+       Este formato se genera cuando el parámetro window se fija en el rango
+       de 8 a 15.
+       Las funciones correspondientes que operan directamente sobre strings son
+       <function>gzcompress</function> y <function>gzuncompress</function>.
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+       <literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>)
+       aplica el algoritmo <literal>DEFLATE</literal> añadiendo un encabezado y
+       un tráiler con la suma de verificación <literal>CRC32</literal> de los
+       datos sin comprimir y su longitud, ambos en orden de bytes little-endian:
+       <literal><![CDATA[GZIP = GZIPHEADER(10B)  DEFLATE  CRC32(4B)  LENGTH(4B)]]></literal>
+
+       Es el formato de los ficheros <literal>.gz</literal>, en el que
+       <literal>GZIPHEADER</literal> contiene, en este orden, la firma
+       <literal>GZIP</literal> (<literal>\x1f\x8B</literal>), el método de
+       compresión (<literal>\x08</literal>), un byte de flags a cero, una fecha
+       de modificación a cero en 4 bytes, un byte de flags adicionales que
+       depende del nivel de compresión, y el sistema operativo fijado al sistema
+       actual (<literal>\x00</literal> = sistema de ficheros FAT,
+       <literal>\x03</literal> = Unix, etc.).
+       Este formato se genera cuando el parámetro window se fija en el rango
+       de 9+16=25 a 15+16=31. Tenga en cuenta que existe un límite de 4GB para
+       la longitud máxima de los datos sin comprimir; más allá de este límite,
+       solo se almacena el módulo 2^32 de la longitud real en la parte
+       <literal>LENGTH</literal>.
+       Las funciones correspondientes que operan directamente sobre strings son
+       <function>gzencode</function> y <function>gzdecode</function>; la
+       función <function>gzopen</function> permite leer y escribir ficheros
+       <literal>.gz</literal>.
+      </simpara>
+     </listitem>
+    </itemizedlist>
+
+    Con el filtro <literal>zlib.inflate</literal>, solo se admite el parámetro
+    <parameter>window</parameter>; cualquier otro parámetro
+    (<parameter>memory</parameter>, <parameter>level</parameter>) se ignora.
+    Sea $W el logaritmo en base 2 del tamaño del búfer de historial, de modo
+    que el descompresor asigna 2^$W bytes. Para el formato ZLIB, este valor
+    debe ser mayor o igual al registrado en el encabezado, lo cual se
+    comprueba durante la descompresión; para los demás formatos, basta con
+    que sea lo suficientemente grande para las distancias de coincidencia
+    realmente presentes en los datos.
+    El rango es 9 ≤ $W ≤ 15. Si se desconoce, $W=15 es la opción más segura.
+
+    <itemizedlist>
+     <listitem>
+      <simpara>
+       <literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>):
+        utilice window=-$W, siendo $W un valor no inferior al utilizado para
+        la compresión. Si se desconoce, fije window=-15.
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+       <literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>):
+        utilice window=$W. El valor de $W puede obtenerse del propio encabezado
+        ZLIB; en caso contrario, fije window=15.
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+       <literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>):
+       utilice window=$W+16. Un encabezado GZIP no contiene el tamaño de la
+       ventana, por lo que debe fijarse window=31, salvo que se conozca el valor
+       utilizado para la compresión.
+      </simpara>
+     </listitem>
+
+     <listitem>
+      <simpara>
+       <literal>ZLIB o GZIP</literal>:
+       utilice window=$W+32 para la detección automática del encabezado, de
+       modo que ambos formatos puedan reconocerse y descomprimirse;
+       window=15+32=47 es la opción más segura.
+      </simpara>
+     </listitem>
+    </itemizedlist>
+
+    <parameter>memory</parameter> es una escala que indica cuánta memoria de
+    trabajo debe asignarse.
     Los valores válidos van de 1, para la asignación mínima, a 9, para una
-    asignación máxima. La asignación de memoria afecta la velocidad de ejecución,
-    y no el coste global.
-   </simpara>
+    asignación máxima. La asignación de memoria afecta únicamente a la velocidad
+    de ejecución y no influye en el tamaño de los datos generados.
+   </para>
 
    <note>
     <simpara>
@@ -332,23 +449,23 @@ fclose($fp);
 $params = array('level' => 6, 'window' => 15, 'memory' => 9);
 
 $original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
-echo "El texto original es largo de " . strlen($original_text) . " bytes.\n";
+echo "El texto original tiene " . strlen($original_text) . " caracteres.\n";
 
 $fp = fopen('test.deflated', 'w');
 stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, $params);
 fwrite($fp, $original_text);
 fclose($fp);
 
-echo "El fichero comprimido hace " . filesize('test.deflated') . " bytes de largo.\n";
-echo "El texto original era :\n";
+echo "El fichero comprimido tiene " . filesize('test.deflated') . " bytes.\n";
+echo "El texto original era:\n";
 /* Utiliza readfile y zlib.inflate para descomprimir al vuelo */
 readfile('php://filter/zlib.inflate/resource=test.deflated');
 
-/* Muestra :
+/* Muestra:
 
-El texto original es largo de 70 bytes
-El fichero comprimido hace 56 bytes de largo.
-El texto original era :
+El texto original tiene 70 caracteres.
+El fichero comprimido tiene 56 bytes.
+El texto original era:
 This is a test.
 This is only a test.
 This is not an important string.
@@ -367,20 +484,20 @@ This is not an important string.
 <![CDATA[
 <?php
 $original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
-echo "El texto original es largo de " . strlen($original_text) . " bytes.\n";
+echo "El texto original tiene " . strlen($original_text) . " caracteres.\n";
 
 $fp = fopen('test.deflated', 'w');
 /* Aquí, "6" indica el nivel de compresión de 6 */
 stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, 6);
 fwrite($fp, $original_text);
 fclose($fp);
 
-echo "El fichero comprimido hace " . filesize('test.deflated') . " bytes de largo.\n";
+echo "El fichero comprimido tiene " . filesize('test.deflated') . " bytes.\n";
 
-/* Muestra :
+/* Muestra:
 
-El texto original es largo de 70 bytes
-El fichero comprimido hace 56 bytes de largo.
+El texto original tiene 70 caracteres.
+El fichero comprimido tiene 56 bytes.
 
  */
 ?>
@@ -404,7 +521,7 @@ El fichero comprimido hace 56 bytes de largo.
 
     <parameter>work</parameter> es también un &integer; cuyo valor va de
     0 a 250, e indica el nivel de esfuerzo proporcionado con un método de
-    compresión antes de pasar a otro método, más lento. Modificar este
+    compresión antes de pasar a otro método, más lento pero más fiable. Modificar este
     parámetro solo tiene efecto en la velocidad de compresión. La ganancia de espacio
     o la memoria utilizada permanecen iguales. Un nivel de 0 indica que la
     biblioteca debe utilizar su configuración por defecto.
@@ -432,19 +549,19 @@ El fichero comprimido hace 56 bytes de largo.
 <?php
 $param = array('blocks' => 9, 'work' => 0);
 
-echo "El fichero original hace " . strlen(LICENSE) . " bytes de largo.\n";
+echo "El fichero original tiene " . filesize('LICENSE') . " bytes.\n";
 
 $fp = fopen('LICENSE.compressed', 'w');
 stream_filter_append($fp, 'bzip2.compress', STREAM_FILTER_WRITE, $param);
 fwrite($fp, file_get_contents('LICENSE'));
 fclose($fp);
 
-echo "El fichero comprimido hace " . filesize('LICENSE.compressed') . " bytes de largo.\n";
+echo "El fichero comprimido tiene " . filesize('LICENSE.compressed') . " bytes.\n";
 
-/* Muestra :
+/* Muestra:
 
-El fichero original hace 3288 bytes de largo.
-El fichero comprimido hace 1488 bytes de largo.
+El fichero original tiene 3288 bytes.
+El fichero comprimido tiene 1488 bytes.
 
  */
 ?>
@@ -484,8 +601,8 @@ El fichero comprimido hace 1488 bytes de largo.
       <thead>
        <row>
         <entry>Parámetro</entry>
-        <entry>Obligatorio ?</entry>
-        <entry>Por omisión</entry>
+        <entry>¿Obligatorio?</entry>
+        <entry>Por defecto</entry>
         <entry>Valores posibles</entry>
        </row>
       </thead>
@@ -500,13 +617,13 @@ El fichero comprimido hace 1488 bytes de largo.
         <entry>algorithms_dir</entry>
         <entry>Opcional</entry>
         <entry>ini_get('mcrypt.algorithms_dir')</entry>
-        <entry>Ruta hacia los algoritmos de módulos</entry>
+        <entry>Ubicación de los módulos de algoritmos</entry>
        </row>
        <row>
         <entry>modes_dir</entry>
         <entry>Opcional</entry>
         <entry>ini_get('mcrypt.modes_dir')</entry>
-        <entry>Ruta hacia los modos de módulos</entry>
+        <entry>Ubicación de los módulos de modos</entry>
        </row>
        <row>
         <entry>iv</entry>