Convenções de marcação para o Manual Krita ¶

Isso detalha as convenções de estilo para usar texto reestruturado no Manual do Krita.

É recomendável consultar a especificação oficial para o reStructuredText e, como ela está disponível no sourceforge, salvar uma cópia no seu disco rígido (o sourceforge tem, no momento da escrita, alguns problemas com o tempo de atividade do servidor):

Manual do Usuário:

Documentação de referência:

Documentos específicos do Sphinx:

Página Sphinx sobre texto reestruturado – Isso é útil para as diretivas e funções específicas do Sphinx que ele usa para gerar, por exemplo, um índice.

Existem diferenças entre o reStructuredText oficial e a documentação do Sphinx em várias maneiras de fazer as coisas. Este documento especifica as convenções sugeridas.

Metadados ¶

Cada página deve começar com as três coisas a seguir:

Uma meta de descrição
Esta é uma descrição geral da página. Ela será convertida em uma etiqueta meta em HTML que será usada pelos mecanismos de busca:
.. meta:: :description: Descrição.
Uma lista de autores e uma licença.
Isto serve apenas para manter o controle de quem editou a página e para dar os devidos créditos. Deve estar em um comentário para que não fique facilmente legível por máquinas. A licença de todo o manual é GDL 1.3 e também deve ser mencionada aqui:
.. metadata-placeholder :authors: - Autor 1 - Autor 2 :license: GNU free documentation license 1.3 ou posterior.
Termos de indexação.
Estes são termos separados por vírgulas sob os quais a página será indexada em Índice. O índice gerado é bastante útil tanto para PDFs quanto para pessoas que não têm certeza do nome exato do termo que estão procurando. Eles são definidos da seguinte forma:
.. index:: Palavra-chave, Palavra-chave com espaços, ! Palavra-chave da definição principal
Um rótulo.
Isso serve para que possamos criar um link para a página facilmente usando :ref:`nome_rotulo`. Tente criar um nome de variável bonito:
.. _nome_rotulo:
Após o rótulo, você precisará adicionar um título, pois :ref:`nome_rotulo` fará referência ao título para preencher o texto do link.

Títulos ¶

Os níveis de títulos serão formatados na seguinte ordem:

############
Parte/Seção
############

Para páginas que possuem muitas sub-páginas.

=========
Título 1
=========

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

Título 2
---------

Título 3
~~~~~~~~~

Título 4
^^^^^^^^^

Título 5
'''''''''

Título 6
"""""""""

Essas convenções foram mais ou menos decididas pela conversão do mediawiki do Pandoc para o reStructuredText. Se precisar de mais de 4 níveis de títulos, pergunte-se primeiro se a página não ficou muito complicada e precisa ser dividida.

Às vezes, você precisa criar um link para uma subseção de uma página. Nesse caso, adicione um rótulo acima do título.

Os títulos não devem terminar com pontuação, pois o título será usado como o nome do link ao vincular a um rótulo.

Links ¶

O link é feita com :ref:`nome_rotulo`. Quando precisar de um texto de link alternativo, use :ref:`Texto alternativo <nome_rotulo>`.

O link para páginas externas é feito com `url`_ e `nome do link <url>`_, que se tornará o ``nome do link.

Pandoc <https://pandoc.org/>`_ gosta de transformá-los em ```nome do link`__ e, em seguida, adicionar .. __ :url ao final do documento. Este é um chamado ‘hiperlink anônimo’, o que significa que, dependendo da ordem dos links que aparecem no texto, a ordem dos links no final do texto são associados uns aos outros. Se isso parece confuso e difícil, é porque é. Essa também é a razão exata pela qual gostaríamos de evitar links como esses.

Notas de rodapé e leituras adicionais ¶

As notas de rodapé podem ser feitas de 3 maneiras, a mais comum é com numeração automática, conforme referência:

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

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

Aqui está uma referência de citação: [CIT2002] .

[CIT2002]

Esta é a citação. É como uma nota de rodapé, exceto que o rótulo é textual.

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

Na verdade, não usamos notas de rodapé no manual por serem um pouco acadêmicas demais para nossos leitores. No entanto, coletamos documentos e links que fornecem um pouco mais de informação sobre um tópico no final de uma página. O Sphinx possui a diretiva .. seealso:: para vincular a links externos, enquanto o reStructuredText sugere o uso de .. rubic:: Footnotes para coletar notas de rodapé especificamente, pois isso funciona bem com LaTeX.

Imagens ¶

Use a diretiva image para imagens sem legendas:

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

E diretrizes de figuras para imagens com legendas:

.. figure:: /images/exemplo.png
   :figwidth: 800
   :align: center
   :alt: uma imagem.

   Uma legenda --  observe como a primeira letra está alinhada com a opção :figwidth:.

Esta última fornece:

Uma legenda — observe como a primeira letra da legenda na diretiva está alinhada com a opção :figwidth:.¶

As imagens devem ir para a pasta /images. Ao usar /images em vez de images, o Sphinx saberá que o caminho do arquivo não é relativo.

Marcação no texto ¶

Você pode tornar o texto enfatizado e forte com um asterisco simples e um duplo, respectivamente:

*enfatizado*
**forte**

Você não pode fazer *enfatizado e forte* ao mesmo tempo, então faça uma escolha.

Você pode _{subscrever texto} e ^{sobrescrever texto} usando :sub:`texto` e :sup:`texto`.

No entanto, use-os com extrema moderação! É preferível usar a marcação semântica existente no Sphinx em qualquer caso, pois isso facilita a tomada de decisões pelos tradutores sobre a natureza do texto.

:menuselection:`Configurações --> Configurar Krita...`
:guilabel:`Arquivo`
:kbd:`Ctrl + Z`
:program:`Krita`

Evite colocar palavras em negrito aleatoriamente. Isso não torna o texto mais fácil ou agradável de ler.

Referências de substituição ¶

Você pode criar uma espécie de abreviação para um pedaço de texto ou uma imagem fazendo:

.. |abreviação| replace:: algo ou aquilo.

o que significa que se você usar |abreviação|, no texto, ele será substituído por ‘algo ou aquilo’. Isso é útil para imagens e textos que precisam ser formatados de forma complexa, como no caso do “LaTeX”.

Para links, se você reutilizar o mesmo link várias vezes, você pode escrever algo como o seguinte no final do arquivo:

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

Então, ao digitar um link, você pode simplesmente usar `bugzilla`_ para criar um link para o bugzilla com “bugzilla” usado como texto do link. `Manual do Krita`_, por sua vez, criará um link para docs.krita.org com o texto “Manual do Krita”.

Listas ¶

Listas ordenadas ¶

Maçã
Pera
Banana

Ou…

Mesa
Cadeira
Armário.

Augustus
Nero
Caligula
Trajano

Eles podem ser definidos da seguinte forma:

1. Maçã
2. Pera
3. Banana

#. Maçã
#. Pera
#. Banana

A. Mesa
B. Cadeira
C. Armário

A. Mesa
#. Cadeira
#. Armário

I. Augustus
#. Nero
#. Caligula
#. Trajano

Listas não ordenadas ¶

vermelho
amarelo
verde
- verde-marinho
- verdete
- verde-petróleo
- verde-esverdeado
- esmeralda
  
  esmeralda escuro
  
  esmeralda claro
  
  esmeralda muito claro.
azul

Definido como:

- vermelho
- amarelo
- verde
    - verde-marinho
    - verdete
    - verde-petróleo
    - verde-esverdeado
    - esmeralda
        - esmeralda escuro
        - esmeralda claro
            - esmeralda muito claro.
- azul

Listas de definição ¶

Uma das favoritas! Listas de definições são especialmente úteis ao enumerar todas as opções em um painel e tentar adicionar uma explicação simples por trás delas.

Definição

Explicação.

Outra opção

Explicação.

Para criá-las.

Você pode criá-las assim:

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

Tabelas ¶

Propósito	Tipo de tabela
lista de atalhos	Tabela simples
muitas colspans	Tabela de grade
Simples mas longa	Tabela de lista

Feita como a seguir:

================== ============
Propósito            Tipo de tabela
================== ============
lista de atalhos  Tabela simples
muitas colspans   Tabela de grade
Simples mas longa    Tabela de lista
================== ============

+-----------------+------------+
|Propósito          |Tipo de tabela  |
+=================+============+
|lista de atalhos|Tabela simples|
+-----------------+------------+
|muitas colspans |Tabela de grade  |
+-----------------+------------+
|Simples mas longa  |Tabela de lista  |
+-----------------+------------+

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

   - * Propósito
     * Tipo de tabela
   - * lista de atalhos
     * Tabela simples
   - * muitas colspans
     * Tabela de grade
   - * simples mas longa
     * Tabela de lista

Tabelas de grade completa são ideais para quando você precisa de todos os recursos, como extensões complexas de colunas e linhas, mas são complicadas de criar. Por esse motivo, tabelas pequenas são mais adequadas para serem criadas com a sintaxe simples, enquanto tabelas muito longas são mais adequadas para serem criadas com uma diretiva de lista, pois é muito mais fácil de escrever e manter.

Advertências e comentários à parte ¶

Nota

As advertências são como uma seção separada à qual o leitor precisa prestar atenção.

As advertências que podem ser usadas são as seguintes (em ordem de gravidade):

Dica

Dicas são úteis para fornecer um pouco mais de informação sobre um tópico do que o texto principal. Por exemplo, “Estes pacotes têm nomes diferentes no OpenSuse e no Debian”.

Dica

Informações extras sobre como fazer algo, como “Você pode criar um modelo da sua configuração de documento favorita” ou “Use m para espelhar a tela e ver erros mais facilmente no seu desenho”.

Importante

Algo que é importante notar, mas não é necessariamente negativo.

Aviso

Isso geralmente ocorre quando algo é negativo.

Atenção

Chamativa geral de atenção. Use quando o assunto for mais importante do que um aviso, mas não tão importante a ponto de causar perda de dados.

Cuidado

Isso é para coisas que podem causar perda de dados, como esquecer de salvar ou que o Python atualmente não tem funcionalidade de desfazer.

Perigo

Isso deve ser feito para coisas que são perigosas para o computador em geral, incluindo coisas que podem causar travamentos por falta de memória.

Erro

Isto provavelmente não é relevante para um manual. O Sphinx pode criá-los manualmente em algumas situações, mas nossa configuração não o faz por padrão.

Advertência genérica que pode ter qualquer texto

Texto.

Você pode criá-lo assim:

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

    Texto.

O Sphinx também adiciona:

.. seealso::

    O que é útil para coletar links e referências externas.

Dito isto, réguas horizontais podem ser feitas com ----.

A diretiva de rubrica

A diretiva rubric é uma diretiva de título que, à primeira vista, parece “tópico”, mas quando o tópico se estende por vários parágrafos, a rubrica em si lida apenas com o cabeçalho, assim:

.. rubric:: A diretiva de rubrica

Então, quando usar isso?

Use-a somente quando achar que o assunto é muito pequeno para ter um título adequado.

Tópico: Quando o texto é separado do fluxo, ele aborda um assunto diferente daquele que o próprio texto abordaria naturalmente.
Rubrica: Quando o texto não está separado do fluxo, mas também não precisa de um cabeçalho.
Advertências: Somente quando se encaixam semanticamente. Isso é especialmente necessário para os avisos de perigo e advertência, pois vê-los com muita frequência pode fazer com que os usuários não os percebam.

Trechos de código ¶

Trechos de código em linha são feitos com ``crases``.

Trechos de código de várias linhas são feitos terminando a seção anterior com ::, que ficará assim:

Este é um parágrafo, e definimos um trecho pré-formatado como::

    Certifique-se de adicionar um espaço em branco e uma tabulação antes de iniciar o trecho.

Você também pode usar a diretiva .. code::. Se você adicionar o nome da linguagem depois dela, o realce de sintaxe apropriado será realizado:

.. code:: python

    # Comentário Python
    def my_function():
        alist = []
        alist.append(1)
        string = "olá mundo"

Se torna

# Comentário Python
def my_function():
    alist = []
    alist.append(1)
    string = "olá mundo"

um pouco mais…

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

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

/* Comentário CSS */
body {
    margin: 0 auto;
    /* 800 ainda é sensível? */
    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 HTML --> um parágrafo.</p>

Outros textos pré-formatados ¶

Você pode
pré-formatar
o texto
precedendo
cada linha
com um símbolo
de pipe

Como a seguir:

| Você pode
| pré-formatar
| o texto
| precedendo
| cada linha
| com um símbolo
| de pipe

Isso geralmente não é usado no manual e só deve ser usado quando for absolutamente necessário representar conteúdo que precisa de formatação exata, mas nunca apenas por razões estéticas.

Glossários, Termos e Índice ¶

Essas são as funcionalidades do sphinx.

O índice é usado na seção superior; no momento, apenas entradas de índice simples são usadas.

Glossários são usados para algumas seções de entrada do menu, mas não para todas.

Citações ¶

As citações são feitas assim:

Não sei por que você precisaria de citações em um manual do usuário...

-- Wolthera

Isto se torna uma citação em bloco.

Não sei por que você precisaria de citações em um manual do usuário…

—Wolthera

Na verdade, usamos aspas em alguns lugares. Tente adicionar um link ao nome para definir de onde ele veio.

Texto somente para traduções em outros idiomas além do inglês ¶

Você pode usar o seguinte para incluir texto que só faça sentido para traduções do manual em outros idiomas, por exemplo, para fornecer aos leitores de outros idiomas os nomes em inglês de um item para referência:

.. only:: non_english

    Este conteúdo está oculto na versão em inglês, mas pode ser traduzido e
    aparece em versões que não sejam em inglês.

Notas para os tradutores ¶

Se você estiver traduzindo o manual para um idioma que normalmente não usa espaços em branco ao redor das palavras (por exemplo, chinês e japonês), você pode usar um espaço em branco de escape para separar a marcação e as palavras. Isso é particularmente útil para links de páginas, como este:

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

Observe que ao traduzir de um arquivo PO, você deve escapar a barra invertida com outra barra invertida:

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

The above produces “床前明月光”, instead of “床前明月光”.