[elpa] externals/denote 9353d23aa4 3/3: Update the documentation of denote-org-extras-extract-org-subtree

[ELPA Syncer]

branch: externals/denote
commit 9353d23aa45242898bc31499da740920a89ef0c1
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Update the documentation of denote-org-extras-extract-org-subtree
    
    This now reflects the refinements made by Vedang Manerikar to honour
    the user option 'denote-prompts'. Done in pull request 241:
    <https://github.com/protesilaos/denote/pull/241>.
---
 README.org           | 28 ++++++++++++++++++++--------
 denote-org-extras.el | 35 +++++++++++++++++++++++++----------
 2 files changed, 45 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index 5e2eb8dae1..c9c6a973d3 100644
--- a/README.org
+++ b/README.org
@@ -551,18 +551,30 @@ The text of the subtree's heading becomes the =#+title= 
of the new
 note. Everything else is inserted as-is.
 
 If the heading has any tags, they are used as the keywords of the new
-note. If the Org file has any =#+filetags= they are taken as well.
-Else the new note has no keywords 
([[#h:ad4dde4a-8e88-470a-97ae-e7b9d4b41fb4][Add or remove keywords 
interactively]]).
+note. If the Org file has any =#+filetags= they are taken as well
+(Org's =#+filetags= are inherited by the headings). If none of these
+are true and the user option ~denote-prompts~ includes an entry for
+keywords, then ~denote-org-extras-extract-org-subtree~ prompts for
+keywords. Else the new note has no keywords 
([[#h:ad4dde4a-8e88-470a-97ae-e7b9d4b41fb4][Add or remove keywords 
interactively]]).
 
 If the heading has a =PROPERTIES= drawer, it is retained for further
 review.
 
-If the heading's =PROPERTIES= drawer includes a =DATE= or =CREATED= or
-=CLOSED= property with a timestamp value, it is used to derive the date
-(or date and time) of the new note (if there is only a date, the time
-is taken as 00:00). If more than one of these properties is present,
-the order of preference is =DATE=, followed by =CREATED=, followed by
-=CLOSED=.
+If the heading's =PROPERTIES= drawer includes a =DATE= or =CREATED=
+property, or there exists a =CLOSED= statement with a timestamp value,
+use that to derive the date (or date and time) of the new note (if
+there is only a date, the time is taken as 00:00). If more than one of
+these is present, the order of preference is =DATE=, then =CREATED=,
+then =CLOSED=. If none of these is present, the current time is used.
+If the ~denote-prompts~ includes an entry for a date, then the command
+prompts for a date at this stage (also see 
~denote-date-prompt-use-org-read-date~).
+
+For the rest, it consults the value of the user option
+~denote-prompts~ in the following scenaria:
+
+- To optionally prompt for a subdirectory, otherwise it produces the
+  new note in the ~denote-directory~.
+- To optionally prompt for a file signature, otherwise to not use any.
 
 The new note is an Org file regardless of the user option
 ~denote-file-type~.
diff --git a/denote-org-extras.el b/denote-org-extras.el
index 79e756ebc0..f1d2e35884 100644
--- a/denote-org-extras.el
+++ b/denote-org-extras.el
@@ -131,27 +131,42 @@ This can be used as the value for the DATE argument of the
 
 ;;;###autoload
 (defun denote-org-extras-extract-org-subtree ()
-  "Create new Denote note using the current Org subtree.
+  "Create new Denote note using the current Org subtree as input.
 Remove the subtree from its current file and move its contents
-into the new Denote file (a subtree is a heading with all of its
+into a new Denote file (a subtree is a heading with all of its
 contents, including subheadings).
 
 Take the text of the subtree's top level heading and use it as
 the title of the new note.
 
 If the heading has any tags, use them as the keywords of the new
-note.  If the Org file has any #+filetags use them as well.  Else
-do not include any keywords.
+note.  If the Org file has any #+filetags use them as well (Org's
+filetags are inherited by the headings).  If none of these are
+true and the user option `denote-prompts' includes an entry for
+keywords, then prompt for keywords.  Else do not include any
+keywords.
 
 If the heading has a PROPERTIES drawer, retain it for further
 review.
 
-If the heading's PROPERTIES drawer includes a DATE or CREATED or
-CLOSED property with a timestamp value, use that to derive the
-date (or date and time) of the new note (if there is only a date,
-the time is taken as 00:00).  If more than one of these
-properties is present, the order of preference is DATE, followed
-by CREATED, followed by CLOSED.
+If the heading's PROPERTIES drawer includes a DATE or CREATED
+property, or there exists a CLOSED statement with a timestamp
+value, use that to derive the date (or date and time) of the new
+note (if there is only a date, the time is taken as 00:00).  If
+more than one of these is present, the order of preference is
+DATE, then CREATED, then CLOSED.  If none of these is present,
+use the current time.  If the `denote-prompts' includes an entry
+for a date, then prompt for a date at this stage (also see
+`denote-date-prompt-use-org-read-date').
+
+For the rest, consult the value of the user option
+`denote-prompts' in the following scenaria:
+
+- Optionally prompt for a subdirectory, otherwise produce the new
+  note in the variable `denote-directory'.
+
+- Optionally prompt for a file signature, otherwise do not use
+  one.
 
 Make the new note an Org file regardless of the value of
 `denote-file-type'."