Bump to version 0.4.1

.dir-locals.el

@@ -3,4 +3,6 @@
 
 ((emacs-lisp-mode . ((sentence-end-double-space . t)
                      (indent-tabs-mode . nil)))
- (makefile-mode . ((indent-tabs-mode . t))))
+ (makefile-mode . ((indent-tabs-mode . t)))
+ (org-mode . ((sentence-end-double-space . nil)
+              (fill-column . 70))))

CONTRIBUTING.org

@@ -11,6 +11,7 @@ hard to follow them.
 - [[#how-can-i-contribute][How Can I Contribute?]]
   - [[#submitting-bugs-and-errors][Submitting Bugs and Errors]]
   - [[#submitting-new-code][Submitting New Code]]
+    - [[#ensuring-the-quality-of-your-code][Ensuring the quality of your code]]
     - [[#git-commit-messages][Git Commit Messages]]
     - [[#describing-the-pull-request][Describing the Pull Request]]
   - [[#finding-something-to-do][Finding Something To Do]]
@@ -46,6 +47,15 @@ the following:
 - And obviously, your code works (I include that because I myself
   sometimes push commits that don’t work)
 
+*** Ensuring the quality of your code
+Although a CI is already in place on the Github repository, you are
+encouraged to make sure yourself everything runs correctly.
+
+This package uses [[https://github.com/emacs-eask/eask][Eask]] to run its linters. Once it is installed, you
+can go to your preferred terminal and run ~make ci~. If everything goes
+well, you’re ready to submit your code to the repository. If not,
+please fix whatever Eask complains about first.
+
 *** Git Commit Messages
 Your commits should also follow [[https://github.com/syl20bnr/spacemacs/blob/develop/CONTRIBUTING.org#commit-messages][Spacemacs’ guidelines]] on this matter,
 especially:

Eask

@@ -1,5 +1,5 @@
 (package "org-unique-id"
-         "0.3.0"
+         "0.3.1"
          "Create unique IDs for org headers")
 
 (website-url "https://labs.phundrak.com/phundrak/org-unique-id")

README.org

@@ -2,6 +2,8 @@
 #+author: Lucien Cartier-Tilet
 #+email: lucien@phundrak.com
 [[https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml][file:https://github.com/Phundrak/org-unique-id/actions/workflows/workflow.yml/badge.svg]]
+[[https://melpa.org/#/org-unique-id][file:https://melpa.org/packages/org-unique-id-badge.svg]]
+[[https://stable.melpa.org/#/org-unique-id][file:https://stable.melpa.org/packages/org-unique-id-badge.svg]]
 
 * Introduction
 ~org-unique-id~ is a utility package for org users that are tired
@@ -14,6 +16,8 @@ user modifies them manually.
 - [[#introduction][Introduction]]
 - [[#installation][Installation]]
 - [[#usage][Usage]]
+- [[#breaking-changes][Breaking changes]]
+  - [[#040][~0.4.0~]]
 - [[#contributing][Contributing]]
 - [[#license][License]]
 
@@ -49,12 +53,12 @@ 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~.
+basis with the option ~unique-id~.
 
 Here is an example of an org buffer with ~org-unique-id~ enabled:
 #+begin_src org
 ,#+title: Test file
-,#+options: auto-id:t
+,#+options: unique-id:t
 
 ,* Test level 1
 :PROPERTIES:
@@ -77,7 +81,7 @@ 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
+Note that ~unique-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
@@ -88,7 +92,11 @@ Note that ~auto-id:t~ is absolutely required in order to get these
 
 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.
+~unique-id~ option.
+
+* Breaking changes
+** ~0.4.0~
+The option ~auto-id~ is renamed to ~unique-id~.
 
 * Contributing
 See [[file:CONTRIBUTING.org]].

org-unique-id.el

@@ -2,7 +2,7 @@
 
 ;; Author: Lucien Cartier-Tilet <lucien@phundrak.com>
 ;; Maintainer: Lucien Cartier-Tilet <lucien@phundrak.com>
-;; Version: 0.3.1
+;; Version: 0.4.1
 ;; Package-Requires: ((emacs "25.1") (org "9.3"))
 ;; Homepage: https://labs.phundrak.com/phundrak/org-unique-id
 ;; Keywords: convenience
@@ -26,17 +26,52 @@
 
 ;;; Commentary:
 
-;; This package is inspired by a blog post I published about a year
-;; before I decided to write this package [1], which in turn is
-;; largely inspired by another blog post [2].
+;; org-unique-id is a utility package for org-mode users that are
+;; tired dealing with random org IDs for their headers’ anchor that
+;; change on each org to HTML exports among others.  This package
+;; creates meaningful custom IDs for org headers that won’t change
+;; unless the user modifies or removes them manually.
 ;;
-;; It will generate a unique ID for each headers in an org file based
-;; on the headers’ name plus a random short string in order to be sure
-;; to make it unique.  This ID will be inserted in each header’s
-;; properties as a custom ID.
+;; In order to be enabled, this package’s `org-unique-id-maybe'
+;; function must be hooked to `before-save-hook', and the string
+;; \\='auto-id:t\\=' must be present in an \\='#+OPTIONS:\\=' line in
+;; the buffer.
 ;;
-;; [1] https://blog.phundrak.com/better-custom-ids-orgmode/
-;; [2] https://writequit.org/articles/emacs-org-mode-generate-ids.html
+;; If the \\='auto-id:t\\=' string is found, then it will create a
+;; slug of the current header (and if there are, its parent headers)
+;; and it will add a unique string suffix generated with a UUID
+;; generator to ensure all IDs are unique.
+;;
+;; Here is an example of an org-mode file without the
+;; \\='auto-id:t\\=' option after save:
+;;
+;;     #+title: Test file
+;;     * Test level 1
+;;     ** Test level 2
+;;     * Test level 1
+;;
+;; And here is the same org-mode file but with the option atop its
+;; content:
+;;
+;;     ,#+title: Test file
+;;     ,#+options: unique-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:
+;;
+;; Of course the last part of the custom ID might differ for you, but
+;; once it is generated, org-unique-id will not modify it or
+;; regenerate it unless you delete it yourself, hence ensuring a
+;; constant ID for your org exports.
 
 ;;; Code:
 
@@ -112,8 +147,8 @@ case, the CUSTOM_ID of the entry is returned."
 (defun org-unique-id ()
   "Add a CUSTOM_ID to all headers missing one.
 
-Only adds ids if the `auto-id' option is set to t in the file
-somewhere, i.e. #+OPTIONS: auto-id:t"
+Only adds ids if the \\='unique-id\\=' option is set to t in the
+file somewhere, i.e. #+OPTIONS: unique-id:t"
   (interactive)
   (save-excursion
     (widen)
@@ -126,14 +161,14 @@ somewhere, i.e. #+OPTIONS: auto-id:t"
 
 This function executes `org-unique-id' when the buffer’s major
 mode is `org-mode', when the buffer is not read-only, and if
-\\='auto-id:t\\' is found in an #+OPTIONS line."
+\\='unique-id:t\\' is found in an #+OPTIONS line."
   (interactive)
   (when (and (eq major-mode 'org-mode)
-             (eq buffer-read-only nil)
+             (not buffer-read-only)
              (save-excursion
                (goto-char (point-min))
                (let ((case-fold-search t))
-                 (re-search-forward "^#\\+OPTIONS:.*auto-id:t" (point-max) t))))
+                 (re-search-forward "^#\\+OPTIONS:.*unique-id:t" (point-max) t))))
     (org-unique-id)))
 
 (provide 'org-unique-id)