Request for Comments: Was sollte die Syntax sein, um Code-Schnipsel in Markdown enthalten? (Aus externen Dateien)

Question

Ich habe mit Markdown vor kurzem.

Eines meiner größten Probleme mit Markdown ist, dass keine Markdown-Syntax für die Aufnahme von Dateien innerhalb eines Dokuments hat (im Vergleich zu, sagen wir, die listings Paket für LaTeX).

Ich mag Markdown erweitern, einschließlich Voll und Teildateien als Code-Schnipsel zu unterstützen. Zum Beispiel könnte es so aussehen:

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

und das würde den Inhalt der bar.rb Zeilen 10-20 in mein Dokument als code Block setzen. Der Grund ist, dass

• Dokumentation kann als die Code-Änderungen aktualisiert werden. (Vs. Kopieren und Einfügen, das wird immer veraltet)
• Sie können dann testen Einheit den genauen Code, der in der Dokumentation
ist

Meine Fragen sind:

1. Was sollte die Syntax sein?
2. Ist dies bereits getan, und ich bin es fehlt?

Answer 1

würde ich eher geneigt, mit einem allgemeinen Mittel zu kommen Markdown-Syntax zu erweitern, und dann, dass die Unterstützung zur Verfügung zu stellen verwenden für eine Funktion enthalten. So zum Beispiel könnten Sie definieren Syntax wie (ich bin nicht wirklich diese besondere Syntax was darauf hindeutet, nur ein Beispiel):

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

.. wo command bezieht sich auf einen Befehl, der Abschlags-Parser nicht versteht, kann aber wieder auf etwas anderes nennen es zu verarbeiten. Dann können Sie bauen eine Include-Funktion, die mit Abschlag wird funktionieren, aber nicht wirklich einen Teil davon sein. So etwas wie:

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

Oh, und wenn Sie dies tun, würde ich wahrscheinlich stellen kein Mittel eine Teildatei aufzunehmen, zumindest nicht durch Zeilennummern mit - wie es heißt, müssen Sie gehen zurück und bearbeiten Sie alle Anrufe enthalten, wenn Sie das ändern Länge des Dokuments, das erschwert die Wiederverwendung tatsächlich (wenn Sie eine Möglichkeit Abschnitte zu markieren, kommen könnte, die besser funktionieren könnte).

Answer 2

Ich bin im Allgemeinen geneigt, zu sehen, ob die Dinge gemacht werden withing bestehende Syntax in einer angemessenen Art und Weise zu arbeiten. Derzeit ist die

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

Syntax und seine Verwandten werden verwendet, um ein Bild in den Text aufzunehmen. In ähnlicher Weise,

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

oder

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

kann verwendet werden, um Text aufzunehmen. In diesem Fall ist der Text in den eckigen Klammern genau wie das alt-text Attribut für Inline-Bilder: Es enthält eine kurze, menschliche nachvollziehbare Beschreibung der Datei enthalten ist

.

Mit + ist intuitiv zu mir. Es bedeutet, in der Inhalt dieser Datei zu diesem Dokument hier

Answer 3

Ich bin ein wenig zu spät, sorry. aber reStructuredText unterstützt bereits diese: http: //docutils.sourceforge. net / docs / ref / rst / directives.html # inklusive-an-external-Dokument-Fragment