contribuindo para o dtdocs

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

It is included in the user manual so that you can see how the page is rendered as well as how it is written. Please go to GitHub to see the source for this page.

The manual structure and content have been carefully considered based on the following critera:

  1. The manual should be comprehensive – it should describe all of the functionality available in darktable
  2. It should have a consistent and logical structure and every piece of functionality should have its own logical place within that structure
  3. It should be as long as necessary but as short as possible – brevity is a must
  4. It should be objective
  5. Functionality should be explained once and only once (with the exception of the basic workflow guidelines in the overview section)
  6. Images should be included only where necessary to improve understanding of key principles and should not contain text unless it is unavoidable

We are generally not interested in:

  1. Restructuring the manual
  2. Switching markup languages
  3. Detailed workflow tutorials (though we are interested in publishing those on the blogs of either darktable.org or pixls.us)

We are interested in

  1. Spelling and grammar corrections
  2. Clarification of text
  3. Documentation for new features

We are always extremely interested in hearing about which sections of the manual did not make sense to you and why, so that we can improve the documentation.

In general, if you wish to make a major change, please open an issue and discuss it with the maintainers first. This is to avoid doing work that wouldn’t be accepted.

🔗format

This website is authored in pure markdown, using some extensions. It is initially designed to work with the Hugo SSG but intended to be portable enough that it can be easily rendered with another application if required.

Files should be rendered in UTF-8 and should not include any column wrapping.

🔗estrutura

The following shows the structure of an example main chapter with subsections in the dtdocs website.

example-chapter/
   _index.md
   section1-with-subsections/
      subsection1/
         image.png
      _index.md
      subsection1.md
      subsection2.md
   section2.md
   section3.md

Algumas notas sobre a estrutura acima:

  • _index.md files do not contain any content (they contain metadata only) and are used to render section headers and ToC entries. In the above example example-chapter/_index.md defines the title of the example chapter and the order in which it appears in the main table of contents. Similarly example-chapter/section1-with-subsections/_index.md defines metadata for the first section of the chapter.

  • Media files should be contained in a directory with the same name as the page to which they relate. In this example, example-chapter/section1-with-subsections/subsection1 contains media related to the subsection1.md page.

🔗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, o seguinte define alguns metadados mínimos para a página de exemplo example-chapter/section1-with-subsections/subsection1.md.

---
título: Título da subseção 1
id: subseção1
carga: 10
---
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 o diretório principal (para arquivos _index.md).
carga
Este é um campo de metadados opcional usado para definir a ordem em que as seções são apresentadas no Índice. Se o campo carga 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:
   example-chapter/
      section1-with-subsections/
         _index.md               # carga: 30 (coloque a página da seção 1 no final do capítulo de exemplo)
         subsection1.md             # carga: 20 (coloque a página da subseção 1 no final da seção 1)
         subsection2.md             # carga: 10 (coloque a página da subseção 2 no início da seção 1)
      section2.md                # carga: 20 (coloque a seção 2 no meio do capítulo de exemplo)
      section3.md                # carga: 10 (coloque 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 shortcodes e a quantidade de HTML deve ser mínima, se houver.

  • Minimalismo é absolutamente necessário. Prefererem-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 tenha 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.

controle de nome na interface gráfica
Uma declaração do que o controle faz. Por exemplo “Defina 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 e adicione-o antes do nome do controle
caixa de combinação de nomes 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:


Observação: 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.

🔗ligações

As ligações internas devem ser relativas ao arquivo atual e devem apontar para uma marcação válida de arquivo (.md). Inicie as ligações com ./ para representar o diretório atual ou ../ para representar o diretório pai.

🔗imagens

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

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 na ligação. O markdown ![squirrel icon](./contributing/contributing.png#icon) produz o seguinte: squirrel icon
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 na ligação, onde xx e a largura desejada. Por exemplo:
![squirrel](./contributing/squirrel.png#w25) saídas
squirrel
![squirrel](./contributing/squirrel.png#w75) saídas
squirrel
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.
![squirrel](./contributing/squirrel.png#w25#inline) saídas squirrel
padrão
Por padrão, as imagens são apresentadas como elementos de bloco com largura de 100%. Então ![squirrel](./contributing/squirrel.png#w100) e ![squirrel](./contributing/squirrel.png) são equivalentes e ambos produzem o seguinte:
squirrel

Translations