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'm not as familiar with Org's TOC facilities as I should be, so I'll
> update to handle these cases after some research. I want to avoid letting
> these patches get too big, too.

See `org-html-toc' and `org-html--toc-text' for an illustration.

> Here's the patch for generating the footnotes section as Markdown, let me
> know what you think.

It looks good. However, I'm not able to apply them, they seem to be
created from a subdirectory instead of the root dir.

> From 63d985425d3995985bd340fe195d8e25bd7f2cc6 Mon Sep 17 00:00:00 2001
> From: Jake Romer <jkrmr@github.com>
> Date: Sat, 13 Aug 2016 11:45:34 -0400
> Subject: [PATCH 1/4] Extract org-md-headline-title to generate title
>
> In order to generate a headline title in the preferred Markdown
> style ('atx or 'setext), I extracted this bit of logic from
> `org-md-headline'.
>
> Since `org-md-headline' doesn't process the headline for the footnotes
> section, extracting `org-md-headline-title' will allow us to generate
> the Footnote section header in the preferred Markdown style without
> duplicating the logic for doing so.
>
> As an enhancement, `org-md-headline-title' places the anchor tag above
> the section header. This makes it so that in a browser, clicking on the
> TOC entry for that section scrolls to the section header without
> obscuring it.
>
> Example generated section title:
>
>     <a id="orgheadline1"></a>

Great. However, you need to supply modified variables and functions
names in the commit message, e.g.,

* lisp/ox-md.el (org-md-headline-title): New function.
(org-md-headline): Use new function.

>     Summary of Changes
>     ==================
> ---
>  ox-md.el | 37 +++++++++++++++++++++++--------------
>  1 file changed, 23 insertions(+), 14 deletions(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 0aaade6..4bd445c 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -216,20 +216,29 @@ a communication channel."
>  			  (car (last (org-export-get-headline-number
>  				      headline info))))
>  			 "."))))
> -	  (concat bullet (make-string (- 4 (length bullet)) ?\s) heading tags
> -		  "\n\n"
> -		  (and contents
> -		       (replace-regexp-in-string "^" "    " contents)))))
> -       ;; 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))))))
> -
> +	  (concat bullet (make-string (- 4 (length bullet)) ?\s) heading tags "\n\n"
> +		  (and contents (replace-regexp-in-string "^" "    " contents)))))
> +       (t (concat (org-md-headline-title style level title anchor tags) contents))))))
> +
> +
> +;; Headline Title
> +
> +(defun org-md-headline-title (style level title &optional anchor tags)

I suggest to name it `org-md--headline-title' to highlight the fact that
it is an internal function.

> +  "Generate a headline title in the preferred Markdown headline style.
> +STYLE is the preferred style ('atx or 'setext)
> +LEVEL is the header level.
> +TITLE is the headline title.
> +ANCHOR is the HTML anchor tag for the section as a string.
> +TAGS are the tags set on the section."
> +  (let ((anchor-lines (if anchor (concat anchor "\n\n") nil)))

  (and anchor (concat anchor "\n\n"))

> Subject: [PATCH 2/4] Add customizable footnotes-related variables
>
> Taking a cue from `ox-html.el', this patch adds
> `org-md-footnotes-section' and `org-md-footnote-format' to allow user
> customization of the formatting for the footnotes section and individual
> footnotes, respectively.

Ditto (variable names...)

> +(defcustom org-md-footnotes-section "%s%s"
> +  "Format for the footnotes section.

Format string for...

> +The first %s placeholder will be replaced with the localized Footnotes section
> +heading, the second with the contents of the Footnotes section."
> + :group 'org-export-md
> +  :type 'string)

You need to provide additional keywords, i.e.,

  :version "25.1"
  :package-version '(Org . "9.0")


> +(defcustom org-md-footnote-format "<sup>%s</sup>"
> +  "The format for the footnote reference.
> +The %s will be replaced by the footnote reference itself."
> +  :group 'org-export-md
> +  :type 'string)

Ditto.

> Subject: [PATCH 3/4] Add footnote-generating functions
>
> Introduces the following functions:
>
> * `org-md-footnote-formatted'
> * `org-md-footnote-section'

See above.

> +;;;; Footnote Section
> +
> +(defun org-md-footnote-formatted (footnote info)

Suggestion: `org-md--footnote-formatted'

> +  "Formats a single footnote entry FOOTNOTE.

You should specify the data type for FOOTNOTE, i.e., a cons cell 

  (number . definition)

> +INFO is a plist with contextual information."
> +  (let* ((fn-num (car footnote))
> +         (fn-text (cdr footnote))
> +         (fn-format (plist-get info :md-footnote-format))
> +         (fn-anchor (format "fn.%d" fn-num))
> +         (fn-href (format " href=\"#fnr.%d\"" fn-num))
> +         (fn-link-to-ref (org-html--anchor fn-anchor fn-num fn-href info)))
> +    (concat (format fn-format fn-link-to-ref) " " fn-text "\n")))
> +
> +(defun org-md-footnote-section (info)
> +  "Format the footnote section.
> +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)))))

`cl-loop'

> +         (headline-style (plist-get info :md-headline-style))
> +         (section-title (org-html--translate "Footnotes" info)))
> +    (when fn-alist
> +      (format (plist-get info :md-footnotes-section)
> +              (org-md-headline-title headline-style 1 section-title)
> +              (mapconcat #'(lambda (fn) (org-md-footnote-formatted fn info))

  (mapconcat (lambda (fn) ...) ...)

> +                         fn-alist
> +                         "\n")))))
> +
>  ;;;; Template
>  
>  (defun org-md-inner-template (contents info)
> -- 
> 2.9.2
>
>
> From a2e353da09d0db9bbde14641bd94e12e156a143c Mon Sep 17 00:00:00 2001
> From: Jake Romer <jkrmr@github.com>
> Date: Sat, 13 Aug 2016 13:11:26 -0400
> Subject: [PATCH 4/4] Update org-md-inner-template to Markdown footnotes
>
> Updates `org-md-inner-template' to use `org-md-footnotes-section' to
> generate a Markdown version of the footnotes section.
>
> Also appends `:md-footnote-format' and `md-footnotes-section' to the
> exporter :options-alist.
> ---
>  ox-md.el | 15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 19b8912..7d78ff7 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -105,7 +105,10 @@ The %s will be replaced by the footnote reference itself."
>  		     (src-block . org-md-example-block)
>  		     (template . org-md-template)
>  		     (verbatim . org-md-verbatim))
> -  :options-alist '((:md-headline-style nil nil org-md-headline-style)))
> +  :options-alist
> +  '((:md-headline-style nil nil org-md-headline-style)
> +    (:md-footnote-format nil nil org-md-footnote-format)
> +    (:md-footnotes-section nil nil org-md-footnotes-section)))

These new parameters need to be documented in the manual: (info "(org)
Publishing options").

Would you mind providing an entry in ORG-NEWS and send again the patches
from root directory so I can apply them?

Thank you!

Regards,

-- 
Nicolas Goaziou