From 12c4350787c1d52025a678465ed6aa60a97363bd Mon Sep 17 00:00:00 2001 From: Gerard Vermeulen Date: Thu, 10 Nov 2022 06:58:33 +0100 Subject: [PATCH] Improve readability of the Org customization section --- README.org | 189 +++++++++++++++++++++++++++-------------------------- 1 file changed, 98 insertions(+), 91 deletions(-) diff --git a/README.org b/README.org index 2bd554c..ef85460 100644 --- a/README.org +++ b/README.org @@ -1926,11 +1926,14 @@ zeromatrix zmat"))) (when (ensure-package-installation 'markdown-mode)) #+end_src -** Writing Org files +** Writing [[info:org#Top][Org (info)]] files :PROPERTIES: :CUSTOM_ID: sec:writing-org-files :END: +The [[https://org-babel.readthedocs.io/en/latest/][Org Babel reference card]] complements section [[info:org#Working with Source Code][Working with Source Code (info)]] +of the [[info:org#Top][Org (info)]] manual. + *** [[info:org#Activation][Org activation (info)]] :PROPERTIES: :CUSTOM_ID: sec:activate-org @@ -1953,69 +1956,32 @@ zeromatrix zmat"))) :CUSTOM_ID: sec:customize-org :END: -Listing [[lst:customize-org-babel]], [[lst:customize-org]], [[lst:customize-org-link]], and -[[lst:customize-org-src]] handle basic customization of [[https://orgmode.org/][Org-mode]] variables, where: -1. listing [[lst:customize-org-babel]] selects the Python interpreter by means of +I have split the initial customization of [[https://orgmode.org/][Org-mode]] over several listings. Here, +follows a list detailing and motivating each listing: +1. Listing [[lst:customize-org]] handles basic customization of [[https://orgmode.org/][Org-mode]] variables +2. Listing [[lst:customize-org-babel]] handles basic customization of [[https://orgmode.org/][Org-mode]] + variables specific to [[info:org#Working with Source Code][working with source code (info)]] and it selects the + Python interpreter by means of src_emacs-lisp{(choose-common-python-interpreter)} defined in listing [[lst:choose-common-python-interpreter]]. -2. listing [[lst:customize-org-src]] facilitates [[info:org#Editing Source Code][editing Python source code blocks]] and - provides a function to remove the indentation of all =org-src-mode= blocks - without =-i= switch. -Listing [[lst:configure-org-mode-map]] extends the =org-mode-map= with useful -key-bindings. Listing [[lst:customize-ob-python]] allows to pretty-print Python -session source block values with [[https://github.com/psf/black#readme][black]] instead of [[https://docs.python.org/3/library/pprint.html][pprint]]. Listing -[[lst:customize-org-export-ui]] selects the expert user interface for export -dispatching. Listing [[lst:customize-org-for-lualatex-export]], and -[[lst:customize-ox-latex-for-lualatex-export]] configure [[https://orgmode.org/][Org-mode]] for export to -LuaLaTeX. Listing [[lst:customize-org-link]] configures =org-link= to use relative -file path links. -Listing [[lst:customize-org-latex-classes]] defines [[info:org#LaTeX -specificexportsettings][org-latex-classes (info)]] for backward -compatibility. See table [[tab:org-latex-class-tag-placeholder]] and type {{{kbd(C-h -v org-latex-classes)}}} for an explanation of the code in listing -[[lst:customize-org-latex-classes]]. - -#+attr_latex: :booktabs yes :float table -#+caption[The relation tag-placeholder in listing [[lst:customize-org-latex-classes]]]: -#+caption: The relation tag-placeholder in listing [[lst:customize-org-latex-classes]]. -#+name: tab:org-latex-class-tag-placeholder -| tag | placeholder | -|-----+-----------------------| -| +1 | [DEFAULT-PACKAGES] | -| +2 | [PACKAGES] | -| +3 | [EXTRA] | -| -1 | [NO-DEFAULT-PACKAGES] | -| -2 | [NO-PACKAGES] | -| -3 | [NO-EXTRA] | - -#+caption[Customize =org-babel=]: -#+caption: Customize =org-babel=. -#+name: lst:customize-org-babel -#+begin_src emacs-lisp -(with-eval-after-load 'ob-core - (custom-set-variables - '(org-confirm-babel-evaluate nil))) - -(with-eval-after-load 'ob-latex - (custom-set-variables - '(org-babel-latex-preamble - (lambda (_) - "\\documentclass[preview]{standalone}\n")) - '(org-babel-latex-begin-env - (lambda (_) - "\\begin{document}\n")) - '(org-babel-latex-end-env - (lambda (_) - "\\end{document}\n")))) - -(with-eval-after-load 'ob-lisp - (with-eval-after-load 'sly - (custom-set-variables - '(org-babel-lisp-eval-fn #'sly-eval)))) - -(with-eval-after-load 'ob-python - (choose-common-python-interpreter 'python)) -#+end_src +3. Listing [[lst:customize-org-link]] handle basic customization of [[https://orgmode.org/][Org-mode]] + variables specific to [[info:org#Hyperlinks][hyperlinks (info)]]. +4. Listing [[lst:configure-org-mode-map]] extends the =org-mode-map= with useful + key-bindings. +5. Listing [[lst:customize-org-src]] facilitates [[info:org#Editing Source Code][editing Python source code blocks]], + and it provides a function to remove the indentation of all =org-src-mode= + blocks without =-i= switch. +6. Listing [[lst:customize-ob-python]] allows to pretty-print Python session source + block values with [[https://github.com/psf/black#readme][black]] instead of [[https://docs.python.org/3/library/pprint.html][pprint]]. +7. Listing [[lst:customize-org-export-ui]] selects the =non-intrusive= expert user + interface for export dispatching. +8. Listing [[lst:customize-org-for-lualatex-export]] and + [[lst:customize-ox-latex-for-lualatex-export]] configure [[https://orgmode.org/][Org-mode]] to generate + output for the LuaLaTeX compiler. +9. Listing [[lst:customize-org-latex-classes]] defines [[info:org#LaTeXspecificexportsettings][org-latex-classes (info)]] for + backward compatibility. See table [[tab:org-latex-class-tag-placeholder]] and + type {{{kbd(C-hv org-latex-classes)}}} for an explanation of the code in + listing [[lst:customize-org-latex-classes]]. #+caption[Customize =Org=]: #+caption: Customize =Org=. @@ -2067,6 +2033,34 @@ v org-latex-classes)}}} for an explanation of the code in listing ("v" . "verse"))))) #+end_src +#+caption[Customize =org-babel=]: +#+caption: Customize =org-babel=. +#+name: lst:customize-org-babel +#+begin_src emacs-lisp +(with-eval-after-load 'ob-core + (custom-set-variables + '(org-confirm-babel-evaluate nil))) + +(with-eval-after-load 'ob-latex + (custom-set-variables + '(org-babel-latex-preamble + (lambda (_) + "\\documentclass[preview]{standalone}\n")) + '(org-babel-latex-begin-env + (lambda (_) + "\\begin{document}\n")) + '(org-babel-latex-end-env + (lambda (_) + "\\end{document}\n")))) + +(with-eval-after-load 'ob-lisp + (with-eval-after-load 'sly + (custom-set-variables + '(org-babel-lisp-eval-fn #'sly-eval)))) + +(with-eval-after-load 'ob-python + (choose-common-python-interpreter 'python)) +#+end_src #+caption[Customize =org-link=]: #+caption: Customize =org-link=. @@ -2077,35 +2071,6 @@ v org-latex-classes)}}} for an explanation of the code in listing '(org-link-file-path-type 'relative))) #+end_src -#+caption[Customize =org-src=]: -#+caption: Customize =org-src=. -#+name: lst:customize-org-src -#+begin_src emacs-lisp -(with-eval-after-load 'emacs - (custom-set-variables - '(org-src-preserve-indentation t)) - - (declare-function org-babel-map-src-blocks "ext:ob-core" (file &rest body)) - (declare-function org-do-remove-indentation "ext:org-macs" (n skip-fl)) - - (defun zero-all-org-src-blocks-indentation () - "Remove the indentation of all `org-src-mode' blocks without `-i' switch." - (interactive) - (when (derived-mode-p 'org-mode) - (save-excursion - (org-babel-map-src-blocks - nil - (unless (or (string-match "-i " switches) - (string-match (rx (or bos bol) graph) body)) - (when-let ((new (with-temp-buffer - (insert body) - (org-do-remove-indentation) - (buffer-string)))) - (goto-char beg-body) - (delete-region beg-body end-body) - (insert new)))))))) -#+end_src - #+caption[Configure =org-mode-map=]: #+caption: Configure =org-mode-map=. #+name: lst:configure-org-mode-map @@ -2152,6 +2117,35 @@ When called twice, replace the previously inserted \\(\\) by one $." (define-key org-mode-map (kbd "M-q") #'org-fill-paragraph))) #+end_src +#+caption[Customize =org-src=]: +#+caption: Customize =org-src=. +#+name: lst:customize-org-src +#+begin_src emacs-lisp +(with-eval-after-load 'emacs + (custom-set-variables + '(org-src-preserve-indentation t)) + + (declare-function org-babel-map-src-blocks "ext:ob-core" (file &rest body)) + (declare-function org-do-remove-indentation "ext:org-macs" (n skip-fl)) + + (defun zero-all-org-src-blocks-indentation () + "Remove the indentation of all `org-src-mode' blocks without `-i' switch." + (interactive) + (when (derived-mode-p 'org-mode) + (save-excursion + (org-babel-map-src-blocks + nil + (unless (or (string-match "-i " switches) + (string-match (rx (or bos bol) graph) body)) + (when-let ((new (with-temp-buffer + (insert body) + (org-do-remove-indentation) + (buffer-string)))) + (goto-char beg-body) + (delete-region beg-body end-body) + (insert new)))))))) +#+end_src + #+caption[Customize =ob-python=]: #+caption: Customize =ob-python=. #+name: lst:customize-ob-python @@ -2329,6 +2323,19 @@ else: ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))))))) #+end_src +#+attr_latex: :booktabs yes :float table +#+caption[The relation tag-placeholder in listing [[lst:customize-org-latex-classes]]]: +#+caption: The relation tag-placeholder in listing [[lst:customize-org-latex-classes]]. +#+name: tab:org-latex-class-tag-placeholder +| tag | placeholder | +|-----+-----------------------| +| +1 | [DEFAULT-PACKAGES] | +| +2 | [PACKAGES] | +| +3 | [EXTRA] | +| -1 | [NO-DEFAULT-PACKAGES] | +| -2 | [NO-PACKAGES] | +| -3 | [NO-EXTRA] | + *** [[https://github.com/bdarcus/citar][Citar: citing bibliography]] with [[https://orgmode.org/][Org Mode]] :PROPERTIES: :CUSTOM_ID: sec:citing-bibliography