PEP 287 – reStructuredText 독스트링 형식

Author:

David Goodger <goodger at python.org>

Discussions-To:

Doc-SIG list

Status:

Active

Type:

Informational

Created:

25-Mar-2002

Post-History:

02-Apr-2002

Replaces:

216

---

Table of Contents

• 초록
• 이점
• 목표
• 근거
• 명세
• 독스트링에서 중요한 기능
• 질문과 답변
• 참고 문헌 및 각주
• Copyright
• Acknowledgements

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

평문만으로는 인라인 문서화를 충분히 표현할 수 없었기 때문에 Python 프로그래머들은 독스트링에 쓸 형식을 찾아 왔습니다. 이 PEP는 reStructuredText markup을 Python 독스트링뿐만 아니라 PEP와 부수 문서에서도 구조화된 평문 문서화의 표준 마크업 형식으로 채택할 것을 제안합니다. reStructuredText는 풍부하고 확장 가능하면서도 읽기 쉬운, 보이는 그대로 결과가 나오는(what-you-see-is-what-you-get) 평문 마크업 문법입니다.

여기서는 독스트링의 저수준 문법만을 다룹니다. 이 PEP는 독스트링의 의미나 처리 방식은 전혀 다루지 않습니다(“독스트링 PEP 로드맵”은 PEP 256을 참조하십시오). 또한 순수 일반 텍스트 독스트링을 폐기하려는 것도 아니며, 순수 일반 텍스트 독스트링은 앞으로도 언제나 정당한 형식입니다. reStructuredText 마크업은 표현력이 더 풍부한 독스트링을 원하는 사람들을 위한 대안입니다.

이점

프로그래머는 본래 게으른 족속입니다. 우리는 함수, 클래스, 모듈, 서브시스템을 통해 코드를 재사용합니다. Python은 독스트링 문법을 통해 코드 내부에서 코드를 문서화할 수 있게 해 줍니다. Python 문서화 특별 관심 그룹(Doc-SIG)의 “성배”는 자동 문서화를 가능하게 하는 마크업 문법과 도구 모음이었습니다. 자동 문서화란 Python 시스템의 독스트링을 맥락과 함께 추출하고 처리하여 여러 목적에 쓸 수 있는 유용한 고품질 문서를 만드는 것을 말합니다.

문서 마크업 언어에는 세 부류의 고객이 있습니다. 문서를 작성하는 저자, 데이터를 처리하는 소프트웨어 시스템, 그리고 최종 소비자이자 가장 중요한 부류인 독자입니다. 대부분의 마크업은 저자와 소프트웨어 시스템을 위해 설계되었으며, 독자는 종이나 브라우저 소프트웨어를 통해 처리된 형태만 보도록 되어 있습니다. ReStructuredText는 다릅니다. 마크업에 대한 사전 지식 없이도 소스 형태 그대로 쉽게 읽을 수 있도록 만들어졌습니다. ReStructuredText는 일반 텍스트 형식으로도 완전히 읽을 수 있으며, 많은 마크업 형태가 일상적인 표기 관행과 일치하므로(예: *emphasis*) 아주 자연스럽게 읽힙니다. 그러면서도 복잡한 문서를 만들어 낼 만큼 풍부하고, 제약이 거의 없을 만큼 확장 가능합니다. 물론 reStructuredText 문서를 작성하려면 어느 정도의 사전 지식이 필요합니다.

이 마크업은 소스 텍스트를 쉽게 읽을 수 있게 유지하면서도 기능성과 표현력을 제공합니다. 처리된 형태(HTML 등)는 이 모든 것을 독자가 이용할 수 있게 해 줍니다. 인라인 활성 하이퍼링크, 각주로 가고 각주에서 돌아오는 활성 링크, (활성 링크가 걸린!) 자동 목차, 표, 다이어그램 등을 위한 이미지, 보기 좋고 읽기 쉬운 서식 있는 텍스트가 그것입니다.

reStructuredText 파서는 Docutils 프로젝트의 일부로 현재 사용할 수 있습니다. 독립된 reStructuredText 문서와 PEP는 HTML로 변환할 수 있습니다. 다른 출력 형식을 위한 작성기도 개발 중이며, 시간이 지나면서 사용할 수 있게 될 것입니다. 독스트링으로부터 자동 문서화를 구현할 Python 소스 “Reader”에 대한 작업이 진행 중입니다. 기존 자동 문서화 도구의 작성자들은 reStructuredText 파서를 자신의 프로젝트에 통합하거나, 더 나아가 힘을 모아 Python 표준 라이브러리를 위한 세계적 수준의 도구 모음을 만들 것을 권장합니다.

머지않아 도구들이 나올 것이며, 프로그래머는 이를 이용해 기존 독스트링으로부터 사실상 “공짜로” 온라인 도움말용 HTML, 여러 용도의 XML, 그리고 궁극적으로는 인쇄 문서용 PDF, DocBook, LaTeX를 생성할 수 있게 됩니다. 표준을 채택하면 적어도 더 이상의 “바퀴의 재발명”을 막아 줌으로써 독스트링 처리 도구에 도움이 될 것입니다.

결국에는 현존하는 유일한 표준 자동 문서화 도구인 PyDoc에 reStructuredText 지원이 추가될 수도 있습니다. 그 전까지도 PyDoc은 모든 독스트링을 서식이 미리 지정된 일반 텍스트로 취급하므로, reStructuredText 마크업을 다루는 데 아무런 문제가 없습니다.

목표

다음은 Doc-SIG에서 논의된, 독스트링 형식에 대해 일반적으로 받아들여지는 목표입니다.

1. 무심코 보는 사람도 소스 형태 그대로 읽을 수 있어야 합니다.
2. 어떤 표준 텍스트 편집기로든 쉽게 입력할 수 있어야 합니다.
3. 모듈을 파싱하여 알아낼 수 있는 정보는 담을 필요가 없어야 합니다.
4. 합리적인 마크업 형식이라면 어떤 형식으로든 변환할 수 있도록 충분한 정보(구조)를 담고 있어야 합니다.
5. 마크업 언어 때문에 제약을 느끼지 않고 모듈의 문서 전체를 독스트링으로 작성할 수 있어야 합니다.

reStructuredText는 이 모든 목표를 충족하고 넘어설 뿐 아니라, 이보다 훨씬 더 엄격한 자체 목표도 세우고 있습니다. 아래의 Docstring-Significant Features를 참조하십시오.

이 PEP의 목표는 다음과 같습니다.

1. reStructuredText를 독스트링(Python 모듈과 패키지의 인라인 문서), PEP, README류 파일 및 기타 독립 문서를 위한 표준 구조화 평문 형식으로 확립하는 것입니다. “Accepted” 상태는 Python 커뮤니티의 합의와 최종적인 BDFL의 선언을 통해 얻고자 합니다.

   reStructuredText는 유일한 표준이 아니라 하나의 표준으로 제안되고 있다는 점에 유의하십시오. 사용 여부는 전적으로 선택 사항입니다. 사용하고 싶지 않은 사람은 사용하지 않아도 됩니다.

2. Python 커뮤니티가 제기하는 모든 관련 우려 사항을 수렴하고 해결하는 것입니다.
3. 커뮤니티의 지지를 이끌어 내는 것입니다. 서로 경쟁하는 여러 마크업이 존재하는 한, 개발 커뮤니티는 분열된 상태로 남습니다. 일단 표준이 존재하면 사람들이 그것을 사용하기 시작할 것이고, 필연적으로 추진력이 생길 것입니다.
4. 관련된 자동 문서화 프로젝트들의 노력을 통합하는 것입니다. 관심 있는 개발자들이 힘을 합쳐 공동/병합/공통 구현을 함께 만들어 나가기를 바랍니다.

reStructuredText가 Python 표준이 되면 표준을 두고 논쟁하는 대신 도구에 노력을 집중할 수 있습니다. Python에는 표준 문서화 도구 모음이 필요합니다.

PEP와 관련해서는 다음 전략 중 하나 또는 둘 다를 적용할 수 있습니다.

1. 기존 PEP 섹션 구조 구성 요소(한 줄짜리 섹션 헤더, 들여쓴 본문)를 유지합니다. 하위 섹션은 금지하거나, 들여쓴 본문 안에서 reStructuredText 스타일의 밑줄 헤더로 지원할 수 있습니다.
2. PEP 섹션 구조 구성 요소를 reStructuredText 문법으로 대체합니다. 섹션 헤더에는 밑줄이 필요하고, 하위 섹션은 별도 설정 없이 지원되며, 본문은 (블록 인용을 제외하고) 들여쓸 필요가 없습니다.

전략 (b)를 권장하며, 그 구현은 완료되었습니다.

PEP용 reStructuredText 파서에 RFC 2822 헤더 지원이 추가되었습니다(문서의 첫 번째 연속 블록이라는 특정 맥락이 주어지므로 모호하지 않습니다). 일관성을 위해 PEP 섹션 헤더에 허용되는 윗줄/밑줄 스타일을 구체적으로 명시하는 것이 바람직할 수 있습니다.

근거

독스트링을 위한 표준 문법이 없었기 때문에, 독스트링을 추출하여 표준 형식(예: HTML, DocBook, TeX)의 문서로 변환하는 표준 도구의 개발이 저해되어 왔습니다. 여러 마크업 형식과 그 변형이 제안되었고 이러한 제안에 연계된 도구도 많았지만, 표준 독스트링 형식이 없었기 때문에 이들은 확고한 지지를 얻지 못했거나 절반쯤 완성된 채 흐지부지되었습니다.

Doc-SIG가 존재해 온 기간 내내 단일 표준 독스트링 형식에 대한 합의는 한 번도 이루어지지 않았습니다. 가볍고 암묵적인 마크업이 추구되어 온 이유는 (여러 이유 가운데) 다음과 같습니다.

1. Python 코드 안에 작성된 독스트링은 대화형 인터프리터에서 사용할 수 있으며, “print”로 출력할 수 있습니다. 따라서 쉽게 읽을 수 있도록 일반 텍스트를 사용합니다.
2. 프로그래머는 원시 독스트링의 가독성을 희생하지 않으면서 독스트링에 구조를 더하기를 원합니다. 꾸밈없는 일반 텍스트는 유용한 구조화된 형식으로 변환(“상향 번역”)할 수 없습니다.
3. (XML이나 TeX 같은) 명시적 마크업은 익숙하지 않은 사람이 읽기 어렵다고 널리 여겨집니다.
4. 암시적 마크업은 깔끔하고 미니멀한 Python 문법과 미적으로 잘 어울립니다.

수년간 Doc-SIG에서 독스트링을 위한 여러 대안 마크업이 제안되었으며, 그중 대표적인 예를 아래에 나열합니다. 각각을 위에서 언급한 목표의 관점에서 간략히 분석합니다. 이 목록은 현존하는 모든 마크업 시스템을 망라하려는 것이 아님에 유의하십시오. 여기서 언급하지 않은 다른 마크업(Texinfo, Doxygen, TIM, YODL, AFT, …)도 많이 있습니다.

• XML, SGML, DocBook, HTML, XHTML

  XML과 SGML은 모든 종류의 문서화에 적합한, 명시적이고 잘 정형화된 메타 언어입니다. XML은 SGML의 변형입니다. 훈련되지 않은 눈에는 장황하고 입력하기 어려우며 너무 어수선해서 소스로 편하게 읽을 수 없으므로, 이들은 보이지 않는 내부에서 사용하는 것이 가장 좋습니다. DocBook, HTML, XHTML은 모두 SGML 및/또는 XML의 응용이며, 모두 같은 기본 문법과 같은 단점을 공유합니다.

• TeX

  TeX는 명시적이라는 점에서 XML/SGML과 비슷하지만, 작성하기가 그리 쉽지 않고 익숙하지 않은 사람이 읽기도 쉽지 않습니다.

• Perl POD

  대부분의 Perl 모듈은 POD(Plain Old Documentation)라는 형식으로 문서화됩니다. 이는 입력하기 쉽고 매우 저수준인 형식으로, Perl 파서와 긴밀하게 통합되어 있습니다. POD 문서를 info, HTML, man 페이지 등 다른 형식으로 변환하는 도구가 많이 있습니다. 그러나 POD 문법은 가독성 면에서 Perl 자체를 닮았습니다.

• JavaDoc

  Java 클래스와 함수 앞에 오는 특수 주석이 코드를 문서화하는 역할을 합니다. 이 주석을 추출하여 HTML 문서로 변환하는 프로그램은 javadoc이라고 하며, 표준 Java 배포판에 포함되어 있습니다. 그러나 JavaDoc은 대부분의 마크업에 HTML 태그를 사용하므로 HTML과 매우 밀접한 관계에 있습니다. 따라서 HTML의 가독성 문제를 그대로 공유합니다.

• Setext, StructuredText

  초기에는 Zope Corp의 StructuredText를 비롯한 Setext(Structure Enhanced Text)의 변형들이 Python 독스트링 서식으로 제안되었습니다. 이하에서는 이 변형들을 통틀어 “STexts”라고 부릅니다. STexts는 특별한 지식 없이도 읽기 쉽고 비교적 작성하기도 쉽다는 장점이 있습니다.

  일부에서 사용되고 있기는 하지만(기존 Python 자동 문서화 도구 대부분을 포함하여), STexts는 지금까지 다음과 같은 이유로 표준이 되지 못했습니다.

  • STexts는 불완전했습니다. 사람들이 독스트링에서 쓰고 싶어 하는 “필수적인” 구성 요소가 없어서, STexts는 이상적이라고 하기 어려웠습니다. 이러한 “필수적인” 구성 요소는 보편적이지 않다는 점에 유의하십시오. 사람마다 요구 사항이 다릅니다.
  • STexts는 때때로 예상치 못한 결과를 낳았습니다. 텍스트 일부가 뜻하지 않게 마크업으로 해석되어 사용자를 좌절시켰습니다.
  • SText 구현에는 버그가 많았습니다.
  • 대부분의 STexts에는 구현 자체 외에는 공식 명세가 없습니다. 구현에 버그가 있으면 명세에도 버그가 있는 셈이었고, 그 반대도 마찬가지였습니다.
  • 마크업 문자를 마크업이 아닌 맥락에서 사용할 때 SText 마크업 규칙을 피해 갈 메커니즘이 없었습니다. 다시 말해, 마크업을 이스케이프할 방법이 없었습니다.

암시적 STexts 지지자들은 명시적 마크업(XML, HTML, TeX, POD 등) 제안에 강하게 반대해 왔으며, 이 논쟁은 1996년 또는 그 이전부터 간헐적으로 계속되어 왔습니다.

reStructuredText는 SText 아이디어를 완전히 개정하고 재해석한 것으로, 위에 나열한 모든 문제를 해결합니다.

명세

reStructuredText의 명세와 사용자 문서는 상당히 방대합니다. 여기서 그 전부를 반복하거나 요약하는 대신 원본 문서의 링크를 제공합니다.

먼저 짧고 친절한 입문서인 A ReStructuredText Primer를 살펴보십시오. Quick reStructuredText 사용자 참조 문서는 모든 마크업 구성 요소를 간략히 요약합니다. 완전하고 상세한 내용은 다음 문서를 참조하십시오:

• An Introduction to reStructuredText
• reStructuredText Markup Specification
• reStructuredText Directives

또한 Problems With StructuredText는 StructuredText와 관련하여 내린 여러 마크업 결정을 설명하고, A Record of reStructuredText Syntax Alternatives는 독자적으로 내린 마크업 결정을 기록합니다.

독스트링에서 중요한 기능

• 마크업 이스케이프 메커니즘.

  백슬래시(\)는 마크업 문자를 마크업이 아닌 용도로 써야 할 때 이를 이스케이프하는 데 사용합니다. 그러나 인라인 마크업 인식 규칙은 백슬래시 이스케이프가 필요한 경우를 최소화하도록 만들어졌습니다. 예를 들어 별표는 강조에 사용되지만, “*”나 “(*)”, “x * y”처럼 마크업이 아닌 맥락에서는 별표가 마크업으로 해석되지 않고 그대로 남습니다. 백슬래시를 마크업이 아닌 용도로 사용하는 여러 경우(예: 정규 표현식 설명)에는 인라인 리터럴이나 리터럴 블록을 사용할 수 있습니다. 다음 항목을 참조하십시오.

• Python 소스 코드와 Python 대화형 세션을 포함하기 위한 마크업: 인라인 리터럴, 리터럴 블록, doctest 블록.

  인라인 리터럴은 double-backquotes를 사용하여 프로그램 입출력이나 코드 조각을 나타냅니다. 인라인 리터럴 안에서는 어떤 마크업 해석(백슬래시 이스케이프 [\] 해석 포함)도 이루어지지 않습니다.

  리터럴 블록(코드 발췌나 ASCII 그래픽 같은 블록 수준 리터럴 텍스트)은 들여쓰기하며, 바로 앞 문단 끝에 이중 콜론(“::”)을 붙여 표시합니다(바로 여기 –>):

  if literal_block:
      text = 'is left as-is'
      spaces_and_linebreaks = 'are preserved'
      markup_processing = None
  

  Doctest 블록은 “>>> “로 시작하고 빈 줄로 끝납니다. 들여쓰기도, 리터럴 블록용 이중 콜론도 필요하지 않습니다. 예를 들면 다음과 같습니다:

  Here's a doctest block:
  
  >>> print 'Python-specific usage examples; begun with ">>>"'
  Python-specific usage examples; begun with ">>>"
  >>> print '(cut and pasted from interactive sessions)'
  (cut and pasted from interactive sessions)
  

• Python 식별자를 분리하는 마크업: 해석 텍스트(interpreted text).

  역따옴표 하나로 둘러싼 텍스트는 “해석 텍스트(interpreted text)”로 인식되며, 이를 어떻게 해석할지는 애플리케이션에 따라 다릅니다. Python 독스트링의 맥락에서 해석 텍스트는 기본적으로 Python 식별자로 해석됩니다. 이 텍스트에는 해당 식별자의 문서로 연결되는 하이퍼링크가 마크업됩니다. 조회 규칙은 Python 자체와 동일합니다. 즉, LGB 네임스페이스 조회(지역, 전역, 내장)를 따릅니다. 해석 텍스트의 “역할(role)”(클래스, 모듈, 함수 등 무엇을 가리키는지)은 네임스페이스 조회를 통해 암묵적으로 결정됩니다. 예를 들면 다음과 같습니다:

  class Keeper(Storer):
  
      """
      Keep data fresher longer.
  
      Extend `Storer`.  Class attribute `instances` keeps track
      of the number of `Keeper` objects instantiated.
      """
  
      instances = 0
      """How many `Keeper` objects are there?"""
  
      def __init__(self):
          """
          Extend `Storer.__init__()` to keep track of
          instances.  Keep count in `self.instances` and data
          in `self.data`.
          """
          Storer.__init__(self)
          self.instances += 1
  
          self.data = []
          """Store data in a list, most recent last."""
  
      def storedata(self, data):
          """
          Extend `Storer.storedata()`; append new `data` to a
          list (in `self.data`).
          """
          self.data = data
  

  각 해석 텍스트는 해당 독스트링을 포함하는 블록의 지역 네임스페이스에 따라 조회됩니다.

• Python 식별자를 분리하고 그 타입을 지정하는 마크업: 역할(role)이 있는 해석 텍스트.

  Python 소스 맥락 리더는 명시적인 역할이 필요하지 않도록 설계되었지만, 역할을 사용할 수도 있습니다. 식별자를 명시적으로 분류하려면 식별자와 함께 역할을 접두사나 접미사 형태로 지정합니다:

  Use :method:`Keeper.storedata` to store the object's data in
  `Keeper.data`:instance_attribute:.
  

  역할에 대해 선택한 문법은 장황하지만, 그럴 수밖에 없습니다(더 나은 대안이 있다면 Doc-SIG에 올려 주십시오). 이 마크업은 명시적인 역할을 쓸 일이 거의 없도록 하려는 것이므로, 역할은 꼭 필요한 경우에만 최소한으로 사용해야 합니다.

• “태그 목록(tagged list)” 또는 “레이블 목록(label list)”을 위한 마크업: 필드 목록.

  필드 목록은 필드 이름에서 필드 본문으로의 매핑을 나타냅니다. 이들은 주로 “서지 필드 리스트”(작성자, 날짜, 버전과 같은 문서 메타데이터를 나타냄)나 지시어(directive)의 확장 속성(아래 참조)과 같은 확장 문법에 사용됩니다. 매개변수나 발생하는 예외 등을 식별하는 것처럼 방법론(독스트링 의미)을 구현하는 데 사용할 수도 있지만, 그러한 용도는 이 PEP의 범위를 벗어납니다.

  수정된 RFC 2822 문법을 사용하며, 필드 이름의 앞과 뒤 모두에 콜론을 둡니다. 필드 본문도 더 다양하게 쓸 수 있습니다. 필드 본문 안에 여러 필드 본문(중첩된 필드 목록까지)이 들어갈 수 있습니다. 예를 들면 다음과 같습니다:

  :Date: 2002-03-22
  :Version: 1
  :Authors:
      - Me
      - Myself
      - I
  

  표준 RFC 2822 헤더 문법은 모호하기 때문에 이 구성에 사용할 수 없습니다. 줄 맨 앞에 단어와 콜론이 오는 형태는 일반 글에서 흔히 나타납니다.

• 마크업 확장성: 지시자와 치환.

  지시어는 reStructuredText의 확장 메커니즘으로 사용되며, 새로운 문법을 추가하지 않고도 새로운 블록 수준 구성에 대한 지원을 추가하는 방법입니다. 이미지, 권고문(note, caution 등), 목차 생성 등을 위한 지시자가 구현되어 있습니다. 예를 들어, 이미지는 다음과 같이 배치합니다:

  .. image:: mylogo.png
  

  치환 정의를 사용하면 블록 수준 지시자의 강력함과 유연성을 인라인 텍스트에서도 활용할 수 있습니다. 예를 들면 다음과 같습니다:

  The |biohazard| symbol must be used on containers used to
  dispose of medical waste.
  
  .. |biohazard| image:: biohazard.png
  

• 섹션 구조 마크업.

  reStructuredText의 섹션 헤더는 들여쓰기 대신 밑줄(경우에 따라 윗줄도 함께)로 장식하는 방식을 사용합니다. 예를 들면 다음과 같습니다.:

  This is a Section Title
  =======================
  
  This is a Subsection Title
  --------------------------
  
  This paragraph is in the subsection.
  
  This is Another Section Title
  =============================
  
  This paragraph is in the second section.
  

질문과 답변

1. reStructuredText는 충분히 풍부합니까?

   네, 대부분의 사람에게는 충분합니다. 특정 애플리케이션에 필요한 구문 요소가 없다면 지시자(directive) 메커니즘을 통해 추가할 수 있습니다. 유용하고 흔히 쓰이는 구문 요소가 누락되었고 적절히 읽기 쉬운 문법을 찾을 수 있다면, 명세와 파서에 추가할 수 있습니다.

2. reStructuredText는 지나치게 풍부합니까?

   특정 애플리케이션이나 개인에게는 그럴 수도 있습니다. 일반적으로는 그렇지 않습니다.

   맨 처음부터 Doc-SIG에서 독스트링 마크업 문법이 제안될 때마다, 누군가는 이런저런 구문 요소가 지원되지 않는다고 불평했습니다. 그에 대한 답변은 흔히 “우리가 이야기하는 것은 독스트링이며, 독스트링에는 복잡한 마크업이 있어서는 안 됩니다.”와 같은 식이었습니다. 문제는 어떤 사람에게 불필요해 보이는 구문 요소가 다른 사람에게는 절대적으로 필수적일 수 있다는 점입니다.

   reStructuredText는 정반대의 접근 방식을 취합니다. 풍부한 암시적 마크업 구문 요소 집합(그리고 명시적 마크업을 위한 범용 확장 메커니즘)을 제공하여 모든 종류의 문서를 작성할 수 있게 합니다. 특정 애플리케이션에 비해 구문 요소 집합이 지나치게 풍부하다면, 사용하지 않는 구문 요소를 (애플리케이션별 재정의를 통해) 파서에서 제거하거나 단순히 관례에 따라 생략할 수 있습니다.

3. StructuredText처럼 섹션 구조에 들여쓰기를 사용하지 않는 이유는 무엇입니까? 그편이 더 “파이썬답지” 않습니까?

   Guido van Rossum은 2001-06-13 Doc-SIG 게시물에서 다음과 같이 썼습니다:

   저는 여전히 섹션 구분을 나타내는 데 들여쓰기를 사용하는 것이 잘못되었다고 생각합니다. 실제 책과 기타 인쇄 출판물의 레이아웃을 살펴보면, 들여쓰기가 자주 사용되기는 하지만 대부분 섹션 내부 수준에서 사용된다는 것을 알 수 있습니다. 들여쓰기는 목록, 표, 인용문, 예제 등을 본문과 구분하는 데 쓸 수 있습니다. (독스트링은 텍스트 포매터에 입력으로 넘기는 인자이므로 다르다는 주장은 틀렸습니다. 요점은 독스트링을 따로 처리하지 않아도 읽을 수 있어야 한다는 것입니다.)

   저는 들여쓰기를 사용하는 것이 Pythonic하다는 주장(인자)을 받아들이지 않습니다. 텍스트는 코드가 아니며, 텍스트에는 다른 전통과 관례가 적용됩니다. 사람들은 30세기가 넘는 기간 동안 읽기 쉽게 텍스트를 표현해 왔습니다. 불필요하게 혁신하지 맙시다.

   더 자세한 설명은 Problems With StructuredText의 Section Structure via Indentation을 참조하십시오.

4. PEP에 reStructuredText를 사용하는 이유는 무엇입니까? 기존 표준에는 어떤 문제가 있습니까?

   PEP의 기존 표준은 전반적인 표현력 측면에서 매우 제한적이며, 특히 이처럼 참조가 많은 문서 유형인데도 참조 기능이 크게 부족합니다. 현재 PEP는 HTML로 변환되지만, 그 결과물(대부분 고정폭 텍스트)은 그다지 보기 좋지 않으며, HTML이 제공할 수 있는 부가 가치(특히 인라인 하이퍼링크)의 대부분이 활용되지 않고 있습니다.

   reStructuredText를 PEP의 표준 마크업으로 채택하면 섹션 구조, 인라인 마크업, 그래픽, 표 지원을 포함해 훨씬 더 풍부하게 표현할 수 있습니다. 여러 PEP에 ASCII 그래픽 다이어그램이 들어 있는데, 일반 텍스트 문서가 지원할 수 있는 것은 이것뿐입니다. PEP는 HTML 형식으로 제공되므로, 제대로 된 다이어그램을 넣을 수 있다면 곧바로 유용할 것입니다.

   현재 PEP 관행에서는 본문에 “[1]” 형태의 참조 표시를 쓸 수 있으며, 각주/참조 자체는 문서 끝부분의 한 섹션에 나열됩니다. 현재는 참조 표시와 각주/참조 자체 사이에 하이퍼링크가 없습니다(pep2html.py에 이 기능을 추가할 수는 있지만, 현재 상태의 “마크업”은 모호하여 실수가 불가피할 것입니다). 참조가 많은 PEP(이 PEP처럼 ;-)는 앞뒤로 자주 넘겨 보아야 합니다. PEP를 수정할 때는 새 참조가 추가되거나 사용하지 않는 참조가 삭제되는 경우가 많습니다. 참조 번호를 다시 매기는 일은 번거롭습니다. 두 곳에서 작업해야 하고 연쇄적인 영향을 줄 수 있기 때문입니다(새 참조 1을 하나 끼워 넣으면 다른 모든 참조의 번호를 다시 매겨야 합니다. 새 참조를 항상 끝에 추가하는 것도 최선은 아닙니다). 참조가 서로 어긋나기 쉽습니다.

   PEP는 참조를 두 가지 목적, 즉 단순 URL 참조와 각주로 사용합니다. reStructuredText는 이 둘을 구분합니다. PEP에는 다음과 같은 참조가 있을 수 있습니다:

   Abstract
   
       This PEP proposes adding frungible doodads [1] to the core.
       It extends PEP 9876 [2] via the BCA [3] mechanism.
   
   ...
   
   References and Footnotes
   
       [1] http://www.example.org/
   
       [2] PEP 9876, Let's Hope We Never Get Here
           http://peps.python.org/pep-9876/
   
       [3] "Bogus Complexity Addition"
   

   참조 1은 단순 URL 참조입니다. 참조 2는 텍스트와 URL을 담은 각주입니다. 참조 3은 텍스트만 담은 각주입니다. reStructuredText로 다시 작성하면 이 PEP는 다음과 같은 모습이 될 수 있습니다:

   Abstract
   ========
   
   This PEP proposes adding `frungible doodads`_ to the core.  It
   extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
   
   ...
   
   References & Footnotes
   ======================
   
   .. _frungible doodads: http://www.example.org/
   
   .. [#pep9876] PEP 9876, Let's Hope We Never Get Here
   
   .. [#] "Bogus Complexity Addition"
   

   원한다면 URL과 각주를 참조 가까이에 정의할 수 있으므로, 소스 텍스트에서 읽기 쉬워지고 PEP를 수정하기도 쉬워집니다. “References and Footnotes”(참조 및 각주) 섹션은 문서 트리 변환으로 자동 생성할 수 있습니다. PEP 전체에 흩어진 각주를 모아 표준 헤더 아래에 표시하게 됩니다. URL 참조도 마찬가지로 (인용 형태로) 명시적으로 적어야 한다면, 또 다른 트리 변환을 사용할 수 있습니다.

   URL 참조에는 이름(“frungible doodads”)을 붙일 수 있으며, 추가 정의 없이 문서의 여러 곳에서 참조할 수 있습니다. HTML로 변환하면 참조는 인라인 하이퍼링크(HTML <a> 태그)로 바뀝니다. 두 각주는 번호가 자동으로 매겨지므로 항상 서로 어긋나지 않습니다. 첫 번째 각주에는 내부 참조 이름 “pep9876”도 들어 있어서, 소스 텍스트에서 참조와 각주 사이의 연결을 알아보기가 더 쉽습니다. 이름 붙은 각주는 일관된 번호를 유지하면서 여러 번 참조할 수 있습니다.

   “#pep9876” 각주는 인용 형태로 작성할 수도 있습니다:

   It extends PEP 9876 [PEP9876]_ ...
   
   .. [PEP9876] PEP 9876, Let's Hope We Never Get Here
   

   각주는 번호를 쓰는 반면, 인용은 참조에 텍스트를 씁니다.

5. 독스트링 제안과 PEP 제안을 분리해 두는 편이 더 낫지 않겠습니까?

   PEP 마크업이 필요 없다고 판단되면 PEP 마크업 제안은 제거될 수 있으며, 별도의 PEP로 만들 수도 있습니다. 채택되면 PEP 1 PEP 목적 및 지침과 PEP 9 샘플 PEP 템플릿이 갱신될 것입니다.

   Python에서 구조화된 일반 텍스트를 쓰는 모든 경우에 일관된 단일 마크업 표준을 채택하고, 이를 모두 한곳에서 제안하는 것이 자연스러워 보입니다.

6. 기존 pep2html.py 스크립트는 기존 PEP 형식을 HTML로 변환합니다. 새 형식의 PEP는 어떻게 HTML로 변환됩니까?

   reStructuredText 파싱이 통합된 새 버전의 pep2html.py가 완성되었습니다. Docutils 프로젝트는 “PEP Reader” 컴포넌트를 통해 PEP를 지원하며, 여기에는 현재 pep2html.py에 있는 모든 기능(PEP 및 RFC 참조 자동 인식, 이메일 마스킹 등)이 포함됩니다.

7. 기존 PEP를 reStructuredText로 변환하는 일은 누가 합니까?

   PEP 작성자나 자원봉사자가 원한다면 기존 PEP를 변환할 수 있지만, 반드시 그래야 하는 것은 아닙니다. reStructuredText 기반 PEP는 기존 PEP 표준과 공존하게 됩니다. 답변 6에서 언급한 pep2html.py는 기존 표준과 새 표준을 모두 처리합니다.

8. README와 기타 부속 파일에 reStructuredText를 사용하는 이유는 무엇입니까?

   위의 답변 4에서 PEP에 대해 제시한 근거는 README와 기타 부속 파일에도 마찬가지로 적용됩니다. 표준 마크업을 채택하면 이러한 파일을 상호 참조가 갖춰진 보기 좋은 HTML로 변환하여 python.org에 게시할 수 있습니다. 다른 프로젝트의 개발자들도 자신의 문서화에 이 기능을 활용할 수 있습니다.

9. 기존 마크업 관례와 겉보기에 비슷하다는 점이 문제를 일으켜, 사람들이 잘못된 마크업을 작성하게 되지(그리고 평문이 자연스러워 보이기 때문에 이를 알아차리지 못하게 되지) 않겠습니까? reStructuredText는 “약간 잘못된” 마크업에 대해 얼마나 관대합니까?

   한 프로그래밍 언어에서 다른 프로그래밍 언어로 옮겨 갈 때와 마찬가지로 약간의 시행착오는 있을 것입니다. 어떤 언어든 그렇듯이, 숙련도는 경험과 함께 늘어납니다. 다행히도 reStructuredText는 정말로 아주 작은 언어입니다.

   어떤 문법이든 그렇듯이, 문법 오류가 발생할 가능성이 있습니다. 사용자는 자신의 입력에 대해 처리 시스템을 실행하고 출력이 올바른지 확인할 것으로 예상됩니다.

   엄밀한 의미에서 reStructuredText 파서는 매우 엄격합니다(마땅히 그래야 합니다. “In the face of ambiguity, refuse the temptation to guess”는 컴퓨터 언어뿐 아니라 마크업 파싱에도 적용됩니다). 다음은 An Introduction to reStructuredText의 설계 목표 3입니다:

   모호하지 않을 것. 마크업 규칙은 해석의 여지가 있어서는 안 됩니다. 주어진 입력에 대해 가능한 출력(오류 출력 포함)은 단 하나뿐이어야 합니다.

   파서는 엄격하지만, 동시에 유용한 진단 출력(“시스템 메시지”)을 생성하여 도움을 주려고 합니다. 파서는 문제를 보고하면서 그 심각도 수준(낮은 것부터 높은 것 순으로: debug, info, warning, error, severe)을 함께 표시합니다. 사용자나 클라이언트 소프트웨어는 보고 임계값을 정할 수 있습니다. 낮은 수준의 문제는 무시하거나, 높은 수준의 문제가 발생하면 처리를 즉시 중단하게 할 수 있습니다. 문제는 파싱 중에 보고될 뿐만 아니라 출력에도 포함되며, 문제의 발생 위치와 이를 설명하는 시스템 메시지 사이에 양방향 링크가 걸리는 경우가 많습니다.

10. Python 표준 라이브러리 모듈의 독스트링은 reStructuredText로 변환됩니까?

    아닙니다. Python의 라이브러리 레퍼런스 문서는 소스와 별도로 관리됩니다. Python 표준 라이브러리의 독스트링은 라이브러리 레퍼런스 문서의 내용을 중복하려 해서는 안 됩니다. Python 표준 라이브러리의 독스트링에 대한 현재 정책은, 독스트링이 간결한 힌트에 그쳐야 하며 단순하고 마크업이 없어야 한다는 것입니다(다만 상당수는 임시방편적인 암묵적 마크업을 실제로 포함하고 있습니다).

11. 저는 모든 문자열을 유니코드로 작성하고 싶습니다. 문제가 생기는 부분이 있습니까?

    파서는 유니코드를 완전히 지원합니다. Docutils는 임의의 입력 및 출력 인코딩을 지원합니다.

12. 커뮤니티에 새로운 구조화 텍스트 설계가 필요한 이유는 무엇입니까?

    기존 구조화 텍스트 설계들은 위의 “근거”에서 제시한 이유로 인해 부족합니다. reStructuredText는 “읽기 쉬운 평문”이라는 매체의 한계 안에서 완전한 마크업 문법이 되는 것을 목표로 합니다.

13. 기존 문서화 방법론에는 어떤 문제가 있습니까?

    어떤 기존 방법론을 말하는 것입니까? Python 독스트링에는 JavaDoc과 같은 문서화 방법론은 고사하고 공식 표준 마크업 형식조차 없습니다. 방법론의 문제는 (이 PEP가 다루는) 문법보다 훨씬 더 높은 수준의 문제입니다. 이는 잠재적으로 훨씬 더 논란의 여지가 크고 해결하기 어려운 문제이므로, 이 논의에서는 의도적으로 제외합니다.

참고 문헌 및 각주

Copyright

This document has been placed in the public domain.

Acknowledgements

Some text is borrowed from PEP 216, Docstring Format, by Moshe Zadka.

Special thanks to all members past & present of the Python Doc-SIG.