Por que prefiro rST ao Markdown

• O reStructured Text (rST) do Sphinx é mais difícil de aprender do que Markdown, mas facilita o controle detalhado da estrutura e do formato de saída em documentos grandes, como livros
• Markdown se aproxima mais de uma notação leve para HTML, enquanto rST gira em torno de uma árvore abstrata de documentos, permitindo combinar diretivas, nós e renderizadores para adicionar novos objetos ao documento
• O Sphinx transforma a doctree antes da renderização, então tarefas como referências cruzadas, tratamento por formato de saída e transformações em etapas específicas do build podem ser tratadas dentro do próprio sistema de documentação
• Em Logic for Programmers, exercícios e soluções são escritos próximos no texto-fonte, e uma extensão personalizada altera sua posição e forma de exibição nas saídas EPUB e LaTeX
• O Markdown simples carece de uma sintaxe de extensão unificada e de suporte a transformações antes da renderização; quanto mais um gerador de documentação contorna isso com pré-processamento separado, mais fracos tendem a ficar o suporte das ferramentas e a extensibilidade

---

Por que escolhi rST

• A nova versão de Logic for Programmers é o segundo livro escrito com Sphinx; o trabalho anterior, o novo Learn TLA+, também usa Sphinx
• O Sphinx usa reStructured Text, e o rST tem uma curva de aprendizado mais íngreme que Markdown
• Depois de escrever vários livros em Markdown, surgiu a necessidade de ferramentas melhores, o que motivou a migração para rST
• O rST em si é independente do Sphinx, mas na prática muita gente usa rST por causa do Sphinx, então os dois são tratados em conjunto

Diferença estrutural entre Markdown e rST

• A maior diferença é que Markdown se aproxima de uma notação leve para HTML, enquanto rST é uma notação de porte intermediário voltada para criar uma árvore abstrata de documentos
• A sintaxe de imagem em Markdown pode ser convertida com facilidade para HTML como <img alt="alttext" src="example.jpg"/>
  • Motores modernos de Markdown também costumam fazer parsing para uma representação intermediária, mas sua natureza básica continua mais próxima de uma notação leve para HTML
• Em rST, imagens são representadas com a diretiva .. image::
  • O Sphinx procura o handler de diretiva registrado e executa ImageDirective.run
  • O resultado da execução é um objeto de nó, como image_node, com campo alt
  • Quando o processamento completo da doctree termina, o HTML Writer procura a função de renderização de image_node e gera a tag HTML
• A abordagem do rST é mais complexa em implementação e sintaxe, e tem mais boilerplate que Markdown, mas imagens são tratadas pelo mesmo mecanismo de extensão usado para outras diretivas

Como adicionar novos objetos de documento

• Em rST/Sphinx, é possível adicionar novos objetos de texto por meio de extensões
• Por exemplo, se você quiser gerar <figure> e <figcaption> em vez de apenas <image>, no Markdown básico seria preciso inserir HTML manualmente
• No Sphinx, isso é feito registrando uma nova diretiva figure
  • FigureDirective pode até herdar de ImageDirective para reutilizar a maior parte do processamento de imagem
• O padrão de registrar diretivas, criar nós e registrar renderizadores por builder se aplica da mesma forma a todas as extensões

Transformações de doctree antes da renderização

• O Sphinx pode executar transformações de doctree antes da renderização
• Referências cruzadas entre documentos também são tratadas por esse recurso
  • Se um documento tiver a âncora foo e outro tiver :ref:\image <foo>``, o Sphinx insere a URL correta na etapa de pós-processamento
• O código de transformação é tratado como um recurso de primeira classe dentro do processo de build
  • É possível aplicar uma transformação específica apenas na saída HTML
  • É possível executar a transformação em uma etapa específica do build
  • Também é possível remover transformações internas que você não queira executar
• Nem todo documento precisa desse nível de poder; Markdown continua amplamente usado por ser leve e portável

Caso de extensão para exercícios e soluções

• Logic for Programmers é um livro mais próximo da matemática, então precisa de exercícios para o leitor
• Ao escrever, é mais fácil manter exercícios e soluções próximos dentro do documento, mas para o leitor as soluções devem aparecer no fim do livro
• Os requisitos variavam conforme o formato de saída
  • Exercícios e soluções precisavam ser ligados entre si
  • Considerando a possibilidade de impressão, o PDF também precisava de referências de página
  • A forma de renderização precisava ser diferente entre as saídas LaTeX/PDF e EPUB
• Para isso, foi criada uma extensão personalizada do Sphinx para tratar exercise, solution e solutionlist
• Na saída HTML de depuração, exercícios e soluções são renderizados inline
• Na geração de EPUB e LaTeX, a transformação é executada depois que a doctree completa é criada
  • Todos os solution_node da posição original são movidos para baixo de solutionlist
  • Em cada exercício, é anexado um nó de referência para a nova localização da solução
  • Em cada solução, é anexado um nó de referência de volta para o exercício original
• O builder de LaTeX envolve exercícios e soluções no answers environment
• O builder de EPUB renderiza soluções como popup footnote
• Essa estrutura também ajuda na criação de amostras grátis do livro
  • No fim da amostra grátis, entram apenas as soluções da parte incluída na amostra, não as soluções do livro inteiro

Preferência de sintaxe e alternativas

• A objeção mais comum ao rST é que sua sintaxe é feia
• Não usar uma ferramenta por achar sua aparência desagradável é uma escolha perfeitamente válida; a dificuldade de aceitar Lisp também pode ser vista como uma questão semelhante de gosto
• Como alternativas, existem asciidoc, MyST, Typst, Pollen, pandoc-extended markdown
• A ideia principal não é que Sphinx/rST seja excepcionalmente bom para documentação em larga escala, e sim que o Markdown simples é excepcionalmente inadequado para documentação em larga escala

Limitações dos geradores baseados em Markdown

• O Markdown simples não tem uma sintaxe de extensão unificada nem suporte nativo a transformações antes da renderização
• Muitos geradores de documentação baseados em Markdown adicionam sua própria etapa de pré-processamento para dar suporte a novos casos de uso
• Esse método geralmente funciona, mas acaba contornando o Markdown em vez de tratar o problema dentro dele
• Como resultado, surgem limites no poder dos recursos, e ferramentas para programadores têm mais dificuldade para entender essas variações
  • Existem LSP e treesitter para Markdown e rST, mas é difícil esperar o mesmo nível de ferramenta para gitbook-markdown, md-markdown ou leanpub-markdown
• A sintaxe feia do rST pode até virar uma vantagem, por oferecer uma árvore sintática mais rica
  • É possível fazer uma query de treesitter que altere apenas o corpo de uma diretiva todo específica
  • Isso é possível porque a árvore sintática do rST é mais rica do que a do Markdown

Atualização de Logic for Programmers

• Logic for Programmers é um livro sobre como a lógica formal pode ser útil na engenharia de software do dia a dia
• O livro começa com uma visão geral básica de matemática e segue para 8 aplicações, incluindo testes baseados em propriedades, restrições de banco de dados e tabelas de decisão
• Ainda está em fase alfa, mas já tem cerca de 20.000 palavras e está recebendo feedback de leitores

[GN⁺]

Opiniões no Hacker News

• Se me perguntarem “você deixaria de usar uma boa ferramenta só porque ela parece tão feia que dá vontade de vomitar?”, eu responderia que sim. A maior vantagem do Markdown é ser fácil de ler, e a segunda é ser fácil de escrever.
  O quão fácil é fazer parsing ou estender quase não importa. Independentemente de Markdown ser ou não a melhor opção para escrever livros, ele é imbatível para escrever rapidamente textos formatados de um jeito fácil de ler até para quem não conhece bem a sintaxe. Não quero escrever um livro; só preciso fazer anotações, documentação rápida e comentários. E, se fosse escrever um livro, eu usaria LaTeX antes de RST.

  • Quando Markdown começou a ganhar força entre desenvolvedores, parecia uma escolha bastante ridícula. Mesmo naquela época havia muitas opções melhores para transformar texto puro em documentos formatados, mas os desenvolvedores estavam criando CMSs, apps de produtividade, ferramentas de gerenciamento de documentação e plugins centrados em Markdown.
    Mas, ao usá-lo em apps reais, percebi que o ponto central do Markdown não era esse. O objetivo é oferecer apenas formatação mínima, para que, mesmo em texto puro, ele seja lido de forma tão natural quanto quando renderizado em HTML. O conjunto de formatações suportadas é propositalmente pequeno, cabe na cabeça e pode ser usado sem barra de ferramentas. Ele serve para caixas de comentário, chats, mensagens de commit e talvez posts de blog, mas não para escrever documentação de produto em nível corporativo. Hoje em dia, usa-se Markdown até em lugares onde ele não será renderizado em HTML, justamente porque ele é agradável de ler por si só; eu gostaria que o HN também o suportasse.
  • Já escrevi um livro em Markdown e não tive grandes problemas. Era ficção, não documentação técnica, mas não houve nada que não pudesse ser resolvido misturando um pouco de HTML ao Markdown de vez em quando.
    Também produzi bastante documentação técnica em Markdown, e usando extensões do Pandochttps://pandoc.org/MANUAL.html dá para incluir praticamente toda a formatação necessária, incluindo fórmulas complexas e blocos de código com realce de sintaxe. Esse Markdown pode ser convertido para HTML, documentos Word, ePub, PDF etc. Seria preciso um motivo muito convincente para eu recorrer a algo que não fosse Markdown.
  • Acho que estou por volta dos 10% mais experientes entre usuários de TeX, mas não vejo muito espaço para outra linguagem de composição entre Markdown e TeX. Markdown é fácil, mas limitado, e TeX é um pouco difícil, mas praticamente infinitamente flexível.
    O maior problema que vejo no TeX não é a linguagem, e sim as pessoas. Elas frequentemente escrevem TeX espaguete em péssimo estilo. Mas, se for usado com a mentalidade de que “documentos são código”, o resultado pode ficar bastante limpo. O segundo maior problema é a falta de um bom compilador de TeX para HTML.
  • Dizer “se eu fosse escrever um livro, usaria LaTeX” parece uma escolha terrível para a etapa de escrever e estruturar o texto. Eu preferiria escrever em Markdown sem me preocupar com a composição, e converter para LaTeX apenas na etapa de publicação.
    Não sou especialista em LaTeX, mas, quando tentei aprendê-lo, tive a sensação de estar aprendendo a língua de uma civilização alienígena insectoide. Não era nada intuitivo, e era quase impossível fazer algo novo sem copiar algo que outra pessoa já tinha feito e apenas encaixar meu texto. Pelo que me lembro, ele também não tinha suporte de primeira classe a Unicode.
  • É difícil concordar com a afirmação de que Markdown é “a melhor ferramenta para escrever rapidamente textos formatados de um jeito fácil de ler até para quem não conhece bem a sintaxe”. Mesmo no básico, ele não é o melhor.
    Usar asteriscos ou underscores para itálico também exige familiaridade, e existem formas muito mais intuitivas, como /barras para itálico/. Quando se sai do básico, tabelas, metadados e tags obscurecem o texto, tornando-o difícil de escrever e ler sem ferramentas adequadas. Se fosse fácil estendê-lo, esses problemas básicos também poderiam ser corrigidos, então extensibilidade também é relevante.

• Trabalhei como redator técnico por cerca de 12 anos e, no início da carreira, migrei a documentação de uma startup do Word para o Sphinx. Depois trabalhei na plataforma própria de CMS/documentação para desenvolvedores do Google, em um site baseado em Eleventy e, nos últimos 2 anos, novamente em um site baseado em Sphinx, o pigweed.dev. Também trabalhei em uma startup baseada no readme.com e mexi um pouco com Docusaurus, Astro e Hugo
  reStructuredText sozinho pode ser áspero, mas reST combinado com Sphinx é muito bom. Os pontos fortes do Sphinx superam em muito as fraquezas do reST. Para um site grande de documentação profissional, com mais de 100 páginas e mais de 10 colaboradores, acredito com bastante convicção que, no longo prazo, o Sphinx é a escolha mais responsável. Por exemplo, no Pigweed, bastava escrever :bug:\59385981`` para isso virar um link para https://pwbug.dev/59385981, e mesmo que depois fosse preciso migrar links de bugs em massa, seria fácil. Links internos também têm a garantia de sempre serem resolvidos, e, se você criar um link para algo inexistente, aparece um aviso ou erro. Já escrevi em https://technicalwriting.dev/src/link-text-automation.html que acho estranho isso não ser o padrão em sites de documentação. O Sphinx também tem APIs de extensões e temas bem definidas, e há um ecossistema considerável no PyPI. Hoje em dia chamo o Sphinx de gigante adormecido dos sistemas de documentação; com um pouco de esforço conjunto, ele poderia se tornar muito mais impressionante

  • Esta parte é realmente importante. Há muitos CMSs e geradores de sites estáticos que obrigam você a inserir a URL final diretamente ao escrever
    Se o slug mudar ou a estrutura do site for reorganizada, é preciso fazer busca e substituição no site inteiro. Geradores de sites estáticos poderiam permitir links como [Hello](../hello.md) e resolvê-los no build, mas muitas das ferramentas que usei ou avaliei fazem você digitar [Hello](/why/hello/) diretamente. Parece ser um recurso que divide opiniões. Quando falei disso com alguém da equipe de um gerador de sites estáticos, recebi a resposta “por que você iria querer isso?”, e mesmo explicando não consegui convencer. Não sei se é preciso sofrer o problema para entender o valor da solução, ou se as pessoas estão acostumadas a escrever algo uma vez e não mantê-lo por mais de 10 anos, mas eu gostaria que isso tivesse suporte mais amplo
  • O Sphinx é excelente, mas muito subestimado. Pelo que sei, o Sphinx é o único framework de documentação estruturalmente sólido, extensível e amplamente usado
    O ecossistema de plugins é ótimo e oferece uma alavanca enorme para melhorar a documentação de equipes e projetos. Eu não gosto do reStructuredText em si, mas hoje, graças ao MyST-Parser, é possível fazer em Markdown a maior parte das coisas que antes prendiam fortemente o Sphinx ao RST: https://github.com/executablebooks/MyST-Parser
  • Customizar elementos comuns do site também foi muito fácil com Markdown+Pandoc. Converter tags de imagem contendo links do YouTube em tags de vídeo com miniaturas e texto alternativo, e conectar tags de imagem de arquivos de vídeo locais ao ffmpeg para otimizar e redimensionar, tudo isso foi resolvido com poucas linhas de código
  • Eu não conhecia o Sphinx até ver este comentário. Escrevo documentação técnica há mais de 20 anos como atividade paralela ao trabalho de desenvolvimento e, até então, estava mais próximo de TeX e XSL customizado
    Acabei de migrar para o Sphinx um livro de mais de 200 páginas que explica uma linguagem interna/VM/camada de abstração, e é realmente um sistema que muda a vida. Eu gostaria que a documentação do próprio Sphinx tivesse uma barreira de entrada menor ou mais exemplos, mas, por enquanto, estou em uma fase de lua de mel bem intensa. Meu principal interesse é como criar um livro em PDF bonito e um sistema para recortar o livro em páginas man compatíveis com POSIX por capítulos e seções
  • Se o Sphinx quiser fazer grande sucesso popular, a prioridade número 1 é ter temas bonitos e de alta qualidade
    A estética é um fator bastante importante ao escolher um gerador de sites. Hugo e Gatsby têm ótimos temas padrão, e já escolhi projetos por esse motivo apenas. As coleções de temas do Sphinx https://sphinx-themes.org/ e https://sphinxthemes.com/#featured-themes são, em geral, sem graça. O tema padrão Sphinx RTD https://sphinx-rtd-theme.readthedocs.io/en/stable/ parece antiquado quando comparado à documentação da Apple https://developer.apple.com/documentation/swift/array ou ao Fluent UI https://react.fluentui.dev/?path=/docs/concepts-developer-positioning-components--default

• Considero que a frase “Markdown é uma representação leve de HTML” é o maior problema deste texto. Ela certamente é imprecisa
  Markdown foi projetado como uma ferramenta para converter convenções de formatação de texto que eram usadas praticamente como padrão de fato em e-mails e posts da Usenet no início dos anos 1990. Por causa da restrição de ASCII de 7 bits, formatações como ênfase ou títulos passaram a ser marcadas com símbolos especiais, e o HTML também tinha muitos pontos em comum com essas convenções sem nome. Por isso, em 2004 John Gruber escreveu o script básico https://daringfireball.net/projects/markdown/ que convertia isso para HTML, mas provavelmente não esperava que ele se tornasse esse padrão de fato tão universal

  • A primeira frase desse link é justamente “Markdown is a text-to-HTML conversion tool for web writers.”
    Gruber não pegou um padrão de fato da Usenet e simplesmente criou um conversor para HTML; ele se inspirou na Usenet e em outras convenções para projetar sua própria marcação. A seção “Acknowledgements” no fim do link também mostra isso. Markdown foi pensado desde o início como uma sintaxe de marcação para CMSs web, e dizer que ele é uma representação leve de HTML está correto. O ponto central era que todas as partes da sintaxe produzissem HTML diretamente correspondente
  • Discordo. Markdown sempre esteve relacionado a HTML, a ponto de parsers de Markdown de fato darem suporte à mistura de tags HTML
    O fato de ter sido inspirado por convenções de e-mail não torna menos correta a afirmação de que “Markdown é uma representação leve de HTML”
  • Gostaria que parassem com esse tipo de disputa semântica. Isso gera conversas tediosas e também vai contra as diretrizes do HN
    Há uma regra para responder à interpretação mais plausível e forte do que a outra pessoa disse, em vez de pegar uma interpretação fraca fácil de criticar. Também há uma regra para não escolher apenas a frase mais provocativa do texto para reclamar, mas responder às partes interessantes: https://news.ycombinator.com/newsguidelines.html
    Se você não concorda com o ponto central do texto, basta dizer que prefere Markdown a rST e explicar por quê. Brigar por uma única frase sobre o que exatamente é Markdown é bobagem
  • Markdown em si é separado da formatação de e-mail e Usenet. Markdown era uma sintaxe específica, mal definida, e depois se ampliou para várias famílias de sintaxes em geral parecidas entre si
    Ele foi de fato inspirado por convenções como as de e-mail ou Usenet, e algumas delas existiam até antes dos computadores. Por exemplo, acho que já vi documentos antigos datilografados usando asteriscos como se fossem itálico. Mas Markdown é fortemente ligado a HTML, sua sintaxe é muito limitada pelo HTML, e tentativas de separá-lo de HTML em geral estão fadadas ao fracasso
  • Ambos estão certos. A implementação original era um superconjunto de HTML. A ideia era usar a sintaxe leve para o que era comum e HTML para o restante

• Vejo o ponto central do Markdown como fazer coisas mais simples mais rapidamente do que com HTML bruto, mas permitindo misturar HTML bruto quando necessário
  Em projetos em que precisei do poder do RST em vez de Markdown, era mais conveniente simplesmente escrever HTML diretamente

  • Quando o autor escreve algo como “é possível estender o Sphinx para criar novos objetos de texto; no Markdown básico seria preciso inserir HTML diretamente”, fico me perguntando: se você precisa desse recurso, qual é o problema de simplesmente usar HTML? Não entendo por que colocar mais uma camada

• Ao criar um sistema de documentação de complexidade semelhante, avaliamos RST porque precisávamos muito de uma marcação com semântica clara, armazenando a estrutura dos arquivos RST em um banco de dados e misturando resultados do banco com o conteúdo
  Encontramos dois problemas. Primeiro, as ferramentas de RST não têm um unparser que gere RST de volta. Queríamos mesclar vários arquivos RST e outras fontes para gerar automaticamente arquivos RST e manipulá-los por uma API de documentos, mas isso não era suportado. Segundo, as ferramentas de RST esperam um conjunto de blocos definido para um documento específico. Se os blocos fossem representados de forma genérica, seria possível ter ferramentas que transformassem documentos sem conhecer as definições internas dos blocos, mas não era o caso. Isso é mais um problema das ferramentas do que do RST em si, mas toda vez que é preciso raspar o código até o fundo, acabo pensando em outros sistemas de marcação, como os baseados em HTML

  • Em vez de HTML, é possível usar XML para documentos estruturados. XML permite definir as tags customizadas necessárias e, se quiser, também validar contra um esquema
    A vantagem dessa abordagem é ter controle total sobre o esquema de entrada e a saída; a desvantagem é que ela tem muito mais ruído sintático do que Markdown ou RST e exige scripts para fazer parsing e conversão para o formato de saída desejado
  • Em Python, rST é apenas um dos vários formatos de entrada suportados pelo docutils: https://docutils.sourceforge.io/README.html#purpose
    O objetivo geral do docutils é fazer parsing de formatos e convertê-los para uma API: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers
  • rST e AsciiDoc parecem mais ou menos semelhantes em termos de recursos. Fico curioso se suas fraquezas e recursos ausentes também são mais ou menos parecidos
  • Fui committer do docutils, a principal ferramenta de rST. Um dos motivos pelos quais migrei as ferramentas para Markdown foi que lidar com o docutils era doloroso demais. Só a recusa em mudar para lugares como o GitHub já mostra como era pouco amigável trabalhar junto
  • Estou sem computador agora, então não posso testar, mas acho que talvez dê para fazer o que você quer com a diretiva include

• Alguns anos atrás, fiz uma compilação de um subconjunto de reStructuredText que valia a pena memorizar: https://simonwillison.net/2018/Aug/25/restructuredtext/
  Em projetos recentes, comecei a usar MyST, que oferece os recursos de referências e sumário que eu valorizava no reStructuredText, mas permite usar a sintaxe Markdown, mais fácil para colaboradores escreverem

  • A vantagem é grande em links, especialmente links externos. Em sites de documentação, é comum referenciar o mesmo link externo em vários lugares e querer atualizá-lo uma única vez quando ele muda
    O que realmente muda o jogo, em links internos, é rST+Sphinx com as diretivas :ref: e :doc:. Ao referenciar âncoras ou links para documentos dentro do mesmo conteúdo, você não precisa digitar manualmente o cabeçalho e evita que cabeçalhos digitados manualmente acabem ficando desatualizados: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role
    É um dos recursos de que mais sinto falta ao escrever em rST

• Não quero sequestrar a conversa sobre ReStructuredText, mas, se você está procurando uma linguagem de marcação que ofereça mais que Markdown, eu recomendaria olhar para AsciiDoc em vez de ReStructuredText. Escrevi documentação técnica por anos usando os três, e considero AsciiDoc melhor que ReStructuredText e Markdown
  Por exemplo, o suporte a tabelas em Markdown e ReStructuredText é bem trabalhoso. A formatação de tabelas do AsciiDoc é fácil de ler, escrever e manter, e é mais poderosa: dá suporte a cabeçalhos, legendas, tamanhos personalizados de tabelas e linhas, além de formatação complexa dentro de tabelas. É um formato padronizado único, sem vários dialetos como o Markdown; a sintaxe é concisa e legível; e a curva de aprendizado é mais suave que a do ReStructuredText. As opções de estilo de saída são melhores, o toolchain também é superior, e há muitos recursos de documentação embutidos, reduzindo a dependência de plugins de terceiros. O AsciiDoc foi projetado desde o início para documentação técnica, enquanto os outros dois foram meio adaptados para esse papel

• Quando você monta de forma bonita um documento Markdown de umas 5 a 10 páginas, renderizado por um template Jinja mais dinâmico, o começo é bastante satisfatório. Há também um processo de build para documentação automática, e o conteúdo já é grande demais para um único README no GitHub. Mas é aí que a dor começa
  A documentação via GitHub Project Pages não se encaixa muito bem, e fica a dúvida se ainda é preciso um arquivo .nojekyl ou se o branch gh-pages ainda é necessário. Não dá para saber se é erro de configuração do repositório ou se as mudanças simplesmente não foram refletidas; depois de algumas horas tentando GitHub Actions, a coisa fica irracional. Ao olhar de novo para o Read the Docs, parece que ele quer Sphinx, então você junta Markdown com Sphinx, o build passa, mas depois do deploy a largura da página quebra, embora localmente isso não seja reproduzível — talvez por causa da inserção de anúncios no tier comunitário. Funciona bem em muitos projetos, e eu mesmo já fiz, mas até funcionar é incrivelmente cheio de pequenos detalhes chatos. No fim, Markdown versus RST nem é a questão; o ponto central é encontrar uma combinação que sirva bem para projetos de documentação de porte médio e hospedagem estática

  • Fico curioso se você já olhou o mdBook. Não usei pessoalmente, mas gostei da documentação de vários projetos que usam mdBook, e ele parece bem adequado quando se passa do ponto de um único arquivo README
    As instruções de deploy automático também são boas: https://github.com/rust-lang/mdBook

• Parece que estão deixando passar que o autor está falando no contexto da composição tipográfica do próprio livro. Ele não está afirmando que rST é, em geral, melhor que Markdown
  Em casos gerais, a simplicidade do Markdown é justamente o motivo de seu uso amplo, mas não é disso que o autor está falando

• Acho interessante a reação como se reST tivesse sido criado como concorrente do Markdown. Na verdade, é quase o contrário. reST é uma evolução do StructuredText, de 2002, enquanto Markdown foi lançado pela primeira vez em 2004
  Os objetivos dos dois são muito parecidos e, no texto mais básico, ambos podem ser lidos e escritos como texto simples. Naquela época, muita gente passou a querer esse tipo de coisa, e surgiram vários formatos. Não acho que o Markdown tenha vencido por ser “mais simples” ou “mais legível”. Para conteúdos que podem ser expressos facilmente em ASCII puro e espaços em branco, em geral dá para trocar um pelo outro. Alguém diria que o documento reST do exemplo é um texto obscuro, ilegível sem um parser? Não sei bem em que uma variante de Markdown seria melhor que isso; parece mais um acaso histórico que um deles tenha predominado, pois ambos são bons o bastante para seus objetivos centrais

  • O exemplo era muito simples, então tanto Markdown quanto reST conseguem lidar com ele facilmente
    reST oferece muitos recursos adicionais úteis de formatação quando necessário, mas, quando não são necessários, viram excesso. Comecei a usar GitHub-flavored Markdown por volta de 2010, quando entrei no GitHub, e também usei reStructuredText algumas vezes por causa da documentação do Python. Este último tinha uma curva de aprendizado muito maior, e depois disso não tive motivo para continuar usando
  • Se a pergunta é se é ilegível, não; mas, se é irritante de digitar, sim. Títulos com sublinhado são chatos de editar e, mesmo que não seja obrigatório acertar exatamente o comprimento, você sente pressão para acertar
    Os crases duplos também são uma sintaxe irritante demais em relação ao tempo que realmente tomam