contribuir para o dtdocs

Esta página define o guia de estilo para o dtdocs e fornece informações sobre como contribuir para o projeto.

Ela está incluída no manual do usuário para que você possa ver como a página é renderizada e como ela foi escrita. Vá para o GitHub para ver a fonte desta página.

A estrutura e conteúdo do manual considerou cuidadosamente os seguintes critérios:

O manual deve ser completo: deve descrever todas as funcionalidades disponíveis no darktable
Deve ter uma estrutura lógica e coerente e cada parte da funcionalidade deve ter seu próprio local lógico dentro desta estrutura
Deve ser tão longo quanto seja necessário mas o mais curto possível – a brevidade é imprescindível
Deve ser objetivo
A funcionalidade deve ser explicada somente uma vez (com exceção de guias gerais sobre o fluxo de trabalho na seção sobre a visão geral)
As imagens devem ser incluídas somente onde forem necessárias para aprimorar a compreensão dos princípios chave e não devem conter texto, a menos que isso seja inevitável

Geralmente não estamos interessados em:

Reestruturação do manual
Mudanças de linguagem de marcação
Tutoriais detalhados do fluxo de trabalho (ainda que estejamos interessados em publicar estes documentos nos blogs do darktable.org ou pixls.us)

Estamos interessados em:

Correções ortográficas e gramaticais
Aumento da clareza do texto
Documentação para novas funcionalidades

Sempre estamos muito interessados em ouvir sobre quais seções do manual não fazem sentido para você e por quê, para que possamos melhorar a documentação.

Em geral, se deseja realizar uma mudança significativa, abra um tópico para o problema e discuta-o com os mantenedores primeiro. Isto evita que você faça um trabalho que não será aceito.

🔗formato

Esta página Web foi criada em markdown puro, com algumas extensões. Ela foi inicialmente desenhada para funcionar com o Hugo SSG, mas tem a intenção de ser portável o suficiente para ser facilmente renderizada com outra aplicação se necessário.

Os arquivos devem ser renderizados em UTF-8 e não devem incluir ajuste de coluna.

🔗estrutura

Os tópicos a seguir mostram a estrutura de um capítulo principal de exemplo, com subseções, na página do dtdocs.

capítulo-exemplo/
   _index.md
   seção1-com-subseções/
      subseção1/
         imagem.png
      _index.md
      subseção1.md
      subseção2.md
   seção2.md
   seção3.md

Algumas notas sobre a estrutura acima:

Os arquivos _index.md não possuem conteúdo (somente metadados) e são utilizados para renderizar os cabeçalhos de seção e as entradas da tabela de conteúdo. No exemplo acima, capítulo-exemplo/_index.md define o título do capítulo de exemplo e a ordem em que ele aparece no índice principal. De maneira similar, capítulo-exemplo/seção1-com-subseções/_index.md define metadados para a primeira seção do capítulo.
Os arquivos multimídia devem estar colocados em uma pasta com o mesmo nome que a página com a qual se relacionam. Neste exemplo, capítulo-exemplo/seção1-com-subseções/subseção1 contem mídias relacionadas à página subseção1.md.

🔗metadados

Os metadados para os arquivos markdown são apresentados no cabeçalho da página usando yaml. Quaisquer metadados podem ser definidos – as seções de referência do módulo contêm muitos metadados específicos – no entanto, as linhas a seguir definem alguns metadados mínimos para a página de exemplo capítulo-exemplo/seção1-com-subseções/subseção1.md.

---
title: Título da subseção 1
id: subseção1
weight: 10
---

title (título): Deve conter o título renderizado de sua página. Para incluir dois pontos em um título, coloque o título entre aspas duplas.
id: Este é o id usado para identificar a página do Hugo. Normalmente deve ser o mesmo nome do arquivo (para arquivos de conteúdo) ou a pasta principal (para arquivos _index.md).
weight: Este é um campo de metadados opcional usado para definir a ordem em que as seções são apresentadas no Índice. Se o campo weight não for incluído, as páginas serão renderizadas em ordem alfabética por padrão. Por exemplo, para definir as seções e subseções do exemplo acima em ordem reversa, os seguintes metadados precisam ser definidos:

   capítulo-exemplo/
      seção1-com-subseções/
         _index.md 		# weight: 30 (coloca a página da seção 1 no final do capítulo de exemplo)
         subseção1.md 		# weight: 20 (coloca a página da subseção 1 no final da seção 1)
         subseção2.md 		# weight: 10 (coloca a página da subseção 2 no início da seção 1)
      seção2.md 		# weight: 20 (coloca a seção 2 no meio do capítulo de exemplo)
      seção3.md 		# weight: 10 (coloca a seção 3 no início do capítulo de exemplo)

🔗conteúdo

🔗guia geral de estilo

Todo o conteúdo deve ser escrito em markdown puro sem atalhos de código e a quantidade de HTML deve ser mínima, se houver.
Minimalismo é absolutamente necessário. Preferem-se menos palavras.
Arquivos markdown devem ser tão pequenos quanto possível.
Siga as normas de nomenclatura e capitalização presentes na interface gráfica do aplicativo – ou seja, todos os cabeçalhos e títulos estão em minúsculas, exceto para os nomes dos capítulos de nível superior.
Os cabeçalhos de um arquivo não devem exceder o nível três (###).
O idioma principal de autoria é o inglês.
Suponha que o leitor possui o aplicativo aberto enquanto lê o manual do usuário e inclua apenas imagens que contribuam para a explicação de funcionalidades complexas.
Use textos explicativos de imagem se precisar fazer anotações em uma imagem (ou seja, marque partes da imagem com uma letra ou número e, em seguida, explique o significado em algum texto após a imagem). Não coloque palavras diretamente na imagem para anotações, pois isso torna a localização difícil. Veja esta página para um exemplo.
Mudanças no conteúdo devem ser propostas por meio de solicitação “pull request” ou um mecanismo semelhante.
Suas submissões serão editadas – não entenda como algo pessoal.

🔗listas de definições

O método padrão de apresentação de informações sobre os controles dos módulos do darktable é com o uso de listas de definição.

nome do controle na interface gráfica

Uma declaração do que o controle faz. Por exemplo “Define a exposição em unidades EV”.

Você pode incluir quantos parágrafos quiser, mas tente limitar a 2 ou 3 quando possível.

é um controle acessado por meio de um botão com um ícone

Quando um controle é ativado usando um ícone, faça uma captura de tela do ícone usando o tema padrão do darktable e adicione-o antes do nome do controle.

nome da caixa de combinação na interface gráfica

As caixas combinadas geralmente têm várias opções que precisam ser exibidas com definições separadas. Use listas com marcadores com itálicos para os valores da caixa de combinação.

o primeiro valor: O que significa o primeiro valor

o segundo valor: O que significa o segundo valor

Listas de definição também são usadas em todo o documento, sempre que uma parte nomeada de funcionalidade precisa ser definida. Veja, por exemplo, darktable-cli.

🔗notas

Se você deseja apresentar uma observação importante ao usuário, use o seguinte formato:

Nota: Esta é uma observação importante.

🔗fontes de largura fixa e blocos de código

Fontes de largura fixa (usando o caractere `) normalmente devem ser usadas apenas para blocos de código e ao fazer referência a nomes de arquivos e parâmetros de linha de comando.

🔗links

Os links internos devem ser relativos ao arquivo atual e devem apontar para um arquivo markdown (.md) válido. Inicie os links com ./ para representar a pasta atual ou ../ para representar a pasta pai.

Os links para um módulo de processamento devem estar em itálico, por exemplo, exposição
Os links para um módulo de utilitário devem estar em texto simples, por exemplo, pilha de histórico
Faça o link para uma seção de nível superior referenciando o arquivo _index.md, por exemplo, referência de módulos
Faça o link para uma aba na janela de preferências desta maneira: preferências > geral
Faça o link para uma configuração de preferência específica desta maneira: preferências > geral > Interface de idioma
Cada cabeçalho de uma página pode ser vinculado diretamente a uma âncora: contribuição/notas

🔗imagens

Ao fazer capturas de tela do próprio aplicativo darktable, use o tema padrão do darktable.

Vários sufixos de nome de arquivo podem ser usados para controlar como uma imagem é renderizada.

ícone: Para inserir uma imagem como ícone, inclua #icon após o nome da imagem no link. O markdown ![ícone de esquilo](./contributing/esquilo.png#icon) produz o seguinte:
largura da imagem: Você pode definir a largura da imagem em 25, 33, 50, 66, 75 ou 100 por cento da largura da página renderizada, incluindo #wxx após o nome da imagem no link, onde xx é a largura desejada. Por exemplo:; ![esquilo](./contributing/esquilo.png#w25) produz:; ![esquilo](./contributing/esquilo.png#w75) produz:
inline: Com exceção dos ícones, as imagens são incluídas como elementos de bloco por padrão. Você pode substituir isso incluindo #inline após o nome da imagem. Isso pode ser combinado com a configuração de largura da seguinte forma.; ![esquilo](./contributing/esquilo.png#w25#inline) produz:
padrão: Por padrão, as imagens são apresentadas como elementos de bloco com largura de 100%. Então ![esquilo](./contributing/esquilo.png#w100) e ![esquilo](./contributing/esquilo.png) são equivalentes e ambos produzem o seguinte: