Cada archivo del manual debe incluir las siguientes declaraciones XML al principio del archivo:
<?xml version="1.0" encoding="UTF-8"?> <!-- Reviewed: no -->
Los archivos XML de los idiomas traducidos también deben incluir una etiqueta de revisión que contenga la revisión del archivo correspondiente en inglés en la que se basó la traducción.
<?xml version="1.0" encoding="UTF-8"?> <!-- EN-Revision: 14978 --> <!-- Reviewed: no -->
La longitud máxima de línea, incluyendo etiquetas, atributos e indentación, no debe superar los 100 caracteres. Solo hay una excepción a esta regla: los pares de atributo y valor pueden superar los 100 caracteres, ya que no se les permite estar separados.
La indentación debe consistir en 4 espacios. No se permiten tabulaciones.
Las etiquetas que están en el mismo nivel deben tener la misma indentación.
<sect1> </sect1> <sect1> </sect1>
Las etiquetas que están un nivel por debajo de la etiqueta anterior deben indentarse con 4 espacios adicionales.
<sect1>
<sect2>
</sect2>
</sect1>
No se permiten varias etiquetas de bloque en la misma línea; sin embargo, sí se permiten varias etiquetas en línea.
<!-- NOT ALLOWED: -->
<sect1><sect2>
</sect2></sect1>
<!-- ALLOWED -->
<para>
<classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does.
</para>
La terminación de línea sigue la convención de archivos de texto Unix. Las líneas deben terminar con un único carácter de avance de línea (LF). Los caracteres de avance de línea se representan con el ordinal 10, o hexadecimal 0x0A.
Nota: No use retornos de carro (CR) como es la convención en los sistemas operativos de Apple (0x0D) ni la combinación de retorno de carro y avance de línea (CRLF) como es habitual en el sistema operativo Windows (0x0D, 0x0A).
No se permiten etiquetas vacías; todas las etiquetas deben contener texto o etiquetas hijas.
<!-- NOT ALLOWED -->
<para>
Some text. <link></link>
</para>
<para>
</para>
Las etiquetas de bloque de apertura no deben tener ningún espacio en blanco inmediatamente después de ellas, salvo los saltos de línea (y la indentación en la línea siguiente).
<!-- NOT ALLOWED --> <sect1>WHITESPACE </sect1>
Las etiquetas en línea de apertura no deben tener ningún espacio en blanco inmediatamente después de ellas.
<!-- NOT ALLOWED --> This is the class <classname> Zend_Class</classname>. <!-- OK --> This is the class <classname>Zend_Class</classname>.
Las etiquetas de bloque de cierre pueden estar precedidas por espacios en blanco equivalentes al nivel de indentación actual, pero no más que esa cantidad.
<!-- NOT ALLOWED -->
<sect1>
</sect1>
<!-- OK -->
<sect1>
</sect1>
Las etiquetas en línea de cierre no deben estar precedidas por ningún espacio en blanco.
<!-- NOT ALLOWED --> This is the class <classname>Zend_Class </classname> <!-- OK --> This is the class <classname>Zend_Class</classname>
No se permiten múltiples saltos de línea dentro o entre etiquetas.
<!-- NOT ALLOWED -->
<para>
Some text...
... and more text
</para>
<para>
Another paragraph.
</para>
<!-- OK -->
<para>
Some text...
... and more text
</para>
<para>
Another paragraph.
</para>
Las etiquetas en el mismo nivel deben separarse mediante una línea vacía para mejorar la legibilidad.
<!-- NOT ALLOWED -->
<para>
Some text...
</para>
<para>
More text...
</para>
<!-- OK -->
<para>
Some text...
</para>
<para>
More text...
</para>
La primera etiqueta hija debe abrirse directamente debajo de su padre, sin línea vacía entre ellas; la última etiqueta hija debe cerrarse justo antes de la etiqueta de cierre de su padre.
<!-- NOT ALLOWED -->
<sect1>
<sect2>
</sect2>
<sect2>
</sect2>
<sect2>
</sect2>
</sect1>
<!-- OK -->
<sect1>
<sect2>
</sect2>
<sect2>
</sect2>
<sect2>
</sect2>
</sect1>
La etiqueta de apertura <programlisting> debe indicar el atributo "language" apropiado y estar indentada al mismo nivel que sus bloques hermanos.
<para>Sibling paragraph.</para> <programlisting language="php"><![CDATA[
Debe usarse CDATA alrededor de todos los listados de programa.
Las secciones <programlisting> no deben añadir saltos de línea ni espacios en blanco al principio o al final de la sección, ya que estos se representarían en la salida final.
<!-- NOT ALLOWED --> <programlisting language="php"><![CDATA[ $render = "xxx"; ]]></programlisting> <!-- OK --> <programlisting language="php"><![CDATA[ $render = "xxx"; ]]></programlisting>
Las etiquetas de cierre de CDATA y <programlisting> deben estar en la misma línea, sin ninguna indentación.
<!-- NOT ALLOWED -->
<programlisting language="php"><![CDATA[
$render = "xxx";
]]>
</programlisting>
<!-- NOT ALLOWED -->
<programlisting language="php"><![CDATA[
$render = "xxx";
]]></programlisting>
<!-- OK -->
<programlisting language="php"><![CDATA[
$render = "xxx";
]]></programlisting>
La etiqueta <programlisting> debe contener el atributo "language" con un valor apropiado para el contenido del listado de programa. Los valores habituales incluyen "css", "html", "ini", "javascript", "php", "text" y "xml".
<!-- PHP --> <programlisting language="php"><![CDATA[ <!-- Javascript --> <programlisting language="javascript"><![CDATA[ <!-- XML --> <programlisting language="xml"><![CDATA[
Para listados de programa que contengan únicamente código PHP, las etiquetas PHP (por ejemplo, "<?php", "?>") no son necesarias, y no deben utilizarse. Simplemente sobrecargan la narrativa, y están implícitas por el uso de la etiqueta <programlisting>.
<!-- NOT ALLOWED -->
<programlisting language="php"<![CDATA[<?php
// ...
?>]]></programlisting>
<programlisting language="php"<![CDATA[
<?php
// ...
?>
]]></programlisting>
Las longitudes de línea dentro de los listados de programa deben seguir las recomendaciones del estándar de codificación.
Absténgase de usar llamadas a require_once(),
require(), include_once() e
include() dentro de los listados PHP.
Simplemente sobrecargan la narrativa, y quedan en gran parte obviadas cuando se usa un
autocargador. Úselas solo cuando sean esenciales para el ejemplo.
![[Note]](images/note.png) |
Nunca use etiquetas cortas |
|---|---|
Las etiquetas cortas (por ejemplo, "<?", "<?=") nunca deben usarse dentro de programlisting o en la narrativa de un documento. |
La etiqueta <classname> debe usarse cada vez que se represente un nombre de clase por sí solo; no debe usarse cuando se combina con un nombre de método, nombre de variable o constante, y no se permite ningún otro contenido dentro de la etiqueta.
<para>
The class <classname>Zend_Class</classname>.
</para>
Las variables deben envolverse en la etiqueta <varname>. Las variables deben escribirse usando el símbolo "$". No se permite ningún otro contenido dentro de esta etiqueta, salvo que se use un nombre de clase, lo cual indica una variable de clase.
<para>
The variable <varname>$var</varname> and the class variable
<varname>Zend_Class::$var</varname>.
</para>
Los métodos deben envolverse en la etiqueta <methodname>. Los métodos deben incluir la firma completa del método o, como mínimo, un par de paréntesis de cierre (por ejemplo, "()"). No se permite ningún otro contenido dentro de esta etiqueta, salvo que se use un nombre de clase, lo cual indica un método de clase.
<para>
The method <methodname>foo()</methodname> and the class method
<methodname>Zend_Class::foo()</methodname>. A method with a full signature:
<methodname>foo($bar, $baz)</methodname>
</para>
Use la etiqueta <constant> para denotar constantes. Las constantes deben escribirse en MAYÚSCULAS. No se permite ningún otro contenido dentro de esta etiqueta, salvo que se use un nombre de clase, lo cual indica una constante de clase.
<para>
The constant <constant>FOO</constant> and the class constant
<constant>Zend_Class::FOO</constant>.
</para>
Los nombres de archivo y las rutas deben envolverse en la etiqueta <filename>. No se permite ningún otro contenido en esta etiqueta.
<para>
The filename <filename>application/Bootstrap.php</filename>.
</para>
Los comandos, scripts de shell y llamadas a programas deben envolverse en la etiqueta <command>. Si el comando incluye argumentos, estos también deben incluirse dentro de la etiqueta.
<para>
Execute <command>zf.sh create project</command>.
</para>