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:

Podręcznik powinien być wyczerpujący – opisywać wszystkie funkcje, dostępne w darktable.
Powinien mieć spójną i logiczną strukturę, a każda funkcjonalność powinna mieć swoje własne logiczne miejsce w tej strukturze.
Powinien być tak długi, jak to konieczne, ale jak najkrótszy – zwięzłość jest koniecznością.
Powinien być obiektywny.
Funkcjonalność należy wyjaśnić raz i tylko raz (z wyjątkiem podstawowych wytycznych, dotyczących organizacji pracy w sekcji Przegląd).
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:

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

Jesteśmy zainteresowani:

Poprawkami ortograficznymi i gramatycznymi.
Wyjaśnieniem tekstu.
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.
Stosuj się do konwencji nazewniczej, obecnej w GUI aplikacji – w szczególności wszystkie nagłówki i tytuły pisz małą literą, za wyjątkiem tytułów rozdziałów najwyższego poziomu.
Nagłówki w pliku nie powinny mieć więcej poziomów zagnieżdżenia, niż 3 (###).
Podstawowym językiem dokumentacji jest angielski.
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.

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

kontrolka dostępna za pomocą przycisku z ikoną

Gdy kontrolka jest aktywowana za pomocą ikony, zrób zrzut ekranu ikony przy użyciu standardowego motywu darktable i dodaj go przed nazwą kontrolki.

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.

Linki do modułów przetwarzających powinny być pisane kursywą, np. ekspozycja.
Odsyłacze do modułów użytkowych winny być pisane zwykłym tekstem, np. moduł historii.
Linki do poziomu bazowego twórz przez odwołanie do pliku _index.md, np. referencja do modułu.
Link do zakładki w oknie ustawień: ustawienia > ogólne.
Link do konkretnego ustawienia: ustawienia > ogólne > język interfejsu
Każdy nagłówek na stronie może być połączony bezpośrednio za pomocą linku kotwicy: contributing/notes

🔗zdjęcia

Robiąc zrzuty ekranu z aplikacji darktable, korzystaj z domyślnego tematu graficznego darktable.

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:
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](./contributing/squirrel.png#w75)
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
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ą: