Krita 설명서의 마크업 표기 규칙

여기에는 Krita 설명서에서 reStructuredText를 사용할 때의 스타일 표기 규칙이 자세히 설명되어 있습니다.

reStructuredText의 공식 명세를 살펴 보고 SourceForge에 접근할 수 있는 경우 하드 드라이브에 사본을 저장하는 것을 추천합니다(글 작성 시간 현재 SourceForge 서버에 가용성 문제가 있음):

사용자 설명서:
참조 문서:
Sphinx 관련 문서:

공식 reStructuredText와 Sphinx 문서 사이에는 일을 처리하는 여러 방법이 다릅니다. 이 문서에서는 Krita 설명서에서 사용하는 규칙을 안내합니다.

메타데이터

각 페이지는 다음 세 가지 항목으로 시작해야 합니다:

  1. 메타 설명

    페이지에 대한 일반적인 설명입니다. 검색 엔진에서 사용하는 HTML 메타 태그로 변환됩니다:

    .. meta::
    :description:
        설명.
  2. 작성자 및 라이선스 목록.

    페이지를 편집한 사람을 추적하고 크레딧을 제공하기 위한 항목입니다. 기계가 쉽게 읽을 수 없도록 주석에 있어야 합니다. 전체 설명서의 라이선스는 GFDL 1.3이며 여기에도 명시해야 합니다:

    .. metadata-placeholder

   :authors: - 작성자 1
             - 작성자 2
   :license: GNU 자유 문서 라이선스 1.3 이상.
  3. 색인 용어.

    현재 페이지를 색인에 있는 색인 항목에 추가할 때 사용할 쉼표로 구분된 색인 용어입니다. 생성된 색인은 PDF 문서뿐만 아니라 자신이 찾고 있는 용어의 정확한 이름이 무엇인지 모르는 경우에도 상당히 유용합니다. 다음과 같이 정의됩니다:

    .. index:: 키워드, 공백이 있는 키워드, ! 주요 정의 키워드
  4. 레이블.

    :ref:`label_name`처럼 입력하여 페이지로 향하는 링크를 쉽게 추가할 수 있습니다. 멋진 변수 이름을 사용할 수 있습니다:

    .. _label_name:

    레이블 뒤에는 머리글을 지정해야 합니다. :ref:`label_name`처럼 입력하면 링크 텍스트로 해당 머리글을 표시합니다.

제목

제목과 소제목은 다음과 같은 단계로 지정할 수 있습니다:

############
부분/섹션
############

하위 페이지가 많은 페이지의 경우에 사용합니다.

======
제목 1
======

이것으로 대부분의 설명서 페이지를 시작합니다.

제목 2
------

제목 3
~~~~~~

제목 4
^^^^^^

제목 5
''''''

제목 6
""""""

Pandoc의 미디어위키에서 reStructuredText 변환 때문에 이러한 표기 규칙을 결정했습니다. 4단계 이상의 소제목을 사용해야 한다면 페이지가 너무 복잡하거나 분할해야 할지를 먼저 확인하십시오.

만약 페이지의 하위 섹션으로 가는 링크를 추가해야 한다면 해당 제목 위에 레이블을 추가하십시오.

레이블에 연결할 때 머리글이 링크 이름으로 사용되므로 머리글은 구두점으로 끝나지 않아야 합니다.

링크

링크를 추가하려면 :ref:`label_name`처럼 입력하십시오. 링크 텍스트를 변경해야 하는 경우 :ref:`표시할 텍스트 <label_name>`처럼 입력하십시오.

외부 페이지로 향한 링크는 `url`_ 및 `링크 이름 <url>`_처럼 입력할 수 있으며, 링크 이름처럼 표시됩니다.

Pandoc에서는 이것을 `link name`__으로 바꾸고 문서 끝에 .. __ :url을 추가하려고 합니다. 소위 ‘익명 하이퍼링크’라고도 불리며, 텍스트에 나타나는 링크 순서에 따라 텍스트 끝에 있는 링크 순서가 결정됨을 의미합니다. 이 개념은 혼란스럽고 어렵게 들릴 수도 있지만, 실제로도 그렇기 때문입니다. 그래서 이러한 스타일 링크를 피하려고 하는 것입니다.

각주 및 추가 자료

각주는 3가지 방법으로 만들 수 있으며, 가장 일반적인 방법은 참조에 따라 자동 번호 매기기를 사용하는 것입니다:

[1]은 각주 1에 대한 참조이고 [2]는 각주 2에 대한 참조입니다.

[3]은 각주 3에 대한 참조입니다.

문헌 인용은 다음과 같이 입력합니다: [CIT2002].

[CIT2002]

문헌 인용입니다. 레이블이 텍스트라는 점을 제외하면 각주와 같습니다.

인용은 `citation <CIT2002>`_처럼 참조할 수도 있습니다.

독자들에게 너무 학문적이라는 사실 때문에 설명서에 실제로 각주를 사용하지는 않습니다. 그러나 페이지에서 다루는 주제에 대해 좀 더 많은 정보를 제공하는 문서와 링크를 맨 끝에 제시합니다. Sphinx는 외부 링크를 표시하는 .. seealso:: 지시문을 가지고 있으며, reStructuredText에서는 LaTeX에서도 잘 작동하는 .. rubic:: Footnotes를 사용하여 각주를 표시할 것을 권장합니다.

이미지

캡션이 없는 이미지에는 image 지시문을 사용합니다:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: 이미지.

그리고 캡션이 있는 이미지에는 다음과 같이 figure 지시문을 사용합니다:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: 이미지.

   캡션 -- 캡션의 첫 번째 글자가 앞 들여쓰기가 :figwidth: 옵션의 들여쓰기와 같음에 유의하십시오.

후자는 다음과 같이 표시됩니다:

an image.

캡션 – 캡션의 첫 번째 글자가 앞 들여쓰기가 :figwidth: 옵션의 들여쓰기와 같음에 유의하십시오.

이미지는 /images 폴더에 저장해야 합니다. images가 아닌 /images를 사용하여 Sphinx에 파일 경로가 상대적이지 않다는 것을 알려 줍니다.

텍스트 내 마크업

텍스트를 별표 한 개와 두 개로 둘러싸서 기울임꼴 및 굵게 만들 수 있습니다:

*기울임꼴*
**굵게**

동시에 *기울임꼴과 굵게* 표시할 수는 없으므로 둘 중 하나를 선택해야 합니다.

:sub:`문자열` 또는 :sup:`문자열`을 사용하여 각각 아래 첨자와 위 첨자를 사용할 수 있습니다.

그러나 이것의 사용은 권장하지 않습니다! Sphinx의 시맨틱 마크업을 사용하는 것을 추천합니다. 번역가가 텍스트의 특성을 쉽게 파악할 수 있기 때문입니다:

:menuselection:`설정 --> Krita 설정...`
:guilabel:`파일`
:kbd:`Ctrl + Z`
:program:`Krita`

단어를 임의로 굵게 표시하지 마십시오. 텍스트를 읽기 쉽거나 친숙하게 하지 않습니다.

대체 참조

다음을 사용하여 텍스트 또는 이미지에 대한 일종의 단축형을 만들 수 있습니다:

.. |shorthand| replace:: 중요한 것 또는 다른 것.

이렇게 입력한 후 텍스트에 |shorthand|라고 입력하면 ‘중요한 것 또는 다른 것’으로 대체됩니다. “LaTeX”의 경우처럼 복잡한 방식으로 형식을 지정해야 하는 이미지와 텍스트에 유용합니다.

Krita 문서에는 |mouseleft|, |mousemiddle|, |mousescroll| 및 |mouseright| 항목이 있으며, 각각 mouseleft, mousemiddle, mousescroll 및 mouseright 처럼 변합니다. 이 설정은 Sphinx의 conf.py에 정의되어 있으며 각 rst 파일에 추가됩니다.

링크의 경우, 동일한 링크를 반복해서 재사용하는 경우에는 파일 끝에 다음과 같은 내용을 작성할 수 있습니다:

.. _bugzilla: https://bugs.kde.org/
.. _Krita 설명서: https://docs.krita.org/

그 다음, 링크를 입력할 때 `bugzilla`_라고 입력하면 Bugzilla 링크가 추가되며 링크 텍스트로는 “bugzilla”를 사용합니다. `Krita Manual`_이라고 입력하면 docs.krita.org 사이트로 향한 링크가 추가되며 링크 텍스트로는 “Krita Manual”을 사용합니다.

목록

순서가 있는 목록

  1. 사과

  2. 배

  3. 바나나

또는…

  1. 테이블

  2. 의자

  3. 옷장.

  1. 아우구스투스

  2. 네로

  3. 칼리굴라

  4. 트라야누스

다음과 같이 정의할 수 있습니다:

1. 사과
2. 배
3. 바나나

#. 사과
#. 배
#. 바나나

A. 테이블
B. 의자
C. 옷장

A. 테이블
#. 의자
#. 옷장

I. 아우구스투스
#. 네로
#. 칼리굴라
#. 트라야누스

순서가 없는 목록

  • 빨간색

  • 노란색

  • 초록색

    • 바다색

    • 녹청색

    • 암록색

    • 청록색

    • 에메랄드색

      • 진한 에메랄드색

      • 옅은 에메랄드색

        • 매우 옅은 에메랄드색.

  • 파란색

다음과 같이 정의됩니다:

- 빨간색
- 노란색
- 초로삭
    - 바다색
    - 녹청색
    - 암록색
    - 청록색
    - 에메랄드색
        - 진한 에메랄드색
        - 옅은 에메랄드색
            - 매우 옅은 에메랄드색.
- 파란색

정의 목록

자주 사용합니다! 정의 목록은 도커의 모든 옵션을 열거하고 그 뒤에 간단한 설명을 추가하려고 할 때 특히 유용합니다.

정의

설명.

다른 옵션

설명.

만드는 방법.

다음과 같이 만들 수 있습니다:

정의
    설명.
다른 옵션
    설명.

표

목적

표 형식

단축키 나열

간단한 표

많은 열 병합

그리드 표

간단하지만 긺

목록 표

다음과 같이 작성합니다:

============== ============
목적           표 형식
============== ============
단축키 나열    간단한 표
많은 열 병합   그리드 표
간단하지만 긺  목록 표
============== ============

+-------------+---------+
|목적         |표 형식  |
+=============+=========+
|단축키 나열  |간단한 표|
+-------------+---------+
|많은 열 병합 |그리드 표|
+-------------+---------+
|간단하지만 긺|목록 표  |
+-------------+---------+

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

   - * 목적
     * 표 형식
   - * 단축키 나열
     * 간단한 표
   - * 많은 열 병합
     * 그리드 표
   - * 간단하지만 긺
     * 목록 표

완전한 그리드 표는 복잡한 열과 행 합치기 등 모든 기능이 필요한 경우에 적합하지만, 만들기 까다롭습니다. 이러한 이유로 작은 표를 만들 때에는 간단한 구문으로 하는 것이 가장 좋으며, 실제로 긴 표는 목록 지시문으로 만드는 것이 가장 좋습니다. 왜냐하면 그렇게 하는 것이 훨씬 쓰기 쉽고 유지 관리하기도 쉽기 때문입니다.

권고 사항 및 여담

참고

권고 사항은 독자가 주의를 기울여야 하는 별도의 섹션과 같습니다.

사용할 수 있는 권고 사항은 다음과 같습니다(심각한 순서대로):

힌트

힌트는 주제에 대해서 설명할 때 본문 밖에서 설명하는 것이 더 적합한 정보에 유용합니다. 예를 들어, “이 패키지의 이름은 openSuse와 Debian에서 서로 다릅니다”.

팁

작업을 수행하는 방법에 대한 추가 정보입니다. 예를 들어 “자주 사용하는 문서 설정으로 템플릿을 만들 수 있습니다” 또는 “m 키를 눌러서 캔버스를 뒤집어서 도면의 오류를 더 쉽게 확인할 수 있습니다”.

중요

주의하는 것이 중요하지만, 반드시 부정적인 것은 아닙니다.

경고

일반적으로 뭔가 부정적인 경우입니다.

주의

일반적 관심 끌기입니다. 경고보다 더 중요하지만 데이터 손실을 가져올 수 있는 만큼 중요하지는 않을 때 사용합니다.

조심

데이터 손실을 유발할 수 있는 문제(예: 저장하지 않음), 또는 Python에 현재 실행 취소 기능이 없는 경우를 위한 것입니다.

위험

일반적으로 컴퓨터에 위험한 것들입니다. 예를 들어 메모리 부족을 야기할 수 있는 것입니다.

오류

아마 설명서에는 중요하지 않습니다. Sphinx에서는 일부 경우에 이 항목을 수동으로 생성할 수 있지만, Krita에서 사용하는 설정에서는 생성하지 않습니다.

모든 텍스트가 들어갈 수 있는 일반적인 권고 사항

텍스트.

다음과 같이 만들 수 있습니다:

.. admonition:: 모든 텍스트가 들어갈 수 있는 일반적인 권고 사항

    텍스트.

Sphinx에서는 또한 다음을 추가합니다:

.. seealso::

    외부 링크 및 참조를 나열하는 데 유용합니다.

수평선을 추가하고 싶으면 ----처럼 입력하십시오.

rubric 지시문

rubric 지시문은 언뜻 보기에 “topic”처럼 보이지는 머리글 지시문이지만, 주제가 여러 단락으로 나뉘어 있는 경우, rubric 지시문 자체는 다음과 같이 머리글만 처리합니다:

.. rubric:: rubric 지시문

그렇다면 언제 사용합니까?

대상이 너무 미미해서 적절한 제목을 가질 수 없다고 생각할 때만 사용하십시오.

주제

텍스트가 흐름과 분리되어 텍스트 자체가 자연스럽게 진행하는 방향과 다른 주제로 이동합니다.

표제

텍스트가 흐름과 분리되지 않았지만, 머리글이 필요하지 않은 경우입니다.

권고 사항

의미적으로 맞을 경우에만 사용합니다. 특히 위험과 경고에 대한 권고 사항은 꼭 필요한 경우에만 사용하십시오. 너무 자주 나타나면 독자가 필요한 만큼 주의를 기울이지 못할 수도 있습니다.

코드 스니펫

인라인 코드 스니펫``은 ````백틱`` 문자열로 둘러쌉니다.

여러 줄로 된 코드 스니펫은 이전 섹션을 ::로 끝맺어서 시작합니다. 다음과 같이 보입니다:

이것은 단락이며 다음과 같이 미리 형식이 지정된 스니펫을 정의합니다::

    스니펫을 시작하기 전에 공백과 탭 문자를 추가해야 합니다.

또한 .. code:: 지시문을 사용할 수도 있습니다. 그 뒤에 언어 이름을 추가하면 적절한 구문 강조 표시가 수행됩니다:

.. code:: python

    # Python 주석
    def my_function():
        alist = []
        alist.append(1)
        string = "hello world"

결과물

# Python 주석
def my_function():
    alist = []
    alist.append(1)
    string = "hello world"

좀 더…

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

    // 12 이상인지 확인
    if (i>12) {
        i = 0;
    }
    return i;
}

/* CSS 주석 */
body {
    margin: 0 auto;
    /* 800이 여전히 적당한지 확인할 것 */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>이것은 <span style="font-style:italic">한</span> <!-- HTML 주석 --> 단락입니다.</p>

기타 사전 형식이 지정된 텍스트

파이프 기호를
매 줄 맨 앞에
붙여서
텍스트 형태를
사전에 지정할
수
있습니다

예시:

| 파이프 기호를
| 매 줄 맨 앞에
| 붙여서
| 텍스트 형태를
| 사전에 지정할
| 수
| 있습니다

설명서에서는 보통 사용하지 않습니다. 단지 시각적인 이유가 아니라 정확한 형식 지정이 필수적인 내용에 사용합니다.

용어집, 용어 및 색인

Sphinx의 기능입니다.

색인은 최상위 섹션에서 사용되며, 현재 단일 색인 항목만 사용됩니다.

용어집은 일부 메뉴 항목 섹션에 사용되지만, 모두 사용되는 것은 아닙니다.

인용문

인용문은 다음과 같이 작성합니다:

사용자 설명서에 왜 인용문이 필요한지 잘 모르겠습니다 ...

-- Wolthera

이것은 인용구가 됩니다.

사용자 설명서에 왜 인용문이 필요한지 잘 모르겠습니다 …

—Wolthera

실제로 일부 항목에서 인용문을 사용합니다. 이름에 링크를 추가하여 인용 출처를 밝혀 주십시오.

Text for Non-English Translations Only

You can use the following to include text that only makes sense for non-English translations of the manual, for example to provide non-English readers with the English names of an item for reference:

.. only:: non_english

    This content is hidden for the English version, but translatable and
    shows up in non-English versions.

Notes for Translators

If you are translating the manual for a language that does not usually use whitespaces around words (e.g. Chinese and Japanese), you can use an escaped whitespace to separate markup and words. This is particularly useful for page links, like this:

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

Note that when translating from a PO file, you should escape the backslash with another backslash:

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

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