A fim de promover a consistência entre os inumeros autores da documentação do FreeBSD, alguns guidelines foram criados 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.
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 dos 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 des 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 exemplo bom; 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 a fonte do manual 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...>.
Cada arquivo começa com a identação ajustada na coluna 0, não obstante do nível de identação que este pôde conter.
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 linham 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 índice dentro dos elementos deve ser identado por dois espaços se o seu conteúdo ocupar 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>
<para>Every start tag increases the indentation level by 2 spaces, and
every end tag decreases the indentation level by 2 spaces. Content
within elements should be indented by two spaces if the content runs
over more than one line.</para>
...
</sect2>
</sect1>
</chapter>
Se você usa Emacs ou XEmacs para editar os arquivos então o sgml-mode deve 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 se desejarem podem 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 caractéres normais, e o seu conteúdo começam 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 possa conter caractéres normais é utilizado logo após um Tag do tipo que requer outros Tags dentro dele para conter caractéres normais, eles devem estar em linhas separadas e o segundo Tag deve ser corretamente identado.
Quando um Tag que possa conter caractéres normais se fecha imediatamente depois que um Tag que não pode conter caractéres normais fecha-se, eles podem co-existir 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 da media de saída escolhida. Em particular, visualizar um documento em HTML com um navegador em modo texto pode conduzir a paragrafos 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>.