Add note about pandoc + pandoc-citeproc requirement for devel

Move common Org macros to doc-setupfile.org. Ref: https://github.com/kaushalmodi/ox-hugo/issues/195
8 years ago · 7185780b90
parent fc02bd94c3
commit 7185780b90
5 changed files with 90 additions and 33 deletions
--- a/CONTRIBUTING.org
+++ b/CONTRIBUTING.org
@ -22,6 +22,15 @@ for your future contributions to Emacs too!
 5. Commit *only the .org files*, push branch and create PR.
   - The =.org= → =.md= conversion is done by =ox-hugo= on Netlify.
 * Contribute to code
+#+BEGIN_note
+While the end-user does not need Pandoc installed on their machine, a
+code contributor needs to have both ~pandoc~ and ~pandoc-citeproc~
+installed[fn:-1-local1].
+
+These are needed for ~make md~ and ~make test~ steps to work as they
+use/test the [[https://ox-hugo.scripter.co/doc/pandoc-citations][Pandoc Citations]] feature too.
+#+END_note
+
 1. Clone this repo.
 2. Add/edit the .el files, *tests* in =test/site/content-org/=, and
 *documentation* to =doc/ox-hugo-manual.org=.
@ -35,6 +44,13 @@ for your future contributions to Emacs too!
   step before this step).
 7. Fix your commit(s) if the test fails.. repeat till you succeed.
 8. Push your feature branch and create PR.
+
+[fn:-1-local1] The Pandoc Citations feature was last <2018-08-19 Sun>
+tested with Pandoc version 2.2.2. If you are running an
+older version, the quickest way to install might be to simply download
+the latest release archive from [[https://github.com/jgm/pandoc/releases][Pandoc releases]], extract it and put
+the ~pandoc~ and ~pandoc-citeproc~ binaries in one of the directories
+in your /PATH/.
 * Debug
 If the =ox-hugo= exports do not work as expected, or if you get an
 error backtrace,
@ -49,4 +65,7 @@ error backtrace,
       submitting it.
 * Test
 1. Clone this repo.
-2. Run =make test=.
+2. Ensure that Pandoc (at least version 2.2.2) is
+   installed (more info
+   [[https://ox-hugo.scripter.co/doc/contributing-guide/#contribute-to-code][here]]).
+3. Run =make test=.
--- a/README.org
+++ b/README.org
@ -94,15 +94,16 @@ any export).

 You can do that by adding the below to your config:
 #+BEGIN_SRC emacs-lisp
-(require 'ox-hugo-auto-export) ;If you want the auto-exporting on file saves
 (with-eval-after-load 'ox
  (require 'ox-hugo))
+(require 'ox-hugo-auto-export) ;If you want the auto-exporting on file saves
 #+END_SRC
-If you use =use-package=, you can do the below instead:
+If you use [[https://github.com/jwiegley/use-package][=use-package=]], you can do the below instead:
 #+BEGIN_SRC emacs-lisp
-(use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves
 (use-package ox-hugo
+  :ensure t            ;Auto-install the package from Melpa (optional)
  :after ox)
+(use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves
 #+END_SRC

 Also see the [[https://ox-hugo.scripter.co/doc/auto-export-on-saving][Auto Exporting]] section.
@ -119,17 +120,23 @@ Spacemacs users can choose to add this snippet to their

  ;; ox-hugo config
  (use-package ox-hugo
-    :ensure t                           ;Auto-install the package from Melpa
+    :ensure t            ;Auto-install the package from Melpa (optional)
    :after ox)
  (use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves
  )
 #+END_SRC

+#+BEGIN_note
+You do have _have_ to use the =use-package= version when using
+Spacemacs. That version was used because =use-package= is installed by
+default in Spacemacs.
+#+END_note
 If you do so, you *also need to* add =ox-hugo= to
 =dotspacemacs-additional-packages=.

-/Verified to work on Spacemacs =develop= branch with =spacemacs-base=
-distribution, =emacs= editing style. -- <2017-10-09 Mon>/
+/This was verified to work on Spacemacs =develop= branch with
+=spacemacs-base= distribution, =emacs= editing style. --
+<2017-10-09 Mon>/
 ** Before you export
 Before you export check that these properties are set as you need:
 - HUGO_SECTION :: The default Hugo section name for all the posts.  See
@ -326,7 +333,7 @@ available customization options for this package.
 - If you have a case where you need to have an Org source block
  instead a quote block, and then a source block after that quote
  block (/I know, a very common case../ :wink:), Blackfriday barfs
-  (Blackfriday # [[https://github.com/russross/blackfriday/issues/407][407]]). But we now have a workaround, which /just
+  (Blackfriday #[[https://github.com/russross/blackfriday/issues/407][407]]). But we now have a workaround, which /just
  works/ -- #[[https://github.com/kaushalmodi/ox-hugo/issues/98][98]].
 - Now =ATTR_HTML= above even hyper-linked images works (earlier it
  worked only above non-hyper-linked images).
--- a/doc/doc-setupfile.org
+++ b/doc/doc-setupfile.org
@ -0,0 +1,24 @@
+#+macro: pandoc_version 2.2.2
+
+#+macro: commit commit [[https://github.com/kaushalmodi/ox-hugo/commit/$1][$1]]
+#+macro: issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]]
+#+macro: bfissue Blackfriday #[[https://github.com/russross/blackfriday/issues/$1][$1]]
+#+macro: hugoissue Hugo #[[https://github.com/gohugoio/hugo/issues/$1][$1]]
+#+macro: ox-hugo-test-file  [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][=all-posts.org=]]
+#+macro: user @[[https://github.com/$1][*$1*]]
+#+macro: testtag tests tagged [[https://ox-hugo.scripter.co/test/tags/$1][$1]]
+#+macro: test-search Search the ~ox-hugo~ test site for [[https://ox-hugo.scripter.co/test/search/?q=$1]["$1"]] examples.
+
+# https://scripter.co/latex-in-html/
+#+macro: latex @@html:<span class="latex">L<sup>a</sup>T<sub>e</sub>X</span>@@
+
+# Badges
+#+macro: travis [[https://travis-ci.org/kaushalmodi/ox-hugo][https://travis-ci.org/kaushalmodi/ox-hugo.svg?branch=master]]
+#+macro: melpa [[https://melpa.org/#/ox-hugo][file:https://melpa.org/packages/ox-hugo-badge.svg]]
+#+macro: GPLv3 [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]
+#+macro: gitter [[https://gitter.im/KaushalModi/Lobby][https://badges.gitter.im/KaushalModi/Lobby.svg]]
+#+macro: saythanks [[https://saythanks.io/to/kaushalmodi][https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg]]
+
+# Local Variables:
+# org-hugo-auto-export-on-save: nil
+# End:
--- a/doc/github-files.org
+++ b/doc/github-files.org
@ -1,18 +1,11 @@
 #+title: GitHub Ancillary Files
 #+author: Kaushal Modi

-#+macro: commit commit [[https://github.com/kaushalmodi/ox-hugo/commit/$1][$1]]
-#+macro: issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]]
-#+macro: bfissue Blackfriday # [[https://github.com/russross/blackfriday/issues/$1][$1]]
-#+macro: hugoissue Hugo #[[https://github.com/gohugoio/hugo/issues/$1][$1]]
+#+setupfile: doc-setupfile.org
+
 #+macro: imageclick [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/$1][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/$1]]
 #+macro: doc [[https://ox-hugo.scripter.co/doc/$1][$2]]
-#+macro: travis [[https://travis-ci.org/kaushalmodi/ox-hugo][https://travis-ci.org/kaushalmodi/ox-hugo.svg?branch=master]]
-#+macro: melpa [[https://melpa.org/#/ox-hugo][file:https://melpa.org/packages/ox-hugo-badge.svg]]
-#+macro: GPLv3 [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]
-#+macro: gitter [[https://gitter.im/KaushalModi/Lobby][https://badges.gitter.im/KaushalModi/Lobby.svg]]
-#+macro: saythanks [[https://saythanks.io/to/kaushalmodi][https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg]]
-#+macro: user @[[https://github.com/$1][*$1*]]
+

 * Readme                                                             :readme:
 :PROPERTIES:
--- a/doc/ox-hugo-manual.org
+++ b/doc/ox-hugo-manual.org
@ -6,19 +6,11 @@

 #+options: creator:t author:nil

+#+setupfile: doc-setupfile.org
+
 #+macro: imageclick [[file:./static/images/$1][file:/images/$1]]
-#+macro: commit commit [[https://github.com/kaushalmodi/ox-hugo/commit/$1][$1]]
-#+macro: issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]]
-#+macro: bfissue Blackfriday #[[https://github.com/russross/blackfriday/issues/$1][$1]]
-#+macro: hugoissue Hugo #[[https://github.com/gohugoio/hugo/issues/$1][$1]]
-#+macro: ox-hugo-test-file  [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][=all-posts.org=]]
 #+macro: doc [[/doc/$1][$2]]
-#+macro: user @[[https://github.com/$1][*$1*]]
-#+macro: testtag tests tagged [[https://ox-hugo.scripter.co/test/tags/$1][$1]]
-#+macro: test-search Search the ~ox-hugo~ test site for [[https://ox-hugo.scripter.co/test/search/?q=$1]["$1"]] examples.

-# https://scripter.co/latex-in-html/
-#+macro: latex @@html:<span class="latex">L<sup>a</sup>T<sub>e</sub>X</span>@@

 * Changelog
 :PROPERTIES:
@ -574,6 +566,15 @@ for your future contributions to Emacs too!
 5. Commit *only the .org files*, push branch and create PR.
   - The =.org= → =.md= conversion is done by =ox-hugo= on Netlify.
 *** Contribute to code
+#+begin_note
+While the end-user does not need Pandoc installed on their machine, a
+code contributor needs to have both ~pandoc~ and ~pandoc-citeproc~
+installed[fn:local1].
+
+These are needed for ~make md~ and ~make test~ steps to work as they
+use/test the {{{doc(pandoc-citations,Pandoc Citations)}}} feature too.
+#+end_note
+
 1. Clone this repo.
 2. Add/edit the .el files, *tests* in =test/site/content-org/=, and
 *documentation* to =doc/ox-hugo-manual.org=.
@ -587,6 +588,15 @@ for your future contributions to Emacs too!
   step before this step).
 7. Fix your commit(s) if the test fails.. repeat till you succeed.
 8. Push your feature branch and create PR.
+
+# Below footnote was copied manually from [fn:7] because otherwise
+# #+include of just this subtree does not work.
+[fn:local1] The Pandoc Citations feature was last <2018-08-19 Sun>
+tested with Pandoc version {{{pandoc_version}}}. If you are running an
+older version, the quickest way to install might be to simply download
+the latest release archive from [[https://github.com/jgm/pandoc/releases][Pandoc releases]], extract it and put
+the ~pandoc~ and ~pandoc-citeproc~ binaries in one of the directories
+in your /PATH/.
 ** Debug
 :PROPERTIES:
 :CUSTOM_ID: debug
@ -607,7 +617,10 @@ error backtrace,
 :CUSTOM_ID: test
 :END:
 1. Clone this repo.
-2. Run =make test=.
+2. Ensure that Pandoc (at least version {{{pandoc_version}}}) is
+   installed (more info
+   {{{doc(contributing-guide/#contribute-to-code,here)}}}).
+3. Run =make test=.
 ** Thanks
 :PROPERTIES:
 :CUSTOM_ID: thanks
@ -2356,10 +2369,11 @@ and /mark.js/. -- [[https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1
 * Footnotes

 [fn:7] The Pandoc Citations feature was last <2018-08-19 Sun> tested
-with Pandoc version 2.2.2. If you are running an older version, the
-quickest way to install might be to simply download the latest release
-archive from [[https://github.com/jgm/pandoc/releases][Pandoc releases]], extract it and put the ~pandoc~ and
-~pandoc-citeproc~ binaries in one of the directories in your /PATH/.
+with Pandoc version {{{pandoc_version}}}. If you are running an older
+version, the quickest way to install might be to simply download the
+latest release archive from [[https://github.com/jgm/pandoc/releases][Pandoc releases]], extract it and put the
+~pandoc~ and ~pandoc-citeproc~ binaries in one of the directories in
+your /PATH/.

 [fn:6] If you are still using a Hugo version older than 0.25, update
 now! -- Because that version added support for the awesome