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.

  • 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

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

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