14.3. Guia de estilo

Para manter o código fonte da documentação consistente quando muitas pessoas diferentes a estiverem editando, siga estas convenções de estilo.

14.3.1. Letter Case

As tags são digitadas em minúsculas, para, não PARA.

O texto que aparece em contextos SGML é geralmente escrito em letras maiúsculas, <! ENTITY ... >, e <! DOCTYPE… >, não <! entity… > e <! doctype… >.

14.3.2. Siglas

Os acrônimos devem ser definidos na primeira vez que aparecerem em um documento, como em: Network Time Protocol (NTP). Depois que o acrônimo tiver sido definido, use apenas o acrônimo, a menos que faça mais sentido contextualmente usar todo o termo. Acrônimos geralmente são definidos apenas uma vez por capítulo ou por documento.

Todos os acrônimos devem ser colocados em tags acronym.

14.3.3. Indentação

A primeira linha em cada arquivo começa sem recuo, independentemente do nível de recuo do arquivo que pode conter o arquivo atual.

Tags de abertura aumentam o nível de recuo por dois espaços. Tags de fechamento diminuem o nível de recuo por dois espaços. Blocos de oito espaços no início de uma linha devem ser substituídos por um tab. Não use espaços na frente das tabs e não adicione espaço em branco extra no final de uma linha. O conteúdo nos elementos deve ser indentado por dois espaços se o conteúdo for executado em mais de uma linha.

Por exemplo, a fonte desta seção é assim:

<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>The first line in each file starts with no indentation,
	<emphasis>regardless</emphasis> of the indentation level of
	the file which might contain the current file.</para>

      ...
    </sect2>
  </sect1>
</chapter>

Tags contendo atributos longos seguem as mesmas regras. Seguir as regras de recuo neste caso ajuda editores e escritores a ver qual conteúdo está dentro das tags:

<para>See the <link
    linkend="gmirror-troubleshooting">Troubleshooting</link>
  section if there are problems booting.  Powering down and
  disconnecting the original <filename>ada0</filename> disk
  will allow it to be kept as an offline backup.</para>

<para>It is also possible to journal the boot disk of a &os;
  system.  Refer to the article <link
    xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
    Journaling on a Desktop PC</link> for detailed
  instructions.</para>

Quando um elemento é muito longo para caber no restante de uma linha sem quebrá-la, mover a tag inicial para a próxima linha pode facilitar a leitura do código. Neste exemplo, o elemento systemitem foi movido para a próxima linha para evitar a quebra e o recuo:

<para>With file flags, even
  <systemitem class="username">root</systemitem> can be
  prevented from removing or altering files.</para>

Configurações para ajudar vários editores de texto a operar em conformidade com estas diretrizes podem ser encontradas em Capítulo 15, Configuração do Editor.

14.3.4. Estilo de Tag

14.3.4.1. Espaçamento de tag

Tags que começam no mesmo recuo como uma tag anterior devem ser separadas por uma linha em branco, e aquelas que não estão no mesmo recuo como uma tag anterior não devem:

<article lang='en'>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

14.3.4.2. Separando Tags

Tags como itemizedlist, que sempre terão outras tags dentro delas, e de fato não pegam dados de caractere, estão sempre sozinhas em uma linha.

Tags como para e term não precisam de outras tags para conter dados de caracteres normais, e seus conteúdos começam imediatamente após a tag, na mesma linha .

O mesmo se aplica quando esses dois tipos de tags fecham.

Isso leva a um problema óbvio ao misturar essas tags.

Quando uma tag inicial que não pode conter dados de caractere segue diretamente uma tag do tipo que requer outras tags dentro dela para usar dados de caractere, elas estão em linhas separadas. A segunda tag deve estar corretamente recuada.

Quando uma tag que pode conter dados de caractere é fechada diretamente após uma tag que não pode conter dados de caractere fechados, eles coexistem na mesma linha.

14.3.5. Mudanças no espaço em branco

Não faça commit de mudanças no conteúdo ao mesmo tempo em que faz mudanças na formatação.

Quando as alterações de conteúdo e espaço em branco são mantidas separadas, as equipes de tradução podem ver facilmente se uma alteração foi de um conteúdo que deve ser traduzido ou apenas espaço em branco.

Por exemplo, se duas sentenças foram adicionadas a um parágrafo para que os comprimentos de linha passem de 80 colunas, primeiro faça commit da alteração com as linhas longas demais. Em seguida, corrija a quebra de linha e confirme essa segunda alteração. Na mensagem de confirmação da segunda alteração, indique que esta é uma alteração somente de espaço em branco a qual pode ser ignorada pelos tradutores.

14.3.6. Espaços Não Separáveis (Non-Breaking Space)

Evite quebras de linha em locais onde elas pareçam feias ou dificultem o entendimento de uma frase. Quebras de linha dependem da largura do meio de saída escolhido. Em particular, a visualização da documentação em HTML com um navegador de texto pode levar a parágrafos mal formatados como o seguinte:

A capacidade de dados varia de 40 MB a 15
GB Compressão de hardware…

A entidade geral &nbsp; proíbe as quebras de linha entre as partes que estão juntas. Use espaços não separáveis ​​nos seguintes locais:

  • entre números e unidades:

    57600&nbsp;bps
  • entre nomes de programas e números de versão:

    &os;&nbsp;9.2
  • entre nomes com várias palavras (use com cautela ao aplicar isso em nomes de mais de 3-4 palavras como The FreeBSD Portuguese Portuguese Documentation Project):

    Sun &Microsystems

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.