Add "Introduction" section and don't inhibit org TOC

diff --git a/.emacs.d/esy.org b/.emacs.d/esy.org
index 1326df3601e6a9c54930816acdd7bd0cd8b59e38..9f019a81eb25b0d46d4e69606f97fe16ac5742ea 100644 (file)
--- a/.emacs.d/esy.org
+++ b/.emacs.d/esy.org
@@ -1,12 +1,21 @@
-#+TITLE: GNU Emacs configuration file
+#+TITLE: GNU Emacs literate configuration
 #+AUTHOR: Eshel Yaron
 #+EMAIL: eshelshay.yaron@gmail.com
-#+OPTIONS: toc:nil ^:{}
+#+OPTIONS: ^:{}
 #+STARTUP: overview indent
 
-* Emacs configuration
+* Introduction
 
-** Fresh installation
+This document holds my customizations for GNU Emacs. Its source version is written in
+[[https://orgmode.org/][Org mode]], utilizing [[https://orgmode.org/worg/org-contrib/babel/][Babel]] to realize [[https://en.wikipedia.org/wiki/Literate_programming][literate programming]]. The Elisp code blocks
+scattered throughout this document are bundled together to create an Elisp library
+called =esy.el=, which Emacs executes on startup.
+
+The source of this document is managed with Git in [[https://git.sr.ht/~eshel/dotfiles][my dotfiles repository hosted on
+SourceHut]]. An [[https://eshelyaron.com/esy.html][online HTML version]] is also published on my website. See [[#exporting][settings for
+exporting and publishing]] below for more information regarding [[https://eshelyaron.com][my website]].
+
+* Fresh installation
 
 To bootstrap this configuration, fetch a local clone of the repository from
 [[https://git.sr.ht/~eshel/dotfiles][SourceHut]] and create a symlink from the =.emacs.d= subdirectory into your home
@@ -22,7 +31,7 @@ After the first run of the provided =init.el=, modifications to
 =esy.org= will be made available automatically whenever Emacs
 restarts. See also [[#bootstrap][Literate config bootstrap]].
 
-** Elisp Header
+* Elisp Header
 :PROPERTIES:
 :CUSTOM_ID: header
 :END:
@@ -36,7 +45,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   ;;; Code:
 #+end_src
 
-** Set a higher GC threshold during initialization
+* Set a higher GC threshold during initialization
 
 #+begin_src emacs-lisp
   (let ((normal-gc-cons-threshold (* 20 1024 1024))
@@ -46,7 +55,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
               (lambda () (setq gc-cons-threshold normal-gc-cons-threshold))))
 #+end_src
 
-** Package archives
+* Package archives
 
 #+begin_src emacs-lisp
   (require 'package)
@@ -74,20 +83,20 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (package-install-selected-packages)
 #+end_src
 
-** Suppressing native compilation warnings
+* Suppressing native compilation warnings
 
 #+begin_src emacs-lisp
   (setq native-comp-async-report-warnings-errors 'silent)
 #+end_src
 
-** Loading the =modus-vivendi= theme
+* Loading the =modus-vivendi= theme
 
 #+begin_src emacs-lisp
   (load-theme 'modus-vivendi)
   (modus-themes-load-vivendi)
 #+end_src
 
-** No littering!
+* No littering!
 
 #+begin_src emacs-lisp
   (require 'no-littering)
@@ -104,7 +113,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
       (expand-file-name  "var/eln-cache/" user-emacs-directory))))
 #+end_src
 
-** History
+* History
 
 #+begin_src emacs-lisp
   (defun esy/setup-history ()
@@ -121,9 +130,9 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (esy/setup-history)
 #+end_src
 
-** Display settings
+* Display settings
 
-*** Must have display settings
+** Must have display settings
 
 #+begin_src emacs-lisp
   (setq use-file-dialog nil
@@ -142,7 +151,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (put 'suspend-frame 'disabled t)
 #+end_src
 
-*** More display settings
+** More display settings
 
 #+begin_src emacs-lisp
   (defun esy/setup-display ()
@@ -166,9 +175,9 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-display)
 #+end_src
 
-** Org-mode settings                                                   :org:
+* Org-mode settings                                                     :org:
 
-*** Literate config bootstrap
+** Literate config bootstrap
 :PROPERTIES:
 :CUSTOM_ID: bootstrap
 :END:
@@ -189,7 +198,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'kill-emacs-hook #'esy/tangle-and-compile-config)
 #+end_src
 
-*** Org-mode basic settings
+** Org-mode basic settings
 
 #+begin_src emacs-lisp
   (defconst esy/inbox-path "~/inbox.org"
@@ -234,7 +243,10 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
 
 #+end_src
 
-*** Export and publish
+** Export and publish
+:PROPERTIES:
+:CUSTOM_ID: exporting
+:END:
 
 #+begin_src emacs-lisp
   (require 'f)
@@ -293,7 +305,6 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
     (require 'ox-html)
     (require 'htmlize)
     (setq org-export-with-section-numbers nil
-          org-export-with-toc nil
           org-html-html5-fancy t
           org-html-doctype "html5"
           org-html-head-include-default-style nil
@@ -337,7 +348,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-publish)
 #+end_src
 
-*** Org-mode capture templates
+** Org-mode capture templates
 
 #+begin_src emacs-lisp
 
@@ -462,15 +473,15 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
       '(("P" (list project-current))))
 #+end_src
 
-*** Unset =org-mode= binding of =C-,= to =org-cycle-agenda-files=     :kbd:
+** Unset =org-mode= binding of =C-,= to =org-cycle-agenda-files=       :kbd:
 
 #+begin_src emacs-lisp
   (keymap-unset org-mode-map "C-," t)
 #+end_src
 
-** Email settings                                                    :mail:
+* Email settings                                                       :mail:
 
-*** My accounts
+** My accounts
 
 #+begin_src emacs-lisp
   (setq user-full-name "Eshel Yaron")
@@ -482,7 +493,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
     "My SWI-Prolog email address.")
 #+end_src
 
-*** Sending mail from multiple SMTP accounts
+** Sending mail from multiple SMTP accounts
 
 #+begin_src emacs-lisp
   (defun esy/smtpmail-multi-make-accout (address server)
@@ -513,7 +524,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'mail-mode-hook #'esy/customize-message-mode)
 #+end_src
 
-*** Reading mail with Gnus
+** Reading mail with Gnus
 
 #+begin_src emacs-lisp
   (setq mail-user-agent 'gnus-user-agent
@@ -554,9 +565,9 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'gnus-mode-hook #'esy/customize-gnus-mode)
 #+end_src
 
-** Global keybindings                                                  :kbd:
+* Global keybindings                                                    :kbd:
 
-*** Misc. keybindings
+** Misc. keybindings
 
 #+begin_src emacs-lisp
   (defun esy/kill-dwim ()
@@ -610,7 +621,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/customize-global-keymap)
 #+end_src
 
-*** =C-x= keybindings                                                 
+** =C-x= keybindings
 
 #+begin_src emacs-lisp
   (defun esy/customize-ctl-x-map ()
@@ -638,7 +649,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/customize-ctl-x-map)
 #+end_src
 
-*** =C-h= keybindings                                                 
+** =C-h= keybindings
 
 #+begin_src emacs-lisp
   (defun esy/customize-help-map ()
@@ -653,7 +664,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/customize-help-map)
 #+end_src
 
-*** =ace-window= homerow keys
+** =ace-window= homerow keys
 
 #+begin_src emacs-lisp
    (with-eval-after-load 'ace-window
@@ -662,13 +673,13 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
       '(aw-leading-char-face ((t (:inherit (bold modus-themes-reset-soft) :height 1))))))
 #+end_src
 
-*** =ace-link= setup
+** =ace-link= setup
 
 #+begin_src emacs-lisp
   (add-hook 'after-init-hook #'ace-link-setup-default)
 #+end_src
 
-** Display weekly agenda on startup
+* Display weekly agenda on startup
 
 #+begin_src emacs-lisp :tangle no
   (defun esy/display-weekly-agenda ()
@@ -680,9 +691,9 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/display-weekly-agenda)
 #+end_src
 
-** Minibuffer and completions
+* Minibuffer and completions
 
-*** Enable and indicate recursive minibuffers
+** Enable and indicate recursive minibuffers
 
 #+begin_src emacs-lisp
   (defun esy/setup-recursive-minibuffers ()
@@ -694,7 +705,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-recursive-minibuffers)
 #+end_src
 
-*** Completions
+** Completions
 
 #+begin_src emacs-lisp
   (defun esy/setup-completions ()
@@ -731,7 +742,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
 
 #+end_src
 
-** Elfeed
+* Elfeed
 
 #+begin_src emacs-lisp
   (defun esy/setup-elfeed ()
@@ -749,7 +760,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-elfeed)
 #+end_src
 
-** eww
+* eww
 
 #+begin_src emacs-lisp
   (with-eval-after-load 'eww
@@ -757,7 +768,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
           browse-url-browser-function #'eww-browse-url))
 #+end_src
 
-** Async shell commands with =dtache=
+* Async shell commands with =dtache=
 
 #+begin_src emacs-lisp
   (defun esy/setup-dtache ()
@@ -769,7 +780,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-dtache)
 #+end_src
 
-** Mode-line customizations
+* Mode-line customizations
 
 #+begin_src emacs-lisp
   (defvar esy/ping-target "1.1.1.1"
@@ -887,16 +898,16 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/ping-mode)
 #+end_src
 
-** Setup PATH from shell environment
+* Setup PATH from shell environment
 
 #+begin_src emacs-lisp
   (require 'exec-path-from-shell)
   (add-hook 'after-init-hook #'exec-path-from-shell-initialize)
 #+end_src
 
-** Programming
+* Programming
 
-*** General =prog-mode= settings
+** General =prog-mode= settings
 
 #+begin_src emacs-lisp
   (defun esy/setup-programming ()
@@ -911,7 +922,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'prog-mode-hook #'esy/setup-programming)
 #+end_src
 
-*** Prolog specific settings
+** Prolog specific settings
 
 #+begin_src emacs-lisp
   (add-to-list 'auto-mode-alist '("\\.pl\\'"  . prolog-mode))
@@ -925,7 +936,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'prolog-mode-hook #'esy/setup-prolog)
 #+end_src
 
-** LaTeX and PDF settings
+* LaTeX and PDF settings
 
 #+begin_src emacs-lisp
   (defun esy/pdf-tools-install ()
@@ -942,7 +953,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
               #'TeX-revert-document-buffer))
 #+end_src
 
-** Misc. settings
+* Misc. settings
 
 #+begin_src emacs-lisp
   (defun esy/setup-misc ()
@@ -959,7 +970,7 @@ For further information, see [[info:elisp#Library Headers][elisp#Library Headers
   (add-hook 'after-init-hook #'esy/setup-misc)
 #+end_src
 
-** Elisp Footer
+* Elisp Footer
 
 #+begin_src emacs-lisp
   (provide 'esy)