Improve the work-flow demonstration features

* Evaluate named source blocks automatically. This requires adapting the Makefile and the post-merge hook. * Add and tweak functions stolen from ox-extra.el. * Add a quick-start section. * Complete the .gitignore file.
2021-11-30 09:35:15 +01:00 · 2021-11-30 09:35:15 +01:00 · f56531b7bc
commit f56531b7bc
parent 32473562df
4 changed files with 100 additions and 25 deletions
--- a/.githooks/post-merge
+++ b/.githooks/post-merge
@ -1,9 +1,14 @@
 #!/usr/bin/env sh

-job="$(git diff-tree -r --name-only --no-commit-id HEAD^ HEAD README.org)"
+# See: https://gist.github.com/sindresorhus/7996717
+
+job="$(git diff-tree -r --name-only --no-commit-id HEAD^ HEAD -- README.org)"

 if [ -n "$job" ]; then
-  emacs --batch --eval "(require 'org)" --eval "(org-babel-tangle-file \"$job\")"
+  emacs --batch \
+        --eval "(add-to-list 'safe-local-eval-forms '(apply 'my-org-eval-blocks-named '(\"emacs-lisp-setup\")))" \
+        --eval "(require 'org)" \
+        --eval "(org-babel-tangle-file \"$job\")"
 fi

 # Local Variables:
--- a/.gitignore
+++ b/.gitignore
@ -1,7 +1,23 @@
+*.aux
+*.bbl
+*.bcf
+*.blg
 *.el
+*.fdb_latexmk
+*.fls
+*.html
+*.log
+*.out
+*.pdf
 *.py
+*.run.xml
+*.tex
+*.toc
+
 latexmkrc
 org-store-link
+
+/_minted-README
 /eln-cache
 /elpa-*
 /quelpa
--- a/7
+++ b/7
@ -1,3 +1,8 @@
+# See:
+# https://www.viget.com/articles/two-ways-to-share-git-hooks-with-your-team/
+# https://emacs.stackexchange.com/questions/27126/is-it-possible-to-org-bable-tangle-an-org-file-from-the-command-line
 init:
 	git config core.hooksPath .githooks
-	emacs --batch --eval "(require 'org)" --eval '(org-babel-tangle-file "README.org")'
+	emacs --batch \
+	--eval "(add-to-list 'safe-local-eval-forms '(apply 'my-org-eval-blocks-named '(\"emacs-lisp-setup\")))" \
+	--eval "(require 'org)" --eval '(org-babel-tangle-file "README.org")'
--- a/README.org
+++ b/README.org
@ -27,6 +27,23 @@
 #+latex_header:   verbose,
 #+latex_header: ]{geometry}

+* Quick start
+:PROPERTIES:
+:CUSTOM_ID: sec:quick-start
+:END:
+
+Backup your =~/.emacs.d= directory to execute the following commands:
+#+begin_src shell :noeval :tangle no
+  cd ~
+  git clone ccdr@mercury.grenoble.cnrs.fr:SERVER/.emacs.d
+  make --directory=.emacs.d init
+#+end_src
+After its invokation, Emacs will install a minimal set of packages.  Now, you
+have the option to install all optional packages using the command
+=my-install-optional-packages=, but you can do this any time, or you can install
+any package using the command =package-install= whenever you like.  Quit Emacs
+and invoke Emacs again.
+
 * Introduction
 :PROPERTIES:
 :CUSTOM_ID: sec:introduction
@ -39,9 +56,9 @@ format of the presentations is [[https://www.latex-project.org/][LaTeX]].

 This [[info:org#Top][org]] file (more precisely the original [[info:org#Top][org]] source file of this file)
 illustrates my work-flow by showing:
-1. How tangle (or export) source blocks from [[info:org#Top][org]] files. This file contains the
-   files =early-init.el=, =init.el=, =latexmkrc=, =org-store-link=, and
- =example.py= for tangling.
+1. How to tangle (or export) source blocks from [[info:org#Top][org]] files. This file contains
+   source blocks to produce the files =early-init.el=, =init.el=, =latexmkrc=,
+ =org-store-link=, and =example.py= by tangling.
 2. How to export [[info:org#Top][org]] files to other formats such as [[https://en.wikipedia.org/wiki/HTML][HTML]], [[https://www.latex-project.org/][LaTeX]], and [[https://en.wikipedia.org/wiki/PDF][PDF]].
 3. How [[info:org#Hyperlinks][org hyperlinks (info)]] allow to link inside and outside [[info:org#Top][Org Mode]]: hover
   over or click on the links to experiment.
@ -59,15 +76,15 @@ The [[https://github.com/andras-simonyi/citeproc-el][citeproc]] extension packag
 capabilities to [[https://github.com/bdarcus/citar][citar]] and [[https://orgmode.org/][Org Mode]].

 The [[https://github.com/vedang/pdf-tools][pdf-tools]] extension package renders [[https://en.wikipedia.org/wiki/PDF][PDF]] file with the possibility to
-annotate the file or to click on anchors in the file that link back to the
-original [[https://www.latex-project.org/][LaTeX]] file of a document.  An example of my work-flow are the steps how
+annotate the file or to click on anchors in the [[https://en.wikipedia.org/wiki/PDF][PDF]] file that link back to the
+original [[https://www.latex-project.org/][LaTeX]] file of the document.  An example of my work-flow are the steps
 to convert this [[info:org#Top][org]] file to [[https://en.wikipedia.org/wiki/PDF][PDF]] and to see the result with [[https://github.com/vedang/pdf-tools][pdf-tools]] in Emacs:
 execute the commands ~pdf-tools-install~, ~org-babel-tangle~,
 ~org-latex-export-latex-to-latex~, and ~compile~.  This sets up an infinite
 [[https://www.latex-project.org/][LaTeX]] compilation loop to update and redisplay the [[https://en.wikipedia.org/wiki/PDF][PDF]] file after excution of
 the ~org-latex-export-latex-to-latex~ command in this buffer.

-[[info:emacs#Top][Emac (info)]]
+[[info:emacs#Top][Emacs (info)]]


 Here follows a list of interesting Emacs configurations:
@ -94,7 +111,7 @@ Here follows a list of interesting Emacs configurations:
 The err
 [[#sec:package-bootstrapping][Package Bootstrapping]]

-qLF FF
+The [[info:elisp#Basic Char Syntax][Basic Char Syntax (info)]] page

 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src emacs-lisp :tangle early-init.el
@ -105,7 +122,7 @@ qLF FF
  (setq-default load-prefer-newer t)

  (provide 'early-init)
-  ;; Emacs looks for "Local variables:" after the last "C-q C-j C-q C-l".
+  ;; Emacs looks for "Local variables:" after the last "?\n?\f".
  
  ;; Local Variables:
  ;; indent-tabs-mode: nil
@ -342,15 +359,17 @@ command =emacsclient=.
      (add-hook 'after-init-hook #'server-start)))
 #+end_src

-** [[https://www.personal.psu.edu/jcc8/latexmk/][Usage: latexmk compilation loop]]
+** LaTeX compile-display-loop
 :PROPERTIES:
-:CUSTOM_ID: sec:latexmk-compilation-loop
+:CUSTOM_ID: sec:latex-compile-display-loop
 :END:

 The =latexmk= resource file in the next source code block shows how to use
 =emacsclient= to (re)display the PDF file in Emacs after each succesful
 (re)compilation on condition that the settings of the ~compile-command~ local
-variable in section [[#sec:compile-with-latexmk][compile with latexmk]] are compatible.
+variable in section are compatible.  The local variable ~compile-command~ in
+section [[#sec:local-variables][Local Variables]] (only visible in =org= files, but not in =html= and
+=pdf= files) shows how to use the =latexmkrc= file..

 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src perl :tangle latexmkrc
@ -366,14 +385,14 @@ variable in section [[#sec:compile-with-latexmk][compile with latexmk]] are comp
      my ($name, $path) = fileparse( $$Psource );
      return system "makeglossaries -d '$path' '$name'";
  }
-  # Emacs looks for "Local variables:" after the last "C-q C-j C-q C-l".
+  # Emacs looks for "Local variables:" after the last "?\n?\f".
  
  # Local Variables:
  # mode: perl
  # End:
 #+end_src

-** [[https://qutebrowser.org/doc/userscripts.html][Usage: qutebrowser userscript]]
+** [[https://qutebrowser.org/doc/userscripts.html][Qutebrowser userscript]]

 The next block contains an userscript that sends a [[info:org#The store-link protocol][store-link org-protocol]]
 message with the url and the title from [[https://qutebrowser.org][qutebrowser]] to =emacsclient=.  The
@ -704,7 +723,27 @@ Stolen from [[https://git.sr.ht/~bzg/org-contrib/tree/master/item/lisp/ox-extra.
 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src emacs-lisp
  (with-eval-after-load 'ox
+    (defun my-org-export-ignore-headline-filter (_)
+      "Ignore all headlines with the \":ignore:\" tag."
+      (org-map-entries
+       (lambda ()
+         (delete-region (point) (line-beginning-position 2)))
+       ":ignore:"))
+
    (defun my-org-latex-header-blocks-filter (backend)
+      "Convert marked LaTeX export blocks to \"#+latex_header: \" lines.
+  The marker is a line \"#+header: :header yes\" preceding the block.
+
+  For instance, the LaTeX export block
+
+  ,#+header: :header yes
+  ,#+begin_export latex
+  % This line converts to a LaTeX header line.
+  ,#+end_export
+
+  converts to
+
+  \"#+latex_header: % This line converts to a LaTeX header line.\"."
      (when (org-export-derived-backend-p backend 'latex)
        (let ((blocks
               (org-element-map
@ -730,7 +769,18 @@ Stolen from [[https://git.sr.ht/~bzg/org-contrib/tree/master/item/lisp/ox-extra.
                ;; positions earlier in the file.
                (reverse blocks)))))

-    (add-hook 'org-latex-header-blocks-filter #'my-org-latex-header-blocks-filter))
+    (defun my-activate-buffer-local-org-export-filters ()
+      "Activate my export filters locally in the current buffer."
+      (add-hook 'org-export-before-parsing-hook
+                #'my-org-export-ignore-headline-filter nil 'local)
+      (add-hook 'org-export-before-parsing-hook
+                #'my-org-latex-header-blocks-filter nil 'local)))
+#+end_src
+
+#+name: emacs-lisp-setup
+#+begin_src emacs-lisp :tangle no
+  (with-eval-after-load 'ox
+    (my-activate-buffer-local-org-export-filters))
 #+end_src

 #+attr_latex: :options bgcolor=LightGoldenrodYellow
@ -804,7 +854,7 @@ Stolen from [[https://git.sr.ht/~bzg/org-contrib/tree/master/item/lisp/ox-extra.
            (goto-char (org-element-property :begin block))
            (org-babel-execute-src-block)))))

-  ;; Emacs looks for "Local variables:" after the last "C-q C-j C-q C-l".
+  ;; Emacs looks for "Local variables:" after the last "?\n?\f".
  (add-to-list 'safe-local-eval-forms
               '(apply 'my-org-eval-blocks-named '("emacs-lisp-setup")))
  (add-to-list 'safe-local-eval-forms
@ -1124,7 +1174,7 @@ instance those themes fail to display ~hl-line-mode~ with Emacs-27.2 on Darwin.
 #+begin_src emacs-lisp
  (provide 'init)

-  ;; Emacs looks for "Local variables:" after the last "C-q C-j C-q C-l".
+  ;; Emacs looks for "Local variables:" after the last "?\n?\f".
  
  ;; Local Variables:
  ;; indent-tabs-mode: nil
@ -1132,18 +1182,17 @@ instance those themes fail to display ~hl-line-mode~ with Emacs-27.2 on Darwin.
  ;;; init.el ends here
 #+end_src

-* Compile with [[https://www.personal.psu.edu/jcc8/latexmk/][latexmk]]
+* Local variables anchor                                            :ignored:
 :PROPERTIES:
-:CUSTOM_ID: sec:compile-with-latexmk
+:CUSTOM_ID: sec:local-variables
 :END:

-The local variable ~compile-command~ (only visible in =org= files, but not in
-=html= and =pdf= files) below shows how to use the =latexmkrc= file in section
-[[#sec:latexmk-compilation-loop][usage: latexmk compilation loop]].
+* Local variables linking back to [[#sec:latex-compile-display-loop][LaTeX compile-display-loop]]       :noexport:

-# Emacs looks for "Local variables:" after the last "C-q C-j C-q C-l".
+# Emacs looks for "Local variables:" after the last "\?n\?f".

 # Local Variables:
 # compile-command: "latexmk -interaction=nonstopmode -lualatex -pvc -shell-escape README.tex"
+# eval: (apply 'my-org-eval-blocks-named '("emacs-lisp-setup"))
 # fill-column: 80
 # End: