bijdragen aan dtdocs

Deze pagina definieert de stijlgids voor dtdocs en informatie over hoe je kan bijdragen aan het project.

Het is opgenomen in de gebruikershandleiding, zodat je kunt zien hoe de pagina wordt weergegeven en hoe deze is geschreven. Ga naar GitHub om de bron voor deze pagina te zien.

De structuur en inhoud van de handleiding zijn zorgvuldig overwogen op basis van de volgende criteria:

  1. De handleiding moet uitgebreid zijn – het moet alle functionaliteit beschrijven die beschikbaar is in darktable
  2. Het moet een consistente en logische structuur hebben en elk stukje functionaliteit moet zijn eigen logische plaats binnen die structuur hebben
  3. Het moet zo lang zijn als nodig is, maar zo kort mogelijk - beknoptheid is een must
  4. Het moet objectief zijn
  5. Functionaliteit moet eenmalig worden uitgelegd (met uitzondering van de basisworkflowrichtlijnen in het overzichtsgedeelte)
  6. Afbeeldingen mogen alleen worden toegevoegd als dat nodig is om het begrip van de belangrijkste principes te verbeteren en mogen geen tekst bevatten, tenzij dit onvermijdelijk is Best is om de handleiding voor vertaling te lezen vooraleer aan de slag te gaan. Als je gewoon begint te vertalen kom je deze tekst tegen als je 96 % van de vertaling afgewerkt hebt.

We zijn over het algemeen niet geïnteresseerd in:

  1. Herstructurering van de handleiding
  2. Wisselen van opmaaktalen
  3. Gedetailleerde werkstroom-tutorials (hoewel we geïnteresseerd zijn in het publiceren ervan op de blogs van darktable.org of pixls.us)

We zijn geïnteresseerd in

  1. Spelling- en grammaticacorrecties
  2. Verduidelijking van tekst
  3. Documentatie voor nieuwe functies

We zijn altijd zeer geïnteresseerd om te horen welke delen van de handleiding voor jou niet logisch waren en waarom, zodat we de documentatie kunnen verbeteren.

In het algemeen, als je een grote wijziging wilt aanbrengen, open dan een probleem en bespreek dit eerst met de beheerders. Dit om te voorkomen dat je werk doet dat niet zou worden geaccepteerd.

🔗format

Deze website is geschreven in pure afwaardering, met behulp van enkele extensies. Het is in eerste instantie ontworpen om met de Hugo SSG te werken, maar het is bedoeld om draagbaar genoeg te zijn zodat het, indien nodig, gemakkelijk kan worden weergegeven met een andere toepassing.

Bestanden moeten worden weergegeven in UTF-8 en mogen geen kolomomloop bevatten.

🔗struktuur

Hieronder zie je de opbouw van een voorbeeldhoofdhoofdstuk met subparagrafen op de dtdocs-website.

voorbeeld-hoofdstuk/
    _index.md
    sectie1-met-subsecties/
       onderafdeling1/
          afbeelding.png
       _index.md
       subsectie1.md
       subsectie2.md
    sectie2.md
    sectie3.md

Een paar opmerkingen over de bovenstaande structuur:

  • _index.md-bestanden bevatten geen inhoud (ze bevatten alleen metadata) en worden gebruikt om sectiekoppen en inhoudstafel-items weer te geven. In het bovenstaande voorbeeld definieert voorbeeld-hoofdstuk/_index.md de titel van het voorbeeldhoofdstuk en de volgorde waarin het in de hoofdinhoudsopgave verschijnt. Op dezelfde manier definieert voorbeeld-hoofdstuk/sectie1-met-subsecties/_index.md metadata voor de eerste sectie van het hoofdstuk.

  • Mediabestanden moeten in een map staan met dezelfde naam als de pagina waarop ze betrekking hebben. In dit voorbeeld bevat voorbeeld-hoofdstuk/sectie1-with-subsections/subsection1 media gerelateerd aan de subsection1.md pagina.

🔗metadata

Metadata voor de markdown-bestanden worden bovenaan de pagina weergegeven met yaml. Elke metadata kan worden gedefinieerd – de modulereferentiesecties bevatten nogal wat specifieke metadata – maar het volgende definieert enkele minimale metadata voor de voorbeeldpagina voorbeeld-hoofdstuk/sectie1-met-subsecties/subsectie1.md.

---
titel: Subsectie 1 Titel
id: subsectie1
gewicht: 10
---
titel
Dit moet de weergegeven titel van jouw pagina bevatten. Om een dubbele punt in een titel op te nemen, plaats je de titel tussen dubbele aanhalingstekens.
ID
Dit is de id die Hugo gebruikt om de pagina te identificeren. Het moet meestal dezelfde naam hebben als het bestand (voor inhoudsbestanden) of de bovenliggende map (voor _index.md-bestanden).
gewicht
Dit is een optioneel metagegevensveld dat wordt gebruikt om de volgorde te definiëren waarin secties worden weergegeven in de inhoudsopgave. Als het veld gewicht niet is opgenomen, worden pagina’s standaard in alfabetische volgorde weergegeven. Als je bijvoorbeeld de secties en subsecties van het bovenstaande voorbeeld in omgekeerde volgorde wilt definiëren, moeten de volgende metagegevens worden ingesteld:
   voorbeeld-hoofdstuk/
       sectie1-met-subsecties/
          _index.md # gewicht: 30 (plaats sectie1 pagina aan het einde van voorbeeldhoofdstuk)
          subsectie1.md # gewicht: 20 (plaats subsectie1 pagina aan het einde van sectie1)
          subsectie2.md # gewicht: 10 (plaats subsectie2 pagina aan het begin van sectie1)
       section2.md # gewicht: 20 (plaats section2 in het midden van het voorbeeld-hoofdstuk)
       section3.md # gewicht: 10 (plaats section3 aan het begin van het voorbeeldhoofdstuk)

🔗inhoud

🔗algemene stijlbegeleiding

  • Alle inhoud moet worden geschreven in duidelijke markdown zonder shortcodes en HTML moet tot een absoluut minimum worden beperkt, als het al wordt gebruikt

  • Minimalisme is een absolute must. Minder woorden hebben de voorkeur

  • Markdown-bestanden moeten zo kort mogelijk zijn

  • Volg de naamgevings- en hoofdletternormen die aanwezig zijn in de GUI van de applicatie – namelijk alle hoofdingen en titels zijn in kleine letters, behalve de hoofdstuknamen op het hoogste niveau

  • Headers in een bestand mogen niet hoger zijn dan niveau drie (###)

  • De primaire auteurstaal is Engels

  • Ga ervan uit dat de lezer de applicatie heeft geopend tijdens het lezen van de gebruikershandleiding. Neem enkel afbeeldingen die bijdragen aan de uitleg van complexe functionaliteit.

  • Gebruik afbeeldingsbijschriften als je een afbeelding moet toelichten (d.w.z. markeer delen van de afbeelding met een letter of cijfer en leg vervolgens de betekenis uit in tekst die volgt op de afbeelding). Plaats geen woorden rechtstreeks in de afbeelding voor toelichtingen, omdat dit de lokalisatie bemoeilijkt. Zie deze pagina voor een voorbeeld.

  • Wijzigingen in de inhoud moeten worden voorgesteld via een pull-verzoek of een vergelijkbaar mechanisme

  • Jouw inzendingen worden aangepast - vat het niet persoonlijk op

🔗definitielijsten

De standaardmethode voor het presenteren van informatie over de besturingselementen van darktable-modules is het gebruik van definitielijsten.

gui-besturingsnaam
Een verklaring van wat de besturing doet. Bijvoorbeeld “Stel de belichting in EV-eenheden in”.

Je kan zoveel alinea’s opnemen als je wilt, maar probeer waar mogelijk te beperken tot 2 of 3.

active-icon een besturingselement dat toegankelijk is via een knop met een pictogram
Wanneer een besturingselement is geactiveerd met een pictogram, maak dan een screenshot van het pictogram met behulp van het standaard darktable-thema en voeg het toe vóór de naam van het besturingselement
gui keuzemenunaam
Keuzemenus hebben vaak meerdere opties die allemaal moeten worden weergegeven met aparte definities. Gebruik lijsten met opsommingstekens met italics voor de keuzemenu-waarden.
  • de eerste waarde: Wat de eerste waarde betekent
  • de tweede waarde: Wat de tweede waarde betekent

Definitielijsten worden ook overal in het document gebruikt, overal waar een benoemd stuk functionaliteit moet worden gedefinieerd. Zie bijvoorbeeld darktable-cli.

🔗opmerkingen

Als je een belangrijke opmerking aan de gebruiker wilt presenteren, gebruikt je het volgende formaat:

Opmerking: dit is een belangrijke opmerking.

🔗lettertypen en codeblokken met vaste breedte

Lettertypen met een vaste breedte (met het teken `) mogen normaal gesproken alleen worden gebruikt voor codeblokken en bij het verwijzen naar bestandsnamen en opdrachtregelparameters.

Interne links moeten relatief zijn aan het huidige bestand en moeten verwijzen naar een geldig markdown-bestand (.md). Start koppelingen met ./ om de huidige map aan te geven of met ../ om de bovenliggende map weer te geven.

🔗afbeeldingen

Gebruik het standaard darktable-thema wanneer je schermafbeeldingen maakt vanuit de darktable-toepassing zelf.

Er kunnen verschillende achtervoegsels voor bestandsnamen worden gebruikt om te bepalen hoe een afbeelding wordt weergegeven.

pictogram
Om een afbeelding als pictogram in te voegen, voeg je #icon toe achter de afbeeldingsnaam in de link. De prijsverlaging ` eekhoornpictogram ’ geeft het volgende weer: eekhoornpictogram
afbeeldingsbreedte
Je kan de afbeeldingsbreedte instellen op 25, 33, 50, 66, 75 of 100 procent van de weergegeven paginabreedte door #wxx achter de afbeeldingsnaam in de link op te nemen, waarbij xx de gewenste breedte is. Bijvoorbeeld:
![eekhoorn](./contributing/squirrel.png#w25) uitgangen
eekhoorn
![eekhoorn](./contributing/squirrel.png#w75) uitgangen
eekhoorn
in lijn
Met uitzondering van pictogrammen worden afbeeldingen standaard als blokelementen opgenomen. Je kan dit overschrijven door #inline achter de afbeeldingsnaam op te nemen. Dit kan als volgt worden gecombineerd met de breedte-instelling.
![squirrel](./contributing/squirrel.png#w25#inline) uitgangen squirrel
standaard
Standaard worden afbeeldingen weergegeven als blokelementen met een breedte van 100%. Dus ![eekhoorn](./contributing/squirrel.png#w100) en ![eekhoorn](./contributing/squirrel.png) zijn equivalent en geven beide het volgende weer:
eekhoorn

translations