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)
Pergunta
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:
- O que deve a sintaxe ser?
- isso foi feito e eu estou perdendo isso?
Solução
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).
Outras dicas
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
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