From 5d94c667db0ab01e1ce7bb39a22affa0ff064705 Mon Sep 17 00:00:00 2001
From: Lucien Cartier-Tilet <lucien@phundrak.com>
Date: Wed, 24 Aug 2022 02:51:08 +0200
Subject: [PATCH] Update instructions in README

---
 README.org | 82 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 56 insertions(+), 26 deletions(-)

diff --git a/README.org b/README.org
index 57d3f28..9e08a58 100644
--- a/README.org
+++ b/README.org
@@ -12,6 +12,7 @@ user modifies them manually.
 * Table of Contents                                                :TOC_2_gh:
 - [[#introduction][Introduction]]
 - [[#installation][Installation]]
+- [[#usage][Usage]]
 - [[#contributing][Contributing]]
 - [[#license][License]]
 
@@ -20,44 +21,73 @@ This package can be installed like any other simple package. Your
 first option is to download ~org-unique-id~ or clone this package in
 your ~load-path~ and add the following to your configuration:
 #+begin_src emacs-lisp
-  (require 'org-unique-id)
-  (add-hook 'org-mode-hook
-            (lambda ()
-              (add-hook 'before-save-hook
-                        (lambda ()
-                          (when (and (eq major-mode       'org-mode)
-                                     (eq buffer-read-only nil))
-                            (org-unique-id))))))
+(require 'org-unique-id)
+(add-hook 'before-save-hook #'org-unique-id-maybe)
 #+end_src
 
 You can also use a package manager such as Quelpa or Straight in order
 to load automatically your package. In my case, I prefer the latter
 with its ~use-package~ integration:
 #+begin_src emacs-lisp
-  (use-package org-unique-id
-    :require t
-    :after org
-    :straight (org-unique-id :type git
-                             :host github
-                             :repo "Phundrak/org-unique-id")
-    :init
-    (add-hook 'org-mode-hook
-       (lambda ()
-         (add-hook 'before-save-hook
-                   (lambda ()
-                     (when (and (eq major-mode       'org-mode)
-                                (eq buffer-read-only nil))
-                       (org-unique-id)))))))
-
+(use-package org-unique-id
+  :require t
+  :after org
+  :straight (org-unique-id :type git
+                           :host github
+                           :repo "Phundrak/org-unique-id")
+  :init (add-hook 'before-save-hook #'org-unique-id-maybe))
 #+end_src
 
-I also add ~:build t~ to my straight recipe to ensure my package is compiled.
+I personally add ~:build t~ to my straight recipe to ensure my package is compiled.
 
 If you know how to handle this with a pure Straight recipe, or with a
 Quelpa recipe, don’t hesitate to submit a PR to add it to this README!
 
-Also, DAMN that’s one hell of a hook, if you know anything simpler
-than this, please submit it!
+* Usage
+While ~org-unique-id~ may be installed on your Emacs instance, it is not
+active by default. This is because it can take some time to generate
+all the required IDs in your org file which may hang your Emacs
+instance for a bit. Therefore, automatic IDs are enabled on a per-file
+basis with the option ~auto-id~.
+
+Here is an example of an org buffer with ~org-unique-id~ enabled:
+#+begin_src org
+,#+title: Test file
+,#+options: auto-id:t
+
+,* Test level 1
+:PROPERTIES:
+:CUSTOM_ID: Test-level-1-zmb40t305kj0
+:END:
+,** Test level 2
+:PROPERTIES:
+:CUSTOM_ID: Test-level-1-Test-level-2-spn40t305kj0
+:END:
+,* Test level 1
+:PROPERTIES:
+:CUSTOM_ID: Test-level-1-1nx40t305kj0
+:END:
+#+end_src
+
+The ~CUSTOM_ID~ properties are generated on save and only once. Once the
+~CUSTOM_ID~ of a heading is set, the package will not modify it even if
+the name of the heading itself is modified. To regenerate it, delete
+the ~CUSTOM_ID~ and let ~org-unique-id~ regenerate it. If you don’t like
+the ~CUSTOM_ID~ generated by ~org-unique-id~, you can overwrite it
+yourself and ~org-unique-id~ will not modify it.
+
+Note that ~auto-id:t~ is absolutely required in order to get these
+~CUSTOM_ID~. Here is the same buffer after save without this option:
+#+begin_src org
+,#+title: Test file
+,* Test level 1
+,** Test level 2
+,* Test level 1
+#+end_src
+
+It is also possible to manually call ~org-unique-id~ (interactively or
+not) on the current buffer. This will not check the value of the
+~auto-id~ option.
 
 * Contributing
 See [[file:CONTRIBUTING.org]].