Pedido de Comentários: O que deve a sintaxe ser a inclusão de trechos de código em Markdown? (A partir de arquivos externos)

Question

Eu tenho usado Markdown recentemente.

Um dos meus maiores problemas com Markdown é que Markdown não tem sintaxe para incluir arquivos dentro de um documento (vs., digamos, a listings pacotes para LaTeX).

Eu gostaria de estender Markdown para suporte incluindo arquivos inteiros e parciais como trechos de código. Por exemplo, poderia ficar assim:

![:include src/foo/bar.rb](10-20)

e que iria colocar o conteúdo de linhas bar.rb 10-20 no meu documento como um bloco code. A lógica é que

• documentação pode ser atualizado conforme as alterações de código. (Vs. copiar e colar que sempre fica desatualizado)
• Você pode, em seguida, teste de unidade do código exato que está na documentação

As minhas perguntas são:

1. O que deve a sintaxe ser?
2. isso foi feito e eu estou perdendo isso?

Answer 1

Eu estaria mais inclinado para chegar a um meio geral para estender a sintaxe Markdown, e depois usar isso para fornecer suporte para um incluem função. Assim, por exemplo, você poderia definir sintaxe como (Eu realmente não estou sugerindo esta sintaxe particular, apenas um exemplo):

[[command: arg arg arg...]]

.. onde command refere-se a um comando que o analisador de remarcação não entende, mas pode chamar de volta para outra coisa para processá-lo. Então você pode construir um incluem função que irá trabalhar com remarcação, mas na verdade não fazer parte dele. Algo como:

[[include: src/foo/bar.md]]

Ah, e se você fizer isso, eu provavelmente não iria fornecer um meio para incluir um arquivo parcial, pelo menos não usando números de linha - porque significa que você tem que ir para trás e editar toda a incluir as chamadas se você alterar o comprimento do documento, o que realmente faz a reutilização mais difícil (se você poderia vir acima com uma maneira de seções de tag, que pode funcionar melhor).

Answer 2

Estou geralmente inclinado a ver se as coisas podem ser feitas para withing trabalho sintaxe existente de uma forma razoável. Atualmente, a

    ![Example Photo](http://example.com/example.jpg)

sintaxe e seus parentes são usadas para incluir uma imagem no texto. Na mesma linha,

    +[Generic Heading](http://example.com/heading.txt)

ou

    +[Local Heading](file:///dir/a/b/c/example.txt)

pode ser usado para incluir o texto. Neste caso, o texto entre colchetes é como o atributo alt-text para imagens em linha:. Ele contém uma pequena, descrição compreensível humana do arquivo a ser incluído

Usando + é intuitivo para mim:. Significa Adicionar o conteúdo deste arquivo a este documento aqui

Answer 3

Eu sou um pouco tarde, desculpe. mas ReStructuredText já suporta o seguinte: http: //docutils.sourceforge. net / docs / ref / rST / directives.html # incluindo-an-external-document-fragmento