19. 부록 : 이 교재에 공헌하기

이 강의에 자료를 추가하려면, 이 부록에 명시된 지침을 따라야 합니다. 이 부록에 있는 조건들을, 좀 더 명확히하려는 목적이 아니라면, 수정해서는 안 됩니다. 이 교재의 질과 일관성을 유지하기 위해서입니다.

19.1. 리소스 다운로드

이 문서의 소스를 GitHub 에서 구할 수 있습니다. Git 버전 컨트롤 시스템 이용법에 대해서는 GitHub.com 에 문의하십시오.

19.2. 교재 서식

이 교재는 reStructuredText 마크업 언어를 사용하는 파이썬 문서 생성자인 Sphinx 를 이용해서 작성됐습니다. 이 도구들의 사용법은 각 해당 사이트에서 알 수 있습니다.

19.3. 모듈 추가

새 강의를 추가하려면 먼저 새 강의의 명칭으로 (최상위 qgis-training-manual 디렉터리 바로 아래에) 새 디렉터리를 생성하십시오.
이 새 디렉터리에 index.rst 라는 파일을 생성합니다. 빈 파일인 채로 놔두십시오.
최상위 디렉터리에 있는 index.rst 파일을 여십시오. 첫 부분은 다음과 같습니다.
```
.. toctree::
   :maxdepth: 2


   foreword/index
   introduction/index
```

/index 가 뒤에 붙는 디렉터리명 목록이라는 것을 알 수 있습니다. 이 목록이 최상위 인덱스 파일을 각 디렉터리의 인덱스 파일에 연결합니다. 이 목록의 순서가 문서 내부의 강의 순서를 결정합니다.

이 목록의 사용자가 원하는 순서에 새 강의 명칭(예를 들면 새 디렉터리에 부여한 명칭)을 추가하고, 뒤에 /index 를 붙이십시오.
뒤에 오는 강의는 이전 강의에서 배운 지식을 기반으로 하는 것과 같이 강의 순서가 논리적이어야 한다는 사실을 기억하십시오.
사용자의 새 강의의 인덱스 파일( [강의 명칭]/index.rst )을 여십시오.
페이지 맨 위에 별표( * ) 80개를 쓰십시오. 강의명의 시작(module heading)을 나타냅니다.
이 라인 다음 줄에 (“module”을 뜻하는) |MOD| 마크업 구문으로 시작하는 강의명을 작성하십시오.
다음 줄에 다시 별표 80개를 쓰십시오.
그 다음 줄은 빈 줄로 남겨두십시오.
강의의 목적 및 내용을 설명하는 짧은 글을 작성하십시오.
한 줄을 띄운 다음, 다음 텍스트를 추가하십시오.
```
.. toctree::
   :maxdepth: 2


   lesson1
   lesson2
```
… lesson1, lesson2 등은 사용자가 계획한 강의 제목들입니다.

모듈 수준의 인덱스 파일은 다음과 같이 보일 것입니다.

*******************************************************************************
|MOD| Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2


   lesson1
   lesson2

19.4. 강의 추가

새 모듈 또는 기존 모듈에 강의를 추가하려면,

모듈 디렉터리를 여십시오.
(새 모듈인 경우, 앞에서 생성했던) index.rst 파일을 여십시오.
계획한 강의 명칭들이 앞에서와 같이 toctree 지시문 아래 나열되어 있는지 확인하십시오.
모듈 디렉터리에 새 파일을 생성하십시오.
해당 파일명을 모듈의 index.rst 에 적은 강의 명칭과 정확히 동일하게 명명한 다음, 확장자 .rst 를 추가하십시오.

참고

편집 목적을 위해, .rst 파일은 일반 텍스트 파일( .txt )과 정확히 동일하게 동작합니다.

강의를 작성하기 전에 |LS| 마크업 구문으로 시작하는 강의명을 작성하십시오.
다음 줄에 등호 기호( = ) 80개를 쓰십시오.
그 다음 줄은 빈 줄로 남겨두십시오.
강의의 목적을 간단히 설명하십시오.
주제에 대한 일반적인 소개를 포함시키십시오. 이 교재의 기존 강의를 참고하십시오.
그 아래에 다음 구문으로 시작하는 새 문장을 작성하십시오.
```
**The goal for this lesson:**
```
이 강의를 완료하면 얻을 수 있는 결과를 간단히 설명하십시오.
강의의 목적을 문장 하나 또는 두 개로 설명할 수 없을 경우, 해당 주제를 여러 개의 강의로 나누는 것이 좋습니다.

각 강의는 다음 단계에서 설명하는 것처럼 여러 섹션으로 세분화됩니다.

19.5. 섹션 추가

섹션에는 “따라 하기(follow along)” 및 “직접 해보기(try yourself)” 두 가지 유형이 있습니다.

“따라 하기” 섹션은 사용자에게 QGIS의 주어진 측면을 사용하는 방법을 가르치기 위한 상세한 지침들로 이루어집니다. 일반적으로 중간 중간 스크린샷이 들어가는 가능한 한 명확한 단계별 지침들을 제공합니다.
“직접 해보기” 섹션은 사용자가 직접 시연해볼 수 있는 간단한 과제들을 부여합니다. 이 과제는 보통 과제를 완수 하는 방법을 보여주거나 설명하는, 또는 가능한 경우 예상되는 산출물을 보여주는, 이 문서 마지막의 답안지에 있는 항목과 연결됩니다.

19.5.1. “따라 하기” 섹션 추가

이 섹션을 시작하려면, (앞에서 설명한 대로) 의도한 난이도를 나타내는 마크업 구문을 적으십시오.
한 칸 띄운 다음 (“따라 하기”를 나타내는) |FA| 라고 쓰십시오.
다시 한 칸 띄운 다음 섹션 명칭을 쓰십시오. (맨 첫글자만 대문자로 적고, 합당한 명사일 경우에도 첫 글자를 대문자로 적습니다.)
다음 줄에 빼기/대시( - ) 기호를 80개 쓰십시오. 사용자의 텍스트 편집기가 기본 빼기/대시 문자를 긴 대시 또는 다른 문자로 대체하지 않는지 확인하십시오.
섹션의 목적을 설명하는 간단한 소개문을 작성하십시오. 그 다음 시연할 과정에 대한 자세한 (클릭 단계별) 지침을 작성하십시오.
각 섹션에 필요한 만큼 내부 링크, 외부 링크 및 스크린샷을 첨부하십시오.
가능하다면, 결론을 내리는 동시에 자연스럽게 다음 섹션으로 이어지는 문단으로 각 섹션을 끝내도록 합니다.

19.5.2. “직접 해보기” 섹션 추가

이 섹션을 시작하려면, (앞에서 설명한 대로) 의도한 난이도를 나타내는 마크업 구문을 적으십시오.
의도한 난이도를 나타내는 마크업 구문을 쓴 다음, 한 칸 띄고 (“직접 해보기”를 나타내는) |TY| 라고 쓰십시오.
다음 줄에 빼기/대시( - ) 기호를 80개 쓰십시오. 사용자의 텍스트 편집기가 기본 빼기/대시 문자를 긴 대시 또는 다른 문자로 대체하지 않는지 확인하십시오.
사용자가 완수하길 바라는 예제를 설명하십시오. 필요할 경우 이전 섹션, 강의, 또는 모듈을 언급하십시오.
텍스트만으로 이루어진 설명이 명확하지 않을 경우, 요구 사항을 명확하게 하는 스크린샷을 첨부하십시오.

대부분의 경우 해당 섹션이 할당하는 과제를 완수하는 방법에 대한 답안을 제공하고자 할 것입니다. 그러려면 답안지에 해당 항목을 추가해야 합니다.

먼저 답안에 대해 유일한 명칭을 결정하십시오. 이 명칭에 강의 명칭과 함께 순차적인 숫자를 붙이는 것이 이상적입니다.
다음과 같이 이 답안에 대한 링크를 생성하십시오.
```
:ref:`Check your results <answer-name>`
```
답안지( answers/answers.rst )를 여십시오.
다음 라인을 작성해서 “직접 해보기” 섹션으로 연결되는 링크를 생성하십시오.
```
.. _answer-name:
```
필요한 경우 링크 및 이미지를 사용해서 해당 과제를 완수하는 방법에 대한 지침을 작성하십시오.
다시 “직접 해보기” 섹션으로 돌아가는 링크를 다음과 같이 첨부해서 답안을 완성하십시오.
```
:ref:`Back to text <backlink-answer-name>`
```
이 링크가 동작하게 하려면, “직접 해보기” 섹션의 제목 위에 다음 라인을 추가해야 합니다.
```
.. _backlink-answer-name:
```

지금까지 살펴본 모든 라인들의 위아래가 빈줄이어야 한다는 사실을 기억하십시오. 그렇지 않다면 문서 생성 시 오류가 발생할 수 있습니다.

19.6. 결론 추가

강의를 끝내려면 “결론을 내리면(in conclusion)” 을 나타내는 |IC| 구문을 작성하고, 다음 줄에 빼기/대시( - ) 80개를 쓰십시오. 이 강의에서 어떤 개념을 배웠는지 설명하는 강의의 결론을 작성하십시오.

19.7. 참고 문헌 섹션 추가

이 섹션이 꼭 필요한 것은 아닙니다.
“참고 문헌(further reading)”을 나타내는 |FR| 구문을 작성하고, 다음 줄에 빼기/대시( - ) 80개를 쓰십시오.
적합한 외부 웹사이트로 연결되는 링크를 첨부하십시오.

19.8. 다음 주제 섹션 추가

“다음 주제(what’s next)”를 나타내는 |WN| 구문을 작성하고, 다음 줄에 빼기/대시( - ) 80개를 쓰십시오.
현재 강의가 어떻게 다음 강의 또는 모듈을 위해 사용자를 준비시켰는지 설명하십시오.
필요할 경우 이전 강의의 “다음 주제” 섹션이 새 강의를 언급하도록 변경하는 일을 잊지 마십시오. 기존 강의들 사이에 또는 기존 강의 마지막에 새 강의를 삽입하는 경우 필요한 작업입니다.

19.9. 마크업 사용

이 문서의 표준을 준수하려면, 사용자의 텍스트에 표준 마크업을 추가해야 합니다.

19.9.1. 새로운 개념

새로운 개념을 설명할 경우, 해당 개념의 명칭을 별표( * )로 둘러싸 이탤릭체로 만들어야 합니다.
```
This sample text shows how to introduce a *new concept*.
```

19.9.2. 강조

새로운 개념이 아닌 중요한 용어를 강조하려면, 쌍별표( ** )로 둘러싸 볼드체로 만들어야 합니다.
사용에 주의하십시오! 강조를 너무 많이 사용할 경우 독자에게 소리를 지르거나 잘난 체하는 것으로 보일 수 있습니다.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. 이미지

이미지 추가 시 _static/강의_명칭/ 폴더를 만들고 저장하십시오.

문서에 다음과 같이 이미지를 추가하십시오.

.. figure:: img/image_file.extension
   :align: center

이미지 마크업 위아래에 빈 줄을 삽입하는 것을 잊지 마십시오.

19.9.4. 내부 링크

링크를 위한 앵커(anchor)를 생성하려면, 사용자가 링크가 가리키게 하고자 하는 곳 윗 줄에 다음과 같은 라인을 작성하십시오.
```
.. _link-name:
```
다음과 같은 라인을 추가해서 링크를 생성하십시오.
```
:ref:`Descriptive link text <link-name>`
```
이 라인 위아래에 빈 줄을 삽입하는 것을 잊지 마십시오.

19.9.5. 외부 링크

외부 링크를 생성하려면 다음과 같이 작성하십시오.
```
`Descriptive link text <link-url>`_
```
이 라인 위아래에 빈 줄을 삽입하는 것을 잊지 마십시오.

19.9.6. 고정폭 텍스트 사용

사용자가 입력해야 하는 텍스트, 경로명, 테이블이나 열 명칭 같은 데이터베이스 요소명 등을 텍스트로 작성할 때, 다음과 같이 monospaced text 로 써야 합니다.
```
Enter the following path in the text box: :kbd:`path/to/file`.
```

19.9.7. GUI 항목 라벨링

버튼 같은 GUI 항목을 언급하는 경우, 그 명칭을 다음과 같이 the GUI label format 으로 써야 합니다.
```
To access this tool, click on the :guilabel:`Tool Name` button.
```
사용자가 버튼을 클릭할 필요 없이, 도구명만을 언급할 경우에도 역시 적용됩니다.

19.9.9. 주석 추가

텍스트 안에 강의의 흐름의 일부로 쉽게 녹아들지 못 하는 추가적인 세부 사항을 설명하는 주석이 필요할 수도 있습니다. 해당 마크업은 다음과 같습니다.
```
[Normal paragraph.]

.. note:: Note text.
   New line within note.

   New paragraph within note.

[Unindented text resumes normal paragraph.]
```

19.9.10. 스폰서/작성자 주석 추가

스폰서를 대신해서 새 모듈, 강의 또는 섹션을 작성하는 경우, 스폰서가 선택한 간단한 스폰서의 메시지를 첨부해야 합니다. 이 메시지는 독자들에게 스폰서의 명칭을 알려야 하며, 스폰서가 후원하는 모듈, 강의 또는 섹션 제목 아래에 위치해야 합니다. 하지만, 꼭 스폰서 회사를 위한 광고일 필요는 없습니다.

스폰서를 대신하는 것이 아니라 스스로 모듈, 강의 또는 섹션을 작성하는 데 자원했다면, 작성한 모듈, 강의 또는 섹션 제목 아래에 작성자 주석을 삽입할 수 있습니다. This [module/lesson/section] contributed by [author name]. 이라는 서식을 지켜야만 합니다. 다른 문장이나 연락처 등을 추가하지 마십시오. 그런 세부 정보는 추가한 부분(들)의 명칭(들)과 함께 서문의 “개인 공헌자(Contributors)” 섹션에 추가될 것입니다. 내용을 업데이트하거나 수정하거나 추가하기만 했다면 편집자 목록에 이름을 추가하십시오.

19.10. 감사합니다!

이 프로젝트에 공헌해주셔서 감사합니다! 당신 덕분에 QGIS의 접근성을 향상시키고 전체 QGIS 프로젝트에 가치를 더할 수 있습니다.