In an export transcoder, when should I use org-element-property to get values vs. the contents parameter

In an export transcoder, when should I use org-element-property to get values vs. the contents parameter

[Rohit Patnaik]

I'm looking at function that handles transcoding inline code and verbatim text
in ox-md: 

(defun org-md-verbatim (verbatim _contents _info)
  "Transcode VERBATIM object into Markdown format.
CONTENTS is nil.  INFO is a plist used as a communication
channel."
  (let ((value (org-element-property :value verbatim)))
    (format (cond ((not (string-match "`" value)) "`%s`")
		  ((or (string-prefix-p "`" value)
		       (string-suffix-p "`" value))
		   "`` %s ``")
		  (t "``%s``"))
	    value)))

My question is, why does org-md-verbatim use org-element-property to retrieve
the text to be transcoded, when org-md-bold and org-md-italic use the contents
parameter. In other words, couldn't the function be simplified to something like
this:

(defun org-md-verbatim (_verbatim contents _info)
  "Transcode VERBATIM object into Markdown format.
CONTENTS is nil.  INFO is a plist used as a communication
channel."
  (format (cond ((not (string-match "`" contents)) "`%s`")
                ((or (string-prefix-p "`" contents)
                     (string-suffix-p "`" contents))
                 "`` %s ``")
                (t "``%s``"))
          contents))

The broader context for my question is that I'm writing my own org exporter, and
I'd like some more clarity on what the distinction is between getting the value
of the element with org-element-property and relying on the export framework to
pass the value to the transcoder via the contents parameter.

Thanks,
Rohit

Re: In an export transcoder, when should I use org-element-property to get values vs. the contents parameter

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

> My question is, why does org-md-verbatim use org-element-property to retrieve
> the text to be transcoded, when org-md-bold and org-md-italic use the contents
> parameter. In other words, couldn't the function be simplified to something like
> this:

You can't because the contents of verbatim element is always nil.
Verbatim cannot contain other objects inside. All the objects that can
contain other objects are listed in org-element-object-containers.

> The broader context for my question is that I'm writing my own org exporter, and
> I'd like some more clarity on what the distinction is between getting the value
> of the element with org-element-property and relying on the export framework to
> pass the value to the transcoder via the contents parameter.

Any Org element is structured as (type properties contents). However,
not all the Org elements have contents (as I mentioned above). Elements
without contents generally store their text in one of the PROPERTIES.
You may find it useful to examine org-element-interpret-TYPE functions
to see how the element text can be recovered from its PROPERTIES and
CONTENTS.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92