diff --git a/.githooks/post-merge b/.githooks/post-merge index 9a4e32a..9e41132 100755 --- 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: diff --git a/.gitignore b/.gitignore index a53de0d..960959d 100644 --- 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 diff --git a/Makefile b/Makefile index 7e888c2..a060de3 100644 --- a/Makefile +++ b/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")' diff --git a/README.org b/README.org index 1a86346..e730855 100644 --- 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: