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.
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.
Use o comando cvsup
para
atualizar seus fontes.
Use o cvsup
para atualizar seus
fontes.
Estes dois exemplos mostram isto para nomes de arquivo. O segundo exemplo é preferido.
… no arquivo
/etc/rc.local
…
… no
/etc/rc.local
…
Estes dois exemplos mostram isto para
referências aos manuais. O segundo exemplo
é preferido (o segundo exemplo usa
citerefentry
).
Veja o man csh
para maiores
informações
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:
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:
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:
Entre os nomes dos programas e os seus números de versão:
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”):
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>.