contribuyendo a dtdocs

Esta página define la guía de estilo para dtdocs e información sobre cómo contribuir al proyecto.

Se incluye en el manual del usuario para que pueda ver cómo se representa la página y cómo está escrita. Vaya a GitHub para ver la fuente de esta página.

La estructura y el contenido del manual se han considerado cuidadosamente con base en los siguientes criterios:

  1. El manual debe ser completo: debe describir todas las funciones disponibles en darktable.
  2. Debe tener una estructura lógica y coherente y cada parte de la funcionalidad debe tener su propio lugar lógico dentro de esa estructura.
  3. Debe ser tan largo como sea necesario pero lo más corto posible; la brevedad es imprescindible
  4. Debe ser objetivo
  5. La funcionalidad debe explicarse una vez y solo una vez (con la excepción de las pautas básicas del flujo de trabajo en la sección de descripción general)
  6. Las imágenes deben incluirse solo cuando sea necesario para mejorar la comprensión de los principios clave y no deben contener texto a menos que sea inevitable.

Generalmente no estamos interesados en:

  1. Reestructuración del manual
  2. Cambio de lenguajes de marcado
  3. Tutoriales de flujo de trabajo detallados (aunque estamos interesados en publicarlos en los blogs de darktable.org o pixls.us)

Estamos interesados en

  1. Correcciones ortográficas y gramaticales
  2. Aclaración del texto
  3. Documentación de nuevas funciones

Siempre estamos muy interesados en saber qué secciones del manual no tienen sentido para usted y por qué, para que podamos mejorar la documentación.

En general, si desea realizar un cambio importante, abra un problema y discútalo primero con los encargados del mantenimiento. Esto es para evitar hacer un trabajo que no sería aceptado.

🔗formato

Este sitio web está creado en markdown, utilizando algunas extensiones. Inicialmente está diseñado para funcionar con Hugo SSG, pero tiene la intención de ser lo suficientemente portátil como para que se pueda renderizar fácilmente con otra aplicación si es necesario.

Los archivos deben renderizarse en UTF-8 y no deben incluir ningún ajuste de columna.

🔗estructura

A continuación se muestra la estructura de un capítulo principal de ejemplo con subsecciones en el sitio web dtdocs.

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

Un par de notas sobre la estructura anterior:

  • Los archivos _index.md no contienen ningún contenido (solo contienen metadatos) y se utilizan para representar encabezados de sección y entradas de TdC. En el ejemplo anterior, example-chapter/_index.md define el título del capítulo de ejemplo y el orden en el que aparece en la tabla de contenido principal. De manera similar, example-chapter/section1-with-subsections/_index.md define metadatos para la primera sección del capítulo.

  • Los archivos multimedia deben estar contenidos en un directorio con el mismo nombre que la página con la que se relacionan. En este ejemplo, example-chapter/section1-with-subsections/subsection1 contiene medios relacionados con la página subsection1.md`.

🔗metadatos

Los metadatos para los archivos de markdown se presentan en el encabezado de la página usando yaml. Se pueden definir todos los metadatos (las secciones de referencia del módulo contienen bastantes metadatos específicos), sin embargo, a continuación se definen algunos metadatos mínimos para la página de ejemplo example-chapter/section1-with-subsections/subsection1.md.

---
title: Sub Section 1 Title
id: subsection1
weight: 10
---
title
Este debe contener el título renderizado de su página. Para incluir dos puntos dentro de un título, encierre el título entre comillas dobles.
id
Esta es la identificación utilizada para identificar la página por Hugo. Por lo general, debe tener el mismo nombre que el archivo (para archivos de contenido) o el directorio principal (para archivos _index.md).
weight
Este es un campo de metadatos opcional que se utiliza para definir el orden en el que se presentan las secciones en la Tabla de contenido. Si no se incluye el campo weight, las páginas se mostrarán en orden alfabético de forma predeterminada. Por ejemplo, para definir las secciones y subsecciones del ejemplo anterior en orden inverso, es necesario configurar los siguientes metadatos:
   example-chapter/
		section1-with-subsections/
			_index.md				# weight: 30 (coloca la página section1 al final de example-chapter)
			subsection1.md				# weight: 20 (coloca la página subsection1 al final de section1)
			subsection2.md				# weight: 10 (coloca la página subsection2 al principio de section1)
		section2.md				# weight: 20 (coloca section2 en medio de example-chapter)
		section3.md				# weight: 10 (coloca section3 al principio example-chapter)

🔗contenido

🔗orientación general 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

  • El minimalismo es una necesidad absoluta. Se prefieren menos palabras

  • Los archivos de Markdown deben ser lo más cortos posible

  • Follow the naming and capitalization norms present in the GUI of the application – namely all headers and titles are in lower case, except for the very top-level chapter names. Similarly, use all lower case when referencing module names and controls.

  • Los encabezados de un archivo no deben exceder el nivel tres (###)

  • The primary authoring language is English. Avoid idiomatic language where possible as the English version of the documentation may be read by people for whom English is not their native language

  • Suponga que el lector tiene la aplicación abierta mientras lee el manual del usuario y solo incluya imágenes donde contribuyan a la explicación de una funcionalidad compleja.

  • Use leyendas de imagen si necesita anotar una imagen (es decir, marque partes de la imagen con una letra o número y luego explique el significado en algún texto después de la imagen). No coloque palabras directamente en la imagen para las anotaciones, ya que esto dificulta la localización. Consulte esta página para ver un ejemplo.

  • Los cambios en el contenido deben proponerse mediante una solicitud de extracción o un mecanismo similar.

  • Sus envíos serán corregidos – no se lo tome como algo personal.

🔗keyboard and mouse shortcuts

  • Reference named keyboard keys using CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)

  • Reference single letter keys in lower case (this avoids confusion between for example, Ctrl+H and Ctrl+Shift+h). Quotation marks might help with clarification (press “h” to see a list of active shortcuts)

  • Reference mouse actions using lower case, with multiple words joined by a hyphen (scroll, click, single-click, double-click, right-click)

  • Connect combinations of keys/actions with a plus sign (Ctrl+Shift+h, Shift+double-click)

🔗listas de definiciones

El método estándar de presentar información sobre los controles del módulo darktable es con el uso de listas de definición.

nombre de control de interfaz gráfica de usuario
Una declaración de lo que hace el control. Por ejemplo, “Establezca la exposición en unidades EV”.

Puede incluir tantos párrafos como desee, pero trate de limitarlo a 2 o 3 cuando sea posible.

active-icon a control accessed through a button with an icon
When a control is activated using an icon, take a screenshot of the icon using the standard darktable theme (darktable-elegant-grey) and add it before the name of the control
nombre del cuadro combinado de interfaz gráfica de usuario
Los cuadros combinados suelen tener varias opciones que deben mostrarse con definiciones independientes. Utilice listas con viñetas con cursivas para los valores del cuadro combinado.
  • el primer valor: lo que significa el primer valor
  • el segundo valor: lo que significa el segundo valor

Las listas de definiciones también se utilizan en todo el documento, siempre que sea necesario definir una función con nombre. Vea, por ejemplo, darktable-cli.

🔗notas

Si desea presentar una nota importante al usuario, utilice el siguiente formato:

Nota: esta es una nota importante.

🔗fuentes de ancho fijo y bloques de código

Las fuentes de ancho fijo (que usan el carácter `) normalmente solo deben usarse para bloques de código y cuando se hace referencia a nombres de archivos y parámetros de línea de comandos.

🔗enlaces

Los enlaces internos deben ser relativos al archivo actual y deben apuntar a un archivo de markdown válido (.md). Inicie los enlaces o con ./ Para representar el directorio actual o ../ para representar el directorio padre.

🔗imágenes

When taking screenshots from the darktable application itself, use the default darktable theme (darktable-elegant-grey).

Se pueden usar varios sufijos de nombre de archivo para controlar cómo se representa una imagen.

icono
Para insertar una imagen como un icono, incluya #icon después del nombre de la imagen en el enlace. El markdown ![squirrel icon](./contributing/contributing.png#icon) da como resultado lo siguiente: squirrel icon
image width
Puede fijar el ancho de la imagen en un 25, 33, 50, 66, 75 o 100 por ciento de la página renderizada incluyendo #wxx tras el nombre de la imagen en el enlace, donde xx es el ancho deseado. por ejemplo:
![squirrel](./contributing/squirrel.png#w25) produce
squirrel
![squirrel](./contributing/squirrel.png#w75) produce
squirrel
inline
Con la excepción de los iconos, las imágenes se incluyen como elementos de bloque de forma predeterminada. Puede anular esto incluyendo #inline después del nombre de la imagen. Esto se puede combinar con la configuración de ancho de la siguiente manera.
![squirrel](./contributing/squirrel.png#w25#inline) produce squirrel
default
Por defecto, las imágenes se presentan como elementos de bloque con un ancho del 100%. Así que ![squirrel](./contributing/squirrel.png#w100) y ![squirrel](./contributing/squirrel.png) son equivalentes y ambos generan lo siguiente:
squirrel

translations