[PATCH] ox-md.el export code blocks using grave accents

[PATCH] ox-md.el export code blocks using grave accents

[Rodrigo Morales]

[PATCH] ox-md.el export code blocks using grave accents.

This patch includes the following changes in =ox-md.el=

+ =org-md-example-block= now exports code blocks using triple grave
  accents instead of four spaces of indentation. This has been done
  for two main reasons:
  1. To be able to include the language so that Markdown engines can
     syntax highlight the content of code blocks
  2. To be able to put the source code and the results of evaluation
     in different code blocks. When using indentation, both the source
     code and the results are shown in the same code block by Markdown
     engines.
+ The variable =org-md-lang-export= is now included in order to map
  Org Mode language names to Markdown language names.

The file =mre.org= contains a minimal reproducible example; =mre.md= ,
the resulting file when exporting using the current version; and
=mre-patched.md=, the resulting file when exporting with the changes
of this patch applied.

The patch is shown below.

#+begin_src dash :dir (progn default-directory) :epilogue ":"
diff -u ox-md.el ox-md-patched.el
#+end_src

#+RESULTS:
#+begin_example
--- ox-md.el	2021-01-28 22:18:51.566067501 -0500
+++ ox-md-patched.el	2021-01-28 22:14:34.762735829 -0500
@@ -50,6 +50,14 @@
 	  (const :tag "Use \"atx\" style" atx)
 	  (const :tag "Use \"Setext\" style" setext)))
 
+(defcustom org-md-lang-export
+  '(("dash" . "sh"))
+  "Alist mapping languages to the corresponding language names in Markdown."
+  :group 'org-export-md
+  :type '(repeat
+	  (cons
+	   (string "Org Mode language name")
+	   (string "Markdown language name"))))
 
 ;;;; Footnotes
 
@@ -181,10 +189,24 @@
   "Transcode EXAMPLE-BLOCK element into Markdown format.
 CONTENTS is nil.  INFO is a plist used as a communication
 channel."
-  (replace-regexp-in-string
-   "^" "    "
-   (org-remove-indentation
-    (org-export-format-code-default example-block info))))
+  (let* (language
+	 (org-language
+	  (plist-get (car (cdr example-block)) :language))
+	 (markdown-language
+	  (cdr (assoc org-language org-md-lang-export))) ;
+	 (content
+	  (org-remove-indentation
+	   (org-export-format-code-default example-block info))))
+
+    (if markdown-language
+	(setq language markdown-language)
+      (setq language org-language))
+
+    (setq content (replace-regexp-in-string
+                   "\\`" (concat "```" language "\n")
+                   content))
+    
+    (replace-regexp-in-string "\\'" "```" content)))
 
 (defun org-md-export-block (export-block contents info)
   "Transcode a EXPORT-BLOCK element from Org to Markdown.
#+end_example

-- 
Greetings,
Rodrigo Morales.

Re: [PATCH] ox-md.el export code blocks using grave accents

[Rodrigo Morales]

[-- Attachment #1: Type: text/plain, Size: 52 bytes --]


Sorry for not attaching the files. Here they are.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: mre.md --]
[-- Type: text/markdown, Size: 726 bytes --]


# Table of Contents



When exporting the following code block using indentation, it is not
possible to know where the source code ends and the results of
evaluation starts.

    echo "echo ab"
    echo "seq 1 2"

    echo ab
    seq 1 2

The language of the following code block will be `sh` because `dash`
doesn't belong to `org-md-lang-export`

    result=0
    
    for i in $(seq 1 5)
    do
      for j in $(seq 1 5)
      do
        result=$((result + i + j))
      done
    done
    
    echo "$result"

    150

The language of the following code block will be the same as the one
used in Org Mode because `R` doesn't belong to `org-md-lang-export`

    data(Loblolly)
    
    max(Loblolly $ height)

    [1] 64.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: mre-patch.md --]
[-- Type: text/markdown, Size: 699 bytes --]


# Table of Contents



When exporting the following code block using indentation, it is not
possible to know where the source code ends and the results of
evaluation starts.

```sh
echo "echo ab"
echo "seq 1 2"
```

```
echo ab
seq 1 2
```

The language of the following code block will be `sh` because `dash`
doesn't belong to `org-md-lang-export`

```sh
result=0

for i in $(seq 1 5)
do
  for j in $(seq 1 5)
  do
    result=$((result + i + j))
  done
done

echo "$result"
```

```
150
```

The language of the following code block will be the same as the one
used in Org Mode because `R` doesn't belong to `org-md-lang-export`

```R
data(Loblolly)

max(Loblolly $ height)
```

```
[1] 64.1
```


[-- Attachment #4: mre.org --]
[-- Type: application/vnd.lotus-organizer, Size: 822 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #5: patch-export-src-code.diff --]
[-- Type: text/x-patch, Size: 1460 bytes --]

--- ox-md.el	2021-01-28 22:18:51.566067501 -0500
+++ ox-md-patched.el	2021-01-28 22:14:34.762735829 -0500
@@ -50,6 +50,14 @@
 	  (const :tag "Use \"atx\" style" atx)
 	  (const :tag "Use \"Setext\" style" setext)))
 
+(defcustom org-md-lang-export
+  '(("dash" . "sh"))
+  "Alist mapping languages to the corresponding language names in Markdown."
+  :group 'org-export-md
+  :type '(repeat
+	  (cons
+	   (string "Org Mode language name")
+	   (string "Markdown language name"))))
 
 ;;;; Footnotes
 
@@ -181,10 +189,24 @@
   "Transcode EXAMPLE-BLOCK element into Markdown format.
 CONTENTS is nil.  INFO is a plist used as a communication
 channel."
-  (replace-regexp-in-string
-   "^" "    "
-   (org-remove-indentation
-    (org-export-format-code-default example-block info))))
+  (let* (language
+	 (org-language
+	  (plist-get (car (cdr example-block)) :language))
+	 (markdown-language
+	  (cdr (assoc org-language org-md-lang-export))) ;
+	 (content
+	  (org-remove-indentation
+	   (org-export-format-code-default example-block info))))
+
+    (if markdown-language
+	(setq language markdown-language)
+      (setq language org-language))
+
+    (setq content (replace-regexp-in-string
+                   "\\`" (concat "```" language "\n")
+                   content))
+    
+    (replace-regexp-in-string "\\'" "```" content)))
 
 (defun org-md-export-block (export-block contents info)
   "Transcode a EXPORT-BLOCK element from Org to Markdown.

[-- Attachment #6: Type: text/plain, Size: 33 bytes --]


-- 
Greetings,
Rodrigo Morales.

[PATCH] ox-md.el export code blocks using grave accents.

[Rodrigo Morales]

[-- Attachment #1: Type: text/plain, Size: 2942 bytes --]


This patch includes the following changes in =ox-md.el=

+ =org-md-example-block= now exports code blocks using triple grave
  accents instead of four spaces of indentation. This has been done
  for two main reasons:
  
  1. To be able to include the language so that Markdown engines can
     syntax highlight the content of code blocks. Syntax highlighting
     can also occur when using indentation in some websites (see
     [[https://meta.stackexchange.com/questions/184108][this]]. However,
     this method doesn't work in all websites (I haven't found
     information about this on Github.). Therefore, using grave accents
     is more generic.
     
  2. To be able to put the source code and the results of evaluation
     in different code blocks. When using indentation, both the source
     code and the results are shown in the same code block by Markdown
     engines.
     
+ The variable =org-md-lang-export= is now included in order to map
  Org Mode language names to Markdown language names.

The file =mre.org= contains a minimal reproducible example; =mre.md= ,
the resulting file when exporting using the current version; and
=mre-patch.md=, the resulting file when exporting with the changes
of this patch applied.

The patch is shown below.

#+begin_src dash :dir (progn default-directory) :epilogue ":"
gunzip -c /usr/share/emacs/27.1/lisp/org/ox-md.el.gz > ox-md.el
diff -u ox-md.el ox-md-patched.el
#+end_src

#+RESULTS:
#+begin_example
--- ox-md.el	2021-01-30 16:49:33.459042367 -0500
+++ ox-md-patched.el	2021-01-30 16:48:40.232375347 -0500
@@ -50,6 +50,14 @@
 	  (const :tag "Use \"atx\" style" atx)
 	  (const :tag "Use \"Setext\" style" setext)))
 
+(defcustom org-md-lang-export
+  '(("dash" . "sh"))
+  "Alist mapping languages to the corresponding language names in Markdown."
+  :group 'org-export-md
+  :type '(repeat
+	  (cons
+	   (string "Org Mode language name")
+	   (string "Markdown language name"))))
 
 ;;;; Footnotes
 
@@ -181,10 +189,24 @@
   "Transcode EXAMPLE-BLOCK element into Markdown format.
 CONTENTS is nil.  INFO is a plist used as a communication
 channel."
-  (replace-regexp-in-string
-   "^" "    "
-   (org-remove-indentation
-    (org-export-format-code-default example-block info))))
+  (let* (language
+	 (org-language
+	  (plist-get (car (cdr example-block)) :language))
+	 (markdown-language
+	  (cdr (assoc org-language org-md-lang-export))) ;
+	 (content
+	  (org-remove-indentation
+	   (org-export-format-code-default example-block info))))
+
+    (if markdown-language
+	(setq language markdown-language)
+      (setq language org-language))
+
+    (setq content (replace-regexp-in-string
+                   "\\`" (concat "```" language "\n")
+                   content))
+    
+    (replace-regexp-in-string "\\'" "```" content)))
 
 (defun org-md-export-block (export-block contents info)
   "Transcode a EXPORT-BLOCK element from Org to Markdown.
#+end_example


[-- Attachment #2: mre.org --]
[-- Type: application/vnd.lotus-organizer, Size: 822 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: mre.md --]
[-- Type: text/markdown, Size: 726 bytes --]


# Table of Contents



When exporting the following code block using indentation, it is not
possible to know where the source code ends and the results of
evaluation starts.

    echo "echo ab"
    echo "seq 1 2"

    echo ab
    seq 1 2

The language of the following code block will be `sh` because `dash`
doesn't belong to `org-md-lang-export`

    result=0
    
    for i in $(seq 1 5)
    do
      for j in $(seq 1 5)
      do
        result=$((result + i + j))
      done
    done
    
    echo "$result"

    150

The language of the following code block will be the same as the one
used in Org Mode because `R` doesn't belong to `org-md-lang-export`

    data(Loblolly)
    
    max(Loblolly $ height)

    [1] 64.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: mre-patch.md --]
[-- Type: text/markdown, Size: 699 bytes --]


# Table of Contents



When exporting the following code block using indentation, it is not
possible to know where the source code ends and the results of
evaluation starts.

```sh
echo "echo ab"
echo "seq 1 2"
```

```
echo ab
seq 1 2
```

The language of the following code block will be `sh` because `dash`
doesn't belong to `org-md-lang-export`

```sh
result=0

for i in $(seq 1 5)
do
  for j in $(seq 1 5)
  do
    result=$((result + i + j))
  done
done

echo "$result"
```

```
150
```

The language of the following code block will be the same as the one
used in Org Mode because `R` doesn't belong to `org-md-lang-export`

```R
data(Loblolly)

max(Loblolly $ height)
```

```
[1] 64.1
```


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #5: patch-export-src-code.diff --]
[-- Type: text/x-patch, Size: 1460 bytes --]

--- ox-md.el	2021-01-28 22:18:51.566067501 -0500
+++ ox-md-patched.el	2021-01-28 22:14:34.762735829 -0500
@@ -50,6 +50,14 @@
 	  (const :tag "Use \"atx\" style" atx)
 	  (const :tag "Use \"Setext\" style" setext)))
 
+(defcustom org-md-lang-export
+  '(("dash" . "sh"))
+  "Alist mapping languages to the corresponding language names in Markdown."
+  :group 'org-export-md
+  :type '(repeat
+	  (cons
+	   (string "Org Mode language name")
+	   (string "Markdown language name"))))
 
 ;;;; Footnotes
 
@@ -181,10 +189,24 @@
   "Transcode EXAMPLE-BLOCK element into Markdown format.
 CONTENTS is nil.  INFO is a plist used as a communication
 channel."
-  (replace-regexp-in-string
-   "^" "    "
-   (org-remove-indentation
-    (org-export-format-code-default example-block info))))
+  (let* (language
+	 (org-language
+	  (plist-get (car (cdr example-block)) :language))
+	 (markdown-language
+	  (cdr (assoc org-language org-md-lang-export))) ;
+	 (content
+	  (org-remove-indentation
+	   (org-export-format-code-default example-block info))))
+
+    (if markdown-language
+	(setq language markdown-language)
+      (setq language org-language))
+
+    (setq content (replace-regexp-in-string
+                   "\\`" (concat "```" language "\n")
+                   content))
+    
+    (replace-regexp-in-string "\\'" "```" content)))
 
 (defun org-md-export-block (export-block contents info)
   "Transcode a EXPORT-BLOCK element from Org to Markdown.

[-- Attachment #6: Type: text/plain, Size: 33 bytes --]


-- 
Greetings,
Rodrigo Morales.

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Tim Cross]

I don't think this patch is correct.

There are no precise standards for markdown, but org states in the
manual that the version of markdown it supports is that defined at
http://daringfireball.net/projects/markdown - which uses the indentation
style for code blocks, not the ```` style. Note that there is the github
markdown exporter which does support the '''' style.

One of the problems with markdown is the differing flavours out there.
While ```` may be supported on sites like github and stackoverflow,
other sites only support the indentation style. We therefore need to be
somewhat conservative with respect to introducing changes as while we
may 'fix' things for some sites, we could easily break them for others.
Given there is a package which supports the ```` style code blocks, I
don't think modifying the existing markdown exporter is necessary.

From your explanation, I suspect what you really need is to use the
github flavoured markdown package available as ox-gfm on MELPA rather
than the default ox-md package in org mode.

Note that I have no particular preference for the markdown style defined
on daringfireball.net and there has been past discussions on this list
regarding what flavour of markdown org should support, so I know there
are varying opinions in this area. My main point is that if we specify
in the manual that we support a particular flavour, then that is the
flavour of markdown we should support. In other words, if we are going
to add features/support for syntax not defined on the daringfireball.net
flavour of markdown, we would need to document what syntax we do support
and consider things like backwards compatibility for any changes introduce.

Rodrigo Morales <moralesrodrigo1100@gmail.com> writes:

> This patch includes the following changes in =ox-md.el=
>
> + =org-md-example-block= now exports code blocks using triple grave
>   accents instead of four spaces of indentation. This has been done
>   for two main reasons:
>
>   1. To be able to include the language so that Markdown engines can
>      syntax highlight the content of code blocks. Syntax highlighting
>      can also occur when using indentation in some websites (see
>      [[https://meta.stackexchange.com/questions/184108][this]]. However,
>      this method doesn't work in all websites (I haven't found
>      information about this on Github.). Therefore, using grave accents
>      is more generic.
>
>   2. To be able to put the source code and the results of evaluation
>      in different code blocks. When using indentation, both the source
>      code and the results are shown in the same code block by Markdown
>      engines.
>
> + The variable =org-md-lang-export= is now included in order to map
>   Org Mode language names to Markdown language names.
>
> The file =mre.org= contains a minimal reproducible example; =mre.md= ,
> the resulting file when exporting using the current version; and
> =mre-patch.md=, the resulting file when exporting with the changes
> of this patch applied.
>
> The patch is shown below.
>
> #+begin_src dash :dir (progn default-directory) :epilogue ":"
> gunzip -c /usr/share/emacs/27.1/lisp/org/ox-md.el.gz > ox-md.el
> diff -u ox-md.el ox-md-patched.el
> #+end_src
>
> #+RESULTS:
> #+begin_example
> --- ox-md.el	2021-01-30 16:49:33.459042367 -0500
> +++ ox-md-patched.el	2021-01-30 16:48:40.232375347 -0500
> @@ -50,6 +50,14 @@
>     (const :tag "Use \"atx\" style" atx)
>     (const :tag "Use \"Setext\" style" setext)))
>
> +(defcustom org-md-lang-export
> +  '(("dash" . "sh"))
> +  "Alist mapping languages to the corresponding language names in Markdown."
> +  :group 'org-export-md
> +  :type '(repeat
> +   (cons
> +    (string "Org Mode language name")
> +    (string "Markdown language name"))))
>
>  ;;;; Footnotes
>
> @@ -181,10 +189,24 @@
>    "Transcode EXAMPLE-BLOCK element into Markdown format.
>  CONTENTS is nil.  INFO is a plist used as a communication
>  channel."
> -  (replace-regexp-in-string
> -   "^" "    "
> -   (org-remove-indentation
> -    (org-export-format-code-default example-block info))))
> +  (let* (language
> +	 (org-language
> +   (plist-get (car (cdr example-block)) :language))
> +	 (markdown-language
> +   (cdr (assoc org-language org-md-lang-export))) ;
> +	 (content
> +   (org-remove-indentation
> +    (org-export-format-code-default example-block info))))
> +
> +    (if markdown-language
> +	(setq language markdown-language)
> +      (setq language org-language))
> +
> +    (setq content (replace-regexp-in-string
> +                   "\\`" (concat "```" language "\n")
> +                   content))
> +
> +    (replace-regexp-in-string "\\'" "```" content)))
>
>  (defun org-md-export-block (export-block contents info)
>    "Transcode a EXPORT-BLOCK element from Org to Markdown.
> #+end_example


--
Tim Cross

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Rodrigo Morales]

Tim Cross <theophilusx@gmail.com> writes:

> I don't think this patch is correct.
>
> From your explanation, I suspect what you really need is to use the
> github flavoured markdown package available as ox-gfm on MELPA rather
> than the default ox-md package in org mode.

Thank you very much for the detailed information. Didn't know much of
the things you mentioned.

I mainly wrote the patch because most of the times I wrote Markdown for
answering questions in Stack Exchange and writing issues in Github and
these changes were really helpful to me. I wouldn't have done this if I
had known of "ox-gfm", which I suppose solve some of my needs (I will
check it out later).

Next time I will make sure to read the relevant part in the Info manual
and search some related keywords in the mailing list archive.

-- 
Greetings,
Rodrigo Morales.

Re: [PATCH] ox-md.el export code blocks using grave accents

[Rodrigo Morales]

[-- Attachment #1: Type: text/plain, Size: 301 bytes --]

Please, omit this duplicated thread. It has already been discussed.

This thread was created due to an error of mine.

On Thu, 28 Jan 2021 at 22:51, Rodrigo Morales <moralesrodrigo1100@gmail.com>
wrote:

>
> Sorry for not attaching the files. Here they are.
>
>
> --
> Greetings,
> Rodrigo Morales.
>

[-- Attachment #2: Type: text/html, Size: 622 bytes --]

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Bastien]

Tim Cross <theophilusx@gmail.com> writes:

> I don't think this patch is correct.

I'm marking it as "canceled" right now, thanks.

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Bruce D'Arcus]

On Sat, Jan 30, 2021, 6:29 PM Tim Cross <theophilusx@gmail.com> wrote:

> There are no precise standards for markdown, but org states in the
> manual that the version of markdown it supports is that defined at
> http://daringfireball.net/projects/markdown

Perhaps at some point it would make sense to change to this, which is
much more precisely specified:

https://commonmark.org/

Bruce

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Timothy]

Bruce D'Arcus <bdarcus@gmail.com> writes:

> On Sat, Jan 30, 2021, 6:29 PM Tim Cross <theophilusx@gmail.com> wrote:
>
>> There are no precise standards for markdown, but org states in the
>> manual that the version of markdown it supports is that defined at
>> http://daringfireball.net/projects/markdown
>
> Perhaps at some point it would make sense to change to this, which is
> much more precisely specified:
>
> https://commonmark.org/

The only change I'd think would be worthwhile, is to complicate ox-md by
introducing the concept of styles/presets.

Even just commonmark has multiple ways you can do things (backticks and
spaces for code), and I'd think supporting a set like: Gruber's
original, commonmark, and GFM would make sense.

Alternatively, we can leave that to other backends like ox-gfm.

Basically: markdown is a mess and I'm not sure what would be a good
course of action.

--
Timothy

Re: [PATCH] ox-md.el export code blocks using grave accents.

[Nicolas Goaziou]

Hello,

Timothy <tecosaur@gmail.com> writes:

> Even just commonmark has multiple ways you can do things (backticks and
> spaces for code), and I'd think supporting a set like: Gruber's
> original, commonmark, and GFM would make sense.
>
> Alternatively, we can leave that to other backends like ox-gfm.

That is the idea. "ox-md" is here to do the boring tasks, while being as
neutral as possible. There no need to handle specific syntax since you
can easily create a derived back-end.

> Basically: markdown is a mess and I'm not sure what would be a good
> course of action.

Regards,
-- 
Nicolas Goaziou