# Norma sobre a documentação do Zend Framework

## Visão Geral

### Escopo

Este documento fornece diretrizes para a criação da documentação de usuário final fornecida junto com o Zend Framework. É um guia destinado aos colaboradores do Zend Framework, que devem escrever a documentação como parte de suas contribuições de componentes, bem como aos tradutores de documentação. As normas contidas neste documento são destinadas a facilitar a tradução da documentação, minimizar as diferenças visuais e de estilo entre os diferentes arquivos de documentação, e facilitar a busca por diferenças na documentação com o comando `diff`.

Você pode adotar e/ou modificar estas normas, em conformidade com os termos de nossa licença.

Os tópicos compreendidos nas normas sobre a documentação do Zend Framework incluem a formatação dos arquivos de documentação e recomendações sobre a qualidade da documentação.

## Formatação dos Arquivos de Documentação

### Tags XML

Cada arquivo do manual deve incluir as seguintes declarações XML no topo do arquivo:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Reviewed: no -->

Os arquivos XML provenientes de traduções devem também incluir uma tag de revisão contendo a revisão do arquivo correspondente em inglês na qual a tradução se baseou.

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 14978 -->
    <!-- Reviewed: no -->

### Comprimento Máximo da Linha

O comprimento máximo da linha, incluindo tags, atributos e indentação, não deve exceder 100 caracteres. Existe apenas uma exceção a essa regra: os pares de atributo e valor são autorizados a ultrapassar os 100 caracteres, desde que não seja permitido estarem separados.

### Indentação

A indentação deve ser composta por 4 espaços. Tabs não são permitidos.

Tags que estão no mesmo nível devem ter a mesma indentação.

    <sect1>
    </sect1>

    <sect1>
    </sect1>

Tags que estão um nível abaixo da tag anterior devem ser indentadas com 4 espaços adicionais.

    <sect1>
        <sect2>
        </sect2>
    </sect1>

Vários elementos de bloco dentro de uma mesma linha não são permitidos, no entanto vários elementos inline são permitidos.

    <!-- NÃO PERMITIDO -->
    <sect1><sect2>
    </sect2></sect1>

    <!-- PERMITIDO -->
    <para>
        <classname>Zend_Magic</classname> não existe. <classname>Zend_Acl</classname> existe.
    </para>

### Terminação de Linha

A terminação de linha segue a convenção para arquivos de texto do Unix. As linhas devem terminar com um simples caractere line feed (LF). Caracteres line feed são representados pelo ordinal 10 ou hexadecimal 0x0A.

Nota: Não utilize o carriage return (CR), como na convenção dos sistemas operacionais da Apple (0x0D) ou a combinação carriage return - line feed (CRLF) como no padrão para os sistemas operacionais Windows (0x0D, 0x0A).

### Tags vazias

Tags vazias não são permitidas; todas as tags devem conter texto ou tags filhas.

    <!-- NÃO PERMITIDO -->
    <para>
        Algum texto. <link></link>
    </para>

    <para>
    </para>

### Uso de espaços em branco dentro de documentos

#### Espaço em branco dentro de tags

Não deve haver nada imediatamente apoś as tags de abertura de elementos de bloco além de uma quebra linha (e a indentação na linha seguinte).

    <!-- NÃO PERMITIDO -->
    <sect1>ESPAÇO
    </sect1>

Não deve haver espaço em branco imediatamente após as tags de abertura de elementos inline.

    <!-- NÃO PERMITIDO -->
    Esta é a classe <classname> Zend_Class</classname>.

    <!-- PERMITIDO -->
    Esta é a classe <classname>Zend_Class</classname>.

As tags de fechamento de elementos de bloco podem ser precedidos por espaços em branco equivalentemente ao nível atual de indentação, mas não mais do que isso.

    <!-- NÃO PERMITIDO -->
        <sect1>
         </sect1>

    <!-- PERMITIDO -->
        <sect1>
        </sect1>

As tags de fechamento de elementos inline não devem ser precedidas por nenhum espaço em branco.

    <!-- NÃO PERMITIDO -->
    Esta é a classe <classname>Zend_Class </classname>

    <!-- PERMITIDO -->
    Esta é a classe <classname>Zend_Class</classname>

#### Várias quebras de linha

Várias quebras de linha dentro ou entre as tags não são permitidas.

    <!-- NÃO PERMITIDO -->
    <para>
        Algum texto...

        ... e mais texto
    </para>

    <para>
        Outro parágrafo.
    </para>

    <!-- PERMITIDO -->
    <para>
        Algum texto...
        ... e mais texto
    </para>

    <para>
        Outro parágrafo.
    </para>

#### Separação entre as tags

Tags em um mesmo nível devem ser separadas por uma linha em branco para melhorar a legibilidade.

    <!-- NÃO PERMITIDO -->
    <para>
        Algum texto...
    </para>
    <para>
        Mais texto...
    </para>

    <!-- PERMITIDO -->
    <para>
        Algum texto...
    </para>

    <para>
        Mais texto...
    </para>

O primeiro elemento filho de ser aberto diretamente abaixo de seu pai, sem linha vazia entre eles. O último elemento filho deve ser fechado diretamente antes da tag de fechamento de seu pai.

    <!-- NÃO PERMITIDO -->
    <sect1>

        <sect2>
        </sect2>

        <sect2>
        </sect2>

        <sect2>
        </sect2>

    </sect1>

    <!-- PERMITIDO -->
    <sect1>
        <sect2>
        </sect2>

        <sect2>
        </sect2>

        <sect2>
        </sect2>
    </sect1>

### Códigos de Exemplo

A tag de abertura de <programlisting> deve indicar o atributo "language" adequado e ser indentado no mesmo nível que seus blocos irmãos.

    <para>Parágrafo irmão.</para>

    <programlisting language="php"><![CDATA[

CDATA deve ser usado junto de todos os códigos de exemplo.

As seções de <programlisting> não devem conter quebras de linha ou espaços em branco no início ou no final da seção, uma vez que estas são representadas no resultado final.

    <!-- NÃO PERMITIDO -->
    <programlisting language="php"><![CDATA[

    $render = "xxx";

    ]]></programlisting>

    <!-- PERMITIDO -->
    <programlisting language="php"><![CDATA[
    $render = "xxx";
    ]]></programlisting>

As tags de fechamento de CDATA e <programlisting> devem estar na mesma linha, sem qualquer indentação.

    <!-- NÃO PERMITIDO -->
        <programlisting language="php"><![CDATA[
    $render = "xxx";
    ]]>
        </programlisting>

    <!-- NÃO PERMITIDO -->
        <programlisting language="php"><![CDATA[
    $render = "xxx";
        ]]></programlisting>

    <!-- PERMITIDO -->
        <programlisting language="php"><![CDATA[
    $render = "xxx";
    ]]></programlisting>

A tag <programlisting> deve conter o atributo "language" com um valor correspondente ao conteúdo do código de exemplo. Os valores típicos incluem "css", "html", "ini", "javascript", "php", "text", e "xml".

    <!-- PHP -->
    <programlisting language="php"><![CDATA[

    <!-- Javascript -->
    <programlisting language="javascript"><![CDATA[

    <!-- XML -->
    <programlisting language="xml"><![CDATA[

Para códigos de exemplo que contenham apenas código PHP, as tags do PHP (por exemplo, "<?php", "?>") não são necessárias, e não devem ser usadas. Elas dificultam a legibilidade do código, e estão implícitas no uso do elemento <programlisting>.

    <!-- NÃO PERMITIDO -->
    <programlisting language="php"<![CDATA[<?php
        // ...
    ?>]]></programlisting>

    <programlisting language="php"<![CDATA[
    <?php
        // ...
    ?>
    ]]></programlisting>

Os comprimentos de linha dentro de códigos de exemplo devem seguir as recomendações das normas de codificação.

Evite utilizar `require_once()`, `require()`, `include_once()`, e `include()` dentro de exemplos em PHP. Eles dificultam a legibilidade do código, e são basicamente evitados quando utiliza-se um carregador automático. Use-os apenas quando forem essenciais ao exemplo.

#### Nunca utilize tags curtas

Tags curtas (por exemplo, "<?", "<?=") nunca devem ser usadas dentro do elemento programlisting ou no restante da documentação.

### Notas sobre elementos inline específicos

#### classname

O elemento <classname> deve ser usado cada vez que um nome de classe é representado sozinho. Não deve ser usado quando combinado com um nome de método, nome de variável ou constante, e nenhum outro conteúdo é permitido dentro do elemento.

    <para>
        A classe <classname>Zend_Class</classname>.
    </para>

#### varname

Variáveis devem ser envolvidas pelo elemento <varname>. As variáveis devem ser escritas usando o símbolo "$". Nenhum outro conteúdo é permitido dentro deste elemento, exceto se um nome de classe é usado, o que indica uma variável de classe.

    <para>
        A variável <varname>$var</varname> e a variável de classe
        <varname>Zend_Class::$var</varname>.
    </para>

#### methodname

Métodos devem ser envolvidos pelo elemento <methodname>. Os métodos devem ou incluir sua assinatura completa ou pelo menos um par de parênteses (por exemplo, "()"). Nenhum outro conteúdo é permitido dentro do elemento, exceto se um nome de classe é usado, o que indica um método de classe.

    <para>
        O método <methodname>foo()</methodname> e o método de classe
        <methodname>Zend_Class::foo()</methodname>. Um método com uma assinatura
        completa: <methodname>foo($bar, $baz)</methodname>
    </para>

#### constant

Use o elemento <constant> quando designar constantes. As constantes devem ser escritas em MAIÚSCULAS. Nenhum outro conteúdo é permitido dentro deste elemento, exceto se um nome de classe é usado, o que indica uma constante de classe.

    <para>
        A constante <constant>FOO</constant> e a constante de classe
        <constant>Zend_Class::FOO</constant>.
    </para>

#### filename

Nomes de arquivos e caminhos devem ser envolvidos pelo elemento <filename>. Nenhum outro conteúdo é permitido neste elemento.

    <para>
        O nome de arquivo <filename>application/Bootstrap.php</filename>.
    </para>

#### command

Comandos, shell scripts e chamadas de programa devem ser envolvidos pelo elemento <command>. Se o comando incluir argumentos, estes também devem ser incluídos dentro do elemento.

    <para>
        Execute <command>zf.sh create project</command>.
    </para>

#### code

O uso do elemento <code> é desencorajado, em favor dos outros elementos inline discutidos anteriormente.

### Notas sobre elementos de bloco específicos

#### title

O elemento <title> não permite ter elementos filhos.

    <!-- NÃO PERMITIDO -->
    <title>Usando <classname>Zend_Class</classname></title>

    <!-- PERMITIDO -->
    <title>Usando Zend_Class</title>

## Recomendações

### Use editores sem formatação automática

Para editar a documentação, normalmente você não deve usar os editores XML clássicos. Esses editores geralmente formatam automaticamente os documentos existentes para que se adaptem as suas próprias normas e/ou não seguem rigorosamente o padrão docbook. Como exemplos, já os vimos apagar as tags CDATA, substituírem 4 espaços por tabs ou 2 espaços etc.

Estas diretrizes foram escritas em grande parte para auxiliar os tradutores no reconhecimento das linhas que foram alteradas usando as ferramentas de `diff` normais. A formatação automática torna esse processo mais difícil.

### Use Imagens

Boas imagens e diagramas podem melhorar a legibilidade e a compreensão. Use-as sempre que ajudarem nesses objetivos. Imagens devem ser colocadas no diretório `documentation/manual/en/figures/`, e nomeadas após o identificador de seção em que lhes diz respeito.

### Use Exemplos de Caso de Uso

Procure por bons casos de uso apresentados pela comunidade, especialmente aqueles que são publicados nos comentários de sugestão ou nas listas de discussão. Os exemplos frequentemente ilustram a utilização muito melhor do que todo o texto.

Ao escrever seus exemplos para inclusão no manual, siga todas as normas de codificação e de documentação.

### Evite Duplicar o Conteúdo de phpdoc

O manual pretende ser um guia de referência para a utilização do usuário final. A duplicação da documentação de phpdoc para componentes e classes de uso interno não é desejada, e a documentação deve estar focada na utilização e não no funcionamento interno. Em qualquer caso, neste momento, gostaríamos que as equipes de documentação se concentrassem na tradução do manual em inglês, e não nos comentários de phpdoc.

### Use Links

Crie links para outras seções do manual ou para fontes externas em vez de recriar documentação.

Os links para outras seções do manual podem ser feitos usando o elemento <link> (para o qual você deve fornecer o nome do link).

    <para>
        "Link" cria um link para uma seção, usando um texto descritivo: <link
            linkend="doc-standard.recommendations.links">documentação sobre os
            links</link>.
    </para>

Para criar um link para uma fonte externa, use <ulink>:

    <para>
        O <ulink url="http://framework.zend.com/">site do Zend Framework</ulink>.
    </para>