Uso de HTML em páginas web do Debian

Esta página ainda é um esboço.

Prefácio

Esta página foi criada para ajudar editores(as) e tradutores(as) a criar páginas com tags bem estruturadas. Há dicas sobre uso de tags e sobre como criar novas páginas de forma que a tradução fique mais fácil.

Algumas dicas gerais

Para novas páginas ou traduções, aqui está uma lista de conselhos gerais

não use linhas longas
Os arquivos wml e outros devem conter linhas que caibam numa janela de terminal normal. Desse modo fica mais fácil editar no vi, fazer pesquisas e traduzir. Também é importante porque é mais difícil solucionar conflitos em linhas longas.
mantenha tags em linhas separadas, se possível
Grande parte das tags HTML podem ser mantidas em linhas separadas. Algumas delas são <div>, <p>, <table>, <ul>. Para deixar as coisas mais simples para tradutores(as), mantenha em linhas separadas todas as tags que podem ser posicionadas assim. De outra forma, tradutores(as) podem apagar tags acidentalmente e esquecer de restaurá-las após terminar a tradução.
não use espaços ou quebras de linhas em tags de linha única
Algumas tags produzem espaços se forem colocadas em linhas separadas. Uma delas é a tag <q>, para pequenas citações ou menções. Você só pode separar essas tags como um todo, com o conteúdo numa única linha. De outro modo, pode ocorrer um espaço entre o conteúdo e a tag na página HTML final. Entre as palavras dessas tags você pode ter quantas quebras de linhas ou espaços quiser.

Abreviaturas e Acrônimos

Para abreviaturas e acrônimos, a tag HTML <acronym> deve ser usada. Existem duas razões para que o uso da tag <abbr> não seja recomendada: primeiro, nem todos os navegadores suportam essa tag; segundo, existem definições inconsistentes sobre o que é um acrônimo e o que é uma abreviatura.

Um acrônimo é adicionado numa página pela seguinte sintaxe: <acronym lang="código do idioma" title="Definição completa do acrônimo">ACRÔNIMO</acronym>. O título contém todas as palavras em extenso. Se o acrônimo é criado a partir das letras iniciais de palavras, essas letras devem estar em maiúsculas no título. O atributo lang somente é necessário se o acrônimo ou abreviatura está num idioma estrangeiro.

Já existe um conjunto de acrônimos comuns nos modelos wml, incluídos para serem utilizados em sua página; você tem que adicionar uma linha para usar acrônimos no arquivo wml. Por exemplo, a tag wml para DD é <acronym_DD />.

Citações e Menções

Existem diversas regras sobre o que significa uma citação ou uma menção para diferentes idiomas. Se você tem uma citação curta de uma linha, você tem que usar a tag <q> . O processamento do conteúdo é feito pela linguagem CSS. As tags <q> não devem ter espaços ou quebras de linha entre a tag de abertura e fechamento, e o conteúdo.

Para citações mais longas, a tag <blockquote> é usada. A tag <blockquote> inclui um ou mais parágrafos de texto, que são marcados com <p>. Por favor, não use tags <blockquote> para centralizar blocos de texto que não sejam citações. Tags blockquote são exclusivas para citações e serão processadas no futuro por código específico da linguagem CSS.

Também existe uma tag HTML <cite>. A tag <cite> não é usada para citação de texto propriamente, mas para a fonte da citação. Pode ser o nome da pessoa que originou a citação. A tag é adicionada como um atributo para um <blockquote>, como uma URL.

Nome de programas e Código

Para nomes de programas e códigos de computador existe uma tag chamada <code>. Navegadores normalmente sabem como exibir código e nomes de programas, mas o processamento também pode ser alterado por CSS. Não é uma boa ideia usar <tt> no lugar, já que ela não diz nada sobre o conteúdo.

Amostras de saídas de processamento

Para saídas de processamento na tela, existe uma tag especial chamada <samp>. Se você tem um bloco grande de saída de processamento, você também deve dar uma olhada no arquivo CSS, caso exista uma classe especial para isto.

Entrada de teclado

Se existir exemplos em que o(a) usuário(a) tenha que digitar alguma coisa no teclado, a tag <kbd> é usada para a entrada de usuário(a). Veja também o capítulo sobre variáveis para saber como usar tags nas entradas de variável.

Variáveis

Algumas vezes é preciso enfatizar uma entrada de variável, como um endereço IP especial ou o nome de usuário(a) que deve ser dado numa chamada de programa da linha de comando. Para essas entradas de variável, a tag <var> é usada.

Conteúdo pré-formatado

A tag <pre> é usada somente para texto pré-formatado. Tamanho de linha, espaços e outras coisas serão preservados. Naturalmente, esta tag não pode conter a maioria das outras tags HTML.

Imagens

Se há imagens adicionadas na página, não é preciso adicionar border=0 como um atributo inválido. Mas, se possível, o tamanho da imagem e o atributo alt deve ser adicionado. O tamanho é adicionado pelo wml se não estiver presente, mas isso demanda tempo de compilação. O atributo alt deve conter alguma coisa que diga o quê está na imagem para usuários(as) que navegam via lynx e pessoas com deficiência visual.

Links

Se você pretende criar um link para uma página dentro de https://www.debian.org na documentação, por favor use variáveis definidas no arquivo .wmlrc para cada idioma. Por exemplo, a URL na tag
<a href="https://www.debian.org/devel/website/htmlediting">htmlediting</a>
deve ser substituída usando a variável DEVEL desse jeito <a href="$(DEVEL)/website/htmlediting">htmlediting</a>.