게시판 질문을 위한 최소예제 만들기

2014.12.17 12:22

karnes 조회 수:7718 추천:2

게시판에 질문하여 원하는 답변을 얻으려면, 현재 문제가 된 상황을 답변자가 재현해볼 수 있어야 한다.

아무런 정보도 제공하지 않고 단순히 "잘 안 돼요"라고 해봐야 누구도 뭐가 문제인지 알아낼 수 없다. 따라서 아무리 기다려도 원하는 답변을 얻을 수 없을 것이다.

 

기본정보

그러므로 다음과 같은 기본 정보를 제공하여야 한다.

  1. 운영체제, 설치한 텍시스템, 컴파일 엔진에 대한 기본적인 사항. 예: "Windows 8.1, TeX Live 2014, xelatex으로 컴파일"
  2. 문제를 기술하는 최소 예제 파일
  3. 문제점이나 원치 않는 상황에 대한 간단한 설명과 원하는 결과

답변을 하는 사람은 아무런 대가 없이 선의로 하는 것이므로 답변을 강요할 수 없다. 질문자는 이 사이트에서 어떤 경우에도 "고객"과 같은 답변을 강요할 권리를 누릴 수 없으며 전적으로 답변자의 선의에 호소하여야 하는 것이므로, 간단한 감사와 존중을 표하는 것이 좋다. 그리고 "흥미로운 문제"일수록 더 쉽게 답변을 얻을 수 있다. 자신에게 이 문제가 중요하고 급하다고 호소하는 것은 아무런 도움도 되지 않는다.

Minimal Working Example

최소 예제 파일(Minimal Example) 또는 최소 작업례(Minimal Working Example) 파일은 다음과 같은 사항이 반드시 포함되어야 한다.

  1. 완전히 컴파일 가능하여야 한다. 즉 \documentclass와 \begin{document} \end{document}가 모두 갖추어진 문서여야 한다.
  2. 에러나 문제점을 재현하는 것이어야 한다. "최소 예제에서는 아무 문제 없는데 제 파일을 컴파일하면 문제가 생겨요"라는 것은 최소 예제로서 의미가 없는 것이다. 간혹 "말씀하신 문제는 재현되지 않습니다"라는 답변이 달리는데, 이것은 제공한 샘플 파일에서 아무런 문제도 찾을 수 없다는 의미이다.
  3. 문제와 관련이 없는 패키지는 모두 제외하고 문제를 일으키는 패키지만 제시하는 것이 좋다. 그러나 잘 모르겠으면 preamble을 통째로 복사해서 올려도 대부분의 답변자는 이를 용인할 것이다. 패키지 간의 충돌이 일으키는 문제와 같이 초보자가 잘 파악할 수 없는 에러의 경우에는 차라리 preamble의 내용을 그대로 보여주고 도움을 청하는 것이 좋을 수도 있다.

그림

최소 예제를 만들 때 그림을 포함하여야 할 필요가 있다.

  1. 그림은 example-image를 사용한다. \includegraphics[width=3cm]{example-image}. 이 그림은 TeX Live를 설치하였다면 당연히 포함되는 것이므로 굳이 그림을 첨부하지 않아도 된다.
  2. example-image를 포함하였을 때는 아무 문제도 없는데 자신의 그림을 대신 넣으면 에러가 발생하는 경우라면 그림 자체에 문제가 있는 것이므로 이 때는 문제가 된 그림도 함께 첨부하여야 한다.

채우기 텍스트

채우기 텍스트가 필요할 경우가 있다.

  1. 자신이 작업 중인 문서의 구체적인 내용을 다른 사람에게 알릴 필요는 없다. 그러므로 텍스트를 무의미한 채우기 문장으로 구성하는 것이 좋은 방법이다. 영문의 경우는 lipsum이나 blindtext, 한글 문장의 경우는 jiwonlipsum을 사용하라.

파일 첨부

질문을 위한 게시글에 최소 예제는 "파일 첨부"하는 것이 copy&paste해서 질문 글 본문에 붙이는 것보다 좋다.

질문과 관련된 핵심부분을 게시글에 붙여넣어 나중에 검색이 가능하도록 하는 것은 더 좋다.

파일이 둘 이상이면 zip 등으로 압축하여 첨부(attach)하라.

alz나 egg같은 것으로는 압축하지 않는 것이 좋다. 이 사이트에서 답변하시는 분들이 압축 파일을 풀지 못할 수도 있다.
zip, 7zip, tar.gz 정도가 적절한 압축 포맷이다.

중요한 것은 답변자가 최대한 쉽게 테스트해볼 수 있도록 배려하는 것이다. 특히 표준 TeX Live와 KTUG 사설저장소에서 제공하지 않는 클래스나 패키지(예: myuniversitysthesisclass.cls)의 경우에는 반드시 이를 함께 첨부하여야 한다. CTAN에 등재되어 있으나 TeX Live에는 포함되지 않는 패키지의 경우에도 이를 함께 첨부하여야 한다.

폰트

XeLaTeX이 거의 디폴트 엔진으로 활용되는 현재 질문자가 올린 샘플 파일을 테스트하려 할 때 문제가 되는 것이 사용자 설정 폰트이다. 답변을 위해 테스트하는 사람에게는 TeX Live의 기본 폰트밖에 가지고 있지 않을 것으로 상정하는 것이 당연하다. 따라서 자신만이 사용하고 있는 폰트 설정을 그대로 올린다면 답변자가 이를 테스트해볼 수 없다. 즉, MWE에서 \set...font 관련된 부분은 완전히 삭제하는 것이 좋다.

한글 폰트의 경우, "바탕"도 사용하면 안 된다. 왜냐하면 윈도우즈 이외의 시스템에서 이 폰트를 발견할 수 없기 때문이다. 상호 소통을 위해 KTUG 사설저장소에서 제공되는 다음 한글 폰트만이 허용되는 것으로 보아야 한다: 나눔명조, 나눔고딕, 나눔바른고딕, 나눔명조옛한글, 나눔바른고딕옛한글, 함초롬 바탕 LVT, 함초롬 돋움 LVT. 그리고 은 글꼴.

그런데, 질문을 하게 된 이유 자체가 폰트 문제에서 비롯된 것일 수 있다. 예를 들면 웹상에 떠돌아다니는 Minion Pro.ttf라는 폰트 파일은 이상한 결과를 얻게 하는데 이 폰트 때문에 발생한 문제를 질문하려면 폰트 자체가 없으면 안 된다. MWE를 작성하면서 자신이 직면한 문제가 폰트에서 오는 것인지 그렇지 않은 것인지를 반드시 확인한다. 그리고 폰트 때문에 발생하는 문제라고 확신한다면 이 폰트 자체를 제공해야 한다. 문제는 폰트 파일을 KTUG 게시판에 업로드하지 못할 것이라는 것이다. (용량 제한 때문에)

이를 위하여 KTUG 사설저장소에서 제공되는 preparefont 패키지를 활용할 수 있다. 이는 TeX Live와 KTUG 사설저장소가 잘 설정되어 있을 때 > tlmgr install ksmisc 의 명령으로 설치할 수 있다.

요컨대,

  1. 폰트 설정 부분을 제외하고 문제가 재현되도록 샘플 파일을 작성한다.
  2. 정말로 폰트 자체의 문제라서 특정 폰트를 꼭 이용하지 않으면 문제를 재현할 수 없을 경우에는 해당 폰트 하나를 잠시 dropbox 같은 걸로 일시적으로 공유하는 방법이 있을 수도 있다.

preparefont를 이용하지 않더라도, 폰트를 다운받을 수 있는 url을 제공한다면, 대부분의 답변자들은 "클릭하여 다운받는" 정도의 수고는 아끼지 않을 것이다.

질문글의 삭제

만약 게시판 문답을 통하여 원하는 결과를 얻었다면 그 사실을 답글로 달아서 해결되었음을 알리는 것이 좋다. 답변을 얻은 후에 글타래 자체를 삭제하는 분이 있는데 이것은 예의도 아닐 뿐 아니라 대단히 이기적인 행동으로 비난받아 마땅한 일이다.

질문을 한 후에 답변을 기다리지 않고 자신이 스스로 문제를 해결하였다면, 해당 게시물을 삭제하지 말고 그 사실을 알려두고 글타래를 종료하는 것이 훨씬 좋다. 혹시 다른 누군가 그 글을 통해서 문제를 해결하게 될는지도 모르는 일이다.

그밖의 질문

문제점이 LaTeX에 있는 것이 아니라 에디터나 특정 운영체제의 설치 문제에 관한 것이라면 자신이 무슨 조작을 어떻게 했을 때 어떤 원치 않는 현상이 일어나는지를 자세히 기술하여야 한다. 이 경우에도 중요한 것은 답변할 의사와 능력이 있는 사람이 그 "문제"를 재현해볼 수 있어야 한다는 것이다. 그리고 자신이 테스트하고 있는 최소 예제를 첨부하는 것이 답변을 듣기 더 쉬우며 혹시 있을지 모를 실수를 누군가가 지적해줄 수도 있다.

참고문서

최소 예제의 작성에 관하여 다음 두 문서를 참고한다.

그리고 2015년 한국텍학회 학술대회에서 목봉균이 발표한 내용을 참고하자.




XE Login