From 6c94396a6114c66768c7f24777ce33c13f0cd563 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Thu, 19 Jul 2018 21:59:24 -0400 Subject: [PATCH] Don't run Pandoc at all if neither nocite nor citation keys present --- doc/ox-hugo-manual.org | 24 ++++++++++++-------- ox-hugo-pandoc-cite.el | 51 +++++++++++++++++++++++++++++++++++------- ox-hugo.el | 7 +++--- 3 files changed, 62 insertions(+), 20 deletions(-) diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 25d555f..bb0307c 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -2074,18 +2074,24 @@ front-matter keys"/ in {{{ox-hugo-test-file}}}. :PROPERTIES: :EXPORT_FILE_NAME: pandoc-citations :END: -[[https://pandoc.org/][Pandoc]] based citation parsing is enabled by setting the -~#+hugo_pandoc_citations:~ keyword or ~:EXPORT_HUGO_PANDOC_CITATIONS:~ -subtree property to ~t~. +The [[https://pandoc.org/][Pandoc]] Citations are prefixed with the *@* character. If the +citation is ~@foo~, that particular /foo/ reference much be present in +one of the specified bibliography files. #+begin_note Users need to have the ~pandoc~ executable present in their ~PATH~. #+end_note +**** Enabling +Pandoc based citation parsing is enabled by setting the +~#+hugo_pandoc_citations:~ keyword or ~:EXPORT_HUGO_PANDOC_CITATIONS:~ +subtree property to ~t~. -The Pandoc Citations are prefixed with the *@* character. If the -citation is ~@foo~, that particular /foo/ reference much be present in -one of the specified bibliography files. - +#+begin_note +If a post has neither [[* Nocite][~nocite~]] meta-data, nor valid citation keys +(~@foo~), the Pandoc parsing step is skipped *even if* the above +Pandoc Citations parsing option is enabled. +#+end_note +**** Bibliography Bibliography files (~example.bib~) are specified using the ~#+bibliography:~ keyword or ~:EXPORT_BIBLIOGRAPHY:~ subtree property. *It is mandatory to specify at least one bibliography file.* @@ -2093,12 +2099,12 @@ property. *It is mandatory to specify at least one bibliography file.* Multiple comma-separated bibliography files can be specified. /Note that the path to these files should be relative to the Org file directory./ - +**** Nocite ~nocite~ is a special Pandoc-specific meta-data which can be used to add extra citations even when they are not referenced in the post. It is set like any other list-type custom front-matter parameter (i.e. ~:LIST_PARAM '(ELEMENT1 ELEMENT2)~). - +**** Example Here is a mini-example using Pandoc Citations: #+begin_src org ,* Citations Example diff --git a/ox-hugo-pandoc-cite.el b/ox-hugo-pandoc-cite.el index 1fd1e81..094394d 100644 --- a/ox-hugo-pandoc-cite.el +++ b/ox-hugo-pandoc-cite.el @@ -151,20 +151,55 @@ LOFFSET is the offset added to the base level of 1 for headings." (buffer-substring-no-properties (point-min) (point-max))))) (defun org-hugo-pandoc-cite--parse-citations-maybe (info) - "Check if Pandoc needs to be run to parse citations. + "Check if Pandoc needs to be run to parse citations; and run it. INFO is a plist used as a communication channel." ;; (message "pandoc citations keyword: %S" ;; (org-hugo--plist-get-true-p info :hugo-pandoc-citations)) ;; (message "pandoc citations prop: %S" ;; (org-entry-get nil "EXPORT_HUGO_PANDOC_CITATIONS" :inherit)) - (let ((orig-outfile (plist-get info :outfile))) - (when (and orig-outfile - (or (org-entry-get nil "EXPORT_HUGO_PANDOC_CITATIONS" :inherit) - (org-hugo--plist-get-true-p info :hugo-pandoc-citations))) - (unless (executable-find "pandoc") - (user-error "[ox-hugo] pandoc executable not found in PATH")) - (org-hugo-pandoc-cite--parse-citations info orig-outfile)))) + (let* ((orig-outfile (plist-get info :outfile)) + (pandoc-enabled (or (org-entry-get nil "EXPORT_HUGO_PANDOC_CITATIONS" :inherit) + (org-hugo--plist-get-true-p info :hugo-pandoc-citations))) + (fm (plist-get info :front-matter)) + (has-nocite (string-match-p "^nocite\\(:\\| =\\) " fm)) + (orig-outfile-contents (with-temp-buffer + (insert-file-contents orig-outfile) + (buffer-substring-no-properties + (point-min) (point-max)))) + ;; http://pandoc.org/MANUAL.html#citations + ;; Each citation must have a key, composed of `@' + the + ;; citation identifier from the database, and may optionally + ;; have a prefix, a locator, and a suffix. The citation key + ;; must begin with a letter, digit, or _, and may contain + ;; alphanumerics, _, and internal punctuation characters + ;; (:.#$%&-+?<>~/). + ;; A minus sign (-) before the @ will suppress mention of the + ;; author in the citation. + (valid-citation-key-char-regexp "a-zA-Z0-9_:.#$%&+?<>~/-") + (citation-key-regexp (concat "[^" valid-citation-key-char-regexp "]" + "\\(-?@[a-zA-Z0-9_]" + "[" valid-citation-key-char-regexp "]+\\)")) + (has-@ (string-match-p citation-key-regexp orig-outfile-contents))) + (when pandoc-enabled + ;; Either the nocite front-matter should be there, or the + ;; citation keys should be present in the `orig-outfile'. + (if (or has-nocite has-@) + (progn + (unless (executable-find "pandoc") + (user-error "[ox-hugo] pandoc executable not found in PATH")) + (org-hugo-pandoc-cite--parse-citations info orig-outfile)) + ;; Otherwise restore the front-matter format to TOML if set so + ;; by the user. + (unless (string= fm org-hugo--fm-yaml) + (let* ((orig-contents-only + (replace-regexp-in-string + ;; The `orig-contents-only' will always be in YAML. + ;; Delete that first. + "\\`---\n\\(.\\|\n\\)+\n---\n" "" orig-outfile-contents)) + (toml-fm-plus-orig-contents (concat fm orig-contents-only))) + ;; (message "[ox-hugo-pandoc-cite] orig-contents-only: %S" orig-contents-only) + (write-region toml-fm-plus-orig-contents nil orig-outfile))))))) (defun org-hugo-pandoc-cite--parse-citations (info orig-outfile) "Parse Pandoc Citations in ORIG-OUTFILE and update that file. diff --git a/ox-hugo.el b/ox-hugo.el index 99ee969..118be3c 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -978,9 +978,10 @@ This is an internal function." (setq org-hugo--section nil) (setq org-hugo--bundle nil) (advice-remove 'org-babel-exp-code #'org-hugo--org-babel-exp-code) - (plist-put info :outfile outfile) - (plist-put info :front-matter org-hugo--fm) - (org-hugo-pandoc-cite--parse-citations-maybe info) + (when outfile + (plist-put info :outfile outfile) + (plist-put info :front-matter org-hugo--fm) + (org-hugo-pandoc-cite--parse-citations-maybe info)) (setq org-hugo--fm nil) (setq org-hugo--fm-yaml nil))