emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Tim Cross <theophilusx@gmail.com>
To: emacs-orgmode@gnu.org
Subject: Re: [PATCH] ox-md.el export code blocks using grave accents.
Date: Sun, 31 Jan 2021 09:51:27 +1100	[thread overview]
Message-ID: <875z3e2ef5.fsf@gmail.com> (raw)
In-Reply-To: <87lfcaytom.fsf@gmail.com>


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


  reply	other threads:[~2021-01-30 23:29 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-30 21:57 Rodrigo Morales
2021-01-30 22:51 ` Tim Cross [this message]
2021-01-30 23:53   ` Rodrigo Morales
2021-04-27  8:43   ` Bastien
2021-04-27 10:03   ` Bruce D'Arcus
2021-04-27 10:18     ` Timothy
2021-04-27 11:32       ` Nicolas Goaziou
  -- strict thread matches above, loose matches on Subject: below --
2021-01-29  3:43 Rodrigo Morales
2021-01-29  3:47 ` Rodrigo Morales
2021-01-31 19:55   ` Rodrigo Morales

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=875z3e2ef5.fsf@gmail.com \
    --to=theophilusx@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: [PATCH] ox-md.el export code blocks using grave accents.' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).