Richiesta di commenti: quale dovrebbe essere la sintassi per includere snippet di codice in Markdown? (da file esterni)

Question

Ho usato Markdown recentemente.

Uno dei miei maggiori problemi con Markdown è che Markdown non ha sintassi per includere file all'interno di un documento (vs., diciamo, elenchi pacchetto per LaTeX).

Vorrei estendere Markdown per supportare l'inclusione di file interi e parziali come frammenti di codice. Ad esempio, potrebbe apparire così:

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

e questo metterebbe il contenuto di bar.rb righe 10-20 nel mio documento come blocco code . La logica è quella

• la documentazione può essere aggiornata quando il codice cambia. (vs. copia e incolla che diventa sempre obsoleto)
• puoi quindi testare l'unità il codice esatto che si trova nella documentazione

Le mie domande sono:

1. Quale dovrebbe essere la sintassi?
2. È già stato fatto e mi manca?

Answer 1

Sarei più propenso a trovare un mezzo generale per estendere la sintassi di Markdown, e quindi usarlo per fornire supporto per una funzione di inclusione. Quindi, ad esempio, potresti definire la sintassi come (non sto davvero suggerendo questa sintassi particolare, solo un esempio):

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

..where command si riferisce a un comando che il parser di markdown non comprende, ma può richiamare a qualcos'altro per elaborarlo. Quindi puoi creare una funzione di inclusione che funzionerà con markdown, ma in realtà non ne farà parte. Qualcosa del tipo:

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

Oh, e se lo fai, probabilmente non fornirei un mezzo per includere un file parziale, almeno non usando i numeri di linea - poiché significa che devi tornare indietro e modificare tutte le chiamate incluse se cambi il lunghezza del documento, che in realtà rende più difficile il riutilizzo (se potessi trovare un modo per taggare le sezioni, potrebbe funzionare meglio).

Answer 2

Sono generalmente propenso a vedere se è possibile far funzionare le cose con la sintassi esistente in modo ragionevole. Attualmente, il

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

La sintassi

??e i suoi parenti sono usati per includere un'immagine nel testo. Allo stesso modo,

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

o

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

può essere usato per includere testo. In questo caso, il testo tra parentesi quadre è proprio come l'attributo alt-text per le immagini incorporate: contiene una breve descrizione umana comprensibile del file che viene incluso.

L'uso di + è intuitivo per me: significa aggiungi il contenuto di questo file in questo documento qui.

Answer 3

Sono un po 'in ritardo, scusa. ma ristrutturatoText supporta già questo: http: //docutils.sourceforge. net / docs / ref / rST / directives.html # incluso-un-esterna-documenti-frammento