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:

  1. O manual deve ser completo: deve descrever todas as funcionalidades disponíveis no darktable
  2. Deve ter uma estrutura lógica e coerente e cada parte da funcionalidade deve ter seu próprio local lógico dentro desta estrutura
  3. Deve ser tão longo quanto seja necessário mas o mais curto possível – a brevidade é imprescindível
  4. Deve ser objetivo
  5. 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)
  6. 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:

  1. Reestruturação do manual
  2. Mudanças de linguagem de marcação
  3. 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:

  1. Correções ortográficas e gramaticais
  2. Aumento da clareza do texto
  3. 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

  • All content should be authored in plain markdown without shortcodes and HTML should be kept to an absolute minimum, if used at all

  • Minimalismo é absolutamente necessário. Preferem-se menos palavras.

  • Arquivos markdown devem ser tão pequenos quanto possível.

  • Siga as normas de nomeação 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. Da mesma forma, use todas as letras minúsculas ao fazer referência a nomes de módulos e controles.

  • Os cabeçalhos de um arquivo não devem exceder o nível três (###).

  • O idioma de autoria principal é o inglês. Evite linguagem idiomática sempre que possível, pois a versão em inglês da documentação pode ser lida por pessoas para quem o inglês não é seu idioma nativo.

  • 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.

🔗atalhos de teclado e mouse

  • Referencie teclas de teclado nomeadas usando CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)

  • Referencie teclas de uma única letra em minúsculas (isso evita confusão entre, por exemplo, Ctrl+H e Ctrl+Shift+h). As aspas podem ajudar no esclarecimento (pressione “h” para ver uma lista de atalhos ativos)

  • Faça referência às ações do mouse usando letras minúsculas, com várias palavras unidas por um hífen (rolagem, clique, clique-único, clique-duplo, clique-direito)

  • Conecte combinações de teclas/ações com um sinal de mais (Ctrl+Shift+h, Shift+clique-duplo)

🔗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.

active-icon é 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 (darktable-elegant-grey) 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ções 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.

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.

🔗imagens

Ao fazer capturas de tela do próprio aplicativo darktable, use o tema padrão do darktable (darktable-elegant-grey).

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: ícone de esquilo
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
![esquilo](./contributing/esquilo.png#w75) produz:
esquilo
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: esquilo
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:
esquilo

translations