طلب للحصول على تعليقات:ما الذي يجب أن يكون عليه بناء الجملة لتضمين مقتطفات التعليمات البرمجية في Markdown؟(من الملفات الخارجية)

Question

لقد تم استخدام تخفيض السعر حديثاً.

إحدى أكبر مشكلاتي مع Markdown هي أن Markdown لا يحتوي على صيغة لتضمين الملفات داخل المستند (مقابل، على سبيل المثال، listings حزمة LaTeX).

أرغب في توسيع نطاق Markdown لدعم تضمين الملفات الكاملة والجزئية كمقتطفات من التعليمات البرمجية.على سبيل المثال، يمكن أن يبدو مثل هذا:

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

وهذا من شأنه أن يضع محتويات bar.rb الأسطر 10-20 في المستند الخاص بي كـ a code حاجز.الأساس المنطقي هو ذلك

• يمكن تحديث الوثائق مع تغير الكود.(ضد.النسخ واللصق الذي أصبح دائمًا قديمًا)
• يمكنك بعد ذلك وحدة اختبار الكود الدقيق الموجود في الوثائق

أسئلتي هي:

1. ماذا يجب أن يكون بناء الجملة؟
2. هل تم ذلك بالفعل وأنا في عداد المفقودين؟

Answer 1

سأكون أكثر ميلاً للتوصل إلى وسيلة عامة لتوسيع جملة Markdown، ثم استخدامها لتقديم الدعم لوظيفة التضمين.على سبيل المثال، يمكنك تحديد بناء الجملة مثل (أنا لا أقترح بناء الجملة هذا حقًا، مجرد مثال):

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

..أين command يشير إلى أمر لا يفهمه محلل تخفيض السعر، ولكن يمكنه الاتصال مرة أخرى بشيء آخر لمعالجته.بعد ذلك، يمكنك إنشاء دالة تضمين تعمل مع تخفيض السعر، ولكنها لا تكون جزءًا منه فعليًا.شيء مثل:

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

أوه، وإذا قمت بذلك، فربما لن أقدم وسيلة لتضمين ملف جزئي، على الأقل ليس باستخدام أرقام الأسطر - حيث يعني ذلك أنه يتعين عليك العودة وتحرير جميع استدعاءات التضمين إذا قمت بتغيير طول الملف document، مما يجعل إعادة الاستخدام أكثر صعوبة (إذا تمكنت من التوصل إلى طريقة لوضع علامات على الأقسام، فقد يكون ذلك أفضل).

Answer 2

أنا عمومًا أميل إلى معرفة ما إذا كان من الممكن جعل الأمور تعمل مع بناء الجملة الحالي بطريقة معقولة.حاليا،

    ![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 3

لقد تأخرت قليلا، آسف.لكن restructuredText يدعم هذا بالفعل:http://docutils.sourceforge.net/docs/ref/rst/directives.html# Included-an-external-document-fragment