add README.md

Add a rule to the Makefile to generate README.md from the library
commentary in the library.  Track the generated file.

Makefile

@@ -17,3 +17,26 @@ lisp: $(ELCS)
 clean:
 	@echo "Cleaning..."
 	@rm -f $(ELCS)
+
+.PHONY: README.md
+README.md:
+	@echo "Generating README.md..."
+	@$(BATCHE) "\
+(let (start end commentary)\
+  (with-temp-buffer\
+    (insert-file \"auto-compile.el\")\
+    (re-search-forward \"^;;; Commentary:\n\n\")\
+    (setq start (point))\
+    (re-search-forward \"^;;; Code:\")\
+    (forward-line -1)\
+    (setq end (point-marker))\
+    (replace-regexp \"^;; ?\" \"\"  nil start end)\
+    (replace-regexp \"^- \" \"* \"  nil start end)\
+    (replace-regexp \"\\\\(\`[^']+\\\\)'\" \"\\\\1\`\" nil start end)\
+    (setq commentary (buffer-substring start end)))\
+  (with-current-buffer (find-file-noselect \"README.md\")\
+    (erase-buffer)\
+    (insert \"Automatically compile Emacs Lisp libraries\n\")\
+    (insert \"------------------------------------------\n\n\")\
+    (insert commentary ?\n)\
+    (save-buffer)))"

README.md

@@ -0,0 +1,74 @@
+Automatically compile Emacs Lisp libraries
+------------------------------------------
+
+This package provides two minor modes which automatically recompile
+Emacs Lisp source files.  Together these modes guarantee that Emacs
+never loads outdated byte code files.
+
+`auto-compile-on-save-mode` re-compiles source files when they are
+being saved and `auto-compile-on-load-mode` does so before they are
+being loaded (by advising `load` and `require`).  Both modes only
+ever _re-compile_ a source file when the respective byte code file
+already exists but is outdated.  Otherwise they do _not_ compile
+the source file.
+
+Even when using `auto-compile-on-save-mode` it can happen that some
+source file is newer than the respective byte code file, which is a
+problem because by default Emacs load the byte code file even when
+the respective source file has been modified more recently.
+
+Starting with Emacs version 24.4, setting `load-prefer-newer` to t
+prevents outdated byte code files from being loaded.  However this
+does not cause re-compilation of the source file, to actually do
+that `auto-compile-on-load-mode` is still required.
+
+Setup
+-----
+
+To reduce the risk of loading outdated byte code files, enable
+`auto-compile-on-load-mode` as early as possible, preferably even
+before the package manager.  If your Emacs supports it, then also
+set `load-prefer-newer` to t even before requiring `auto-compile`.
+Then also enable `auto-compile-on-save-mode`.
+
+    ;;; init.el --- user init file  -*- no-byte-compile: t -*-
+    (add-to-list 'load-path "/path/to/packed")
+    (add-to-list 'load-path "/path/to/auto-compile")
+    (setq load-prefer-newer t)
+    (require 'auto-compile)
+    (auto-compile-on-load-mode 1)
+    (auto-compile-on-save-mode 1)
+
+Usage
+-----
+
+Take note of the compile warnings and fix them.
+
+To permanently or temporarily toggle automatic compilation of some
+source file use the command `toggle-auto-compile`.  Since the modes
+only ever _update_ byte code files, toggling automatic compilation
+is done simply by either creating the byte code file or by removing
+it.  `toggle-auto-compile` can also toggle automatic compilation of
+multiple files at once; see its doc-string for more information.
+
+Customization
+-------------
+
+Constantly having the *Compile-Log* buffer pop up when a file is
+being saved can quickly become annoying.  Obviously the first thing
+you should do to about that is to actually fix outstanding issues.
+
+Once you have done that you might also want to keep that buffer
+from being automatically displayed and instead only show the number
+of compile warnings for the current file in the mode-line.
+
+    (setq auto-compile-display-buffer nil)
+    (setq auto-compile-mode-line-counter t)
+
+To display the buffer use `M-x auto-compile-display-log` or click
+on the counter in the mode-line.
+
+Using `auto-compile-inhibit-compile-hook` it is possible to inhibit
+automatic compilation under certain circumstances; e.g. when HEAD
+is detached inside a Git repository (useful during rebase sessions).
+