wkład w dtdocs

Ta strona definiuje przewodnik po stylu dla dtdocs oraz informacje o tym, jak przyczynić się do projektu.

Jest on zawarty w instrukcji obsługi, dzięki czemu można zobaczyć, jak strona jest renderowana, a także jak jest napisana. Przejdź do GitHub, aby zobaczyć źródło tej strony.

Struktura i treść podręcznika zostały dokładnie przeanalizowane w oparciu o następujące kryteria:

  1. Podręcznik powinien być wyczerpujący – opisywać wszystkie funkcje, dostępne w darktable.
  2. Powinien mieć spójną i logiczną strukturę, a każda funkcjonalność powinna mieć swoje własne logiczne miejsce w tej strukturze.
  3. Powinien być tak długi, jak to konieczne, ale jak najkrótszy – zwięzłość jest koniecznością.
  4. Powinien być obiektywny.
  5. Funkcjonalność należy wyjaśnić raz i tylko raz (z wyjątkiem podstawowych wytycznych, dotyczących organizacji pracy w sekcji Przegląd).
  6. Obrazy powinny być dołączane tylko tam, gdzie jest to konieczne do lepszego zrozumienia kluczowych zasad i nie powinny zawierać tekstu, chyba że jest to nieuniknione.

Generalnie nie interesuje nas:

  1. Restrukturyzacja instrukcji.
  2. Przełączanie języków znaczników.
  3. Szczegółowe samouczki dotyczące organizacji pracy (chociaż jesteśmy zainteresowani publikacją ich na blogach darktable.org lub pixls.us).

Jesteśmy zainteresowani:

  1. Poprawkami ortograficznymi i gramatycznymi.
  2. Wyjaśnieniem tekstu.
  3. Dokumentowaniem nowych funkcji.

Zawsze jesteśmy bardzo ciekawi, które sekcje podręcznika nie miały dla ciebie sensu i dlaczego tak się stało, abyśmy mogli poprawić dokumentację.

Ogólnie rzecz biorąc, jeśli chcesz wprowadzić poważną zmianę, najpierw otwórz problem i przedyskutuj go z opiekunami. Ma to na celu uniknięcie wykonywania pracy, która nie zostałaby zaakceptowana.

🔗format

Ta strona jest tworzona w czystym markdown, z kilkoma rozszerzeniami. Początkowo został on zaprojektowany do pracy z Hugo SSG, ale ma być na tyle przenośny, aby w razie potrzeby można go było łatwo renderować za pomocą innej aplikacji.

Pliki powinny być renderowane w UTF-8 i nie powinny zawierać zawijania kolumn.

🔗struktura

Poniżej przedstawiono strukturę przykładowego głównego rozdziału z podrozdziałami w witrynie dtdocs.

przykładowy-rozdział/
   _index.md
   sekcja1-z-podsekcjami/
      podsekcja-1/
         image.png
      _index.md
      podsekcja1.md
      podsekcja2.md
   sekcja2.md
   sekcja3.md

Kilka uwag na temat powyższej struktury:

  • Pliki _index.md nie zawierają żadnej treści (zawierają tylko metadane) i są używane do renderowania nagłówków sekcji i wpisów spisu treści. W powyższym przykładzie przykładowy-rozdział/_index.md definiuje tytuł przykładowego rozdziału i kolejność, w jakiej pojawia się w głównym spisie treści. Podobnie przykładowy-rozdział/sekcja1-z-podsekcjami/_index.md definiuje metadane dla pierwszej sekcji rozdziału.

  • Pliki metadanych powinny znajdować się w katalogu o tej samej nazwie, co strona, do której się odnoszą. W tym przykładzie przykładowy-rozdział/sekcja1-z-podsekcjami/podsekcja1 zawiera media, związane ze stroną podsekcja1.md.

🔗metadane

Metadane dla plików markdown są prezentowane na początku strony za pomocą yaml. Można zdefiniować dowolne metadane – sekcje referencyjne modułu zawierają całkiem sporo specyficznych metadanych – jednak poniżej zdefiniowano niektóre minimalne metadane dla przykładowej strony przykładowy-rozdział/sekcja1-z-podsekcjami/podsekcja1.md.

---
title: Sub Section 1 Title
id: subsection1
weight: 10
---
title
Powinien zawierać wyrenderowany tytuł twojej strony. Aby w tytule umieścić dwukropek, umieść go w cudzysłowie.
id
Identyfikator, używany do identyfikacji strony przez Hugo. Zwykle powinien mieć taką samą nazwę jak plik (dla plików zawartości) lub katalog nadrzędny (dla plików _index.md).
weight (waga)
Opcjonalne pole metadanych, używane do zdefiniowania kolejności, w jakiej sekcje są prezentowane w spisie treści. Jeśli pole weight nie zostanie uwzględnione, strony będą domyślnie renderowane w kolejności alfabetycznej. Na przykład, aby zdefiniować sekcje i podsekcje powyższego przykładu w odwrotnej kolejności, należy ustawić następujące metadane:
   przykładowy-rozdział/
      sekcja1-z-podsekcjami/
         _index.md               # waga: 30 (umieść sekcja1 na końcu przykladowy-rozdzial)
         podsekcja1.md             # waga: 20 (umieść podsekcja1 na końcu sekcja1)
         podsekcja2.md             # waga: 10 (umieść podsekcja2 na końcu sekcja1)
      sekcja2.md                # waga: 20 (umieść sekcja2 w środku przykladowy-rozdzial)
      sekcja3.md                # waga: 10 (umieść sekcja3 na początku przykladowy-rozdzial)

🔗zawartość

🔗wskazówki dotyczące ogólnego stylu

  • Cała treść powinna być napisana w zwykłym markdown bez skrótów, a kod HTML powinien być ograniczony do absolutnego minimum, jeśli w ogóle.

  • Minimalizm to absolutna konieczność. Im mniej słów, tym lepiej.

  • Pliki markdown powinny być tak krótkie, jak to możliwe.

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

  • Nagłówki w pliku nie powinny mieć więcej poziomów zagnieżdżenia, niż 3 (###).

  • 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

  • Zakładamy, że czytelnik ma otwartą aplikację podczas czytania instrukcji obsługi, dołączaj więc tylko te obrazy, które przyczynią się do wyjaśnienia złożonej funkcjonalności.

  • Użyj objaśnień obrazu, jeśli chcesz dodać adnotację do obrazu (np. oznaczyć części obrazu literą lub cyfrą, a następnie wyjaśnić znaczenie w tekście za obrazem). Nie umieszczaj słów bezpośrednio na obrazie w przypadku adnotacji, ponieważ utrudnia to lokalizację. Zobacz tę stronę, aby zapoznać się z przykładem.

  • Zmiany zawartości prosimy proponować przez pull requesty lub podobny mechanizm.

  • Twoje zgłoszenie zredagowane – nie bierz tego osobiście.

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

🔗listy definicji

Standardową metodą prezentowania informacji o kontrolkach modułu darktable jest użycie list definicji.

nazwa kontrolki gui
Deklaracja tego, co robi kontrolka. Na przykład „Ustawia ekspozycję w jednostkach EV”.

Możesz dołączać tyle akapitów, ile zechcesz, prosimy jednak próbować ograniczać się do dwóch lub trzech, o ile to możliwe.

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
nazwa rozwijalnej listy gui
Comboboxy często mają wiele opcji, z których wszystkie muszą być wyświetlane z osobnymi definicjami. Użyj list punktowanych z kursywą dla wartości pola kombi.
  • pierwsza wartość: Co oznacza pierwsza wartość
  • druga wartość: Co oznacza druga wartość

Listy definicji są również używane w całym dokumencie, wszędzie tam, gdzie należy zdefiniować nazwany element funkcjonalności. Zobacz na przykład darktable-cli.

🔗notatki

Jeśli chcesz przekazać użytkownikowi uwagę, użyj następującego formatu

Uwaga: To jest ważna uwaga.

🔗czcionki o stałej szerokości i bloki kodu

Czcionki o stałej szerokości (poprzedzone znakiem `) powinny być używane jedynie do oznaczania bloków kodu i odwołań do plików i parametrów linii poleceń.

🔗odsyłacze

Odsyłacze wewnętrzne muszą być względne wobec bieżącego pliku i muszą wskazywać aktualny plik markdown (.md). Link rozpocznij ./dla oznaczenia katalogu bieżącego lub ../ dla oznaczenia katalogu nadrzędnego.

🔗zdjęcia

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

Do kontrolowania sposobu renderowania obrazu można użyć kilku przedrostków nazw plików.

Ikona
Aby wstawić obraz jako ikonę, dołącz „#icon” po nazwie obrazu w łączu. Markdown ![squirrel icon](./contributing/contributing.png#icon) wyświetla następujące informacje: squirrel icon
szerokość obrazu
Możesz ustawić szerokość obrazu na 25, 33, 50, 66, 75 lub 100 procent szerokości renderowanej strony, dodając #wxx po nazwie obrazu w łączu, gdzie xx jest żądaną szerokością. Na przykład:
![squirrel](./contributing/squirrel.png#w25)
squirrel
![squirrel](./contributing/squirrel.png#w75)
squirrel
inline
Z wyjątkiem ikon, obrazy są domyślnie dołączane jako elementy blokowe. Możesz to zmienić, dołączając #inline po nazwie obrazu. Można to połączyć z ustawieniem szerokości w następujący sposób.
![squirrel](./contributing/squirrel.png#w25#inline) wyświetla squirrel
ustawienie domyślne
Domyślnie obrazy są prezentowane jako elementy blokowe o szerokości 100%. Tak więc ![squirrel](./contributing/squirrel.png#w100) i ![squirrel](./contributing/squirrel.png) są równoważne i obydwa wyświetlają:
squirrel

translations