Compare commits

...

5 Commits

Author SHA1 Message Date
Gerard Vermeulen bfa6be4274 Add more hyperlinks 2022-11-13 14:26:06 +01:00
Gerard Vermeulen 12c4350787 Improve readability of the Org customization section 2022-11-10 06:58:33 +01:00
Gerard Vermeulen d8df141bde Add `zero-all-org-src-blocks-indentation' and improve editing 2022-11-09 12:16:59 +01:00
Gerard Vermeulen c51224323e Add the -i switch to the org-structure-template for Python 2022-11-08 07:32:57 +01:00
Gerard Vermeulen 4311d9a6f9 Improve the Org-mode customization documentation 2022-11-07 12:20:41 +01:00
1 changed files with 152 additions and 108 deletions

View File

@ -879,6 +879,7 @@ defined in this Org file.
(org-inactive-current-time-stamp :nomanual t)
(org-syntax-convert-keyword-case-to-lower :no-manual t)
(smart-latex-engrave-org-source-blocks :no-manual t)
(zero-all-org-src-blocks-indentation :no-manual t)
"Python"
(choose-common-python-interpreter :no-manual t))))
#+end_src
@ -1925,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
@ -1952,100 +1956,32 @@ zeromatrix zmat")))
:CUSTOM_ID: sec:customize-org
:END:
Listing [[lst:customize-org-babel]], [[lst:customize-org]], [[lst:customize-org-link]] does
basic customization of [[https://orgmode.org/][Org-mode]] variables. In addition, listing
[[lst:customize-org-babel]] selects the Python interpreter by means of
src_emacs-lisp{(choose-common-python-interpreter)} defined in listing
[[lst:choose-common-python-interpreter]]. 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-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-link]] configures =org-link= to use relative file path links.
Listing [[lst:customize-org-latex-classes]] defines [[info:org#LaTeX specific export settings][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
#+caption[Customize =ob-python=]:
#+caption: Customize =ob-python=.
#+name: lst:customize-ob-python
#+begin_src emacs-lisp
(with-eval-after-load 'ob-python
(defun org-babel-python-format-session-value-override
(src-file result-file result-params)
"Return Python code to evaluate SRC-FILE and write result to RESULT-FILE.
Use `black' instead of `pprint' when \"pp\" is a member of RESULT-PARAMS."
(format "\
import ast
with open('%s') as __org_babel_python_tmpfile:
__org_babel_python_ast = ast.parse(__org_babel_python_tmpfile.read())
__org_babel_python_final = __org_babel_python_ast.body[-1]
if isinstance(__org_babel_python_final, ast.Expr):
__org_babel_python_ast.body = __org_babel_python_ast.body[:-1]
exec(compile(__org_babel_python_ast, '<string>', 'exec'))
__org_babel_python_final = eval(
compile(ast.Expression(__org_babel_python_final.value), '<string>', 'eval')
)
with open('%s', 'w') as __org_babel_python_tmpfile:
if %s:
import black
__org_babel_python_tmpfile.write(
black.format_str(repr(__org_babel_python_final), mode=black.Mode())
)
else:
__org_babel_python_tmpfile.write(str(__org_babel_python_final))
else:
exec(compile(__org_babel_python_ast, '<string>', 'exec'))
__org_babel_python_final = None"
(org-babel-process-file-name src-file 'noquote)
(org-babel-process-file-name result-file 'noquote)
(if (member "pp" result-params) "True" "False")))
(advice-add 'org-babel-python-format-session-value
:override #'org-babel-python-format-session-value-override))
#+end_src
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]].
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=.
@ -2093,18 +2029,46 @@ else:
("l" . "export latex")
("q" . "quote")
("s" . "src")
("p" . "src python :session")
("p" . "src python -i :session")
("v" . "verse")))))
#+end_src
#+caption[Configure =org-src=]:
#+caption: Configure =org-src=.
#+name: lst:configure-org-src
#+caption[Customize =org-babel=]:
#+caption: Customize =org-babel=.
#+name: lst:customize-org-babel
#+begin_src emacs-lisp
(with-eval-after-load 'org-src
(with-eval-after-load 'ob-core
(custom-set-variables
'(org-src-preserve-indentation t)))
'(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=.
#+name: lst:customize-org-link
#+begin_src emacs-lisp
(with-eval-after-load 'ol
(custom-set-variables
'(org-link-file-path-type 'relative)))
#+end_src
#+caption[Configure =org-mode-map=]:
@ -2153,18 +2117,77 @@ 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-link=]:
#+caption: Customize =org-link=.
#+name: lst:customize-org-link
#+caption[Customize =org-src=]:
#+caption: Customize =org-src=.
#+name: lst:customize-org-src
#+begin_src emacs-lisp
(with-eval-after-load 'ol
(with-eval-after-load 'emacs
(custom-set-variables
'(org-link-file-path-type 'relative)))
'(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
#+begin_src emacs-lisp
(with-eval-after-load 'ob-python
(defun org-babel-python-format-session-value-override
(src-file result-file result-params)
"Return Python code to evaluate SRC-FILE and write result to RESULT-FILE.
Use `black' instead of `pprint' when \"pp\" is a member of RESULT-PARAMS."
(format "\
import ast
with open('%s') as __org_babel_python_tmpfile:
__org_babel_python_ast = ast.parse(__org_babel_python_tmpfile.read())
__org_babel_python_final = __org_babel_python_ast.body[-1]
if isinstance(__org_babel_python_final, ast.Expr):
__org_babel_python_ast.body = __org_babel_python_ast.body[:-1]
exec(compile(__org_babel_python_ast, '<string>', 'exec'))
__org_babel_python_final = eval(
compile(ast.Expression(__org_babel_python_final.value), '<string>', 'eval')
)
with open('%s', 'w') as __org_babel_python_tmpfile:
if %s:
import black
__org_babel_python_tmpfile.write(
black.format_str(repr(__org_babel_python_final), mode=black.Mode())
)
else:
__org_babel_python_tmpfile.write(str(__org_babel_python_final))
else:
exec(compile(__org_babel_python_ast, '<string>', 'exec'))
__org_babel_python_final = None"
(org-babel-process-file-name src-file 'noquote)
(org-babel-process-file-name result-file 'noquote)
(if (member "pp" result-params) "True" "False")))
(advice-add 'org-babel-python-format-session-value
:override #'org-babel-python-format-session-value-override))
#+end_src
#+caption[Customize =org-export=]:
#+caption: Customize =org-export=.
#+name: lst:customize-org-export
#+name: lst:customize-org-export-ui
#+begin_src emacs-lisp
(with-eval-after-load 'ox
(custom-set-variables
@ -2300,6 +2323,19 @@ When called twice, replace the previously inserted \\(\\) by one $."
("\\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
@ -3040,6 +3076,8 @@ define the [[https://orgmode.org/][Org mode]] =kbd= macro in listing
:CUSTOM_ID: sec:file-inclusion-and-noweb
:END:
Note: [[https://list.orgmode.org/87sfisf31o.fsf@posteo.net/][How to include LaTeX packages in a LaTeX export block]].
Listing [[lst:source-file-export-keyword-settings]] shows the preamble lines of this
[[file:README.org]] file. It lists the export keyword settings, the definition of
the [[https://orgmode.org/][Org mode]] =kbd= macro and the source block that generates part of the LaTeX
@ -5042,6 +5080,11 @@ initializes a list of =webjump-sites=.
5. [[https://blog.bitside.pl/posts/gnus/][Gnus]]
6. [[http://www.bobnewell.net/publish/35years/gmailhacks.html][Stupid GMail hacks for Gnus]]
7. [[http://www.bobnewell.net/publish/35years/gnuhacks.html][More stupid Gnus hacks]]
8. [[https://config.phundrak.com/emacs.html][See Mu4e section of Phundrak's Emacs configuration]]
1. [[https://www.passwordstore.org/][Pass: the standard unix password manager]]
1. [[https://www.howtogeek.com/devops/how-to-use-pass-a-command-line-password-manager-for-linux-systems/][How to use Pass, a command-line password manager for Unix systems]]
2. [[https://vitalyparnas.com/guides/pass/][Clever uses of pass, the Unix password manager]]
#+attr_latex: :booktabs yes :float table
#+caption[Gnus key bindings]:
@ -5086,6 +5129,7 @@ initializes a list of =webjump-sites=.
4. [[https://github.com/00riddle00/dotfiles/blob/master/.msmtprc][Msmtp resource file for posteo.net]]
5. [[https://www.devdungeon.com/content/gpg-tutorial][GPG tutorial]]
6. [[https://en.wikipedia.org/wiki/Key_server_(cryptographic)#Keyserver_examples][Cryptographic key server examples]]
7. [[https://rakhim.org/fastmail-setup-with-emacs-mu4e-and-mbsync-on-macos/][Fastmail setup with Emacs, mu4e and mbsync on macOS]]
#+caption[Configure =message=]:
#+caption: Configure =message=.