Demande de commentaires: Quelle devrait être la syntaxe pour inclure des extraits de code dans Markdown? (à partir de fichiers externes)

Question

J'ai récemment utilisé Markdown. L'un de mes plus gros problèmes avec Markdown est que Markdown n'a pas de syntaxe pour inclure des fichiers dans un document (par exemple, le paquet listings pour LaTeX).

Je voudrais étendre Markdown à la prise en charge incluant des fichiers entiers et partiels comme extraits de code. Par exemple, il pourrait ressembler à ceci:

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

et qui placerait le contenu des bar.rb lignes 10-20 dans mon document comme un bloc code. La logique est que

• la documentation peut être mise à jour lorsque le code change. (Par rapport à copier et coller qui obtient toujours dépassée)
• , vous pouvez tester l'unité le code exact qui se trouve dans la documentation

Mes questions sont les suivantes:

1. Que doit la syntaxe être?
2. Cela a-t-il déjà été fait et il me manque?

Answer 1

Je serais plus enclin à trouver un moyen général d'étendre la syntaxe Markdown, puis l'utiliser pour fournir un support pour une fonction d'inclusion. Ainsi, par exemple, vous pouvez définir la syntaxe comme (je ne suis pas vraiment suggérer cette syntaxe particulière, juste un exemple):

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

..where command fait référence à une commande que l'analyseur de démarquage ne comprend pas, mais peut rappeler à autre chose pour le traiter. Vous pouvez ensuite créer une fonction d'inclusion qui fonctionnera avec markdown, mais qui n'en fera pas partie. Quelque chose comme:

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

Oh, et si vous faites cela, je serais probablement pas fourni un moyen d'inclure un fichier partiel, du moins pas en utilisant les numéros de ligne - comme cela signifie que vous devez revenir en arrière et modifier tous les appels d'inclusion si vous changez la longueur du document, ce qui rend la réutilisation plus difficile (si vous pouviez trouver un moyen de marquer les sections, cela pourrait fonctionner mieux).

Answer 2

Je suis généralement enclin à voir si les choses peuvent fonctionner de manière raisonnable avec la syntaxe existante. Actuellement, la

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

syntaxe et ses parents sont utilisés pour inclure une image dans le texte. Dans la même veine,

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

ou

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

peut être utilisé pour inclure du texte. Dans ce cas, le texte entre crochets est similaire à l'attribut alt-text pour les images en ligne: Il contient une description courte et compréhensible du fichier inclus.

+ à l'aide est intuitive pour moi: Cela signifie ajouter le contenu de ce fichier dans ce document ici.

Answer 3

Je suis un peu en retard, désolé. mais restructuredText prend déjà en charge ceci: http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment