archived-doc-es/appendices/about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->

<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Acerca del manual</title>

 <sect1 xml:id="about.formats">
  <title>Formatos</title>
  <para>
   El manual de PHP se proporciona en diferentes formatos. Estos formatos se dividen en
   dos grupos: los que están disponibles en línea y los que se pueden descargar.
  </para>
  <note>
   <para>
    Algunos editores han proporcionado versiones impresas de este manual. No se recomienda ninguna, ya que se vuelven obsoletas rápidamente.
   </para>
  </note>
  <para>
   El manual puede ser leído en línea en el sitio
   <link xlink:href="&url.php;">php.net</link>.
   La versión en línea del manual de PHP tiene actualmente dos renderizados
   <acronym>CSS</acronym>: uno agradable a la vista y otro práctico para
   la impresión.
  </para>
  <para>
   Dos ventajas del manual en línea sobre la mayoría de los formatos
   descargables son la integración de las <link
   linkend="about.notes">notas de los usuarios</link> y los <link
   xlink:href="&url.php.urlhowto;">URL de acceso directo</link> que se pueden utilizar
   para acceder rápidamente a una parte del manual. Una desventaja
   evidente es que se debe estar en línea para disfrutar de este formato.
  </para>
  <para>
   Hay muchos formatos del manual para la consulta fuera de línea, y
   el formato más adecuado depende de su sistema operativo y de sus gustos personales.
   Para saber cómo se genera el manual, lea la sección
   <link linkend="about.generate">'Cómo se genera el manual'</link> de este
   apéndice.
  </para>
  <para>
   El formato más portable es el HTML. El manual se proporciona
   en un formato de una sola página HTML, o como un conjunto de ficheros
   de tamaño reducido (pero un buen millar de ficheros en total). Proporcionamos este formato en una forma comprimida, por lo que se necesitará
   una utilidad de descompresión para extraer los ficheros del archivo.
  </para>
  <para>
   Para las plataformas Windows, el formato
   <productname>Windows HTML Help</productname> proporciona una versión HTML
   del manual para usar con la aplicación <productname>Windows HTML Help</productname>:
   incluye un motor de búsqueda completo, un índice y marcadores. Muchos IDE en Windows proporcionan enlaces con este formato para una mejor integración. También existen visualizadores de CHM para
   Linux. Visite <link xlink:href="&url.xchm;">xCHM</link> o <link
   xlink:href="&url.gnochm;">GnoCHM</link>.
  </para>
  <para>
   También existe una <link xlink:href="&url.php.echm;">versión CHM
   extendida</link>, que se actualiza con menos frecuencia pero que proporciona más
   funcionalidades. Solo funcionará en <productname>Microsoft
   Windows</productname> debido a las tecnologías utilizadas para construir
   estas páginas.
  </para>
 </sect1>

 <sect1 xml:id="about.notes">
  <title>Acerca de las notas de los usuarios</title>
  <para>
   Las notas de los usuarios juegan un papel muy importante en el
   desarrollo de este manual. Al permitir a los lectores contribuir con
   ejemplos, comentarios y críticas, o aclaraciones, se integran aspectos muy importantes del lenguaje en el manual. Hasta que las notas más importantes se integren en la documentación,
   están disponibles en el sitio mismo, y en algunos formatos fuera de línea.
  </para>
  <note>
   <para>
    Las notas de los usuarios no son moderadas antes de aparecer en el
    sitio, y aunque lo sean, su veracidad no puede ser garantizada,
    al igual que no existe garantía en cuanto a la exactitud del manual mismo.
   </para>
  </note>
  <note>
   <para>
    Por cuestiones de alcance de la licencia, las notas de los usuarios se
    consideran parte del manual de PHP, y por lo tanto están cubiertas por
    la misma licencia que cubre esta documentación (Creative Commons Attribution
    hasta la fecha). Para más detalles, lea la página <link
    linkend="copyright">Derechos de autor del manual</link>.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="about.prototypes">
  <title>Cómo leer la definición de una función (prototipo)</title>
  <para>
   Cada función en el manual está documentada para permitir una
   comprensión rápida. Saber descifrar el texto facilitará su aprendizaje. En lugar de depender de ejemplos listos para copiar/pegar, es más útil saber leer la definición de una función (prototipo).
   Así es cómo:
  </para>
  <note>
   <title>
    Prerrequisitos: Conocimientos básicos de los
    <link linkend="language.types">tipos</link>.
   </title>
   <para>
    Aunque PHP es un lenguaje sin tipado fuerte, un conocimiento
    básico de los <link linkend="language.types">tipos</link> es esencial,
    ya que tienen significados importantes.
   </para>
  </note>
  <para>
   Las definiciones de funciones indican qué tipo de datos es
   <link linkend="functions.returning-values">devuelto</link>. Examinemos
   la función <function>strlen</function> como ejemplo:
  </para>
  <para>
   <screen role="html">
<![CDATA[
strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Devuelve el tamaño de la cadena

Descripción
strlen ( string $string ) : int

Devuelve el tamaño de la cadena $string.
]]>
   </screen>
  </para>
  <para>
   <table>
    <title>Explicaciones de la definición de la función</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Parte</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>
        strlen
       </entry>
       <entry>
        El nombre de la función.
       </entry>
      </row>
      <row>
       <entry>
        (PHP 4, PHP 5, PHP 7)
       </entry>
       <entry>
        strlen() está presente en todas las versiones de PHP 4, 5 y 7.
       </entry>
      </row>
      <row>
       <entry>
        ( string $string )
       </entry>
       <entry>
        El primer (y aquí el único) parámetro a proporcionar a esta función es el parámetro <parameter>string</parameter>, que debe ser del tipo
        &string;.
       </entry>
      </row>
      <row>
       <entry>
        int
       </entry>
       <entry>
        Tipo de valor devuelto por esta función, que es, en este caso,
        un &integer; (es decir, el tamaño de una cadena se mide por
        un número).
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   Podríamos reescribir este prototipo con una versión más genérica:
  </para>
  <para>
   <screen>
<![CDATA[
      nombre de la función    ( tipo del parámetro   nombre del parámetro ) : tipo de retorno
]]>
   </screen>
  </para>
  <para>
   Varias funciones necesitan varios parámetros,
   como <function>in_array</function>.
   Su prototipo es el siguiente:
  </para>
  <para>
   <screen>
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
   </screen>
  </para>
  <para>
   ¿Qué significa esto? <function>in_array</function> devuelve
   un <link linkend="language.types.boolean">booléano</link> &true; en
   caso de éxito (el parámetro
   <parameter>needle</parameter> se encontró en el array
   <parameter>haystack</parameter>)&return.falseforfailure;
   (el parámetro <parameter>needle</parameter> no se encontró
   en el array <parameter>haystack</parameter>). El primer
   parámetro se llama <parameter>needle</parameter> y puede ser
   de diferentes <link linkend="language.types">tipos</link>: por lo tanto, lleva la mención <emphasis>mixed</emphasis>.
   El parámetro <parameter>needle</parameter> (lo que estamos buscando)
   puede ser un valor escalar ( &string;, &integer;,
   o <link linkend="language.types.float">float</link>), o incluso un <type>array</type>.
   <parameter>haystack</parameter> (el <link linkend="language.types.array">array</link>,
   en el que estamos buscando) es
   el segundo parámetro. El tercer parámetro, <emphasis>opcional</emphasis>,
   <parameter>strict</parameter>,
   es opcional. Todos los parámetros opcionales tienen un valor por defecto;
   si el valor por defecto es desconocido, se muestra como <literal>?</literal>.
   El manual indica que el parámetro <parameter>strict</parameter> vale por
   defecto &false;. Consulte el manual de cada función para saber
   cómo funciona.
  </para>
  <para>
   Además, el signo &amp; (e comercial) añadido al principio del parámetro de
   una función permite pasar este parámetro por
   <link linkend="language.references.pass">referencia</link>, como en este ejemplo:
  </para>
  <para>
   <screen>
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
     </screen>
  </para>
  <para>
   En este ejemplo, se puede ver que el tercer parámetro opcional
   <parameter>&amp;$matches</parameter> será pasado por referencia.
  </para>
  <para>
   También hay funciones con información más compleja
   sobre las versiones de PHP. Tomemos
   <function>html_entity_decode</function> como ejemplo:
  </para>
  <para>
   <screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
   </screen>
  </para>
  <para>
   Esto significa que esta función solo está disponible
   desde PHP 4.3.0.
  </para>
 </sect1>

 <sect1 xml:id="about.phpversions">
  <title>Versiones de PHP documentadas en este manual</title>
  <para>
   Este manual contiene información sobre las versiones antiguas, actuales y futuras
   de PHP. Los cambios de comportamiento están documentados en forma de notas, historiales de versiones,
   pero también en las páginas del manual. La versión documentada más antigua es la versión 7.0.0.
  </para>
  <para>
   Cuando la documentación existe para las últimas versiones de desarrollo (no publicadas)
   de PHP, se titulará "disponible en Git" o "versión de desarrollo." Estos
   cambios están previstos, pero aún pueden evolucionar en raros casos.
  </para>
  <para>
   Todos los desarrollos están versionados en el depósito Git y pueden ser recuperados como se describe en
   <link xlink:href="&url.php.anongit;">acceso anónimo Git</link>.
  </para>
  <para>
   Y por cuestiones de claridad, el manual hará referencia a las versiones mayores, menores y
   revisiones de PHP. Por ejemplo, PHP <literal>7.3.1</literal>, el <emphasis>7</emphasis>
   es la versión mayor, <emphasis>3</emphasis> la menor, y
   <emphasis>1</emphasis> la revisión. Típicamente, PHP solo agrega nuevas funcionalidades
   en las versiones mayores o menores, y corrige errores en las revisiones. Sin embargo,
   esta convención no siempre se verifica.
  </para>
  <para>
   Tenga en cuenta también que el manual se refiere al PHP presente y no futuro, incluso para las funcionalidades
   documentadas y que aún no están disponibles. Así, el manual puede perdurar en el
   tiempo y no requiere actualizaciones importantes con cada lanzamiento de PHP.
  </para>
  <para>
   En varias ocasiones, el manual de PHP enumera los valores por defecto de
   las directivas de PHP. Estos valores se basan en el comportamiento de PHP sin archivo de
   configuración &php.ini;, por lo que pueden cambiar de los valores encontrados en los archivos
   distribuidos <filename>php.ini-development</filename> y <filename>php.ini-production</filename>. Los valores indicados son también los de la última versión de PHP, un registro de cambios indica los valores previamente empleados. Vea <link linkend="ini.list">el apéndice sobre las directivas PHP
   </link> para más detalles sobre estos valores y sus evoluciones.
  </para>
 </sect1>

 <sect1 xml:id="about.more">
  <title>Dónde encontrar más información sobre PHP ?</title>
  <para>
   Este manual no tiene como objetivo proporcionar presentaciones sobre las
   prácticas de programación. Si es un completo novato, o incluso
   un programador principiante, puede encontrar difícil aprender
   la programación PHP con solo este manual: sería mejor encontrar
   recursos más orientados al aprendizaje.
  </para>
  <para>
   Hay un buen número de listas de difusión activas, que tratan todos los
   aspectos del lenguaje y la programación PHP. Si está bloqueado por un
   problema, probablemente pueda encontrar ayuda en estas listas.
   Existe un recuento de las listas de difusión en
   <link xlink:href="&url.php.support;">la página de soporte de php.net</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.howtohelp">
  <title>Cómo ayudar a mejorar la documentación ?</title>
  <para>
   Hay varias formas de participar en la mejora de la documentación.
  </para>
  <para>
   Si se encuentra un error, en cualquier traducción de la
   documentación, informe del error en el gestor de incidencias del
   depósito de idioma respectivo en <link xlink:href="&url.php.git;">&url.php.git;</link>;;
   por ejemplo, los errores en el manual en inglés deben ser reportados a
   <link xlink:href="&url.php.git;doc-en/issues">&url.php.git;doc-en/issues</link>;
   Todas las incidencias relacionadas con la documentación, así como sus formatos,
   deben ser enviadas como errores.
  </para>
  <note>
   <para>
    No abuse del gestor de incidencias para enviar solicitudes de ayuda. Utilice
    más bien una de las opciones propuestas por el <link xlink:href="&url.php.support;">soporte</link>.
   </para>
  </note>
  <para>
   Al contribuir con notas, se pueden proporcionar nuevos ejemplos,
   destacar efectos secundarios y aportar aclaraciones para
   los demás lectores. Pero no tome el sistema de anotación como un sistema de envío de errores. Puede obtener más información sobre las
   anotaciones en la sección
   <link linkend="about.notes">'Acerca de las notas de los usuarios'</link>
  </para>
  <para>
   También es posible enviar solicitudes de extracción al
   <link xlink:href="&url.php.git.mirror;doc-en">espejo Github del repositorio de la documentación</link>.
  </para>
  <para>
   El manual de PHP está traducido a muchos idiomas. El conocimiento
   del inglés así como de otro idioma puede permitir ayudar
   a la documentación de PHP trabajando con un equipo de traducción.
   Para más información sobre cómo comenzar una traducción, o
   sobre cómo ayudar a una versión ya traducida, comience por leer
   <link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
  </para>
  <para>
   El proyecto de documentación de PHP tiene un canal IRC donde se puede venir
   y hablar con los autores del manual o encontrar un cierto aspecto del manual
   con el cual se podría ayudar. Las coordenadas:
   <literal>#php.doc</literal> en <literal>irc.efnet.org</literal>.
  </para>
 </sect1>

 <sect1 xml:id="about.generate">
  <title>Cómo se generan las documentaciones</title>
  <para>
   Este manual está escrito en <acronym>XML</acronym>, utilizando
   la <link xlink:href="&url.docbook.xml;">DTD de DocBook XML</link>, y
   <link xlink:href="&url.phd;"><acronym>PhD</acronym></link> (El motor
   [PH]P de visualización [D]ocBook) para el mantenimiento y el formateo.
  </para>
  <para>
   Gracias al formato <acronym>XML</acronym> como fuente, se tiene
   la posibilidad de generar muchos formatos teniendo una
   sola fuente para todos los formatos. La herramienta utilizada para formatear el manual
   en línea es <link xlink:href="&url.phd;">PhD</link>.
   Se utiliza <link xlink:href="&url.winhelp;">Microsoft HTML Help
   Workshop</link> para generar el formato <productname>Windows HTML Help</productname> del manual, y,
   por supuesto, PHP mismo para realizar conversiones y formateo.
  </para>
  <para>
   El manual de PHP se genera en muchos idiomas y formatos, lea
   <link xlink:href="&url.php.docs;">&url.php.docs;</link> para más información.
   El código fuente <acronym>XML</acronym> puede ser descargado desde git y
   visualizado en <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.translations">
  <title>Traducciones</title>
  <para>
   El manual de PHP está disponible no solo en inglés, sino también en
   diferentes idiomas. El texto del manual se escribe primero en inglés, luego
   equipos de todo el mundo aseguran la traducción del manual a su idioma nativo. Si la traducción de una sección aún no está disponible,
   el sistema de creación de la documentación presentará entonces la versión
   en inglés.
  </para>
  <para>
   Los contribuyentes a la documentación parten de los códigos fuente
   <acronym>XML</acronym> disponibles en
   <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
   luego traducen a su idioma. No utilizan
   las versiones generadas (como el <acronym>HTML</acronym> o el texto plano)
   ya que es el sistema de edición el que se encarga de hacer las
   conversiones del formato <acronym>XML</acronym> a un formato legible.
  </para>
  <note>
   <para>
    Si desea ayudar con la traducción de la documentación, póngase en contacto con el equipo de documentación inscribiéndose en la lista de difusión: <link
    xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
    La dirección de la lista de difusión es <literal>&email.php.doc;</literal>.
    Indique en el mensaje que está interesado en la traducción de la
    documentación a un nuevo idioma, y alguien vendrá a ayudar a comenzar una nueva traducción, o unirse al equipo que ha tomado
    a cargo esta traducción.
   </para>
  </note>
  <para>
   Actualmente, el manual está disponible, parcial o totalmente, en
   más de 10 idiomas.
  </para>
  <para>
   Todos pueden ser descargados aquí:
   <link xlink:href="&url.php.docs;">&url.php.docs;</link>.
  </para>
 </sect1>
</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->