Por que prefiro rST ao Markdown

Por que prefiro rST

Não vou parar de defender essa ideia

• Publiquei a nova versão de "Logic for Programmers" v0.2. Esta versão inclui suporte a epub, resolução de restrições e conteúdo sobre especificação formal.
• Também escrevi o segundo livro, "Learn TLA+", com Sphinx. O Sphinx usa uma linguagem de marcação peculiar chamada reStructured Text (rST).
• O rST tem uma curva de aprendizado mais íngreme que o Markdown. Depois de escrever alguns livros em Markdown, senti que precisava de algo melhor e migrei para rST.

Por que o rST é melhor

• O Markdown é uma representação leve de HTML, enquanto o rST é uma representação de peso intermediário de uma árvore abstrata de documentos.
• Como criar uma imagem em Markdown:

  ![alttext](example.jpg)
  

• Como criar uma imagem em rST:

  .. image:: example.jpg
     :alt: alttext
  

• O rST é extensível. Você pode adicionar novos objetos de texto.
• O Sphinx consegue lidar com referências cruzadas. Por exemplo, se você colocar a âncora foo em um documento e :ref:image <foo>`` em outro, o Sphinx insere a URL correta.
• O rST permite compor o código de transformação junto com o restante do processo de build.

Um caso de uso

• "Logic for Programmers" é um livro relacionado à matemática, então ele precisa de exercícios para os leitores.
• Eu queria colocar os exercícios e as soluções lado a lado no documento, mas para os leitores as soluções deveriam aparecer no fim do livro.
• Para isso, escrevi minha própria extensão de exercícios.

  .. in chapter.rst
  .. exercise:: Fizzbuzz
     :name: ex-fizzbuzz
     An exercise
     .. solution:: ex-fizzbuzz
        A solution
  .. in answers.rst
  .. solutionlist::
  

• Em HTML, os exercícios e as soluções são renderizados inline.
• Em epub e LaTeX, por meio de uma transformação, os nós de solução são movidos para baixo de solutionlist, e nós de referência são anexados a cada exercício.

"Mas eu odeio a sintaxe"

• Muita gente acha a sintaxe do rST feia.
• Dá para entender não querer usar uma ferramenta boa por não gostar da sintaxe.
• Também existem outros geradores de documentos, como AsciiDoc, MyST, Typst, Pollen e Markdown estendido com pandoc.
• Geradores de documentos baseados em Markdown frequentemente adicionam sua própria etapa de pré-processamento para dar suporte a novos casos de uso.
• Existem LSP e treesitter para Markdown e rST, mas não para gitbook-markdown, md-markdown ou leanpub-markdown.

Sem newsletter na próxima semana

• Estarei em Hong Kong.

Atualização de 2024-07-31

• Adicionei uma breve explicação sobre "Logic for Programmers".
• O livro trata de como a lógica formal pode ser útil na engenharia de software do dia a dia.
• Inclui uma visão geral básica de matemática e oito aplicações diferentes.
• Ainda está em fase alfa, mas já tem mais de 20.000 palavras escritas e bastante conteúdo útil.

Resumo do GN⁺

• O rST é uma ferramenta de escrita de documentação mais poderosa que o Markdown.
• Quando usado com Sphinx, ele oferece recursos para transformar e estender a árvore de documentos.
• É útil para escrever livros como "Logic for Programmers".
• Muita gente acha a sintaxe do rST feia, mas há outras alternativas.
• Pode ser útil para quem se interessa por engenharia de software relacionada à lógica formal.

[GN⁺]

Discussão no Hacker News

• A maior vantagem do Markdown é ser fácil de ler e fácil de escrever
• O Markdown talvez não seja a ferramenta ideal para escrever livros, mas é excelente para produzir rapidamente texto formatado
• Eu escreveria um livro usando LaTeX, e o Markdown é adequado para anotações, documentação rápida e comentários
• O reStructuredText (reST) é um pouco bruto por si só, mas fica muito bom quando combinado com o Sphinx
  • O Sphinx é uma boa escolha para sites de documentação grandes e profissionais
  • O Sphinx facilita a personalização dos elementos comuns do site
  • Garante que os links internos sempre sejam resolvidos
  • Tem APIs de extensões e temas bem definidas
  • Há várias extensões e temas no PyPI
• O Markdown é uma representação leve de HTML, enquanto o reST é uma representação de peso intermediário de uma árvore abstrata de documentos
• O Markdown foi projetado para converter texto formatado de mensagens de e-mail e posts da Usenet
• As ferramentas de reST carecem da capacidade de gerar arquivos RST automaticamente
• O Markdown permite fazer coisas simples rapidamente e, quando necessário, inserir HTML bruto
• O MyST permite usar a sintaxe Markdown ao mesmo tempo em que oferece os recursos do reStructuredText
• A documentação de páginas de projetos no GitHub pode ser complexa, e pode ser útil usar Sphinx junto com Markdown
• O autor menciona o rST no contexto de diagramar o próprio livro
• O reST não é um concorrente do Markdown, mas um formato que surgiu antes dele
• Markdown e reST têm basicamente o mesmo objetivo
• Tanto o Markdown quanto o reST são fáceis de ler e rápidos de escrever
• O Markdown acabou sendo mais amplamente usado por razões históricas
• O Markdown permite definir tipos de bloco personalizados e transformar a árvore do documento
• O Jupyter Book é um bom exemplo de uso de Markdown para renderizar em outros destinos, como PDF