Zasady oznaczania tekstu dla Podręcznika Krity

To omawia w szczegółach zasady stylistyczne przy składaniu tekstu dla Podręcznika Krity.

Zaleca się przeczytanie oficjalnej specyfikacji reStructuredText i zapisania jej na dysk twardy ze względu na to, że jest ona na sourceforge (w czasie pisania tego, sourceforge ma problemy z dostępnością serwerów):

Podręcznik użytkownika:

• Primer

• Szybkie odniesienie

• Tekstowa ściąga

Dokumentacja odniesienia:

• Wprowadzenie

• Oznaczenie

• Dyrektywy

• Role

Dokumentacja Sphinx:

• Strona Sphinxa na temat składania tekstu – Jest to przydatne przy danych dyrektywach i rolach sphinxa, których używa on np. do spisów treści.

W dokumentacji istnieją różnice pomiędzy oficjalnym reStructuredText oraz sphinx na temat robienia wielu rzeczy. Ten dokument określa zasady, wg których należy postępować.

Metadane

Każda strona powinna zaczynać się od następujących trzech rzeczy:

1. Metaopis

   Oto ogólny opis strony. Zostanie przekształcony na metaznacznik html i używany przez silniki wyszukiwania:

   .. meta::
       :description:
           Opis.
   

2. Wykaz autorów i licencja.

   Służy to tylko temu, aby śledzić kto edytował stronę i przypisać mu autorstwo. Powinien znajdować się w komentarzach, tak aby nie był łatwo czytany przez maszyny. Licencja całego podręcznika to GDL 1.3 i powinna być wspomniana także tutaj:

   .. metadata-placeholder
   
      :authors: - Autor 1
                - Autor 2
      :license: Wolna licencja dokumentacji GNU w wersji 1.3 lub późniejszej.
   

3. Spisywanie pojęć.

   Oto wyrażenia oddzielone przecinkami, pod którymi strona zostanie zaindeksowana w Spis. Stworzony indeks jest całkiem użyteczny zarówno dla PDF jak i ludzi, którzy nie są do końca pewni dokładnego wyrażenia, którego szukają. Są one określone w następujący sposób:

   .. index:: Słowo kluczowe, Słowo kluczowe z odstępami, ! Słowo głównej definicji
   

4. Etykieta.

   Istnieje to do łatwego dowiązywania strony przy użyciu :ref:`label_name`. Spróbuj, aby zrobić z tego ładną nazwę zmiennej:

   .. _nazwa_etykiety:
   

   Po etykiecie, musisz dodać nagłówek, gdyż :ref:`label_name` będzie się odnosić do nagłówka, który zostanie wypełniony odnośnikiem do tekstu.

Nagłówki

Nagłówki zostaną utworzone w następującej kolejności:

############
Część/Rozdział
############

Dla stron, które zawierają wiele podstron.

=========
Nagłówek 1
=========

Tym rozpoczynaj większość ze stron podręcznika.

Nagłówek 2
---------

Nagłówek 3
~~~~~~~~~

Nagłówek 4
^^^^^^^^^

Nagłówek 5
'''''''''

Nagłówek 6
"""""""""

Te zasady pochodzą w większości z Pandoc’s mediawiki nt przekształceń reStructuredText. Jeśli potrzebujesz więcej niż 4 nagłówki, to zapytaj siebie samego, czy twoja strona nie stała się zbyt skomplikowana i czy nie potrzebuje zostać podzielona.

Czasami potrzebujesz dowiązać do podobszaru strony, dodaj etykietę powyżej nagłówka w tym przypadku.

Nagłówki nie powinny kończyć się znakiem interpunkcyjnym, gdyż nagłówki będą używane jako nazwa odnośnika przy dowiązywaniu do etykiety.

Łączenie

Łączenie odbywa się poprzez :ref:`label_name`. Gdy potrzebny jest alternatywny tekst łącza, to można użyć :ref:`właściwy tekst do wyświetlenia <label_name>`.

Dowiązywanie zewnętrznych stron wykonuje się poprzez `url`_ oraz `nazwa odnośnika<url>`_, co stanie się nazwa odnośnika.

Pandoc lubi zamieniać to na `link name`__ a później dodawać .. __ :url na końcu dokumentu. Nazywa się to «anonimowym hiperłączem», co oznacza, że kolejności łączy pojawiających się w tekście, jest skojarzona z kolejność łączy na końcu tekstu. Jeśli brzmi to niezrozumiale i trudno, to dlatego bo takie jest. Jest to także dokładny powód, dla którego chcielibyśmy uniknąć łączy takie jak te.

Stopki i dalsze źródła

Stopki można wykonać na 3 sposoby, najpowszechniejszym jest autonumerowanie wg odnośników:

[1] jest odniesieniem do stopki 1, a [2] jest odniesieniem do stopki 2.

[1]

Oto stopka 1.

[2]

Oto stopka 2.

[3]

Oto stopka 3.

[3] jest odniesieniem do stopki 3.

Oto odwołanie do cytowania: [CIT2002] .

[CIT2002]

Oto cytowanie. Wygląda jak stopka, z tą różnicą, że etykieta jest tekstowa.

Do cytowań można się także odnosić poprzez `cytowanie <CIT2002>`_.

Zazwyczaj nie używamy stopek w naszym podręczniku ze względu, że może to być zbyt akademickie dla naszych czytelników. Jednakże, zbieramy dokumenty i łącza, które dostarczają więcej szczegółów na dany temat, na końcu strony. Sphinx ma także dyrektywę .. seealso:: do łączenia do zewnętrznych odnośników, podczas gdy reStructuredText zaleca używanie .. rubic:: Footnotes aby gromadzić stopki, bo dobrze to współgra z LaTeX.

Obrazy

Stosuj dyrektywę image dla obrazów bez podpisów:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: an image.

I dyrektywę figure dla obrazów z podpisami:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: an image.

   Podpis --  zauważ jak pierwsza listera jest wyrównana przy użyciu ustawienia :figwidth:.

Ten drugi daje:

Podpis – zauważ jak pierwsza litera podpisu w dyrektywie jest wyrównana ustawieniem :figwidth:.

Obrazy powinny trafić do katalogu /images. Używając /images zamiast images sphinx będzie wiedział, że ścieżka nie jest względna.

Oznaczenie w tekście

Możesz uczynić tekst zaakcentowanym oraz wytłuszczonym przy użyciu jednej lub dwóch gwiazdek odpowiednio:

*zaakcentowanie*
**wytłuszczenie**

Nie możesz wykonać zarówno *zaakcentowania oraz wytłuszczenia*, więc wybierz jedno z nich.

Możesz _{tekst w indeksie} oraz ^{tekst w indeksie} używając :sub:`tekst` oraz :sup:`tekst`.

Używaj jednak tego bardzo oszczędnie! Zaleca się używania znaczników już dostępnych w Sfinksie, bo to umożliwia tłumaczom na podejmowanie kroków wobec natury text:

:menuselection:`Ustawienia --> Ustawienia Krity...`
:guilabel:`Plik`
:kbd:`Ctrl + Z`
:program:`Krita`

Unikaj losowego wytłuszczania słów. Nie czyni on tekstu łatwiejszym lub bardziej przyjaznym w czytaniu.

Odwołania zastępcze

Możesz utworzyć coś na kształt krótkiego opisu dla tekstu lub obrazu poprzez:

.. |shorthand| replace:: coś lub coś innego.

co oznacza, że gdy użyjesz |shorthand|, w tekście, to zostanie on zamieniony «czymś lub czymś innym». Jest to użyteczne dla obrazów i tekstu, który musi być sformatowany w skomplikowany sposób, jak w przypadku „LaTeX”.

Dokumentacja Krity ma |mouseleft|, |mousemiddle|, |mousescroll| oraz |mouseright|, które przekształcą się odpowiednio na , , oraz . Są one określone w pliku Sfinksa conf.py oraz dołączane do każdego pliku rst.

Dla odnośników, gdy w kółko używasz tego samego odnośnika, to możesz napisać coś takiego na końcu pliku:

.. _bugzilla: https://bugs.kde.org/
.. _Krita Manual: https://docs.krita.org/

Następnie, wpisując łącze, możesz użyć `bugzilla`_ aby dowiązać dobugzilli z „bugzilla” użytym jako tekst łącza. `Krita Manual`_ zamieni łącze na docs.krita.org z tekstem „Podręcznik Krity”.

Listy

Uporządkowana lista

1. Jabłko

2. Gruszka

3. Banan

Lub…

1. Stół

2. Krzesło

3. Szafa na ubrania.

1. Augustus

2. Nero

3. Caligula

4. Trajan

Można je określić następująco:

1. Jabłko
2. Gruszka
3. Banan

#. Jabłko
#. Gruszka
#. Banan

A. Stół
B. Krzesło
C. Szafa na ubrania.

A. Stół
#. Krzesło
#. Szafa na ubrania.

I. Augustus
#. Nero
#. Caligula
#. Trajan

Nieuporządkowana lista

• czerwony

• źółty

• zielony

  • morski zielony

  • grynszpan

  • cyraneczka

  • viridian

  • emerald

    • ciemny emerald

    • jasny emerald

      • bardzo jasny emerald.

• niebieski

Określony jako:

- czerwony
- żółty
- zielony
    - morski zielony
    - grynszpan
    - zielononiebieski
    - zieleń Guigneta
    - szmaragdowy
        - ciemny szmaragdowy
        - jasny szmaragdowy
            - bardzo jasny szmaragdowy.
- niebieski

Wypisanie definicji

Ulubione! Listy są szczególnie użyteczne przy wymienianiu wszystkich ustawień w doku i przy próbie dodania prostego opisu za nimi.

Definicja

Wyjaśnienie.

Inne ustawienie

Wyjaśnienie.

Aby je zrobić.

Możesz je stworzyć następująco:

Definicja
    Wyjaśnienie.
Inne ustawienie
    Wyjaśnienie.

Tabele

Tytuł przelewu	Rodzaj tabeli
wypisanie skrótów	Prosta tabela
wiele kolumn	Tabela siatki
Proste, lecz długie	Tabela listy

Robione następująco:

================== ============
Przeznaczenie            Rodzaj tabeli
================== ============
wymienianie skrótów Prosta tabela
wiele rozpórek kolumn   Tabela siatki
Prosta lecz długa    Tabela listy
================== ============

+-----------------+------------+
|Przeznaczenie          |Rodzaj tabeli  |
+=================+============+
|wymienianie skrótów|Prosta tabela|
+-----------------+------------+
|wiele rozpórek kolumn |Tabela siatki  |
+-----------------+------------+
|Prosta lecz długa  |Tabela listy  |
+-----------------+------------+

.. list-table::
   :header-rows: 1

   - * Przeznaczenie
     * Rodzaj tabeli
   - * wymienianie skrótów
     * prosta tabela
   - * wiele rozpórek kolumn
     * tabela siatki
   - * prosta lecz długa
     * tabela listy

Pełne tabele siatkowe są najlepsze, gdy potrzebujesz wszystkich możliwości złożonych rozpórek kolumn i wierszy, lecz jest je także trudniej stworzyć. Z tego powodu, najlepiej tworzyć małe tabele, przy użyciu prostej składni, podczas gdy długie table dyrektywą listy, bo jest je łatwiej zapisać, a później utrzymać.

Pouczenia i uwagi na boku

Informacja

Pouczenia są rodzajem osobnego rozdziału, na które czytelnik musi zwrócić uwagę.

Pouczenia, których można używać są następujące (w kolejności poważności):

Podpowiedź

Wskazówki są użyteczne do dawania trochę więcej danych nt. tematu niż zrobiłoby to użytek w głównym tekście. Takie jak, „Pakiety te nazywają się inaczej w openSuse względem Debiana”.

Wskazówka

Dodatkowe informacje nt. wykonywania czegoś, takie jak „Możesz utworzyć szablon ze swoich ulubionych ustawień dokumentu” lub „Naciśnij m, aby odbić lustrzanie płótno i łatwiej zauważyć błędy na swoim rysunku”

Ważne

Coś wartego zaznaczenia, lecz niekoniecznie negatywnego.

Ostrzeżenie

W ogólności jest tak, gdy coś jest ujemne.

Uwaga

Ogólny przyciągacz uwagi. Stosuj, gdy temat jest ważniejszy niż ostrzeżenie, lecz nie tak ważny, że może doprowadzić do utraty danych.

Ostrzeżenie

To jest przeznaczone dla rzeczy, które mogą spowodować utratę danych. Rzeczy jak zapomnienie o zapisaniu lub takie, że Python obecnie nie ma możliwości cofania.

Niebezpieczeństwo

Powinno się to stosować dla rzeczy, które są niebezpieczne dla komputerów w ogólności. Uwzględnia to rzeczy, które mogą wywołać zawieszenia komputera ze względu na wyczerpanie pamięci.

Błąd

Prawdopodobnie nie jest to odpowiednie dla podręcznika. Sphinx może utworzyć je ręcznie w niektórych przypadkach, lecz nasze ustawienia nie pozwalają, aby zadziało się tak domyślnie.

Ogólne pouczenie, które może zawierać dowolny tekst

Tekst.

Możesz to stworzyć następująco:

.. admonition:: Zwykłe pouczenie, które może zawierać dowolny tekst

    Tekst.

Sfinks dodaje również:

.. seealso::

    Co jest użyteczne przy zbieraniu odnośników zewnętrznych.

Linijki w poziomie

Linijki w poziomie są zazwyczaj używane, gdy temat zmienia się raczej bezpośrednio. Jest to bardzo powszechne w bardziej narracyjnym pisaniu, takim jak o historii lub fikcji. Podręcznik Krity jest bardziej pisany jako instrukcja, czy źródło odniesienia, co oznacza, że zazwyczaj nie opowiadamy długiej historii o tym jak różne elementy zostały złożone w całość, lecz długie historie są tu po to, żeby opowiedzieć dlaczego pewne kroki są podejmowane w pewien sposób. Temat wtedy się zmienia zazwyczaj z powoduj przejścia do nowego rozdziału, raczej ze względu na przejście do powiązanego rozdziału. Lepiej jest zatem użyć nagłówków lub dyrektywy .. Topic:: . Nagłówki ułatwiają także czytanie.

---

Linijki w poziomie można stworzyć poprzez ----.

Dyrektywa rubryki

Dyrektywa rubryki jest dyrektywą nagłówka, która na pierwszy rzut oka wygląda jak „temat”, lecz podczas gdy temat jest na kilku akapitach, to rubryka dotyczy tylko nagłówka, w następujący sposób:

.. rubric:: Dyrektywa rubryki

Tak więc, kiedy ich używać?

Używaj tylko wtedy, gdy uważasz, że temat jest zbyt poboczny, aby miał swój własny nagłówek.

Temat

Gdy tekst jest oddzielony od głównego przepływu, więc trafia do innego tematu niż naturalnie powinien trafić.

Rubryka

Gdy tekst nie jest oddzielony od głównego przepływu, lecz nie potrzebuje także nagłówka.

Pouczenia

Tylko gdy pasują semantycznie. Jest to szczególnie niezbędne dla pouczeń o niebezpieczeństwie lub ostrzeżeniach, gdyż widzenie ich zbyt często, może spowodować, że użytkownicy staną się na nie ślepi.

Wstawki kodu

Wstawki kodu w wierszu tworzy się poprzez ``backticks``.

Wielowierszowe wstawki kodu wykonuje się poprzez edytowanie poprzedniego rozdziału przy użyciu ::, co będzie wyglądać następująco:

To jest akapit, a my określamy wstępnie sformatowany wycinek jako::

   Upewnij się, ze dodasz biały znak oraz tabulator, zanim rozpoczniesz wycinek.

Możesz także zastosować dyrektywę .. code::. Jeśli dołączysz za nią nazwę języka, to zostanie zastosowane odpowiednie podświetlanie składni:

.. code:: python

    # uwaga Pythona
    def moja_funkcja():
        alist = []
        alist.append(1)
        string = "hello world"

Staje się

# uwaga Pythona
def moja_funkcja():
    alist = []
    alist.append(1)
    string = "hello world"

trochę więcej…

// uwaga C++
int mojaFunkcja(int i) {
    i += 1;

    // Sprawdź czy większa niż 12
    if (i>12) {
        i = 0;
    }
    return i;
}

/* Uwagi CSS */
body {
    margin: 0 auto;
    /* is 800 still sensible? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>to <span style="font-style:italic">jest</span> <!-- a HTML comment --> rozdział.</p>

Inne wstępnie sformatowany tekst

Można

wstępnie sformatowane

tekst autorstwa

poprzedzając

każdy wiersz

z rurą

symbol

Następująco:

| Można
| wstępnie sformatować
| tekst
| poprzedzając
| każdy wiersz
| symbolem
| rury

Ogólnie, nie używamy tego w podręczniku i powinno to być używane tylko, gdy jest to bezwzględnie wymagane do przedstawienia treści, która wymaga dokładnego formatowania, lecz nigdy tylko z powodów estetycznych.

Słowniki, pojęcia, spis treści

To są możliwości sfinksa.

Spis jest używany w górnym obszarze. Obecnie używane są tylko pojedyncze wpisy.

Słowniki są używane dla niektórych wpisów menu, lecz nie do wszystkich z nich.

Cudzysłowy

Cytaty tworzy się następująco:

Nie jestem pewny po co ci cytowania w podręczniku użytkownika...

-- Wolthera

To staje się blockquote.

Nie jestem pewien po co ci cudzysłowy w podręczniku użytkownika…

—Wolthera

W niektórych miejscach używamy cudzysłowów. Spróbuj dodać odnośnik do nazwy, aby wskazać skąd ona pochodzi.

Tekst tylko dla nieangielskich tłumaczeń

Możesz użyć następującej rzeczy, aby dodać tekst, który ma sens tylko dla nieangielskich tłumaczeń podręcznika, na przykład, aby podać czytelnikom nieangielskim angielskie nazwy rzeczy, aby mogli się oni łatwiej odnaleźć:

.. tylko:: nie_angielski

    Ta treść jest ukryta dla wersji angielskiej, a w wersji nieangielskiej
    pojawia się i można ją przetłumaczyć.

Uwagi dla tłumaczy

Jeśli tłumaczysz podręcznik na język, który zazwyczaj nie używa odstępów pomiędzy słowami (np. chiński czy japoński), to możesz użyć znaku wykluczającego z przetwarzania dla odstępów, aby oddzielić znaczniki od słów. Jest to szczególnie użyteczne dla odnośników stron, takich jak te:

床前\ `明月 <https://krita.org/>`_\ 光

Pamiętaj, że tłumacząc z pliku PO, powinieneś wykluczyć z przetwarzania ukośnik wsteczny drugim ukośnikiem wstecznym:

床前\\ `明月 <https://krita.org/>`_\\ 光

The above produces „床前明月光”, instead of „床前 明月 光”.