Krita Kılavuzu için imleme kuralları

Bu bölüm, Krita Kılavuzu için yeniden yapılandırılmış metin biçem kurallarını ayrıntılandırır.

reStructuredText’in resmi tanımlarına bakmanız önerilir ve SourceForge’da barındırıldığından bir kopyasını da sabit diskinize indirebilirsiniz (SourceForge’un siteyi çalışır tutma istatistikleri pek iyi değildir, en azından bu metin yazılırken öyle):

Kullanıcı Kılavuzu:
Başvuru Belgelendirmesi:
Sphinx’e özel belgeler:

  • Yeniden yapılandırılmış metin üzerine Sphinx sayfası – Bu, örneğin içindekiler tablosu oluşturmak için kullandığı belirli Sphinx yönergeleri ve rolleri için kullanışlıdır.

Resmi reStructuredText ve Sphinx belgeleri arasında bir şeyler yapmanın birçok yolu arasında farklılıklar vardır. Bu belge, birlikte kullanılması önerilen kuralları belirtir.

Üst veri

Her sayfa aşağıdaki üç şeyle başlamalıdır:

  1. Bir meta açıklama

    Bu, sayfanın genel bir açıklamasıdır. Arama motorları tarafından kullanılacak bir html meta künyenine dönüştürülecektir:

    .. meta::
    :description:
        Açıklama.
  2. Yazarların bir listesi ve bir lisans.

    Bu yalnızca sayfayı kimin düzenlediğini takip etmek ve kredi vermek içindir. Makineler tarafından kolayca okunamayacak şekilde yorumda olmalıdır. Tüm kılavuzun lisansı GDL 1.3’tür ve burada ayrıca belirtilmelidir:

    .. metadata-placeholder

   :authors: - 1. Yazar
             - 2. Yazar
   :license: GNU özgür belgelendirme lisansı sürüm 1.3 veya sonrası.
  3. Terimleri indeksleme.

    Bunlar, sayfanın İndeks dizinine ekleneceği virgülle ayrılmış terimlerdir. Oluşturulan indeks, hem PDF hem de aradıkları terimin tam adının ne olduğundan emin olmayan kişiler için oldukça kullanışlıdır. Bunlar aşağıdaki gibi tanımlanır:

    .. index:: Anahtar sözcük, Boşluklarla anahtar sözcük, ! Ana tanım anahtar sözcüğü
  4. Bir etiket.

    Bu, :ref:`etiket_adı kullanarak sayfaya kolayca bağlantı verebilmemiz içindir. Bunu güzel bir değişken adı yapmaya çalışın:

    .. _etiket_adı:

    Etiketten sonra bir başlık eklemeniz gerekecek; çünkü :ref:`etiket_adı bağlantı metnini doldurmak için başlığa atıfta bulunacaktır.

Başlıklar

Başlıklar aşağıdaki sırada yapılır:

############
Kısım/Bölüm
############

Pek çok alt sayfası olan sayfalar için.

=========
Başlık 1
=========

Çoğu kılavuz sayfasına bununla başlayın.

Başlık 2
---------

Başlık 3
~~~~~~~~~

Başlık 4
^^^^^^^^^

Başlık 5
'''''''''

Başlık 6
"""""""""

Bu kurallar az çok Pandoc’un Mediawiki-reStructuredText dönüşümü tarafından belirlenmiştir. Dörtten çok başlığa gerek duyuyorsanız kendinize sayfanın biraz karmaşıklaşıp karmaşıklaşmadığını ve başka sayfalara bölmeye gereksiniminiz olup olmadığını sorun.

Bazen bir sayfanın bir alt bölümüne bağlantı vermeniz gerekir, bu durumda başlığın üstüne bir etiket ekleyin.

Başlık, bir etikete bağlanırken bağlantı adı olarak kullanılacağından, başlıklar noktalama işaretleri ile bitmemelidir.

Bağlantılama

Bağlantılama :ref:`etiket_adı` ile yapılır. Alternatif bir bağlantı metnine gereksiniminiz olduğunda, :ref:`gösterilen gerçek metin <etiket_adı>` kullanırsınız.

Dış sayfaya bağlantılama, daha sonra link name olacak olan `url`_ ve `link name <url>`_ ile yapılır.

Pandoc, bunları bağlantı adına`__ dönüştürmeyi ve ardından belgenin sonuna .. __ :url eklemeyi sever. Bu sözde ‘anonim köprü’dür, yani metinde görünen bağlantıların sırasına bağlı olarak metnin sonundaki bağlantıların sırası birbiriyle ilişkilendirilir. Bu kulağa kafa karıştırıcı ve zor gelebilir; çünkü öyledir. Bunun gibi bağlantılardan kaçınmak istememizin tam nedeni de budur.

Dipnotlar ve daha fazla okuma

Dipnotlar 3 şekilde yapılabilir, en yaygın olanı başvuruya göre kendiliğinden numaralandırmadır:

[1], 1. dipnota bir başvurudur ve [2], 2. dipnota bir başvurudur.

[3], 3. dipnota bir başvurudur.

İşte bir atıf referansı: [CIT2002] .

[CIT2002]

Bu atıftır. Etiketin metinsel olması dışında, tıpkı bir dipnot gibidir.

Atıfa ayrıca atıf <CIT2002>`_ ile de başvurulabilr.

Okuyucularımız için biraz fazla akademik olduğu için aslında kılavuzda dipnot kullanmıyoruz. Ancak, bir sayfanın sonunda bir konu hakkında biraz daha fazla bilgi veren belgeler ve bağlantılar topluyoruz. Sphinx, harici bağlantılara bağlanmak için ..seealso:: yönergesine sahipken, reStructuredText, LaTeX ile iyi çalıştığı için özellikle dipnotları toplamak için .. rubic:: Footnotes kullanılmasını önerir.

Görseller

Alt yazısı olmayan görseller için image yönergesini kullanın

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: bir görsel.

Ve alt yazılı görseller için şekil yönergeleri:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: bir görsel.

   Bir alt yazı --  ilk harfin :figwidth: seçeneği ile nasıl hizalandığına dikkat edin.

İkincisi şunu verir:

an image.

Bir alt yazı – ilk harfin :figwidth: seçeneği ile nasıl hizalandığına dikkat edin.

Görseller /images klasörüne gitmelidir. images yerine /images kullanınca Sphinx, dosya yolunun göreceli olmadığını bilecektir.

Metin İçi İmleme

Metni sırasıyla bir yıldız kullanarak yatık ve iki yıldız kullanarak kalın yapabilirsiniz:

*yatık*
**kalın**

Aynı anda *hem yatık hem kalın* yapamazsınız; dolayısıyla birini seçin.

:sub:`metin` ve :sup:`metin` kullanarak alt simge ve üst simge yapabilirsiniz.

Ancak, bunları çok dikkatli kullanın! Her halükarda Sphinx’te var olan anlamsal imlemenin kullanılması tercih edilir; çünkü bu, çevirmenlerin metnin doğası hakkında karar vermesini kolaylaştırır:

:menuselection:`Ayarlar --> Krita'yı Yapılandır...`
:guilabel:`Dosya`
:kbd:`Kontrol + Z`
:program:`Krita`

Rastgele sözcükleri kalınlaştırmaktan kaçının. Metni okunması daha kolay veya arkadaş canlısı yapmaz.

Değiştirme Başvuruları

Aşağıdakileri yaparak, bir metin parçası veya bir görsel için bir tür steno oluşturabilirsiniz:

.. |shorthand| replace:: biri veya bir başkası.

demek oluyor ki, metinde |shorthand| kullanırsanız ‘biri veya bir başkası’ ile değiştirilecektir. Bu, karmaşıkça biçimlendirilmesi gereken görseller ve metinler için yararlıdır; örneğin “LaTeX” gibi.

Krita belgelendirmesinde, sırasıyla mouseleft, mousemiddle, mousescroll ve mouseright olarak dönüşecek |mouseleft|, |mousemiddle|, |mousescroll| ve |mouseright| kodları bulunur. Bunlar, Sphinx’in conf.py dosyasında tanımlıdır ve her bir rst dosyasına iliştirilirler.

Bağlantılar için, aynı bağlantıyı hep kullanıyorsanız dosyanın sonuna buna benzer bir şey yazabilirsiniz:

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

Böylece bir bağlantı yazarken; örneğin BugZilla’ya bağlantı vermek için yalnızca```bugzilla`_`` yazmanız yeterlidir. `Krita Manual`_ yazınca bağlantı docs.krita.org adresine “Krita Manual” metniyle bir bağlantı oluşturur.

Listeler

Sıralı listeler

  1. Elma

  2. Armut

  3. Muz

Veya…

  1. Masa

  2. Sandalye

  3. Gardrop.

  1. Augustus

  2. Nero

  3. Caligula

  4. Trajan

Aşağıdaki biçimde tanımlanabilirler:

1. Elma
2. Armut
3. Muz

#. Elma
#. Armut
#. Muz

A. Masa
B. Sandalye
C. Gardrop

A. Masa
#. Sandalye
#. Gardrop

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

Sırasız listeler

  • kırmızı

  • sarı

  • yeşil

    • denizyeşili

    • bakıryeşili

    • camgöbeği

    • zümrütyeşili

    • zümrüt

      • koyu zümrüt

      • açık zümrüt

        • çok açık zümrüt.

  • mavi

Şöyle tanımlanır:

- kırmızı
- sarı
- yeşil
    - denizyeşili
    - bakıryeşili
    - camgöbeği
    - zümrütyeşili
    - zümrüt
        - koyu zümrüt
        - açık zümrüt
            - çok açık zümrüt.
- mavi

Tanım Listeleri

En sevdiklerimden! Tanım listeleri, özellikle bir paneldeki tüm seçenekleri sıralarken ve bunların arkasına basit bir açıklama eklemeye çalışırken kullanışlıdır.

Tanım

Açıklama.

Başka bir seçenek

Açıklama.

Onları yapmak.

Onları şöyle yapabilirsiniz:

Tanım
    Açıklama.
Başka bir seçenek
    Açıklama.

Tablolar

Amaç

Tablo türü

kısayollar listesi

Basit tablo

pek çok sütun açıklığı

Izgara tablo

Basit; ancak uzun

Liste Tablo

Şöyle yapılır:

================== ============
Amaç            Tablo türü
================== ============
kısayollar listesi  Basit tablo
pek çok sütun açıklığı   Izgara tablo
Basit; ancak uzun    Liste Tablo
================== ============

+-----------------+------------+
|Amaç          |Tablo Türü  |
+=================+============+
|kısayollar listesi|Basit tablo|
+-----------------+------------+
|pek çok sütun açıklığı |Izgara tablo  |
+-----------------+------------+
|Basit; ancak uzun  |Liste tablo  |
+-----------------+------------+

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

   - * Amaç
     * Tablo Türü
   - * kısayollar listesi
     * basit tablo
   - * pek çok sütun açıklığı
     * ızgara tablo
   - * basit; ancak uzun
     * liste tablo

Tam ızgara tabloları, karmaşık sütun ve satır aralıkları gibi tüm özelliklere gereksinim duyduğunuz; ancak bunları oluşturmanın zor olduğu durumlar için en iyisidir. Bu nedenle, küçük tablolar en iyi şekilde basit sözdizim ile yapılırken, gerçekten uzun tablolar en iyi şekilde bir liste yönergesiyle yapılır; çünkü bunun yazılması ve bakımı çok daha kolaydır.

Uyarılar ve Bilgi Kutuları

Not

Uyarılar, kullanıcının dikkatini vermesi gereken ayrıcı kutucuklardır.

Kullanılabilir uyarıların bir listesi aşağıdaki gibidir (ciddilik düzeyine göre):

İpucu

İpuçları, bir konu hakkında ana metinde olduğundan biraz daha fazla bilgi vermek için kullanışlıdır. “Bu paketler, Debian’da başka openSuse’da başka biçimde adlandırılmıştır” gibi.

Tüyo

“Favori belge kurulumunuzun bir şablonunu oluşturabilirsiniz” veya “Tuvali yansıtmak ve çiziminizdeki hataları daha kolay görmek için m’yi kullanın” gibi bir şeyin nasıl yapılacağına ilişkin ek bilgiler.

Önemli

Dikkate alınması gereken; ancak mutlaka olumsuz olmayan bir şey.

Uyarı

Bu genellikle bir şey olumsuz olduğunda olur.

Dikkat

Genel dikkat çekici. Konunun uyarıdan daha önemli olduğu, ancak veri kaybına neden olabilecek kadar önemli olmadığı durumlarda bunu kullanın.

Uyarı

Bu, kaydetmeyi unutmak veya Python’un şu anda geri alma işlevine sahip olmaması gibi veri kaybına neden olabilecek şeyler içindir.

Tehlike

Bu, genel olarak bilgisayar için tehlikeli olan şeyler için olmalıdır; bu, yetersiz bellek tarzı donmalara neden olabilecek şeyleri içerir.

Hata

Bu, büyük olasılıkla bir kılavuzla ilgili değildir. Sphinx, bazı durumlarda bunları elle olarak oluşturabilir; ancak yapılandırmamız bunu öntanımlı olarak yapmaz.

Herhangi bir metne sahip olabilecek genel uyarı

Metin.

Bunu şöyle kılabilirsiniz:

.. admonition:: Herhangi bir metne sahip olabilecek genel uyarı

    Metin.

Sphinx ayrıca şunları ekler:

.. seealso::

    Dış başvuruları ve bağlantıları toplamada yararlıdır.

Bununla birlikte, yatay cetveller ---- ile yapılabilir.

Bölüm yönergesi

Dereceli puanlama anahtarı yönergesi, ilk bakışta “konu” gibi görünen bir başlık yönergesidir; ancak konunun birkaç paragraftan uzun olduğu durumlarda, değerlendirme tablosunun kendisi yalnızca başlıkla ilgilenir, şöyle:

.. rubric:: Bölüm yönergesi

Bunları ne zaman kullanmalı?

Bunları yalnızca konunun uygun bir başlığa sahip olmak için çok küçük olduğunu düşündüğünüzde kullanın.

Konu

Metin akıştan ayrıldığında; doğal olarak metnin kendisinden farklı bir konuya girer.

Bölüm

Metin akıştan ayrılmadığında; ancak bir başlığa da gereksinim duymadığında.

Uyarılar

Yalnızca anlamsal olarak uyduklarında. Bu, özellikle tehlike ve uyarı uyarıları için gereklidir; çünkü bunları çok sık görmek kullanıcıları bunlara karşı körleştirebilir.

Kod Parçacıkları

Satır içi kod parçacıkları, `geri kesme imleri`` ile yapılır.

Çok satırlı kod parçacıkları önceki bölümü :: ile bitirerek yapılır, bu şuna benzer:

Bu bir paragraf ve şu şekilde önceden biçimlendirilmiş bir parçacık tanımlanır::

     Başlamadan önce bir boşluk ve sekme eklediğinizden emin olun.snippet.

.. code:: direktifini de kullanabilirsiniz. Ondan sonra dil adını eklerseniz uygun sözdizimi vurgulanır:

.. code:: python

    # Python yorumu
    def my_function():
        alist = []
        alist.append(1)
        string = "merhaba, dünya"

Şu Olur

# Python yorumu
def my_function():
    alist = []
    alist.append(1)
    string = "merhaba, dünya"

biraz daha…

// C++ yorumu
int myFunction(int i) {
    i += 1;

    // 12'den büyük olup olmadığını denetle
    if (i>12) {
        i = 0;
    }
    return i;
}

/* CSS yorumu */
body {
    margin: 0 auto;
    /* 800 hâlâ uygun mu? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>bu <span style="font-style:italic">bir</span> <!-- a HTML comment --> paragraftır.</p>

Diğer önceden biçimlendirilmiş metinler

Birisi
bir metni
her satırının
önüne
bir veriyolu simgesi
ekleyerek
önden biçimlendirebilir

Şöyle:

| Birisi,
| bir metni
| her satırının
| önüne
| bir veriyolu simgesi
| ekleyerek
| önden biçimlendirebilir

Bu genellikle kılavuzda kullanılmaz ve yalnızca tam olarak biçimlendirilmesi gereken içeriği temsil etmenin kesinlikle gerekli olduğu durumlarda kullanılmalıdır, asla yalnızca estetik nedenlerle kullanılmamalıdır.

Kavram Dizinleri, Terimler ve İndeks

Bunlar, Sphinx özellikleridir.

İndeks, üst bölümde kullanılır; şu anda yalnızca tekli indeks girdileri kullanılır.

Kavram dizinleri bazı menü girdisi bölümleri için kullanılır; ancak tümü için değil.

Alıntılar

Alıntılar şöyle yapılır:

Bir kullanıcı kılavuzunda neden alıntılara gerek duyasınız ki...

-- Saldıray Abi

Bu, bir blok alıntıya dönüşür.

Bir kullanıcı kılavuzunda neden alıntılara gerek duyasınız ki…

—Saldıray Abi

Aslında bazı yerlerde alıntıları kullanıyoruz. Nereden geldiğini tanımlamak için ada bir bağlantı eklemeye çalışın.

İngilizce Olmayan Çeviriler için Metin

Kılavuzun yalnızca İngilizce olmayan çevirileri için anlamlı olan metinleri içermek için aşağıdakileri kullanabilirsiniz; örneğin İngilizce olmayan okuyuculara atıf olarak bir ögenin İngilizce adlarını sağlamak için:

.. only:: non_english

    Bu içerik, İngilizce sürüm için gizlidir; ancak çevrilebilir ve İngilizce
    olmayan sürümlerde görünür.

Çevirmenler için Notlar

Kılavuzu genellikle sözcüklerin etrafında boşluk kullanılmayan bir dil için çeviriyorsanız (örneğin, Çince ve Japonca) imlemeyi ve sözcükleri ayırmak için çıkış karakterli bir boşluk kullanabilirsiniz. Bu, özellikle aşağıdaki gibi sayfa bağlantıları için kullanışlıdır:

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

Bir PO dosyasından çevirirken, ters eğik çizgiyi başka bir ters eğik çizgi ile kaçırmanız gerektiğini unutmayın:

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

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