Use of #+begin/end_example for md export?

[jwhendy]

I'm giving a talk on Org-mode for reproducible research at an upcoming R user group and want to take some time to show off the vast export capabilities of Org. I'm planning on demonstrating LaTeX/PDF, html, beamer, reveal, and Rmd/slidify (using ox-ravel). I have a slide where I show the markup used to create the slide, like so:

* ok, so what is it?

=Org-mode= is a major mode for the Emacs text editor.
- it uses markup to allow for structuring

#+begin_example

,* ok, so what is it?                          # heading

=Org-mode= is a major mode for the Emacs text editor.
- it uses markup to allow for structuring     # unordered list

#+end_example

This works fine for Beamer/reveal.js, but not Rmd. I can manually edit the generated .Rmd by adding backticks around the code, but otherwise it just exports as-is. In other words, I get this with ox-ravel:

# ok, so what is it?

`Org-mode` is a major mode for the Emacs text editor.

-   it uses markup to allow for structuring

    * ok, so what is it?                          # heading

    =Org-mode= is a major mode for the Emacs text editor.
    - it uses markup to allow for structuring     # unordered list

It appears I'd need this:

# ok, so what is it?

`Org-mode` is a major mode for the Emacs text editor.

-   it uses markup to allow for structuring

* ok, so what is it?                          # heading

=Org-mode= is a major mode for the Emacs text editor.
- it uses markup to allow for structuring     # unordered list

Thanks for any pointers on how to proceed the "correct" way with ox-ravel!

[chasberry]

Looking at http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html#verbatim-code-blocks, it seems that what you got is correct, viz. verbatim (code) blocks are specified by "A block of text indented four spaces". So why is this a problem?

BTW, Rmd exports depend on ox-md, so this isn't specifically an ox-ravel issue.

The back-tics are used to define fenced code blocks. AFAICS, there is no automatic use of fenced code blocks in ox-md. If you can have them using ox-md by putting them in #+MD: lines surrounding the example block.

In ox-gfm (Github Flavored Markdown) src blocks get exported as fenced code blocks. If the way it is implemented there works better for you, you can use

#+BEGIN_SRC emacs-lisp
(require 'ox-gfm)
 (eval-after-load 'ox-gfm
    '(org-ravel-define-exporter
     'ravel-gfm
     'gfm ?g "Ravel-gfm" "md" nil t ))
#+END_SRC

to create a Ravel-gfm exporter if you use the ravel-lang branch of orgmode-accessories.

In the master branch, it is more involved, but you could use this section https://github.com/chasberry/orgmode-accessories/blob/master/ox-ravel.org#46-md-knitr-backend as a template by substituting gfm for md in a bunch of places and ?g for ?m for the menu entry and I think you would be in business. Of course you'ld need to (require 'ox-gfm), too.

[jwhendy]

Hmmm. I do see four spaces, so perhaps this is an inherent issue with markup?

Typing it here to see what happens, first in backticks:

# ok, so what is it?

`Org-mode` is a major mode for the Emacs text editor.

-   it uses markup to allow for structuring

    * ok, so what is it?                          # heading

    =Org-mode= is a major mode for the Emacs text editor.
    - it uses markup to allow for structuring     # unordered list

And with just the literal markup in backticks to see if the markup format gets picked up on the top part:

ok, so what is it?

Org-mode is a major mode for the Emacs text editor.

• it uses markup to allow for structuring

    * ok, so what is it?                          # heading

    =Org-mode= is a major mode for the Emacs text editor.
    - it uses markup to allow for structuring     # unordered list

So far so good, how about nothing in backticks?

ok, so what is it?

Org-mode is a major mode for the Emacs text editor.

• it uses markup to allow for structuring

  • ok, so what is it? # heading

  =Org-mode= is a major mode for the Emacs text editor.

  • it uses markup to allow for structuring # unordered list

So, none of those fail. Would you suggest taking this up with slidify, as that's what I'm using for the final export process (C-c C-e m r) + slidify("file.Rmd").

EDIT: Whoops! I missed deleting the backticks from the third example when I copied/pasted the second. It looks like the behavior here and with ox-ravel/slidify are the same. So does this mean that md formatting is not ignored when indenting four spaces (verbatim blocks as you've identified)?

[chasberry]

Weird. Here is what I get cutting and pasting from the email copy of your msg that github sent to me being careful not to include the back-tics:

* ok, so what is it?                          # heading

=Org-mode= is a major mode for the Emacs text editor.
- it uses markup to allow for structuring     # unordered list

When I preview that it looks like your first (correct) rendering.

I wonder if there is some invisible (non-printing) character in your original that got cleaned up in the emailed version? You can check in emacs in hexl-mode to see that there really are 4 spaces following the newline. Something like

0a20 2020 203d

for a line that starts with four spaces and a `='

[jwhendy]

I must have missed this response! Sorry for the delay. Going to paste one more time here without backticks:

ok, so what is it?

Org-mode is a major mode for the Emacs text editor.

• it uses markup to allow for structuring

  • ok, so what is it? # heading

  =Org-mode= is a major mode for the Emacs text editor.

  • it uses markup to allow for structuring # unordered list

Edit: posted to see what it would look like and it's still not seeming to pick up the four spaces. I'll just try manually typing:

* ok, so what is it?                            #heading

=Org-mode is a major mode for the Emacs text editor.
- it uses markup to allow for structuring   #unordered list

Edit: Woah! Manually typing the spaces works! How can I diagnose why my output would include odd characters? My locale is set to LANG=en_US.UTF-8

Here's a screenshot of hexl-mode on the normal section and the one that should show up as verbatim. I see a couple of periods in there and no 203d character. Does it look incorrect to you?

[jwhendy]

Wanted to follow up on this one more time in case the issue I reported in #6 was related. Here's another screenshot of the test file in hexl-mode (this time with the new, #+begin_export md syntax):

I see the sequence 2020 2020 203d, but there's also a dot in there?

Here's what the slide looks like:

Any thoughts based on the hexl output?

[jwhendy]

Thought of another bit of info in case it's helpful. I opened ./test-deck/my.Rmd and did M-x describe-char on each of the four spaces before the example block. Here's what I get (seemed normal?):

             position: 601 of 721 (83%), column: 3
            character: SPC (displayed as SPC) (codepoint 32, #o40, #x20)
    preferred charset: ascii (ASCII (ISO646 IRV))
code point in charset: 0x20
               script: latin
               syntax:      which means: whitespace
             category: .:Base, a:ASCII, l:Latin
             to input: type "C-x 8 RET HEX-CODEPOINT" or "C-x 8 RET NAME"
          buffer code: #x20
            file code: #x20 (encoded by coding system undecided-unix)
              display: by this font (glyph code)
    xft:-unknown-Droid Sans Mono Slashed-normal-normal-normal-*-14-*-*-*-m-0-iso10646-1 (#x03)

Character code properties: customize what to show
  name: SPACE
  general-category: Zs (Separator, Space)
  decomposition: (32) (' ')

[chasberry]

John,

There is no relation to #6. AFAICS, this problem lies somewhere between your setup and ox-md and has nothing to do with ox-ravel.

When I export the (block quoted) file below using ox-md and again as Rmd using ox-ravel, and diff the resulting files, the only diffs I get are those that pertain to block quoting the R src code - the parts between the abc and the def are identical. Unless you get something different in that portion, please close this issue.

• MD is OK

+BEGIN_SRC R

x <- 1

+END_SRC

abc

+BEGIN_EXAMPLE

,* I said /MD is OK/

• and it is
• seriously!

+END_EXAMPLE

def

BTW, #+BEGIN_EXAMPLE... is for example blocks. If you had that before, you should still have it.

[jwhendy]

Dammit. I was fiddling around and happened to try a line with a character between the list and the code block, and it worked! That started me wondering if it had to do with md syntax/behavior, and not anything about ravel or slidify.

I really wish I'd stumbled on that discovery sooner, as this whole issue has simply been due to inherent markdown behavior. It all came down to my happening to choose a list as one way to show Org syntax, followed by trying to display it verbatim immediately afterwards.

A suggested workaround is to have a line containing <!-- --> in between the list and the code block.

Closing, sorry for the noise, and sincere thanks for persevering on the issue!