Markdown보다 rST를 선호하는 이유

 (buttondown.email)
1P by GN⁺ | ★ favorite | 댓글 1개
  • Sphinx의 reStructured Text(rST) 는 Markdown보다 배우기 어렵지만, 책처럼 규모가 큰 문서에서 구조와 출력 형식을 세밀하게 제어하기 쉬움
  • Markdown은 HTML을 가볍게 쓰는 표기에 가깝고, rST는 추상 문서 트리를 중심으로 지시자, 노드, 렌더러를 조합해 새 문서 객체를 추가할 수 있음
  • Sphinx는 렌더링 전에 doctree를 변환하므로 교차 참조, 출력 형식별 처리, 특정 빌드 단계의 변환 같은 작업을 문서 시스템 안에서 다룰 수 있음
  • Logic for Programmers에서는 연습문제와 해설을 원문 가까이에 작성한 뒤, EPUB와 LaTeX 출력에서 위치와 표시 방식을 바꾸는 커스텀 확장을 사용함
  • 단순 Markdown은 통일된 확장 문법과 렌더링 전 변환 지원이 부족해, 문서 생성기가 별도 전처리로 우회할수록 도구 지원과 확장성이 약해짐

rST를 선택한 이유

  • Logic for Programmers 새 버전은 Sphinx로 작성한 두 번째 책이며, 이전 작업인 새 Learn TLA+도 Sphinx를 사용함
  • Sphinx는 reStructured Text를 사용하고, rST는 Markdown보다 학습 곡선이 가파름
  • Markdown으로 여러 권의 책을 쓴 뒤 더 나은 도구가 필요해 rST로 전환함
  • rST 자체는 Sphinx와 독립적이지만, 실제로는 Sphinx 때문에 rST를 쓰는 경우가 많아 둘을 함께 다룸

Markdown과 rST의 구조 차이

  • 가장 큰 차이는 Markdown이 HTML 경량 표기에 가깝고, rST는 추상 문서 트리를 만드는 중간 규모 표기라는 점임
  • Markdown의 이미지 문법은 간단한 변환만으로 <img alt="alttext" src="example.jpg"/> 같은 HTML로 바뀔 수 있음
    • 최신 Markdown 엔진도 중간 표현으로 파싱하는 경우가 많지만, 기본 성격은 가벼운 HTML 표기에 가까움
  • rST의 이미지는 .. image:: 지시자로 표현됨
    • Sphinx는 등록된 지시자 핸들러를 찾아 ImageDirective.run을 실행함
    • 실행 결과는 alt 필드를 가진 image_node 같은 노드 객체가 됨
    • 전체 doctree 처리가 끝나면 HTML Writer가 image_node 렌더링 함수를 찾아 HTML 태그를 출력함
  • rST 방식은 구현과 문법이 더 복잡하고 Markdown보다 보일러플레이트가 많지만, 이미지도 다른 지시자와 같은 확장 메커니즘으로 다뤄짐

새 문서 객체를 추가하는 방식

  • rST/Sphinx에서는 새 텍스트 객체를 확장으로 추가할 수 있음
  • 예를 들어 <image> 대신 <figure>와 <figcaption>을 만들고 싶다면, 기본 Markdown에서는 HTML을 직접 삽입해야 함
  • Sphinx에서는 새 figure 지시자를 등록하는 방식으로 처리함
    • FigureDirective가 ImageDirective를 상속해 이미지 처리 대부분을 재사용할 수도 있음
  • 지시자 등록, 노드 생성, 빌더별 렌더러 등록이라는 패턴이 모든 확장에 동일하게 적용됨

렌더링 전 doctree 변환

  • Sphinx는 렌더링 전에 doctree 변환을 수행할 수 있음
  • 문서 간 교차 참조도 이 기능으로 처리됨
    • 한 문서에 foo 앵커가 있고 다른 문서에 :ref:\image <foo>``가 있으면, Sphinx가 후처리 단계에서 올바른 URL을 삽입함
  • 변환 코드는 빌드 과정 안의 일급 기능처럼 다뤄짐
    • HTML 출력일 때만 특정 변환을 적용할 수 있음
    • 특정 빌드 단계에서 변환을 실행할 수 있음
    • 실행하고 싶지 않은 내장 변환을 제거할 수도 있음
  • 모든 문서에 이런 강력함이 필요한 것은 아니며, Markdown은 가볍고 이식성이 좋아 널리 쓰임

연습문제와 해설 확장 사례

  • Logic for Programmers는 수학에 가까운 책이라 독자용 연습문제가 필요함
  • 작성할 때는 연습문제와 해설을 문서 안에서 가까이 두는 편이 쉽지만, 독자에게는 해설이 책 뒤쪽에 나타나야 함
  • 요구사항은 출력 형식마다 달랐음
    • 연습문제와 해설을 서로 링크해야 함
    • 인쇄 가능성을 고려해 PDF에는 페이지 참조도 필요함
    • LaTeX/PDF 출력과 EPUB 출력에서 렌더링 방식이 달라야 함
  • 이를 위해 exercise, solution, solutionlist를 처리하는 커스텀 Sphinx 확장을 작성함
  • HTML 디버깅 출력에서는 연습문제와 해설을 인라인으로 렌더링함
  • EPUB와 LaTeX 생성에서는 전체 doctree를 만든 뒤 변환을 실행함
    • 원래 위치에 있던 모든 solution_node를 solutionlist 아래로 이동함
    • 각 연습문제에는 새 해설 위치로 가는 참조 노드를 붙임
    • 각 해설에는 원래 연습문제로 돌아가는 참조 노드를 붙임
  • LaTeX 빌더는 연습문제와 해설을 answers environment로 감쌈
  • EPUB 빌더는 해설을 popup footnote로 렌더링함
  • 이 구조는 책의 무료 샘플을 만들 때도 도움이 됨
    • 무료 샘플 뒤쪽에는 전체 책의 해설이 아니라 샘플에 포함된 부분의 해설만 들어감

문법 취향과 대안

  • rST에 대한 가장 흔한 반대는 문법이 못생겼다는 점임
  • 도구가 보기 싫어서 쓰지 않는 것도 충분히 가능한 선택이며, Lisp를 받아들이기 어려운 이유도 같은 취향 문제로 볼 수 있음
  • 대안으로 asciidoc, MyST, Typst, Pollen, pandoc-extended markdown이 있음
  • 요지는 Sphinx/rST가 대규모 문서화에 예외적으로 좋다는 것이 아니라, 단순 Markdown이 대규모 문서화에 예외적으로 부적합하다는 점임

Markdown 기반 생성기의 한계

  • 단순 Markdown에는 통일된 확장 문법이나 렌더링 전 변환에 대한 네이티브 지원이 없음
  • 많은 Markdown 기반 문서 생성기는 새 사용 사례를 지원하려고 자체 전처리 단계를 덧붙임
  • 이런 방식은 대체로 동작하지만, Markdown 안에서 처리하는 것이 아니라 Markdown 주변에서 우회하는 구조가 됨
  • 그 결과 기능의 강력함에 한계가 생기고, 프로그래머용 도구가 그 변형을 잘 이해하기 어려움
    • Markdown과 rST용 LSP 및 treesitter는 있지만, gitbook-markdown, md-markdown, leanpub-markdown용으로 같은 수준의 도구를 기대하기 어려움
  • rST의 못생긴 문법은 오히려 구문 트리가 풍부하다는 장점으로 작용할 수 있음
    • 특정 todo 지시자의 본문만 바꾸는 treesitter 쿼리가 가능함
    • 이는 rST 구문 트리가 Markdown 구문 트리보다 더 풍부하기 때문에 가능함

Logic for Programmers 업데이트

  • Logic for Programmers는 형식 논리가 일상적인 소프트웨어 엔지니어링에 어떻게 유용한지 다루는 책임
  • 책은 기본적인 수학 개요로 시작해 속성 테스트, 데이터베이스 제약, 결정표 등 8가지 응용으로 이어짐
  • 아직 알파 단계지만 20,000단어 규모이며, 독자 피드백을 받고 있음

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • “보기만 해도 토할 것 같아서 좋은 도구를 안 쓸 거냐”라고 묻는다면, 그렇다고 답하겠음. Markdown의 가장 큰 장점은 읽기 쉽고, 두 번째 장점은 쓰기 쉽다는 데 있음
    파싱이 얼마나 쉬운지, 확장이 얼마나 쉬운지는 거의 중요하지 않음. 책 쓰기에 Markdown이 최선인지와 별개로, 문법을 잘 모르는 사람도 읽기 쉬운 방식으로 빠르게 서식 있는 글을 쓰는 용도에는 Markdown이 최고임. 책을 쓰려는 게 아니라 메모, 빠른 문서화, 댓글 작성이 필요할 뿐이고, 책을 쓴다면 RST보다 LaTeX를 먼저 쓰겠음

    • Markdown이 개발자들 사이에서 뜨기 시작했을 때는 꽤 우스운 선택처럼 보였음. 당시에도 일반 텍스트를 서식 문서로 바꾸는 더 나은 선택지가 많았는데, 개발자들이 Markdown 중심으로 CMS, 생산성 앱, 문서 관리 도구, 플러그인까지 만들고 있었음
      그런데 실제 앱에서 써보니 Markdown의 핵심은 그게 아니었음. 최소한의 서식만 제공해서 일반 텍스트 상태에서도 HTML로 렌더링된 상태만큼 자연스럽게 읽히는 것이 목적임. 지원하는 서식이 의도적으로 작아서 머릿속에 들어오고 도구막대 없이 쓸 수 있음. 댓글 입력창, 채팅, 커밋 메시지, 어쩌면 블로그 글에는 맞지만, 엔터프라이즈급 제품 문서 작성용으로는 맞지 않음. 요즘은 HTML로 렌더링되지 않을 곳에서도 Markdown을 쓰는데, 그 자체로 읽기 좋기 때문이고 HN도 지원했으면 함
    • Markdown으로 책을 써봤고 별문제 없었음. 기술 문서가 아니라 소설이긴 했지만, Markdown에 가끔 HTML을 섞는 정도로 해결 못 할 일은 없었음
      기술 문서도 꽤 많이 Markdown으로 만들었고, Pandoc 확장https://pandoc.org/MANUAL.html을 쓰면 복잡한 수식과 구문 강조 코드 블록을 포함해 필요한 서식을 거의 다 넣을 수 있음. 그 Markdown은 HTML, Word 문서, ePub, PDF 등으로 변환 가능함. Markdown이 아닌 다른 것을 꺼내 들려면 아주 설득력 있는 이유가 필요함
    • TeX 사용자를 기준으로 상위 10%쯤은 될 것 같지만, Markdown과 TeX 사이에 또 다른 조판 언어가 들어갈 공간이 크다고 보기는 어려움. Markdown은 쉽지만 제한적이고, TeX는 조금 어렵지만 사실상 무한히 유연함
      TeX에서 본 가장 큰 문제는 언어가 아니라 사람 문제임. 사람들이 형편없는 스타일의 스파게티 TeX를 자주 작성함. 하지만 “문서는 코드”라는 사고방식으로 쓰면 꽤 깔끔한 결과가 나옴. 두 번째로 큰 문제는 좋은 TeX → HTML 컴파일러가 없다는 점임
    • “책을 쓴다면 LaTeX를 쓰겠다”는 건 글을 쓰고 구조화하는 단계에서는 끔찍한 선택처럼 보임. 차라리 Markdown으로 작성해서 조판은 신경 쓰지 않고, 출판 단계에서만 LaTeX로 변환하겠음
      LaTeX에 능숙하지는 않지만 한 번 배우려 했을 때 곤충형 외계 문명의 언어를 배우는 느낌이었음. 전혀 직관적이지 않고, 남이 이미 해둔 것을 복사해 내 글만 끼워 넣는 방식이 아니면 새로 뭘 하기가 거의 불가능했음. 기억하기로는 일급 유니코드 지원도 없었음
    • Markdown이 “문법을 잘 모르는 사람도 읽기 쉬운 방식으로 빠르게 서식 있는 글을 쓰는 최고의 도구”라는 말에는 동의하기 어려움. 기본만 봐도 최고는 아님
      기울임꼴에 별표나 밑줄을 쓰는 것도 익숙함이 필요하고, /italic slashes/처럼 훨씬 직관적인 방식이 있음. 기본을 벗어나면 표나 메타데이터, 태그가 텍스트를 가려서 적절한 도구 없이는 쓰고 읽기도 쉽지 않음. 확장이 쉬우면 이런 기본 문제도 고칠 수 있으니 확장성도 관련 있음

  • 기술 문서 작성자로 약 12년 일했고, 커리어 초반에는 스타트업 문서를 Word에서 Sphinx로 옮겼음. 이후 Google의 독자 CMS/개발자 문서 플랫폼, Eleventy 기반 사이트, 최근 2년은 다시 Sphinx 기반 사이트인 pigweed.dev에서 일했음. readme.com 기반 스타트업 일도 했고 Docusaurus, Astro, Hugo도 조금 다뤄봄
    reStructuredText 단독은 거칠 수 있지만, Sphinx와 결합한 reST는 아주 좋음. Sphinx의 강점이 reST의 약점을 훨씬 넘어섬. 100쪽 이상, 기여자 10명 이상의 큰 전문 문서 사이트라면 장기적으로 Sphinx가 가장 책임 있는 선택이라고 꽤 강하게 봄. 예를 들어 Pigweed에서는 :bug:\59385981``만 쓰면 https://pwbug.dev/59385981 링크로 바뀌게 했고, 나중에 버그 링크를 대량 이전해야 해도 쉬움. 내부 링크도 항상 해석되는지 보장되고, 없는 곳을 링크하면 경고나 오류가 남. 이게 문서 사이트의 표준이 아닌 게 이상하다고 예전에 https://technicalwriting.dev/src/link-text-automation.html에 썼음. Sphinx는 확장과 테마 API도 잘 정의되어 있고 PyPI에 생태계가 꽤 큼. 요즘은 Sphinx를 문서 시스템의 잠자는 거인이라고 부르고 있으며, 조금만 힘을 모으면 훨씬 대단해질 수 있음

    • 이 부분이 정말 중요함. CMS나 정적 사이트 생성기 중에 글을 쓸 때 최종 URL을 직접 넣게 하는 시스템이 너무 많음
      슬러그가 바뀌거나 사이트 구조를 재편하면 전체 사이트에서 찾아 바꾸기를 해야 함. 정적 사이트 생성기는 [Hello](../hello.md)처럼 링크하게 하고 빌드 때 해석할 수 있는데도, 많이 쓰거나 살펴본 도구들은 [Hello](/why/hello/)를 직접 치게 함. 이 기능은 호불호가 갈리는 듯함. 정적 사이트 생성기 팀원에게 얘기해도 “그걸 왜 원하냐”는 답을 받았고, 설명해도 통하지 않았음. 문제를 겪어봐야 해결책의 가치를 아는 건지, 한 번 쓰고 10년 이상 유지보수하지 않는 데 익숙한 건지 모르겠지만 더 넓게 지원되면 좋겠음
    • Sphinx는 대단한데 심하게 저평가되어 있음. 아는 한 Sphinx는 구조적으로 탄탄하고 확장 가능하며 널리 쓰이는 유일한 문서 프레임워크임
      플러그인 생태계가 훌륭해서 팀과 프로젝트의 문서를 개선하는 데 엄청난 지렛대가 됨. reStructuredText 자체는 좋아하지 않지만, 요즘은 MyST-Parser 덕분에 예전에는 Sphinx가 RST에 강하게 묶여 있던 대부분의 일을 Markdown으로도 할 수 있음: https://github.com/executablebooks/MyST-Parser
    • 사이트 공통 요소를 커스터마이즈하는 건 Markdown+Pandoc으로도 매우 쉬웠음. YouTube 링크가 들어간 이미지 태그를 비디오 태그와 대체 텍스트가 있는 썸네일로 바꾸고, 로컬 비디오 파일 이미지 태그를 ffmpeg에 연결해 최적화·리사이즈하는 것도 몇 줄 코드로 처리했음
    • 이 댓글을 보기 전까지 Sphinx를 몰랐음. 개발 업무 사이드로 20년 넘게 기술 문서를 써왔고, 그동안은 TeX와 커스텀 XSL 쪽에 가까웠음
      내부 언어/VM/추상화 계층을 설명하는 200쪽 넘는 책을 Sphinx로 막 옮겼는데, 정말 인생을 바꾸는 시스템임. Sphinx 자체 문서가 진입 장벽이 낮거나 예제가 더 많았으면 하지만, 지금은 꽤 강한 신혼기 느낌임. 주된 관심사는 보기 좋은 PDF 책을 만드는 법과, 책을 장·절 단위로 POSIX 호환 man 페이지로 잘라내는 시스템임
    • Sphinx가 대중적으로 크게 성공하길 원한다면 1순위는 고품질의 아름다운 테마를 확보하는 것임
      사이트 생성기를 고를 때 미관은 꽤 중요한 요소임. Hugo와 Gatsby는 기본 테마가 훌륭하고, 실제로 그 이유만으로 프로젝트에 선택한 적도 있음. Sphinx 테마 모음 https://sphinx-themes.org/와 https://sphinxthemes.com/#featured-themes는 대체로 밋밋함. 표준 Sphinx RTD 테마 https://sphinx-rtd-theme.readthedocs.io/en/stable/를 Apple 문서 https://developer.apple.com/documentation/swift/array나 Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default와 비교하면 낡아 보임

  • “Markdown은 HTML의 경량 표현”이라는 문장이 이 글에서 가장 큰 문제라고 봄. 그건 확실히 부정확함
    Markdown은 1990년대 초 이메일과 Usenet 글에서 사실상 표준처럼 쓰이던 텍스트 서식 관습을 변환하기 위한 도구로 설계됐음. 7비트 ASCII라는 제약 때문에 강조나 제목 같은 서식을 특수 기호로 표시하게 됐고, HTML도 그 이름 없는 관습과 비슷한 점이 많았음. 그래서 John Gruber가 2004년에 그것을 HTML로 바꾸는 기본 스크립트 https://daringfireball.net/projects/markdown/를 썼지만, 이렇게 보편적인 실제 표준이 될 거라고 예상하지는 못했을 것임

    • 그 링크의 첫 문장이 바로 “Markdown is a text-to-HTML conversion tool for web writers.”임
      Gruber가 Usenet의 사실상 표준을 가져와 단순히 HTML 변환기를 만든 게 아니라, Usenet과 다른 관습에서 빌려와 자신만의 마크업을 설계했음. 링크 하단의 “Acknowledgements”도 그 사실을 보여줌. Markdown은 처음부터 웹 CMS용 마크업 문법으로 의도됐고, HTML의 경량 표현이라고 말하는 건 맞음. 문법의 모든 부분이 직접 대응되는 HTML을 만들도록 하는 게 핵심이었음
    • 동의하지 않음. Markdown은 항상 HTML과 관련되어 있었고, Markdown 파서가 실제 HTML 태그 혼합을 지원할 정도임
      이메일 관습에서 영감을 받았다는 사실이 “Markdown은 HTML의 경량 표현”이라는 말을 덜 맞게 만들지는 않음
    • 이런 식의 의미론 다툼은 그만했으면 함. 지루한 대화를 만들고 HN 가이드라인에도 어긋남
      상대가 한 말의 가장 그럴듯하고 강한 해석에 답하고, 비판하기 쉬운 약한 해석을 잡지 말라는 규칙이 있음. 글에서 가장 도발적인 문장만 골라 불평하지 말고 흥미로운 부분에 답하라는 규칙도 있음: https://news.ycombinator.com/newsguidelines.html
      글의 핵심에 동의하지 않는다면 rST보다 Markdown을 선호한다고 말하고 왜 그런지 설명하면 됨. Markdown이 정확히 무엇인지 한 문장만 두고 싸우는 건 어리석음
    • Markdown 자체는 이메일과 Usenet 서식과는 별개임. Markdown은 특정 문법이었고 정의가 좋지 않았으며, 이후 서로 대체로 비슷한 여러 문법 계열로 넓어졌음
      이메일이나 Usenet 같은 관습에서 영감을 받긴 했고, 그중 일부는 컴퓨터 이전에도 있었음. 예를 들어 오래된 타자 문서에서 별표를 기울임꼴처럼 쓴 사례도 본 것 같음. 하지만 Markdown은 HTML과 강하게 연결되어 있고, 문법도 HTML에 매우 제약되어 있으며, HTML과 분리하려는 시도는 대체로 실패할 수밖에 없음
    • 둘 다 맞음. 원래 구현은 HTML의 상위집합이었음. 흔한 것은 가벼운 문법으로 쓰고, 나머지는 HTML로 쓰는 방식임

  • Markdown의 핵심은 원시 HTML보다 간단한 일을 더 빠르게 하되, 필요하면 원시 HTML을 섞을 수 있게 하는 데 있다고 봄
    Markdown보다 RST의 힘이 필요했던 프로젝트에서는 차라리 HTML을 직접 쓰는 편이 더 편했음

    • 저자처럼 “Sphinx를 확장해 새 텍스트 객체를 만들 수 있다. 기본 Markdown에서는 HTML을 직접 넣어야 한다”고 쓰면, 그런 기능이 필요할 때 그냥 HTML을 쓰면 뭐가 문제인지 궁금해짐. 왜 층을 하나 더 두는지 모르겠음

  • 비슷한 복잡도의 문서 시스템을 만들면서, RST 파일의 구조를 데이터베이스에 저장하고 데이터베이스 결과를 콘텐츠와 섞는 식으로 명확한 의미를 가진 마크업이 절실해서 RST를 검토했음
    부딪힌 문제는 두 가지였음. 첫째, RST 도구에는 RST를 다시 출력하는 언파서가 없음. 여러 RST 파일과 다른 소스를 병합해 RST 파일을 자동 생성하고 문서 API로 다루고 싶었지만 지원하지 않았음. 둘째, RST 도구는 특정 문서에 대해 정의된 블록 집합을 기대함. 블록을 일반적으로 표현하면 내부 블록 정의를 몰라도 문서를 변환하는 도구가 가능할 텐데 그렇지 않았음. 이는 RST 자체보다 도구 문제지만, 코드를 밑바닥까지 걷어내야 할 때마다 HTML 기반 같은 다른 마크업 시스템을 생각하게 됨

    • HTML 대신 XML로 구조화 문서를 쓸 수 있음. XML은 필요한 커스텀 태그를 정의할 수 있고 원하면 스키마 검증도 가능함
      이 방식의 장점은 입력 스키마와 출력을 완전히 통제할 수 있다는 점이고, 단점은 Markdown이나 RST보다 문법 소음이 훨씬 크며 원하는 출력 형식으로 파싱·변환하는 스크립트가 필요하다는 점임
    • Python에서 rST는 docutils가 지원하는 여러 입력 형식 중 하나일 뿐임: https://docutils.sourceforge.io/README.html#purpose
      docutils의 전체 목적은 형식을 파싱하고 API로 변환하는 것임: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
    • rST와 AsciiDoc은 기능 면에서 대략 비슷해 보임. 약점과 빠진 기능도 대략 비슷한지 궁금함
    • rST의 주요 도구인 docutils에 커미터였음. 도구를 Markdown으로 옮긴 이유 중 하나는 docutils를 다루기가 너무 고통스러웠기 때문임. GitHub 같은 곳으로 옮기기를 거부하는 것만 봐도 함께 일하기 얼마나 불친절한지 드러남
    • 지금 컴퓨터가 없어 테스트는 못 하지만, include 지시어로 원하는 걸 할 수 있지 않나 싶음

  • 몇 년 전 외워둘 만한 reStructuredText 부분집합을 정리한 적이 있음: https://simonwillison.net/2018/Aug/25/restructuredtext/
    최근 프로젝트에서는 MyST를 쓰기 시작했는데, reStructuredText에서 중요하게 여긴 참조와 목차 기능을 제공하면서도 기여자가 쓰기 쉬운 Markdown 문법을 쓸 수 있음

    • 링크, 특히 외부 링크에 대한 장점이 큼. 문서 사이트에서는 같은 외부 링크를 여러 곳에서 참조할 수 있고, 바뀌면 한 번만 갱신하고 싶기 때문임
      진짜 판도를 바꾸는 건 내부 링크에서의 rST+Sphinx와 :ref:, :doc: 지시어임. 같은 콘텐츠 안에서 앵커나 문서 링크를 참조할 때 헤더를 직접 입력하지 않아도 되고, 직접 입력한 헤더가 결국 낡아버리는 일을 피할 수 있음: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
      rST로 글 쓸 때 가장 그리운 기능 중 하나임

  • ReStructuredText 대화를 가로채려는 건 아니지만, Markdown보다 더 많은 것을 주는 마크업 언어를 찾는다면 ReStructuredText보다 AsciiDoc을 보라고 권하고 싶음. 세 가지 모두로 수년간 기술 문서를 써봤고, AsciiDoc이 ReStructuredText와 Markdown보다 낫다고 봄
    예를 들어 Markdown과 ReStructuredText의 표 지원은 아주 번거로움. AsciiDoc 표 서식은 읽고 쓰고 유지보수하기 쉽고, 헤더, 캡션, 표·행의 사용자 지정 크기, 표 안의 복잡한 서식까지 지원해 더 강력함. Markdown처럼 여러 방언이 없는 단일 표준 형식이고, 문법이 간결하고 읽기 쉬우며, ReStructuredText보다 학습 곡선이 완만함. 출력 스타일링 선택지도 더 좋고, 도구 체인도 우수하며, 내장 문서 기능이 풍부해서 서드파티 플러그인에 의존할 일이 적음. AsciiDoc은 처음부터 기술 문서용으로 설계됐고, 다른 둘은 그 역할에 끼워 맞춰진 쪽임

  • 5~10쪽 정도의 Markdown 문서를 예쁘게 구성하고, 그 자체는 더 동적인 Jinja 템플릿에서 렌더링되게 해두면 꽤 만족스럽게 시작됨. 자동 문서를 위한 빌드 프로세스도 있고, 단일 GitHub README로는 너무 큰 정도임. 그런데 그때부터 고통이 시작됨
    GitHub 프로젝트 페이지 문서는 잘 안 맞고, .nojekyl 파일이 필요한지, gh-pages 브랜치가 아직 필요한지 헷갈림. 저장소 설정 오류인지 변경사항이 반영 안 된 건지 모르겠고, GitHub Actions를 시도하다 몇 시간이 지나면 비합리적이 됨. Read the Docs를 다시 보니 Sphinx를 원하는 것 같아 Markdown과 Sphinx를 붙이고, 빌드는 되지만 배포 후 페이지 폭이 깨지는데 로컬에서는 재현이 안 되니 커뮤니티 티어 광고 삽입 탓인 듯함. 많은 프로젝트에서 잘 돌아가고 직접 해본 적도 있지만, 돌아가기 전까지는 믿을 수 없을 만큼 자잘하게 까다로움. 결국 Markdown 대 RST는 관심사도 아니고, 중간 규모 문서 프로젝트와 정적 호스팅에 잘 맞는 조합을 찾는 게 핵심임

    • mdBook을 살펴봤는지 궁금함. 직접 써보지는 않았지만, mdBook을 쓰는 여러 프로젝트의 문서를 좋게 봤고 단일 README 파일을 넘어서는 시점에는 꽤 괜찮아 보임
      자동 배포 안내도 잘 되어 있음: https://github.com/rust-lang/mdBook

  • 저자가 자기 책 조판이라는 맥락에서 말하고 있다는 점을 놓치는 듯함. 일반적으로 rST가 Markdown보다 낫다고 주장하는 게 아님
    일반적인 경우 Markdown의 단순함이 널리 쓰이는 이유이지만, 저자가 말하는 대상은 그게 아님

  • reST가 Markdown의 경쟁자로 만들어진 것처럼 반응하는 게 재미있음. 사실은 반대에 가까움. reST는 2002년 StructuredText의 발전형이고, Markdown은 2004년에 처음 공개됐음
    둘의 목표는 매우 비슷하고, 가장 기본적인 텍스트에서는 둘 다 일반 텍스트처럼 읽고 쓸 수 있음. 그 시기에 모두가 이런 것을 원하게 되면서 여러 형식이 등장했던 것임. Markdown이 이긴 이유는 “더 단순하다”거나 “더 읽기 쉽다”는 점과는 별 관련이 없다고 봄. 순수 ASCII와 공백으로 쉽게 표현되는 내용에서는 대체로 서로 바꿔 쓸 수 있음. 예시의 reST 문서가 파서 없이는 읽을 수 없는 난해한 글이라고 할 사람이 있을까? Markdown 변형이 이보다 어떤 면에서 더 낫다는 건 잘 모르겠고, 역사적 우연에 가깝게 하나가 우세해졌을 뿐 둘 다 핵심 목표에는 충분히 좋음

    • 아주 단순한 예시를 들었기 때문에 Markdown과 reST 둘 다 쉽게 처리할 수 있음
      reST는 필요한 경우 유익한 추가 서식 기능을 많이 제공하지만, 필요 없을 때는 군더더기임. GitHub에 가입한 2010년쯤 GitHub-flavored Markdown을 쓰기 시작했고, Python 문서 때문에 reStructuredText도 몇 번 썼음. 후자는 학습 곡선이 훨씬 높았고 그 뒤로 쓸 이유가 없었음
    • 읽을 수 없냐고 하면 아니지만, 입력하기 답답하냐고 하면 그렇다. 밑줄식 제목은 편집할 때 성가시고, 길이를 꼭 맞출 필요가 없어도 맞춰야 할 것 같은 압박이 생김
      이중 백틱도 실제로 드는 시간에 비해 과하게 짜증 나는 문법임
답변달기