From 8bcb321bbc8f163bd821176f6a4d67f2edc4fdb9 Mon Sep 17 00:00:00 2001
From: Gerard Vermeulen <gerard.vermeulen@neel.cnrs.fr>
Date: Tue, 7 Dec 2021 05:39:02 +0100
Subject: [PATCH] Add documentation

---
 README.org | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/README.org b/README.org
index cc5b43a..53250b3 100644
--- a/README.org
+++ b/README.org
@@ -101,10 +101,9 @@ Here follows a list of interesting Emacs configurations:
    that she is a very practical person trying to achieve her goals by the most
    efficient means.  I have stolen her idea of using [[https://github.com/quelpa/quelpa][quelpa]] to install packages
    from any source.
-5. [[https://github.com/purcell/emacs.d][Steve Purcell's configuration]] is well organized and a show-case of readable
-   [[info:elisp#Top][Emacs lisp (info)]] code.  I have stolen his idea of versioning the
-   ~package-user-dir~ variable to prevent clashes between the byte-compiler
-   output of different Emacs versions.
+5. [[https://github.com/purcell/emacs.d][Steve Purcell's configuration]] is well organized, a showcase of readable code,
+   as well helpful commit and issue histories.  See for instance the discussion
+   on [[https://github.com/purcell/emacs.d/issues/778][the correctness of order of company candidates in Emacs lisp mode]].
 6. [[https://github.com/tecosaur/emacs-config][Timothy E. Chapman's configuration]]
 
 * [[info:emacs#Early Init File][Early Init File (info)]]
@@ -112,8 +111,6 @@ Here follows a list of interesting Emacs configurations:
 :CUSTOM_ID: sec:early-init-file
 :END:
 
-Note: src_emacs-lisp[:exports code]{(find-function #'hack-local-variables)}
-
 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src emacs-lisp :tangle early-init.el
   ;;; early-init.el --- user early-init file        -*- lexical-binding: t -*-
@@ -132,6 +129,16 @@ Note: src_emacs-lisp[:exports code]{(find-function #'hack-local-variables)}
   ;;; earl-init.el ends here
 #+end_src
 
+In order to get help in understanding the code block above in a buffer showing
+the original [[info:org#Top][Org]] source file, move point (or cursor) to one of the items of the
+list the and type =C-c C-c=:
+1. src_emacs-lisp[:exports code]{(describe-variable #'load-prefer-newer t)}
+2. src_emacs-lisp[:exports code]{(apropos-library "no-littering")}
+3. src_emacs-lisp[:exports code]{(find-function #'hack-local-variables)}
+to execute the code between the curly braces for access to help.
+
+This shows why *Emacs is a self-documenting editor.*
+
 * [[info:emacs#Init File][Init File (info)]] header
 :PROPERTIES:
 :CUSTOM_ID: sec:init-file-header
@@ -252,6 +259,11 @@ any packages, hence also [[https://github.com/emacscollective/no-littering][no-l
 You have to refresh the list of available packages yourself before updating
 the installed packages.
 
+The call src_emacs-lisp[:exports_code]{(package-install-selected-packages)}
+checks the installation status of all packages in
+src_emacs-lisp[:exports_code]{package-selected-packages} and installs the
+missing packages after the user has agreed to its prompt.
+
 Finally, ~my-install-packages~ facilitates installation of all packages in a
 list of packages.
 
@@ -273,7 +285,9 @@ list of packages.
         (package-install package))))
 #+end_src
 
-Facilitate installlation of the optional packages.
+The next source code block facilitates installlation of the optional package,
+The user can run src_emacs-lisp[:exports_code]{(my-install-optional-packages)}
+to install all optional packages, or he can install each package one by one.
 
 #+attr_latex: :options bgcolor=LightGoldenrodYellow
 #+begin_src emacs-lisp