forked from protesilaos/denote
-
Notifications
You must be signed in to change notification settings - Fork 0
/
denote.el
4157 lines (3528 loc) · 170 KB
/
denote.el
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; denote.el --- Simple notes with an efficient file-naming scheme -*- lexical-binding: t -*-
;; Copyright (C) 2022-2024 Free Software Foundation, Inc.
;; Author: Protesilaos Stavrou <[email protected]>
;; Maintainer: Protesilaos Stavrou <[email protected]>
;; URL: https://github.com/protesilaos/denote
;; Version: 2.3.5
;; Package-Requires: ((emacs "28.1"))
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Denote aims to be a simple-to-use, focused-in-scope, and effective
;; note-taking and file-naming tool for Emacs.
;;
;; Denote is based on the idea that files should follow a predictable
;; and descriptive file-naming scheme. The file name must offer a
;; clear indication of what the contents are about, without reference
;; to any other metadata. Denote basically streamlines the creation
;; of such files or file names while providing facilities to link
;; between them (where those files are editable).
;;
;; Denote's file-naming scheme is not limited to "notes". It can be used
;; for all types of file, including those that are not editable in Emacs,
;; such as videos. Naming files in a consistent way makes their
;; filtering and retrieval considerably easier. Denote provides relevant
;; facilities to rename files, regardless of file type.
;;
;; The manual describes all the technicalities about the file-naming
;; scheme, points of entry to creating new notes, commands to check
;; links between notes, and more: ;; <https://protesilaos.com/emacs/denote>.
;; If you have the info manual available, evaluate:
;;
;; (info "(denote) Top")
;;
;; What follows is a general overview of its core core design
;; principles (again: please read the manual for the technicalities):
;;
;; * Predictability :: File names must follow a consistent and
;; descriptive naming convention (see the manual's "The file-naming
;; scheme"). The file name alone should offer a clear indication of
;; what the contents are, without reference to any other metadatum.
;; This convention is not specific to note-taking, as it is pertinent
;; to any form of file that is part of the user's long-term storage
;; (see the manual's "Renaming files").
;;
;; * Composability :: Be a good Emacs citizen, by integrating with other
;; packages or built-in functionality instead of re-inventing
;; functions such as for filtering or greping. The author of Denote
;; (Protesilaos, aka "Prot") writes ordinary notes in plain text
;; (`.txt'), switching on demand to an Org file only when its expanded
;; set of functionality is required for the task at hand (see the
;; manual's "Points of entry").
;;
;; * Portability :: Notes are plain text and should remain portable.
;; The way Denote writes file names, the front matter it includes in
;; the note's header, and the links it establishes must all be
;; adequately usable with standard Unix tools. No need for a databse
;; or some specialised software. As Denote develops and this manual
;; is fully fleshed out, there will be concrete examples on how to do
;; the Denote-equivalent on the command-line.
;;
;; * Flexibility :: Do not assume the user's preference for a
;; note-taking methodology. Denote is conceptually similar to the
;; Zettelkasten Method, which you can learn more about in this
;; detailed introduction: <https://zettelkasten.de/introduction/>.
;; Notes are atomic (one file per note) and have a unique identifier.
;; However, Denote does not enforce a particular methodology for
;; knowledge management, such as a restricted vocabulary or mutually
;; exclusive sets of keywords. Denote also does not check if the user
;; writes thematically atomic notes. It is up to the user to apply
;; the requisite rigor and/or creativity in pursuit of their preferred
;; workflow (see the manual's "Writing metanotes").
;;
;; * Hackability :: Denote's code base consists of small and reusable
;; functions. They all have documentation strings. The idea is to
;; make it easier for users of varying levels of expertise to
;; understand what is going on and make surgical interventions where
;; necessary (e.g. to tweak some formatting). In this manual, we
;; provide concrete examples on such user-level configurations (see
;; the manual's "Keep a journal or diary").
;;
;; Now the important part... "Denote" is the familiar word, though it
;; also is a play on the "note" concept. Plus, we can come up with
;; acronyms, recursive or otherwise, of increasingly dubious utility
;; like:
;;
;; + Don't Ever Note Only The Epiphenomenal
;; + Denote Everything Neatly; Omit The Excesses
;;
;; But we'll let you get back to work. Don't Eschew or Neglect your
;; Obligations, Tasks, and Engagements.
;;; Code:
(require 'seq)
(require 'xref)
(require 'dired)
(eval-when-compile (require 'subr-x))
(defgroup denote ()
"Simple notes with an efficient file-naming scheme."
:group 'files)
;;;; User options
;; About the autoload: (info "(elisp) File Local Variables")
;; NOTE: Maybe we could rename or provide the alias `denote-directories'
;; instead. However, it would probably be undesirable to have distinct
;; variables to specify denote directories. We want to avoid the
;; confusion that the existence of two variables would create when silos
;; are involved.
;;;###autoload (put 'denote-directory 'safe-local-variable (lambda (f) (or (stringp f) (listp f))))
(defcustom denote-directory (list (expand-file-name "~/Documents/notes/"))
"Directories for storing personal notes.
The first file in the list is used as the default location to
create notes. When a note is created using `denote', a different
directory can be choosen by including `subdirectory' in
`denote-prompts'.
If you intend to reference this variable in Lisp, consider using
the function `denote-directories' instead.
For historical compatibility, this option accepts a string. A
value of \"~/notes\" is equivalent to a value of (list
\"~/notes\")."
:group 'denote
:safe (lambda (f) (or (stringp f) (listp f)))
:type '(repeat directory))
(defcustom denote-save-buffers nil
"Control whether commands that handle new notes save their buffer outright.
The default behaviour of commands such as `denote' (or related)
is to not save the buffer they create. This gives the user the
chance to review the text before writing it to a file. The user
may choose to delete the unsaved buffer, thus not creating a new
note.
This option also applies to notes affected by the renaming
commands (`denote-rename-file' and related).
If this user option is set to a non-nil value, such buffers are
saved automatically. The assumption is that the user who opts in
to this feature is familiar with the `denote-rename-file'
operation (or related) and knows it is reliable."
:group 'denote
:type 'boolean)
;;;###autoload (put 'denote-known-keywords 'safe-local-variable #'listp)
(defcustom denote-known-keywords
'("emacs" "philosophy" "politics" "economics")
"List of strings with predefined keywords for `denote'.
Also see user options: `denote-infer-keywords',
`denote-sort-keywords', `denote-file-name-slug-functions'."
:group 'denote
:safe #'listp
:type '(repeat string))
;;;###autoload (put 'denote-infer-keywords 'safe-local-variable (lambda (_) t))
(defcustom denote-infer-keywords t
"Whether to infer keywords from existing notes' file names.
When non-nil, search the file names of existing notes in the
variable `denote-directory' for their keyword field and extract
the entries as \"inferred keywords\". These are combined with
`denote-known-keywords' and are presented as completion
candidates while using `denote' and related commands
interactively.
If nil, refrain from inferring keywords. The aforementioned
completion prompt only shows the `denote-known-keywords'. Use
this if you want to enforce a restricted vocabulary.
The user option `denote-excluded-keywords-regexp' can be used to
exclude keywords that match a regular expression.
Inferred keywords are specific to the value of the variable
`denote-directory'. If a silo with a local value is used, as
explained in that variable's doc string, the inferred keywords
are specific to the given silo.
For advanced Lisp usage, the function `denote-keywords' returns
the appropriate list of strings."
:group 'denote
:safe (lambda (_) t)
:type 'boolean)
(defcustom denote-prompts '(title keywords)
"Specify the prompts followed by relevant Denote commands.
Commands that prompt for user input to construct a Denote file name
include, but are not limited to: `denote', `denote-signature',
`denote-type', `denote-date', `denote-subdirectory',
`denote-rename-file', `denote-dired-rename-files'.
The value of this user option is a list of symbols, which includes any
of the following:
- `title': Prompt for the title of the new note.
- `keywords': Prompts with completion for the keywords of the new
note. Available candidates are those specified in the user
option `denote-known-keywords'. If the user option
`denote-infer-keywords' is non-nil, keywords in existing note
file names are included in the list of candidates. The
`keywords' prompt uses `completing-read-multiple', meaning that
it can accept multiple keywords separated by a comma (or
whatever the value of `crm-separator' is).
- `file-type': Prompts with completion for the file type of the
new note. Available candidates are those specified in the user
option `denote-file-type'. Without this prompt, `denote' uses
the value of `denote-file-type'.
- `subdirectory': Prompts with completion for a subdirectory in
which to create the note. Available candidates are the value
of the user option `denote-directory' and all of their
subdirectories. Any subdirectory must already exist: Denote
will not create it.
- `date': Prompts for the date of the new note. It will expect
an input like 2022-06-16 or a date plus time: 2022-06-16 14:30.
Without the `date' prompt, the `denote' command uses the
`current-time'. (To leverage the more sophisticated Org
method, see the `denote-date-prompt-use-org-read-date'.)
- `template': Prompts for a KEY among `denote-templates'. The
value of that KEY is used to populate the new note with
content, which is added after the front matter.
- `signature': Prompts for an arbitrary string that can be used
to establish a sequential relationship between files (e.g. 1,
1a, 1b, 1b1, 1b2, ...). Signatures have no strictly defined
function and are up to the user to apply as they see fit. One
use-case is to implement Niklas Luhmann's Zettelkasten system
for a sequence of notes (Folgezettel). Signatures are not
included in a file's front matter. They are reserved solely
for creating a sequence in a file listing, at least for the
time being.
The prompts occur in the given order.
If the value of this user option is nil, no prompts are used.
The resulting file name will consist of an identifier (i.e. the
date and time) and a supported file type extension (per
`denote-file-type').
Recall that Denote's standard file-naming scheme is defined as
follows (read the manual for the technicalities):
DATE--TITLE__KEYWORDS.EXT
Depending on the inclusion of the `title', `keywords', and
`signature' prompts, file names will be any of those
permutations:
DATE.EXT
DATE--TITLE.EXT
DATE__KEYWORDS.EXT
DATE==SIGNATURE.EXT
DATE==SIGNATURE--TITLE.EXT
DATE==SIGNATURE--TITLE__KEYWORDS.EXT
DATE==SIGNATURE__KEYWORDS.EXT
When in doubt, always include the `title' and `keywords'
prompts (the default style).
Finally, this user option only affects the interactive use of the
`denote' or other relevant commands (advanced users can call it from
Lisp). In Lisp usage, the behaviour is always what the caller
specifies, based on the supplied arguments.
Also see `denote-history-completion-in-prompts'."
:group 'denote
:type '(radio (const :tag "Use no prompts" nil)
(set :tag "Available prompts" :greedy t
(const :tag "Title" title)
(const :tag "Keywords" keywords)
(const :tag "Date" date)
(const :tag "File type extension" file-type)
(const :tag "Subdirectory" subdirectory)
(const :tag "Template" template)
(const :tag "Signature" signature))))
(defcustom denote-file-name-components '(identifier signature title keywords)
"Specify the file name components of new notes.
The value is a list of symbols, which includes any of the following:
- `identifier': A string that looks like \"20240101T111111\" if
it appears as the first component of a file name. Else, it is
prepended with \"@@\" if it appears anywhere else in the file
name. This is auto-generated by Denote.
- `signature': An arbitrary string that combines \"==\" with the
signature of `denote-signature-prompt'.
- `title': An arbitrary string that combines \"--\" with the
title of `denote-title-prompt'.
- `keywords': A string that represents the keywords of
`denote-keywords-prompt'. Each keyword is prepended with
\"__\".
See `denote-prompts'."
:group 'denote
:type '(radio (const :tag "Use no prompts" nil)
(set :tag "Available prompts" :greedy t
(const :tag "Identifier" identifier)
(const :tag "Signature" signature)
(const :tag "Title" title)
(const :tag "Keywords" keywords))))
(defcustom denote-sort-keywords t
"Whether to sort keywords in new files.
When non-nil, the keywords of `denote' are sorted with
`string-collate-lessp' regardless of the order they were inserted at the
minibuffer prompt.
If nil, show the keywords in their given order."
:group 'denote
:type 'boolean)
(defcustom denote-file-type nil
"The file type extension for new notes.
By default (a nil value), the file type is that of Org mode.
Though the `org' symbol can be specified for the same effect.
When the value is the symbol `markdown-yaml', the file type is
that of Markdown mode and the front matter uses YAML notation.
Similarly, `markdown-toml' is Markdown but has TOML syntax in the
front matter.
When the value is `text', the file type is that of Text mode.
Any other non-nil value is the same as the default.
NOTE: Expert users can change the supported file-types by editing
the value of `denote-file-types'. That variable, which is not a
user option, controls the behaviour of all file-type-aware
functions (creating notes, renaming them, inserting front matter,
formatting a link, etc.). Consult its documentation for the
technicalities."
:type '(choice
(const :tag "Unspecified (defaults to Org)" nil)
(const :tag "Org mode (default)" org)
(const :tag "Markdown (YAML front matter)" markdown-yaml)
(const :tag "Markdown (TOML front matter)" markdown-toml)
(const :tag "Plain text" text))
:group 'denote)
(defcustom denote-date-prompt-use-org-read-date nil
"Whether to use `org-read-date' in date prompts.
If non-nil, use `org-read-date'. If nil, input the date as a
string, as described in `denote'.
This option is relevant when `denote-prompts' includes a `date'."
:group 'denote
:type 'boolean)
(defcustom denote-org-store-link-to-heading t
"Determine whether `org-store-link' links to the current Org heading.
When non-nil store link to the current Org heading inside the
Denote file. If the heading does not have a CUSTOM_ID, create it
and include it in its PROPERTIES drawer. If a CUSTOM_ID exists,
take it as-is.
Make the resulting link a combination of the `denote:' link type,
pointing to the identifier of the current file, plus the value of
the heading's CUSTOM_ID, such as:
- [[denote:20240118T060608][Some test]]
- [[denote:20240118T060608::#h:eed0fb8e-4cc7-478f][Some test::Heading text]]
Both lead to the same Denote file, but the latter jumps to the
heading with the given CUSTOM_ID. Notice that the link to the
heading also has a different description, which includes the
heading text.
The value of the CUSTOM_ID is determined by the Org user option
`org-id-method'. The sample shown above uses the default UUID
infrastructure (though I deleted a few characters to not get
complaints from the byte compiler about long lines in the doc
string...).
If this user option is set to nil, only store links to the Denote
file (using its identifier), but not to the given heading. This
is what Denote was doing in versions prior to 2.3.0.
What `org-store-link' does is merely collect a link. To actually insert
it, use the command `org-insert-link'. Note that `org-capture' uses
`org-store-link' internally when it needs to store a link.
[ This feature only works in Org mode files, as other file types
do not have a linking mechanism that handles unique identifiers
for headings or other patterns to jump to. If `org-store-link'
is invoked in one such file, it captures only the Denote
identifier of the file, even if this user option is set to a
non-nil value. ]"
:group 'denote
:type 'boolean)
(defcustom denote-templates nil
"Alist of content templates for new notes.
A template is arbitrary text that Denote will add to a newly
created note right below the front matter.
Templates are expressed as a (KEY . STRING) association.
- The KEY is the name which identifies the template. It is an
arbitrary symbol, such as `report', `memo', `statement'.
- The STRING is ordinary text that Denote will insert as-is. It
can contain newline characters to add spacing. The manual of
Denote contains examples on how to use the `concat' function,
beside writing a generic string.
The user can choose a template either by changing the user option
`denote-prompts' to always prompt for a template when calling the
`denote' command."
:type '(alist :key-type symbol :value-type string)
:group 'denote)
(defcustom denote-backlinks-show-context nil
"When non-nil, show link context in the backlinks buffer.
The context is the line a link to the current note is found in.
The context includes multiple links to the same note, if those
are present.
When nil, only show a simple list of file names that link to the
current note."
:group 'denote
:type 'boolean)
(defcustom denote-rename-confirmations '(rewrite-front-matter modify-file-name)
"Make renaming commands prompt for confirmations.
This affects the behaviour of renaming commands. The value is either
nil, in which case no confirmation is ever requested, or a list of
symbols among the following:
- `modify-file-name' means that renaming commands will ask for
confirmation before modifying the file name.
- `rewrite-front-matter' means that renaming commands will ask for
confirmation before rewritting the front matter.
- `add-front-matter' means that renaming commands will ask for
confirmation before adding new front matter to the file.
The default behaviour of the `denote-rename-file' command (and others
like it) is to ask for an affirmative answer as a final step before
changing the file name and, where relevant, inserting or updating the
corresponding front matter.
Specialized commands that build on top of `denote-rename-file' (or
related) may internally bind this user option to a non-nil value in
order to perform their operation (e.g. `denote-dired-rename-files' goes
through each marked Dired file, prompting for the information to use,
but carries out the renaming without asking for confirmation)."
:group 'denote
:type '(radio (const :tag "Disable all confirmations" nil)
(set :tag "Available confirmations" :greedy t
(const :tag "Add front matter" add-front-matter)
(const :tag "Rewrite front matter" rewrite-front-matter)
(const :tag "Modify file name" modify-file-name))))
(defcustom denote-excluded-directories-regexp nil
"Regular expression of directories to exclude from all operations.
Omit matching directories from file prompts and also exclude them
from all functions that check the contents of the variable
`denote-directory'. The regexp needs to match only the name of
the directory, not its full path.
File prompts are used by several commands, such as `denote-link'.
Functions that check for files include `denote-directories-files'
and `denote-directories-subdirectories'.
The match is performed with `string-match-p'."
:group 'denote
:type 'string)
(defcustom denote-excluded-keywords-regexp nil
"Regular expression of keywords to not infer.
Keywords are inferred from file names and provided at relevant
prompts as completion candidates when the user option
`denote-infer-keywords' is non-nil.
The match is performed with `string-match-p'."
:group 'denote
:type 'string)
(defcustom denote-after-new-note-hook nil
"Normal hook that runs after the `denote' command."
:group 'denote
:type 'hook)
(defcustom denote-after-rename-file-hook nil
"Normal hook called after a succesful Denote rename operation.
This affects the behaviour of the commands `denote-rename-file',
`denote-dired-rename-files', `denote-rename-file-using-front-matter',
`denote-dired-rename-marked-files-with-keywords',
`denote-dired-rename-marked-files-using-front-matter',
`denote-keywords-add', `denote-keywords-remove', and any other
command that builds on top of them."
:group 'denote
:type 'hook)
(defcustom denote-region-after-new-note-functions nil
"Abnormal hook called after `denote-region'.
Functions in this hook are called with two arguments,
representing the beginning and end buffer positions of the region
that was inserted in the new note. These are called only if
`denote-region' is invoked while a region is active.
A common use-case is to call `org-insert-structure-template'
after a region is inserted. This case does not actually require
the aforementioned arguments, in which case the function can
simply declare them as ignored by prefixing the argument names
with an underscore. For example, the following will prompt for a
structure template as soon as `denote-region' is done:
(defun my-denote-region-org-structure-template (_beg _end)
(when (derived-mode-p \\='org-mode)
(activate-mark)
(call-interactively \\='org-insert-structure-template)))
(add-hook \\='denote-region-after-new-note-functions
#\\='my-denote-region-org-structure-template)"
:group 'denote
:type 'hook)
(defvar denote-prompts-with-history-as-completion
'(denote-title-prompt denote-signature-prompt denote-files-matching-regexp-prompt)
"Prompts that conditionally perform completion against their history.
These are minibuffer prompts that ordinarily accept a free form string
input, as opposed to matching against a predefined set.
These prompts can optionally perform completion against their own
minibuffer history when the user option `denote-history-completion-in-prompts'
is set to a non-nil value.")
(defcustom denote-history-completion-in-prompts t
"Toggle history completion in all `denote-prompts-with-history-as-completion'.
When this user option is set to a non-nil value, use minibuffer history
entries as completion candidates in `denote-prompts-with-history-as-completion'.
Those will show previous inputs from their respective history as
possible values to select, either to (i) re-insert them verbatim or (ii)
with the intent to edit further (depending on the minibuffer user
interface, one can select a candidate with TAB without exiting the
minibuffer, as opposed to what RET normally does by selecting and
exiting).
When this user option is set to a nil value, all of the
`denote-prompts-with-history-as-completion' do not use minibuffer
completion: they just prompt for a string of characters. Their
history is still available through all the standard ways of retrieving
minibuffer history, such as with the command `previous-history-element'.
History completion still allows arbitrary values to be provided as
input: they do not have to match the available minibuffer completion
candidates.
Note that some prompts, like `denote-keywords-prompt', always use
minibuffer completion, due to the specifics of their data.
[ Consider enabling the built-in `savehist-mode' to persist minibuffer
histories between sessions.]
Also see `denote-prompts'."
:type 'boolean
:group 'denote)
(defcustom denote-file-name-slug-functions
'((title . denote-sluggify-title)
(signature . identity)
(keyword . identity))
"Specify the method Denote uses to format the components of the file name.
The value is an alist where each element is a cons cell of the
form (COMPONENT . METHOD).
- The COMPONENT is an unquoted symbol among `title', `signature',
`keyword' (notice the absence of `s', see below), which
refers to the corresponding component of the file name.
- The METHOD is the function to be used to format the given
component. This function should take a string as its parameter
and return the string formatted for the file name. In the case
of the `keyword' component, the function receives a SINGLE
string representing a single keyword and return it formatted
for the file name. Joining the keywords together is handled by
Denote.
Note that the `keyword' function is also applied to the keywords
of the front matter.
By default, if a function is not specified for a component, we
use `denote-sluggify-title' for the title.
Remember that deviating from the default file-naming scheme of Denote
will make things harder to search in the future, as files can/will have
permutations that create uncertainty. The sluggification scheme and
concomitant restrictions we impose by default are there for a very good
reason: they are the distillation of years of experience. Here we give
you what you wish, but bear in mind it may not be what you need. You
have been warned."
:group 'denote
:type '(alist :key (choice (const title)
(const signature)
(const keyword))
:value function))
(defcustom denote-link-description-function #'denote-link-description-with-signature-and-title
"Function to create the description of links.
The function specified takes a FILE argument and returns the description
as a string.
By default, the title of the file is returned as the description. If
the file has a signature, it is prepended to the title."
:group 'denote
:type '(choice
(function :tag "Link to title and include signature, if present" denote-link-description-with-signature-and-title)
(function :tag "Custom function like `denote-link-description-with-signature-and-title'")))
;;;; Main variables
;; For character classes, evaluate: (info "(elisp) Char Classes")
(defconst denote-id-format "%Y%m%dT%H%M%S"
"Format of ID prefix of a note's filename.
The note's ID is derived from the date and time of its creation.")
(defconst denote-id-regexp "\\([0-9]\\{8\\}\\)\\(T[0-9]\\{6\\}\\)"
"Regular expression to match `denote-id-format'.")
(defconst denote-signature-regexp "==\\([^.]*?\\)\\(@@.*\\|==.*\\|--.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the SIGNATURE field in a file name.")
(defconst denote-title-regexp "--\\([^.]*?\\)\\(@@.*\\|==.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the TITLE field in a file name.")
(defconst denote-keywords-regexp "__\\([^.]*?\\)\\(@@.*\\|==.*\\|--.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the KEYWORDS field in a file name.")
(defconst denote-excluded-punctuation-regexp "[][{}!@#$%^&*()=+'\"?,.\|;:~`‘’“”/]*"
"Punctionation that is removed from file names.
We consider those characters illegal for our purposes.")
;;;; File helper functions
(defun denote--completion-table (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category))
(complete-with-action action candidates string pred))))
(defun denote--completion-table-no-sort (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES.
Like `denote--completion-table' but also disable sorting."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category)
(display-sort-function . ,#'identity))
(complete-with-action action candidates string pred))))
(defun denote-directories ()
"Return paths of variable `denote-directory' as proper directories.
Custom Lisp code can `let' bind the variable `denote-directory'
to override what this function returns."
(let ((denote-directories
(if (listp denote-directory)
(mapcar (lambda (d)
(file-name-as-directory (expand-file-name d)))
denote-directory)
(list denote-directory))))
(mapc (lambda (d)
(when (not (file-directory-p d))
(make-directory d :parents)))
denote-directories)
denote-directories))
(defun denote-directory ()
"Return the first element of a call to the function `denote-directories'.
This function is deprecated. Use function `denote-directories' instead."
(car (denote-directories)))
(make-obsolete 'denote-directory 'denote-directories "3.0.0")
(defun denote--slug-no-punct (str)
"Remove punctuation from STR.
Concretely, replace with an empty string anything that matches
the `denote-excluded-punctuation-regexp'."
(if (stringp denote-excluded-punctuation-regexp)
(replace-regexp-in-string denote-excluded-punctuation-regexp "" str)
str))
(defun denote--slug-hyphenate (str)
"Replace spaces and underscores with hyphens in STR."
(replace-regexp-in-string "_\\|\s+" "-" str))
(defun denote--remove-dot-characters (str)
"Remove dot characters from STR."
(replace-regexp-in-string "\\." "" str))
(defun denote--trim-right-token-characters (str component)
"Remove =, -, _ and @ from the end of STR.
The removal is done only if necessary according to COMPONENT."
(if (eq component 'title)
(string-trim-right str "[=@_]+")
(string-trim-right str "[=@_-]+")))
(defun denote--replace-consecutive-token-characters (str component)
"Replace consecutive characters with a single one in STR.
Hyphens, underscores, equal signs and at signs are replaced with
a single one in str, if necessary according to COMPONENT."
(let ((str (replace-regexp-in-string
"_\\{2,\\}" "_"
(replace-regexp-in-string
"=\\{2,\\}" "="
(replace-regexp-in-string
"@\\{2,\\}" "@" str)))))
;; -- are allowed in titles
(if (eq component 'title)
str
(replace-regexp-in-string
"-\\{2,\\}" "-" str))))
(defun denote-sluggify (component str)
"Make STR an appropriate slug for file name COMPONENT.
Apply the function specified in `denote-file-name-slug-function'
to COMPONENT which is one of `title', `signature', `keyword'. If
the resulting string still contains consecutive -,_,= or @, they
are replaced by a single occurence of the character, if necessary
according to COMPONENT. If COMPONENT is `keyword', remove
underscores from STR as they are used as the keywords separator
in file names."
(let* ((slug-function (alist-get component denote-file-name-slug-functions))
(str-slug (cond ((eq component 'title)
(funcall (or slug-function #'denote-sluggify-title) str))
((eq component 'keyword)
(replace-regexp-in-string
"_" ""
(funcall (or slug-function #'identity) str)))
((eq component 'signature)
(funcall (or slug-function #'identity) str)))))
(denote--trim-right-token-characters
(denote--replace-consecutive-token-characters
(denote--remove-dot-characters str-slug) component) component)))
(defun denote--slug-put-equals (str)
"Replace spaces and underscores with equals signs in STR.
Also replace multiple equals signs with a single one and remove
any leading and trailing signs."
(replace-regexp-in-string
"^=\\|=$" ""
(replace-regexp-in-string
"=\\{2,\\}" "="
(replace-regexp-in-string "_\\|\s+" "=" str))))
(defun denote-sluggify-title (str)
"Make STR an appropriate slug for title."
(downcase (denote--slug-hyphenate (denote--slug-no-punct str))))
(defun denote-sluggify-keywords (keywords)
"Sluggify KEYWORDS, which is a list of strings."
(mapcar (lambda (keyword)
(denote-sluggify 'keyword keyword))
keywords))
(defun denote--file-empty-p (file)
"Return non-nil if FILE is empty."
(zerop (or (file-attribute-size (file-attributes file)) 0)))
(defun denote-file-has-identifier-p (file)
"Return non-nil if FILE has a Denote identifier."
(denote-retrieve-filename-identifier file))
(defun denote-file-has-supported-extension-p (file)
"Return non-nil if FILE has supported extension.
Also account for the possibility of an added .gpg suffix.
Supported extensions are those implied by `denote-file-type'."
(seq-some (lambda (e)
(string-suffix-p e file))
(denote-file-type-extensions-with-encryption)))
(defun denote-filename-is-note-p (filename)
"Return non-nil if FILENAME is a valid name for a Denote note.
For our purposes, its path must be part of the variable
`denote-directory', it must have a Denote identifier in its name,
and use one of the extensions implied by `denote-file-type'."
(and (seq-some
(lambda (d)
(string-prefix-p d (expand-file-name filename)))
(denote-directories))
(denote-file-has-identifier-p filename)
(denote-file-has-supported-extension-p filename)))
(defun denote-file-is-note-p (file)
"Return non-nil if FILE is an actual Denote note.
For our purposes, a note must satisfy `file-regular-p' and
`denote-filename-is-note-p'."
(and (file-regular-p file) (denote-filename-is-note-p file)))
(defun denote-file-has-signature-p (file)
"Return non-nil if FILE has a Denote identifier."
(denote-retrieve-filename-signature file))
(defun denote--file-regular-writable-p (file)
"Return non-nil if FILE is regular and writable."
(and (file-regular-p file)
(file-writable-p file)))
(defun denote-file-is-writable-and-supported-p (file)
"Return non-nil if FILE is writable and has supported extension."
;; We do not want to test that the file is regular (exists) because we want
;; this function to return t on files that are still unsaved.
(and (file-writable-p file)
(denote-file-has-supported-extension-p file)))
(defun denote-get-file-name-relative-to-denote-directories (file)
"Return name of FILE relative to the variable `denote-directory'.
FILE must be an absolute path."
(when-let ((directories (denote-directories))
((file-name-absolute-p file))
(file-name (expand-file-name file))
(directory (seq-find
(lambda (d)
(string-prefix-p d file-name))
directories)))
(substring-no-properties file-name (length directory))))
(defun denote-extract-id-from-string (string)
"Return existing Denote identifier in STRING, else nil."
(when (string-match denote-id-regexp string)
(match-string-no-properties 0 string)))
(defun denote--exclude-directory-regexp-p (file)
"Return non-nil if FILE matches `denote-excluded-directories-regexp'."
(and denote-excluded-directories-regexp
(string-match-p denote-excluded-directories-regexp file)))
(defun denote--directories-files-recursively-predicate (file)
"Predicate used by `directory-files-recursively' on FILE.
Return t if FILE is valid, else return nil."
(let ((rel (denote-get-file-name-relative-to-denote-directories file)))
(cond
((string-match-p "\\`\\." rel) nil)
((string-match-p "/\\." rel) nil)
((denote--exclude-directory-regexp-p rel) nil)
((file-readable-p file)))))
(defun denote--directories-all-files-recursively ()
"Return list of all files in variable `denote-directory'.
Avoids traversing dotfiles (unconditionally) and whatever matches
`denote-excluded-directories-regexp'."
(apply #'append
(mapcar
(lambda (directory)
(directory-files-recursively
directory
directory-files-no-dot-files-regexp
:include-directories
#'denote--directories-files-recursively-predicate
:follow-symlinks))
(denote-directories))))
(defun denote--directories-get-files ()
"Return list with full path of valid files in variable `denote-directory'.
Consider files that satisfy `denote-file-has-identifier-p' and
are not backups."
(mapcar
#'expand-file-name
(seq-filter
(lambda (file)
(and (file-regular-p file)
(denote-file-has-identifier-p file)
(not (backup-file-name-p file))))
(denote--directories-all-files-recursively))))
(defun denote-directories-files (&optional files-matching-regexp omit-current text-only)
"Return list of absolute file paths in variable `denote-directory'.
Files only need to have an identifier. The return value may thus
include file types that are not implied by `denote-file-type'.
With optional FILES-MATCHING-REGEXP, restrict files to those
matching the given regular expression.
With optional OMIT-CURRENT as a non-nil value, do not include the
current Denote file in the returned list.
With optional TEXT-ONLY as a non-nil value, limit the results to
text files that satisfy `denote-filename-is-note-p'."
(let ((files (denote--directories-get-files)))
(when (and omit-current buffer-file-name (denote-file-has-identifier-p buffer-file-name))
(setq files (delete buffer-file-name files)))
(when files-matching-regexp
(setq files (seq-filter
(lambda (f)
(string-match-p files-matching-regexp (denote-get-file-name-relative-to-denote-directories f)))
files)))
(when text-only
(setq files (seq-filter #'denote-filename-is-note-p files)))
files))
(defalias 'denote-directory-files 'denote-directories-files)
(defun denote-directories-subdirectories ()
"Return list of subdirectories in variable `denote-directory'.
Omit dotfiles (such as .git) unconditionally. Also exclude
whatever matches `denote-excluded-directories-regexp'."
(seq-remove
(lambda (filename)
(let ((rel (denote-get-file-name-relative-to-denote-directories filename)))
(or (not (file-directory-p filename))
(string-match-p "\\`\\." rel)
(string-match-p "/\\." rel)
(denote--exclude-directory-regexp-p rel))))
(denote--directories-all-files-recursively)))
;; TODO 2023-01-24: Perhaps there is a good reason to make this a user
;; option, but I am keeping it as a generic variable for now.
(defvar denote-encryption-file-extensions '(".gpg" ".age")
"List of strings specifying file extensions for encryption.")
(defun denote-file-type-extensions-with-encryption ()
"Derive `denote-file-type-extensions' plus `denote-encryption-file-extensions'."
(let ((file-extensions (denote-file-type-extensions))
all)
(dolist (ext file-extensions)
(dolist (enc denote-encryption-file-extensions)
(push (concat ext enc) all)))
(append file-extensions all)))
(defun denote-get-file-extension (file)
"Return extension of FILE with dot included.
Account for `denote-encryption-file-extensions'. In other words,
return something like .org.gpg if it is part of the file, else
return .org."
(let ((outer-extension (file-name-extension file :period)))
(if-let (((member outer-extension denote-encryption-file-extensions))
(file (file-name-sans-extension file))
(inner-extension (file-name-extension file :period)))
(concat inner-extension outer-extension)
outer-extension)))
(defun denote-get-file-extension-sans-encryption (file)
"Return extension of FILE with dot included and without the encryption part.
Build on top of `denote-get-file-extension' though always return
something like .org even if the actual file extension is
.org.gpg."
(let ((extension (denote-get-file-extension file)))
(if (string-match (regexp-opt denote-encryption-file-extensions) extension)
(substring extension 0 (match-beginning 0))
extension)))
(defun denote-get-path-by-id (id)
"Return absolute path of ID string in `denote-directories-files'."
(let ((files
(seq-filter
(lambda (file)
(string= id (denote-retrieve-filename-identifier file)))
(denote-directories-files))))
(if (length< files 2)
(car files)
;; In principle, there should not exist duplicate identifiers.
;; However, when exporting a note, another file with the same file
;; name can be created. This happens mostly with org. Thus, we
;; return the first item that has the same type as