styles and conventions

The following details the writing style and documentation conventions used in this manual.

🔗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

A couple of notes on the above structure:

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

All content should be authored in plain markdown without shortcodes and HTML should be kept to an absolute minimum, if used at all
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. W podobny sposób - małą literą - odwołuj się do nazw modułów i kontrolek.
Nagłówki w pliku nie powinny mieć więcej poziomów zagnieżdżenia, niż 3 (###).
Podstawowym językiem autorskim jest angielski. Jeśli to możliwe, unikaj języka idiomatycznego, ponieważ angielska wersja dokumentacji może być czytana przez osoby, dla których angielski nie jest językiem ojczystym
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.

🔗skróty dla klawiatury i myszki

Nazwane klawisze na klawiaturze opisuj z wykorzystaniem CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)
Klawisze pojedynczych liter oznaczaj małymi literami (pozwala to np. uniknąć pomylenia Ctrl+H i Ctrl+Shift+h). Cudzysłowy mogą pomóc w wyjaśnieniu (naciśnij “h”, aby wyświetlić listę aktywnych skrótów)
Odwołuj się do działań myszy, używając małych liter i wielu słów połączonych łącznikiem (rolka, klik, pojedyncze kliknięcie, podwójne kliknięcie, kliknięcie PPM)
Połącz kombinacje klawiszy/akcji znakiem plus (Ctrl+Shift+h, Shift+podwójne kliknięcie)

🔗listy definicji

The standard method of presenting information about darktable module controls is with the use of definition lists.

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 (darktable-elegant-grey) 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 produkcyjnych powinny być pisane kursywą, np. ekspozycja.
Odsyłacze do modułów narzędziowych 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 (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:
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: With the exception of icons, images are included as block elements by default. You can override this by including #inline after the image name. This can be combined with the width setting as follows.; ![squirrel](./contributing/squirrel.png#w25#inline) outputs
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ą: