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, 15 Aug 2016 17:34:48 +0200 Message-ID: <87fuq6ujtz.fsf@saiph.selenimh> References: <871t1z9ye1.fsf@saiph.selenimh> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48658) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bZJud-0003zY-O9 for emacs-orgmode@gnu.org; Mon, 15 Aug 2016 11:34:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bZJub-0004nU-6Z for emacs-orgmode@gnu.org; Mon, 15 Aug 2016 11:34:50 -0400 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:59465) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bZJua-0004nO-Px for emacs-orgmode@gnu.org; Mon, 15 Aug 2016 11:34:49 -0400 In-Reply-To: (Jake Romer's message of "Sat, 13 Aug 2016 13:52:56 -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'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 > 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: > > 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 "%s" > + "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 > 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