A fim de promover a consistência entre os inúmeros autores da documentação do FreeBSD, foram criadas algumas diretrizes para que os autores sigam.
Existem diversas variantes do inglês, com grafias diferentes para a mesma palavra. Onde as grafias diferem, use a variante inglesa americana. Por exemplo: “color”, não “colour”, “rationalize”, não “rationalise”, e assim por diante.
Nota: O uso do Inglês Britânico pode ser aceito para a contribuição de artigos, contudo a ortografia deverá ser consistente ao longo de todo o documento. Os outros documentos, tais como livros, web sites, páginas de manual, etc. deverão utilizar o Inglês Americano.
Não use contrações. Soletre sempre a frase por completo. A frase “ Don't use contractions ” seria errada.
Evite fazer uso das contrações para obter um tom mais formal, será mais preciso, e ligeiramente mais fácil para os tradutores.
Em uma lista de artigos dentro de um parágrafo, separe cada artigo do outro com uma vírgula. Separe o último artigo do outro com uma vírgula e a palavra “e”.
Por o exemplo, observe o seguinte:
Esta é uma lista de um, dois e três artigos.
Isto é uma lista de três artigos, “um”, “dois”, e “três”, ou de uma lista de dois artigos, “um” e “dois e três”?
É melhor ser explícito e incluir uma vírgula de série:
Esta é uma lista de um, dois, e três artigos.
Tente não usar frases redundantes. No detalhe, “o comando”, “o arquivo”, e “o comando man” são provavelmente redundantes.
Estes dois exemplos mostram isto para comandos. O segundo exemplo é preferido.
Estes dois exemplos mostram isto para nomes de arquivo. O segundo exemplo é preferido.
Estes dois exemplos mostram isto para referências aos manuais. O segundo exemplo é preferido (o segundo exemplo usa <citerefentry>).
veja o csh(1)
Use sempre dois espaços no fim das sentenças, isto melhora a legibilidade, e facilita o uso de ferramentas tais como o Emacs.
Lembre-se que uma letra em caixa alta depois de um período, nem sempre denota uma sentença nova, especialmente na grafia de nomes. “Jordan K. Hubbard” é um bom exemplo; tem um H em caixa alta depois de um período e um espaço, e não há certamente uma sentença nova lá.
Para maiores informações sobre estilo de escrita, consulte Elementos de Estilo, por William Strunk.
Para manter o código fonte da documentação consistente quando muitas pessoas diferentes o estão editando, por favor siga estas convenções de estilo.
As tags devem ser utilizadas em caixa baixa, <para>, não <PARA>.
O texto que aparece em contextos do SGML é escrito geralmente em caixa alta, <!ENTITY…>, e <!DOCTYPE…>, não <!entity…> e <!doctype…>.
Um acrônimo normalmente deve ser soletrado na primeira vez que ele aparecer em um livro, como por exemplo: "Network Time Protocol (NTP)". Depois que um acrônimo for definido, você deveria passar a utilizar apenas ele (e não o termo completo, a não ser que isso faça mais sentido contextualmente). Normalmente um acrônimo é definido uma única vez por livro. Mas se você preferir, você também pode definí-lo quando ele aparecer pela primeira vez em cada capítulo.
Nas três primeiras vezes que um acrônimo for utilizado ele deve ser destacado com a tag <acronym> utilizando o atributo role setado com o termo completo como seu valor. Isto irá permitir que o link para o glossário seja criado, e habilitará um mouseover que quando renderizado irá exibir o termo completo.
Cada arquivo começa com a identação ajustada na coluna 0, independentemente do nível de identação do arquivo que pode vir a incluí-lo.
As tags de abertura aumentam o nível de identação em 2 espaços, as tags de fechamento diminuem o nível de identação em 2 espaços. Blocos de 8 espaços no começo de uma linha devem ser subistituidos por um Tab. Não use espaços na frente dos Tabs, e não adicione espaços em branco no final de uma linha. O conteúdo dentro de um elemento deve ser identado por dois espaços caso ele ocupe mais de uma linha.
Por exemplo, o código para esta seção seria algo como:
+--- This is column 0
V
<chapter>
<title>...</title>
<sect1>
<title>...</title>
<sect2>
<title>Indentation</title>
<para>Each file starts with indentation set at column 0,
<emphasis>regardless</emphasis> of the indentation level of the file
which might contain this one.</para>
...
</sect2>
</sect1>
</chapter>
Se você usar o Emacs ou XEmacs para editar os arquivos o sgml-mode será carregado automaticamente, e as variáveis locais do Emacs ao final de cada arquivo devem reforçar estes estilos.
Os usuários do Vim podem querer configurar o seu editor da seguinte forma:
augroup sgmledit autocmd FileType sgml set formatoptions=cq2l " Special formatting options autocmd FileType sgml set textwidth=70 " Wrap lines at 70 spaces autocmd FileType sgml set shiftwidth=2 " Automatically indent autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab autocmd FileType sgml set autoindent " Automatic indentation augroup END
Tags que começam na mesma identação que um Tag precedente devem ser separados por uma linha em branco, e aqueles que não estão na mesma identação que um Tag precedente não, observe:
Tags tais como <itemizedlist> que terão sempre algum Tag adicional dentro dele, e que não fazem exame dos dados eles mesmos, estarão sempre sozinhos em uma linha.
Tags tais como <para> e <term> não necessitam outros Tags para conter caracteres normais, e o seu conteúdo começa imediatamente depois do Tag, na mesma linha.
O mesmo se aplica quando estes dois tipos de Tag se fecham.
Isto conduz a um problema óbvio ao misturar estes Tags.
Quando um Tag de abertura que não pode conter caracteres normais é utilizado logo após um Tag do tipo que requer outros Tags dentro dele para conter caracteres normais, eles devem estar em linhas separadas e o segundo Tag deve ser corretamente identado.
Quando um Tag que possa conter caracteres normais se fecha imediatamente depois que um Tag que não pode conter caracteres normais se fecha, eles podem coexistir na mesma linha.
Ao enviar mudanças, não envie mudanças de conteúdo ao mesmo tempo que mudanças no formato.
Desta forma as equipes que convertem o manual para outras línguas podem ver rapidamente o que de fato mudou no conteúdo com o seu envio, sem ter que se decidir se uma linha mudou por causa do conteúdo, ou apenas porque foi reformatada.
Por exemplo, se você adicionar duas sentenças a um parágrafo, de forma que o comprimento das linhas no mesmo agora excedem 80 colunas, envie sua mudança sem corrigir o comprimento da linha. Ajuste então a quebra de linha e envie uma segunda mudança. Na mensagem de commit da segunda mudança, deixe claro que se trata apenas de um ajuste de formatação, e que a equipe da tradução pode ignorá-la.
Evite as quebras de linha nos locais onde elas ficarem feias ou onde dificultarem a compreensão de uma sentença. As quebras de linha dependem da largura do meio de saída escolhido. Em particular, visualizar um documento em HTML com um navegador em modo texto pode conduzir a parágrafos mal formatados como o exemplo a seguir:
Data capacity ranges from 40 MB to 15 GB. Hardware compression …
A entidade geral proibe a quebra de linha entre partes que devem permanecer juntas. Utilize nonbreaking spaces nos seguintes lugares:
Entre números e suas unidades:
57600 bps
Entre os nomes dos programas e os seus números de versão:
FreeBSD 4.7
Entre nomes compostos (utilize com cuidado quando estiver lidando com nomes com mais de 3 ou 4 palavras, como por exemplo, “The FreeBSD Brazilian Portuguese Documentation Project”):
Sun Microsystems
Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.