Convenções de formatação para o Manual do Krita ¶

Isto detalha as convenções de estilo para usar o texto estruturado que é usado no Manual do Krita.

Recomenda-se que veja a especificação oficial do reStructuredText, e dado que a mesma reside no Sourceforge, grave uma cópia no seu disco rígido (o Sourceforge, na altura em que isto foi escrito, estava a ter alguns problemas de disponibilidade dos servidores):

Manual do Utilizador:

Documentação de Referência:

Documentação específica do Sphinx:

A página do Sphinx” sobre o texto estruturado – Isto é útil para as directivas específicas do Sphinx e os papéis que usa para gerar por exemplo os índices analíticos.

Existem diferenças entre o formato reStructuredText oficial e a documentação do Sphinx em diversas formas de fazer as coisas. Este documento especifica as convenções sugeridas a seguir.

Meta-dados ¶

Cada página deverá começar pelas seguintes três coisas:

Uma descrição “meta”
Esta é uma descrição geral da página. Será convertida para uma marca “meta” do HTML que será usada pelos motores de busca:
.. meta:: :description: Descrição.
Uma lista de autores e uma licença.
Isto serve apenas para manter um registo de quem editou a página e para atribuir o crédito merecido. Deverá estar num comentário, para que não acabe por se tornar fácil de ler por máquinas. A licença do manual inteiro é a GDL 1.3 e deverá também ser mencionada aqui:
.. metadata-placeholder :authors: - Autor 1 - Autor 2 :license: licença de documentação livre da GNU 1.3 ou posterior.
Termos de indexação.
Estes são termos separados por vírgulas, pelos quais a página será indexada no Índice. O índice gerado é bastante útil tanto no formato PDF como para as pessoas que não sabem qual o nome exacto para o termo que procuram. Estes são definidos da seguinte forma:
.. index:: Palavra-chave, Palavra-chave com Espaços, ! Palavra-chave de Definição Principal
Uma legenda.
Estes existem para que se possa ligar facilmente à página com o :ref:`nome_legenda`. Tente fazer deste um nome de variável adequado:
.. _nome_legenda:
Depois da legenda, terá de adicionar um cabeçalho, como por exemplo :ref:`nome_legenda` para se referir ao cabeçalho como estando em texto de hiperligação.

Cabeçalhos ¶

Os cabeçalhos serão criados pela seguinte ordem:

############
Parte/Secção
############

Para páginas que tenham bastantes sub-páginas.

=========
Cabeçalho 1
=========

Inicie a maioria das páginas de manual com isto.

Cabeçalho 2
---------

Cabeçalho 3
~~~~~~~~~

Cabeçalho 4
^^^^^^^^^

Cabeçalho 5
'''''''''

Cabeçalho 6
"""""""""

Estas convenções foram mais ou menos decididas pela conversão de MediaWiki para reStructuredText do Pandoc. Se precisar de mais que 4 cabeçalhos, pergunte a si próprio se a página não ficou demasiado complicada e se precisa de ser dividida.

Em alguns casos terá de criar uma ligação a uma sub-secção de uma página; adicione uma legenda acima do cabeçalho nesse caso.

Os cabeçalhos não deverão terminar com pontuação, dado que o cabeçalho será usado como o nome da ligação ao criar uma ligação para uma legenda.

Ligação ¶

A ligação é feita com um :ref:`nome_legenda`. Quando precisar de um texto de ligação alternativ, poderá usar a sintaxe :ref:`texto real apresentado <nome_legenda>`.

A ligação a páginas externas é feita com um `url`_ e o `nome da ligação <url>`_, que se tornará nome da ligação.

O Pandoc gosta de transformar estes em `nome da ligação`__ e depois adicionar `` .. __ :url`` ao fim do documento. Isto é o que se chama uma “hiperligação anónima” o que significa que, dependendo da origem das ligações que aparecem no texto, estarão associadas uma à outra na ordem das ligações no fim do texto. Se isto soar confuso e difícil, é porque é. Isto também é a razão exacta pela qual desejamos evitar ligações deste tipo.

Notas de rodapé e leituras posteriores ¶

As notas de rodapé podem ser criadas de 3 formas, sendo a mais comum com numeração automática; de acordo com a referência:

[1] é uma referência à nota de rodapé 1, e [2] é uma referência à nota de rodapé 2.

O [3] é uma referência à nota de rodapé 3.

Esta é uma referência de citação: [CIT2002] .

[CIT2002]

Esta é a citação. É como uma espécie de nota de rodapé, excepto que a legenda é textual.

A citação também poderá ser referenciada com uma `citação <CIT2002>`_.

Não usamos de facto notas de rodapé no manual, pelo motivo que isso é um pouco académico demais para os nossos leitores. Contudo, recolhemos de facto os documentos e ligações que adicionem um pouco mais de informação sobre um dado tópico no fim de uma página. O Sphinx tem a directiva .. seealso:: para se associar a endereços externos, enquanto o reStructuredText sugere o .. rubic:: Notas de Rodapé` para recolher especificamente notas do rodapé, dado que isso resulta bem com o LaTeX.

Imagens ¶

Use a directiva “image” para as imagens sem legendas:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: uma imagem.

E as directivas “figure” para as imagens com legendas:

.. figure:: /images/exemplo.png
   :figwidth: 800
   :align: center
   :alt: uma imagem.
   Uma legenda --  repare como a primeira letra fica aninhada com a opção :figwidth:.

O último caso gera:

Uma legenda – repare como a primeira letra da legenda na directiva está alinhada com a opção :figwidth:.¶

As imagens deverão ir para a pasta /images. Ao usar o /images em vez do images, o Sphinx irá saber que a localização do ficheiro não é relativa.

Formatação Dentro do Texto ¶

Poderá criar ênfase no texto ou torná-lo forte com um asterisco único ou um duplo, respectivamente:

*ênfase*
**negrito**

Não consegue torná-lo *enfatizado e forte ao mesmo tempo*, por isso escolha um deles.

Poderá _{tornar o texto subscrito} e ^sobrescrito se usar o :sub:`texto` e o :sup:`texto`.

Contudo, use-as com muito pouca frequência! É preferível usar a formatação semântica existente em qualquer caso, porque facilita aos tradutores tomarem decisões sobre a natureza do texto:

:menuselection:`Configuração --> Configurar o Krita...`
:guilabel:`Ficheiro`
:kbd:`Ctrl + Z`
:program:`Krita`

Evite escolher palavras aleatórias para estar em negrito. Não torna o texto mais fácil ou amigável para ser lido.

Referências de Substituição ¶

Poderá criar uma espécie de atalho para um pedaço de texto ou uma imagem se escrever:

.. |shorthand| substituição:: uma coisa ou a outra.

o que significa que, se usar o |atalho| no texto, será substituído por “uma coisa ou a outra”. Isto é útil para imagens e texto que precisem de ser formatados de uma forma complicada, como acontece no «LaTeX».

Para as ligações, caso reutilize a mesma ligação uma e outra vez, poderá escrever algo como se segue no fim do ficheiro:

.. _bugzilla: https://bugs.kde.org/
.. _Manual do Krita: https://docs.krita.org/

Então, ao escrever uma ligação, poderá simplesmente usar `bugzilla`_ para se ligar ao Bugzilla, usando o «bugzilla» como texto para a ligação. O `Krita Manual`_ irá por seu turno ligar ao docs.krita.org com o texto «Krita Manual» (Manual do Krita).

Listas ¶

Listas ordenadas ¶

Maçã
Pêra
Banana

Ou…

Mesa
Cadeira
Roupeiro.

Augusto
Nero
Calígula
Trajão

Eles poderão ser definidos como se segue:

1. Maçã
2. Pêra
3. Banana

#. Maçã
#. Pêra
#. Banana

A. Mesa
B. Cadeira
C. Armário

A. Mesa
#. Cadeira
#. Armário

I. Augusto
#. Nero
#. Calígula
#. Trajão

Listas não-ordenadas ¶

vermelho
amarelo
verde
- verde-marinho
- verde-acinzentado
- azul-esverdeado
- veridiano
- esmeralda
  
  esmeralda escuro
  
  esmeralda claro
  
  esmeralda muito claro.
azul

Definido como tal:

- vermelho
- amarelo
- verde
    - verde-marinho
    - verde-acinzentado
    - turquesa
    - esverdeado
    - esmeralda
        - esmeralda escuro
        - esmeralda claro
            - esmeralda muito claro.
- azul

Listas de Definições ¶

Um favorito! As listas de definições são especialmente úteis ao lidar com a enumeração de todas as opções numa área acoplável e ao tentar adicionar uma explicação simples atrás delas.

Definição

Explicação.

Outra opção

Explicação.

Para criá-las.

Podê-las-á criar da seguinte forma:

Definição
    Explicação.
Outra opção
    Explicação.

Tabelas ¶

Objectivo	Tipo de tabela
listagem de atalhos	Tabela simples
bastantes extensões de colunas	Tabela em grelha
Simples mas comprida	Tabela de Listagem

Feita da seguinte forma:

================== ============
Objectivo          Tipo de tabela
================== ============
lista de atalhos   Tabela simples
vários 'colspans'  Grelha
Simples mas longo  Tabela em lista
================== ============

+-----------------+---------------+
|Objectivo        |Tipo de Tabela |
+=================+===============+
|lista de atalhos |Tabela simples |
+-----------------+---------------+
|vários 'colspans'|Grelha         |
+-----------------+---------------+
|Simples mas longo|Tabela em lista|
+-----------------+---------------+

.. list-table::
   :header-rows: 1

   - * Objectivo
     * Tipo de Tabela
   - * lista de atalhos
     * tabela simples
   - * vários 'colspans'
     * grelha
   - * simples mas longo
     * tabela em lista

As tabelas de grelha completa são melhores quando precisa de todas as funcionalidades, como a expansão para árias linhas e colunas, mas são difíceis de criar. Por essa razão, as tabelas pequenas são melhores se forem criadas com a sintaxe simples, enquanto as tabelas realmente grandes são mais fáceis de criar com uma directiva de lista, porque é muito mais fácil de escrever e manter.

Advertências e notas laterais ¶

Nota

As advertências são uma espécie de secção separada que o leitor precisa de prestar atenção.

As advertências que poderão ser usadas são as seguintes (por ordem de severidade):

Dica

As dicas são úteis para nos dar um pouco mais de informações sobre um tópico que é útil no texto principal. Por exemplo, «Estes pacotes têm diferentes nomes no openSuse versus Debian».

Dica

A documentação extra sobre como fazer algo, como por exemplo, se «Pode fazer um modelo da sua configuração favorita de documentos», ou «Use o “m” para criar uma espelho da área de desenho e veja os erros mais facilmente no seu desenho».

Importante

Algo que é bastante importante de anotar, mas que não é necessariamente negativo.

Aviso

Isto é usado na generalidade em que algo é negativo.

Atenção

Chamada de atenção geral. Use isto quando o assunto é mais importante que o aviso, mas não é tão importante que possa provocar uma perda de dados.

Cuidado

Isto serve para as coisas que possam provocar a perda de dados, como se esquecer de gravar ou que o Python não tem de momento nenhuma funcionalidade para desfazer.

Perigo

Isto deverá servir para coisas que sejam perigosas para o computador de um modo geral; isto inclui coisas que possam provocar bloqueios p.ex. por falta de memória.

Erro

Isto provavelmente não é relevante para um manual. O Sphinx pode criar estes manualmente em algumas situações, mas a nossa configuração não o faz por omissão.

Admoestação genérica que poderá ter qualquer texto

Texto.

Podê-las-á criar da seguinte forma:

.. admonition:: Admoestação genérica que poderá ter qualquer texto.

    Texto.

O Sphinx também adiciona:

.. seealso::
    O que é útil para recolher as referências e ligações externas.

Posto isto, as réguas horizontais podem ser criadas com o ----.

A directiva “rubric”

A directiva “rubric” é uma directiva de cabeçalho que à primeira vista parece um «tópico», mas onde o tópico se encontra por vários parágrafos; o “rubric” em si só lida com o cabeçalho, como por exemplo:

.. rubric:: A directiva de rubrica

Por isso, quando devem ser usados?

Use-os apenas quando achar que o assunto é demasiado pequeno para ter um cabeçalho adequado.

Tópico: Quando o texto está separado do fluxo, porque que vai para um assunto diferente do texto de destino.
Rubrica: Quando o texto não está separado do fluxo, mas também não precisa de um cabeçalho para si.
Advertências: Só quando são adequadas a nível semântico. Isto é especialmente necessário para as advertências de perigo e aviso, dado que as ver com frequência poderá tornar os utilizadores mais insensíveis a elas.

Excertos de Código ¶

Os excertos de código incorporados são feitos com plicas invertidas ``backticks``.

Os excertos de código em várias linhas são feitos ao terminar a secção anterior com ::, o que se parecerá com o seguinte:

Isto é um parágrafo, e definimos um excerto pré-formatado da seguinte forma::

    Certifique-se que adiciona um espaço em branco e uma tabulação a seguir antes de iniciar o excerto.

Também poderá usar a directiva .. code::. Se adicionar o nome da linguagem a seguir, irá aplicar o realce de sintaxe apropriado:

.. code:: python
    # comentário
    def minha_funcao():
        lista = []
        lista.append(1)
        texto = "olá mundo"

Torna-se

# Comentário de Python
def minha_funcao():
    lista = []
    lista.append(1)
    texto = "olá mundo"

mais alguns…

// Comentário de C++
int minhaFuncao(int i) {
    i += 1;

    // Verificar se é maior que 12
    if (i>12) {
        i = 0;
    }
    return i;
}

/* Comentário de CSS */
body {
    margin: 0 auto;
    /* 800 ainda faz sentido? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>isto <span style="font-style:italic">é</span> <!-- um comentário de HTML --> um parágrafo.</p>

Outro texto pré-formatado ¶

Uma pessoa pode
pré-formatar
texto se
anteceder
cada linha
com um símbolo
de barra vertical (“pipe”)

Como o seguinte:

| Uma pessoa
| pode pré-formatar
| texto se
| anteceder
| cada linha
| com um símbolo
| de barra vertical

Isto geralmente não é usado no manual, e só deverá ser usado quando for absolutamente necessário representar conteúdos que necessitam de formatações exactas, mas nunca meramente por motivos estéticos.

Glossários, Termos e Índice ¶

Estas são funcionalidades do Sphinx.

O índice é usado na secção de topo; de momento, agora só são usados itens simples de índice.

Os glossários são usados para algumas das secções de itens do menu, mas não para todas.

Citações ¶

As citações são feitas da seguinte forma:

Não tenho a certeza porque irá precisar de citações num manual do utilizador...

-- Wolthera

Isto torna-se uma citação em bloco.

Não tenho a certeza porque irá precisar de citações num manual do utilizador…

—Wolthera

De facto usamos citações em alguns pontos. Tente adicionar uma ligação ao nome para definir de onde vem.

Texto Apenas para Traduções Não-Inglesas ¶

Poderá usar o seguinte para incluir textos que só façam sentido em traduções não-inglesas do manual; por exemplo, para dar aos leitores não-ingleses os nomes ingleses de um dado item, para fins de referência:

.. only:: non_english

    Este conteúdo fica escondido para a versão Inglesa, mas pode ser
    traduzido e aparece nas versões não-Inglesas.

Notas para os Tradutores ¶

Se estiver a traduzir o manual para uma língua que não use normalmente espaços em branco entre palavras (p.ex., Chinês ou Japonês), poderá usar um espaço “escapado” para separar a formatação das palavras. Isto é particularmente útil para as hiperligações das páginas, como o seguinte:

床前\ `明月 <https://krita.org/>`_\ 光

Lembre-se que, ao traduzir a partir de um ficheiro PO, deverá escapar a barra invertida com outra barra invertida:

床前\\ `明月 <https://krita.org/>`_\\ 光

The above produces «床前明月光», instead of «床前明月光».