▲

GN⁺: rST 선호 현상 Markdown에 비해

 (buttondown.email)
1P by neo 4달전 | favorite | 댓글 1개

왜 나는 rST를 선호하는가

나는 이 주장을 멈추지 않을 것임

  • 새로운 버전의 "Logic for Programmers" v0.2를 출판했음. 이 버전은 epub 지원, 제약 해결 및 형식 사양에 대한 내용을 포함하고 있음.
  • 두 번째 책 "Learn TLA+"도 Sphinx로 작성했음. Sphinx는 reStructured Text(rST)라는 독특한 마크업을 사용함.
  • rST는 markdown보다 학습 곡선이 가파름. 몇 권의 책을 markdown으로 작성한 후 더 나은 것이 필요하다고 느껴 rST로 전환했음.

rST가 더 나은 이유

  • markdown은 HTML의 경량 표현인 반면, rST는 추상 문서 트리의 중간 무게 표현임.
  • markdown에서 이미지를 만드는 방법: 
    ![alttext](example.jpg)
  • rST에서 이미지를 만드는 방법: 
    .. image:: example.jpg
   :alt: alttext
  • rST는 확장 가능함. 새로운 텍스트 객체를 추가할 수 있음.
  • Sphinx는 cross-referencing을 처리할 수 있음. 예를 들어, 한 문서에 foo 앵커를 넣고 다른 문서에 :ref:image <foo>``를 넣으면 Sphinx가 올바른 URL을 삽입함.
  • rST는 빌드 프로세스의 나머지 부분과 함께 변환 코드를 구성할 수 있음.

한 가지 사용 사례

  • "Logic for Programmers"는 수학 관련 책으로, 독자를 위한 연습문제가 필요함.
  • 연습문제와 해답을 문서에서 나란히 배치하고 싶지만, 독자를 위해 해답은 책의 뒷부분에 나타나야 함.
  • 이를 위해 자체 연습문제 확장을 작성했음. 
    .. in chapter.rst
.. exercise:: Fizzbuzz
   :name: ex-fizzbuzz
   An exercise
   .. solution:: ex-fizzbuzz
      A solution
.. in answers.rst
.. solutionlist::
  • HTML에서는 연습문제와 해답을 인라인으로 렌더링함.
  • epub과 latex에서는 변환을 통해 해답 노드를 solutionlist 아래로 이동시키고, 각 연습문제에 참조 노드를 첨부함.

"하지만 나는 문법이 싫음"

  • rST의 문법이 못생겼다는 의견이 많음.
  • 문법이 싫어서 좋은 도구를 사용하지 않는 것은 이해할 수 있음.
  • asciidoc, MyST, Typst, Pollen, pandoc-extended markdown 등 다른 문서 빌더도 있음.
  • markdown 기반 문서 생성기는 새로운 사용 사례를 지원하기 위해 자체 전처리 단계를 추가하는 경우가 많음.
  • markdown과 rST를 위한 LSP와 treesitter가 있지만, gitbook-markdown이나 md-markdown, leanpub-markdown을 위한 것은 없음.

다음 주 뉴스레터 없음

  • 홍콩에 있을 예정임.

2024-07-31 업데이트

  • "Logic for Programmers"에 대한 간단한 설명을 추가함.
  • 이 책은 형식 논리가 일상적인 소프트웨어 엔지니어링에서 어떻게 유용한지에 대한 내용을 다룸.
  • 기본적인 수학 개요와 여덟 가지 다른 응용 프로그램을 포함하고 있음.
  • 아직 알파 단계이지만 이미 20,000 단어 이상 작성되었고 많은 유용한 내용을 포함하고 있음.

GN⁺의 정리

  • rST는 markdown보다 더 강력한 문서 작성 도구임.
  • Sphinx와 함께 사용하면 문서 트리를 변환하고 확장할 수 있는 기능이 있음.
  • "Logic for Programmers"와 같은 책 작성에 유용함.
  • rST의 문법이 못생겼다는 의견이 많지만, 다른 대안도 존재함.
  • 형식 논리와 관련된 소프트웨어 엔지니어링에 관심이 있는 사람들에게 유용할 수 있음.
▲
neo 4달전  [-]
Hacker News 의견
  • Markdown의 가장 큰 장점은 읽기 쉽고 쓰기 쉬운 점임
  • Markdown은 책을 쓰기 위한 최적의 도구는 아닐 수 있지만, 빠르게 형식화된 텍스트를 작성하는 데 최적임
  • LaTeX를 사용하여 책을 쓸 것이며, Markdown은 메모 작성, 빠른 문서화 및 댓글 작성에 적합함
  • reStructuredText(reST)는 자체로는 다소 거칠지만, Sphinx와 결합하면 매우 훌륭함
    • Sphinx는 대규모, 전문적인 문서 사이트에 적합한 선택임
    • Sphinx는 사이트의 공통 요소를 쉽게 커스터마이징할 수 있게 함
    • 내부 링크가 항상 해결되도록 보장함
    • 확장 및 테마 API가 잘 정의되어 있음
    • PyPI에 다양한 확장 및 테마가 존재함
  • Markdown은 HTML의 경량 표현이며, reST는 추상 문서 트리의 중간 무게 표현임
  • Markdown은 이메일 메시지와 Usenet 게시물의 형식화 텍스트를 변환하기 위해 설계됨
  • reST 도구는 RST 파일을 자동으로 생성하는 기능이 부족함
  • Markdown은 간단한 작업을 빠르게 수행할 수 있게 해주며, 필요 시 원시 HTML을 삽입할 수 있음
  • MyST는 reStructuredText의 기능을 제공하면서 Markdown 구문을 사용할 수 있게 함
  • GitHub 프로젝트 페이지의 문서화는 복잡할 수 있으며, Sphinx와 Markdown을 함께 사용하는 것이 유용할 수 있음
  • 저자는 자신의 책을 조판하는 맥락에서 rST를 언급하고 있음
  • reST는 MarkDown의 경쟁자가 아니라, MarkDown보다 먼저 등장한 형식임
  • Markdown과 reST는 기본적으로 동일한 목표를 가지고 있음
  • Markdown과 reST는 둘 다 읽기 쉽고 빠르게 작성할 수 있음
  • Markdown은 역사적 이유로 더 널리 사용되게 되었음
  • Markdown은 커스텀 블록 타입을 정의하고 문서 트리를 변환할 수 있음
  • Jupyter Book은 Markdown을 사용하여 PDF와 같은 다른 타겟으로 렌더링할 수 있는 좋은 예임
답변달기