Browse Source

Org-id: Clarify customization documentation for org-id, ts option

* lisp/org-id.el (org-id-ts-format, org-id-method): Clarify docstrings.
* doc/org-manual.org (Handling Links): Mention org-id-method in
the manual.
Gustav Wikström 4 years ago
parent
commit
3d52843269
2 changed files with 10 additions and 7 deletions
  1. 3 2
      doc/org-manual.org
  2. 7 5
      lisp/org-id.el

+ 3 - 2
doc/org-manual.org

@@ -3356,8 +3356,9 @@ current buffer:
   =ID= property for the link[fn:29].  So using this command in Org
   =ID= property for the link[fn:29].  So using this command in Org
   buffers potentially creates two links: a human-readable link from
   buffers potentially creates two links: a human-readable link from
   the custom ID, and one that is globally unique and works even if the
   the custom ID, and one that is globally unique and works even if the
-  entry is moved from file to file.  Later, when inserting the link,
-  you need to decide which one to use.
+  entry is moved from file to file.  The =ID= property can be either a
+  UUID (default) or a timestamp, depending on ~org-id-method~.  Later,
+  when inserting the link, you need to decide which one to use.
 
 
 - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ ::
 - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ ::
 
 

+ 7 - 5
lisp/org-id.el

@@ -129,8 +129,11 @@ nil   Never use an ID to make a link, instead link using a text search for
   :type 'string)
   :type 'string)
 
 
 (defcustom org-id-ts-format "%Y%m%dT%H%M%S.%6N"
 (defcustom org-id-ts-format "%Y%m%dT%H%M%S.%6N"
-  "Default format for IDs generated using `ts' `org-id-method'.
-The format should be suitable to pass as an argument to `format-time-string'."
+  "Timestamp format for IDs generated using `ts' `org-id-method'.
+The format should be suitable to pass as an argument to `format-time-string'.
+
+Defaults to ISO8601 timestamps without separators and without
+timezone, local time and precision down to 1e-6 seconds."
   :type 'string
   :type 'string
   :package-version '(Org . "9.5"))
   :package-version '(Org . "9.5"))
 
 
@@ -150,13 +153,12 @@ uuid       Create random (version 4) UUIDs.  If the program defined in
            `org-id-uuid-program' is available it is used to create the ID.
            `org-id-uuid-program' is available it is used to create the ID.
            Otherwise an internal functions is used.
            Otherwise an internal functions is used.
 
 
-ts         Create ID's based on ISO8601 timestamps (without separators
-           and without timezone, local time).  Precision down to seconds."
+ts         Create ID's based on timestamps as specified in `org-id-ts-format'."
   :group 'org-id
   :group 'org-id
   :type '(choice
   :type '(choice
 	  (const :tag "Org's internal method" org)
 	  (const :tag "Org's internal method" org)
 	  (const :tag "external: uuidgen" uuid)
 	  (const :tag "external: uuidgen" uuid)
-	  (const :tag "ISO8601 timestamp" ts)))
+	  (const :tag "Timestamp with format `org-id-ts-format'" ts)))
 
 
 (defcustom org-id-prefix nil
 (defcustom org-id-prefix nil
   "The prefix for IDs.
   "The prefix for IDs.