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. Cada arquivo do manual deve incluir as seguintes declarações XML no topo do arquivo: ]]> 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. ]]> 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. 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. ]]> Tags que estão um nível abaixo da tag anterior devem ser indentadas com 4 espaços adicionais. ]]> Vários elementos de bloco dentro de uma mesma linha não são permitidos, no entanto vários elementos inline são permitidos. Zend_Magic não existe. Zend_Acl existe. ]]> 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 não são permitidas; todas as tags devem conter texto ou tags filhas. Algum texto. ]]> 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). ESPAÇO ]]> Não deve haver espaço em branco imediatamente após as tags de abertura de elementos inline. Esta é a classe Zend_Class. Esta é a classe Zend_Class. ]]> 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. ]]> As tags de fechamento de elementos inline não devem ser precedidas por nenhum espaço em branco. Esta é a classe Zend_Class Esta é a classe Zend_Class ]]> Várias quebras de linha dentro ou entre as tags não são permitidas. Algum texto... ... e mais texto Outro parágrafo. Algum texto... ... e mais texto Outro parágrafo. ]]> Tags em um mesmo nível devem ser separadas por uma linha em branco para melhorar a legibilidade. Algum texto... Mais texto... Algum texto... Mais texto... ]]> 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. ]]> A tag de abertura de <programlisting> deve indicar o atributo "language" adequado e ser indentado no mesmo nível que seus blocos irmãos. Parágrafo irmão. ]]>< 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. ]]><> ]]><> ]]> As tags de fechamento de CDATA e <programlisting> devem estar na mesma linha, sem qualquer indentação. ]]><> ]]><> ]]><> ]]> 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". ]]>< ]]>< ]]>< 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>. <]]]]>> < ]]]]>> ]]> 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. Tags curtas (por exemplo, "<?", "<?=") nunca devem ser usadas dentro do elemento programlisting ou no restante da documentação. 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. A classe Zend_Class. ]]> 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. A variável $var e a variável de classe Zend_Class::$var. ]]> 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. O método foo() e o método de classe Zend_Class::foo(). Um método com uma assinatura completa: foo($bar, $baz) ]]> 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. A constante FOO e a constante de classe Zend_Class::FOO. ]]> Nomes de arquivos e caminhos devem ser envolvidos pelo elemento <filename>. Nenhum outro conteúdo é permitido neste elemento. O nome de arquivo application/Bootstrap.php. ]]> 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. Execute zf.sh create project. ]]> O uso do elemento <code> é desencorajado, em favor dos outros elementos inline discutidos anteriormente. O elemento <title> não permite ter elementos filhos. ]]> 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. 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. 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. 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. 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). "Link" cria um link para uma seção, usando um texto descritivo: documentação sobre os links. ]]> Para criar um link para uma fonte externa, use <ulink>: O site do Zend Framework. ]]>