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.

.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:

.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

Makefile

@@ -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")'

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
+1. How to tangle (or export) source blocks from [[info:org#Top][org]] files. This file contains
-   files =early-init.el=, =init.el=, =latexmkrc=, =org-store-link=, and
+   source blocks to produce the files =early-init.el=, =init.el=, =latexmkrc=,
- =example.py= for tangling.
+ =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
+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 a document.  An example of my work-flow are the steps how
+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
+* Local variables linking back to [[#sec:latex-compile-display-loop][LaTeX compile-display-loop]]       :noexport:
-=html= and =pdf= files) below shows how to use the =latexmkrc= file in section
-[[#sec:latexmk-compilation-loop][usage: latexmk compilation loop]].
 
-# 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: