From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: ox-md.el: Export TOC and Footnotes as Markdown rather than HTML Date: Mon, 08 Aug 2016 15:35:34 +0200 Message-ID: <871t1z9ye1.fsf@saiph.selenimh> References: Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:60765) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bWkiO-0001V1-4F for emacs-orgmode@gnu.org; Mon, 08 Aug 2016 09:35:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bWkiL-0007pF-Ma for emacs-orgmode@gnu.org; Mon, 08 Aug 2016 09:35:35 -0400 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:49060) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bWkiL-0007oR-6h for emacs-orgmode@gnu.org; Mon, 08 Aug 2016 09:35:33 -0400 In-Reply-To: (Jake Romer's message of "Sun, 7 Aug 2016 21:31:37 -0400") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Jake Romer Cc: emacs-orgmode@gnu.org Hello, Jake Romer 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 > 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 "%s" > + "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 > 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