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

Question

J'utilise Markdown récemment.

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 packages pour LaTeX).

J'aimerais étendre Markdown à la prise en charge de l'inclusion de fichiers entiers et partiels dans des extraits de code. Par exemple, cela pourrait ressembler à ceci:

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

et cela mettrait le contenu des lignes bar.rb 10-20 dans mon document sous forme de bloc code . La raison en est que

La
• documentation peut être mise à jour à mesure que le code change. (vs copier et coller qui devient toujours obsolète)
• vous pouvez alors tester à l'unité le code exact contenu dans la documentation

Mes questions sont les suivantes:

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

Answer 1

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

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

.. où commande fait référence à une commande que l'analyseur de démarquage ne comprend pas, mais peut rappeler à autre chose de le traiter. Ensuite, vous pouvez créer une fonction include qui fonctionnera avec markdown, mais n'en fera pas partie. Quelque chose comme:

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

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

Answer 2

Je suis généralement enclin à voir s’il est possible de travailler de manière raisonnable avec la syntaxe existante. Actuellement, le

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

La syntaxe

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

    +[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 ressemble à l'attribut alt-text pour les images incorporées: il contient une brève description, compréhensible par l'homme, du fichier en cours d'inclusion.

L’utilisation de + me semble intuitive: cela signifie que ajoutez le contenu de ce fichier à ce document ici.

Answer 3

Je suis un peu en retard, désolé. mais restructuredText supporte déjà ceci: http: //docutils.sourceforge. net / docs / ref / rst / directives.html # y compris un fragment de document externe