Запрос комментариев: каким должен быть синтаксис для включения фрагментов кода в Markdown? (из внешних файлов)

Question

Я недавно использовал Уценка .

Одна из моих самых больших проблем с Markdown заключается в том, что у Markdown нет синтаксиса для включения файлов в документ (например, пакет listings для LaTeX).

Я бы хотел расширить Markdown для поддержки включения целых и частичных файлов в виде фрагментов кода. Например, это может выглядеть так:

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

и это поместило бы содержимое bar.rb строк 10-20 в мой документ как code блок. Обоснование состоит в том, что

• документация может обновляться при изменении кода. (против копирования и вставки, которые всегда устаревают)
• затем вы можете выполнить модульное тестирование точного кода, указанного в документации

Мои вопросы:

1. Каким должен быть синтаксис?
2. Это уже было сделано, и я скучаю по нему?

Answer 1

Я обычно склонен смотреть, можно ли заставить работать разумным образом с существующим синтаксисом. В настоящее время

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

Синтаксис

и его родственники используются для включения изображения в текст. В том же духе

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

или

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

может использоваться для включения текста. В этом случае текст в квадратных скобках аналогичен атрибуту alt-text для встроенных изображений: он содержит краткое понятное человеку описание включаемого файла.

Использование + для меня интуитивно понятно: это означает добавить содержимое этого файла в этот документ здесь.

Answer 2

Я был бы более склонен придумать общие средства для расширения синтаксиса Markdown, а затем использовать его для обеспечения поддержки функции включения. Так, например, вы могли бы определить синтаксис как (я на самом деле не предлагаю этот конкретный синтаксис, просто пример):

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

.. где command относится к команде, которую анализатор уценки не понимает, но может перезвонить чему-то другому для ее обработки. Затем вы можете создать функцию включения, которая будет работать с уценкой, но на самом деле не будет ее частью. Что-то вроде:

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

Да, и если вы сделаете это, я бы, вероятно, не предоставил средства для включения частичного файла, по крайней мере, без использования номеров строк - поскольку это означает, что вы должны вернуться назад и отредактировать все включенные вызовы, если вы измените длина документа, что на самом деле затрудняет повторное использование (если вы можете придумать способ пометить разделы, это может работать лучше).

Answer 3

Я немного опоздал, извините. но restructuredText уже поддерживает это: http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment