Re: ox-md.el: Export TOC and Footnotes as Markdown rather than HTML

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Jake Romer <jkrmr.io@gmail.com> writes:

> I notice that in Org 8.3, `org-md-export-as-markdown` and
> `org-md-export-to-markdown` render a document's Table of Contents and
> Footnotes sections as HTML rather than Markdown.

Correct.

> I have a couple of patches that change this behavior so that both are
> rendered as Markdown. I'd love to hear any thoughts or suggestions for
> improvement if you think this would be useful to include in ox-md.el.

That's very interesting. Thank you. Some comments follow.

However, AFAIU, rendering for footnote section is still HTML, albeit
a lightweight one.

> From b64d21e6b5bb35b6446abf37233463e40df040c3 Mon Sep 17 00:00:00 2001
> From: Jake Romer <jkrmr@github.com>
> Date: Sun, 7 Aug 2016 16:04:39 -0400
> Subject: [PATCH 1/2] Export Footnotes section as Markdown

The commit message has to contain the name of new and modified
functions. See commit log for examples.
>
> ---
>  ox-md.el | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 72 insertions(+), 2 deletions(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 0aaade6..865e123 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -50,6 +50,20 @@ This variable can be set to either `atx' or `setext'."
>  	  (const :tag "Use \"atx\" style" atx)
>  	  (const :tag "Use \"Setext\" style" setext)))
>
> +;;;; Footnotes
> +
> +(defcustom org-md-footnote-format "<sup>%s</sup>"
> +  "The format for the footnote reference.
> +%s will be replaced by the footnote reference itself."
> +  :group 'org-export-md
> +  :type 'string)
> +

> +(defcustom org-md-footnote-section-title "Footnotes"
> +  "The title for the Footnotes section.
> +Example: `Footnotes', `References', `Sources', etc."
> +  :group 'org-export-md
> +  :type 'string)

I suggest to ignore the variable above and use an equivalent of

   (org-html--translate "Table of Contents" info)

instead.

> +(defun org-md-footnote-section-header (info)
> +  "Renders a template for the footnotes section header in the preferred style.
> +INFO is used as a communication channel."
> +  (let ((style (plist-get info :md-headline-style))
> +        (section-title (plist-get info :md-footnote-section-title)))
> +    (cond
> +     ((equal style 'atx) (format "\n%s %s\n%%s\n" "##" section-title))
> +     ((equal style 'setext) (format "\n%s\n%s\n%%s\n"
> +                                    section-title
> +                                    (make-string (length section-title) ?-))))))

(if (eq style 'atx)
    ...
 ...)

I think this function should not be specific to footnote section header,
i.e., it could factor out the following code in `org-md-headline'

       ;; Use "Setext" style.
       ((eq style 'setext)
	(concat heading tags anchor "\n"
		(make-string (length heading) (if (= level 1) ?= ?-))
		"\n\n"
		contents))
       ;; Use "atx" style.
       (t (concat (make-string level ?#) " " heading tags anchor "\n\n"
		  contents))

> +;;;; Footnotes Section
> +
> +(defun org-md-footnote-section (info)
> +  "Format the footnote section as Markdown.
> +INFO is a plist used as a communication channel."
> +  (let* ((fn-alist (org-export-collect-footnote-definitions info))
> +         (fn-alist
> +          (loop for (n type raw) in fn-alist collect
> +                (cons n (org-trim (org-export-data raw info))))))
> +    (when fn-alist
> +      (format
> +       (org-md-footnote-section-header info)
> +       (format
> +        "\n%s\n"
> +        (mapconcat
> +         (lambda (fn)
> +           (let ((n (car fn)) (def (cdr fn)))
> +             (format
> +              "%s %s\n"
> +              (format
> +               (plist-get info :md-footnote-format)
> +               (org-html--anchor
> +                (format "fn.%d" n)
> +                n
> +                (format " href=\"#fnr.%d\"" n)
> +                info))
> +              def)))
> +         fn-alist
> +         "\n"))))))
> +
> +
>  ;;;; Template
>
>  (defun org-md-inner-template (contents info)
> @@ -474,7 +536,15 @@ CONTENTS is the transcoded contents string.  INFO is a plist
>  holding export options."
>    ;; Make sure CONTENTS is separated from table of contents and
>    ;; footnotes with at least a blank line.
> -  (org-trim (org-html-inner-template (concat "\n" contents "\n") info)))
> +  (let* ((depth (plist-get info :with-toc))
> +         (headlines (and depth (org-export-collect-headlines info depth)))
> +         (toc-string (org-html-toc depth info))
> +         (toc-tail (if headlines "\n\n" ""))
> +         (footnotes (org-md-footnote-section info)))
> +    (org-trim (concat toc-string
> +                      toc-tail
> +                      contents
> +                      footnotes))))
>
>  (defun org-md-template (contents info)
>    "Return complete document string after Markdown conversion.
> --
> 2.9.2
>
>
> From 31091e4bd4b48d1394482a1542e6d90abf04b32d Mon Sep 17 00:00:00 2001
> From: Jake Romer <jkrmr@github.com>
> Date: Sun, 7 Aug 2016 16:15:50 -0400
> Subject: [PATCH 2/2] Export Table of Contents as Markdown

This commit message is also incomplete.
>
> ---
>  ox-md.el | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 865e123..0e2a499 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -528,6 +528,19 @@ INFO is a plist used as a communication channel."
>           "\n"))))))
>
>
> +;;;; Table of contents
> +
> +(defun org-md-format-toc (headline)

Ideally, this should handethe level and a scope so as to handle toc:3
or #+TOC: headlines local.

> +  "Return an appropriate table of contents entry for HEADLINE.
> +INFO is a plist used as a communication channel."
> +  (let* ((title (org-export-data (org-export-get-alt-title headline info) info))
> +         (level (1- (org-element-property :level headline)))
> +         (indent (concat (make-string (* level 2) ? )))

"? " -> "?\s"

Besides, the indentation is slightly wrong. IIRC, 4 spaces are expected
between two levels. See, e.g., `org-md-item'.

> +         (anchor (or (org-element-property :CUSTOM_ID headline)
> +                     (org-export-get-reference headline info))))
> +    (concat indent "- [" title "]" "(#" anchor ")")))
> +
> +
>  ;;;; Template
>
>  (defun org-md-inner-template (contents info)
> @@ -538,7 +551,7 @@ holding export options."
>    ;; footnotes with at least a blank line.
>    (let* ((depth (plist-get info :with-toc))
>           (headlines (and depth (org-export-collect-headlines info depth)))
> -         (toc-string (org-html-toc depth info))
> +         (toc-string (or (mapconcat 'org-md-format-toc headlines "\n") ""))

#'org-md-format-toc

>           (toc-tail (if headlines "\n\n" ""))

Maybe a better abstraction would be to let `org-md-format-toc' handle
toc-string and toc-tail.

Regards,

-- 
Nicolas Goaziou