2022-06-07 16:22:03 +02:00
|
|
|
|
#+title: denote: Simple notes with a strict file-naming scheme
|
|
|
|
|
#+author: Protesilaos Stavrou
|
|
|
|
|
#+email: info@protesilaos.com
|
|
|
|
|
#+language: en
|
|
|
|
|
#+options: ':t toc:nil author:t email:t num:t
|
|
|
|
|
#+startup: content
|
2022-06-04 06:44:22 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+macro: stable-version N/A
|
|
|
|
|
#+macro: release-date N/A
|
|
|
|
|
#+macro: development-version 0.1.0-dev
|
|
|
|
|
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
|
|
|
|
|
#+macro: space @@texinfo:@: @@
|
|
|
|
|
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
|
2022-06-04 10:15:20 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+export_file_name: denote.texi
|
2022-06-04 10:15:20 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+texinfo_filename: denote.info
|
|
|
|
|
#+texinfo_dir_category: Emacs misc features
|
|
|
|
|
#+texinfo_dir_title: Denote: (denote)
|
|
|
|
|
#+texinfo_dir_desc: Simple notes with a strict file-naming scheme
|
|
|
|
|
#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage}
|
|
|
|
|
#+texinfo_header: @set MAINTAINER Protesilaos Stavrou
|
|
|
|
|
#+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com}
|
|
|
|
|
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer}
|
2022-06-04 10:15:20 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+texinfo: @insertcopying
|
2022-06-04 10:15:20 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
This manual, written by Protesilaos Stavrou, describes the customization
|
|
|
|
|
options for the Emacs package called =denote= (or =denote.el=), and
|
|
|
|
|
provides every other piece of information pertinent to it.
|
2022-06-04 10:15:20 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
The documentation furnished herein corresponds to stable version
|
|
|
|
|
{{{stable-version}}}, released on {{{release-date}}}. Any reference to
|
|
|
|
|
a newer feature which does not yet form part of the latest tagged
|
|
|
|
|
commit, is explicitly marked as such.
|
2022-06-04 06:44:22 +02:00
|
|
|
|
|
2022-06-09 07:36:13 +02:00
|
|
|
|
Current development target is {{{development-version}}}. Note that the
|
|
|
|
|
project is still in active development and THINGS MIGHT CHANGE IN
|
|
|
|
|
BACKWARD-INCOMPATIBLE WAYS until we make the first stable release.
|
2022-06-04 06:44:22 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
+ Homepage: https://protesilaos.com/emacs/denote.
|
2022-06-07 17:47:24 +02:00
|
|
|
|
# + Change log: https://protesilaos.com/emacs/denote-changelog.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
+ Git repository: https://git.sr.ht/~protesilaos/denote.
|
|
|
|
|
+ Mailing list: https://lists.sr.ht/~protesilaos/denote.
|
|
|
|
|
|
|
|
|
|
#+toc: headlines 8 insert TOC here, with eight headline levels
|
|
|
|
|
|
|
|
|
|
* COPYING
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:COPYING: t
|
|
|
|
|
:CUSTOM_ID: h:40b18bb2-4dc1-4202-bd0b-6fab535b2a0f
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2022 Free Software Foundation, Inc.
|
|
|
|
|
|
|
|
|
|
#+begin_quote
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
|
|
|
any later version published by the Free Software Foundation; with no
|
|
|
|
|
Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and
|
|
|
|
|
with the Back-Cover Texts as in (a) below. A copy of the license is
|
|
|
|
|
included in the section entitled “GNU Free Documentation License.”
|
|
|
|
|
|
|
|
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
|
|
|
|
modify this GNU manual.”
|
|
|
|
|
#+end_quote
|
|
|
|
|
|
|
|
|
|
* Overview
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:a09b70a2-ae0b-4855-ac14-1dddfc8e3241
|
|
|
|
|
:END:
|
|
|
|
|
|
2022-06-13 07:11:37 +02:00
|
|
|
|
NOTE THAT WE ARE ACTIVELY WORKING TOWARDS VERSION =0.1.0= AND MIGHT
|
|
|
|
|
STILL INTRODUCE BREAKING, BACKWARD-INCOMPATIBLE CHANGES. This is
|
|
|
|
|
particularly true for the linking facility. Everything else is in a
|
|
|
|
|
stable state.
|
|
|
|
|
|
|
|
|
|
Denote aims to be a simple-to-use, focused-in-scope, and effective
|
|
|
|
|
note-taking tool for Emacs. It is based on the following core design
|
|
|
|
|
principles:
|
|
|
|
|
|
|
|
|
|
+ Predictability :: File names must follow a consistent and descriptive
|
|
|
|
|
naming convention ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][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 ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
|
|
|
|
|
|
|
|
|
|
+ Composability :: Be a good Emacs citizen, by integrating with other
|
|
|
|
|
packages or built-in functionality instead of re-inventing functions
|
2022-06-15 11:06:21 +02:00
|
|
|
|
such as for filtering or greping. Do not introduce strong
|
|
|
|
|
dependencies on specific libraries. The author of Denote (Protesilaos,
|
|
|
|
|
aka "Prot") writes ordinary notes in plain text (=.txt=), switching to
|
|
|
|
|
an Org file only when its expanded set of functionality is required
|
|
|
|
|
for the task at hand ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]).
|
2022-06-13 07:11:37 +02:00
|
|
|
|
|
|
|
|
|
+ Portability :: Notes are plain text and should remain portable. The
|
|
|
|
|
way Denote writes file names, the front matter it include 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. It is
|
|
|
|
|
up to the user to apply the requisite rigor in pursuit of their
|
|
|
|
|
preferred workflow.
|
|
|
|
|
|
|
|
|
|
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
|
2022-06-10 13:21:55 +02:00
|
|
|
|
+ Denote Everything Neatly; Omit The Excesses
|
|
|
|
|
|
2022-06-10 15:10:07 +02:00
|
|
|
|
But we'll let you get back to work. Don't Eschew or Neglect your
|
2022-06-13 07:11:37 +02:00
|
|
|
|
Obligations, Tasks, and Engagements.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
|
|
|
|
* The file-naming scheme
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d
|
|
|
|
|
:END:
|
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
#+vindex: denote-directory
|
|
|
|
|
Notes are stored as a flat list in the ~denote-directory~ (i.e. no
|
|
|
|
|
subdirectories). The default path is =~/Documents/notes=.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
Every note produced by Denote follows this pattern ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]):
|
|
|
|
|
|
|
|
|
|
: DATE--TITLE__KEYWORDS.EXTENSION
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
|
|
|
|
The =DATE= field represents the date in year-month-day format followed
|
2022-06-10 06:46:52 +02:00
|
|
|
|
by the capital letter =T= (for "time") and the current time in
|
|
|
|
|
hour-minute-second notation. The presentation is compact:
|
|
|
|
|
=20220531T091625=. The =DATE= serves as the unique identifier of each
|
|
|
|
|
note.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
The =TITLE= field is the title of the note, as provided by the user. It
|
|
|
|
|
automatically gets downcased and hyphenated. An entry about "Economics
|
|
|
|
|
in the Euro Area" produces an =economics-in-the-euro-area= string for
|
|
|
|
|
the =TITLE= of the file name.
|
2022-06-10 07:05:44 +02:00
|
|
|
|
|
2022-06-13 06:31:15 +02:00
|
|
|
|
#+vindex: denote-allow-multi-word-keywords
|
2022-06-11 11:20:25 +02:00
|
|
|
|
The =KEYWORDS= field consists of one or more entries demarcated by an
|
|
|
|
|
underscore (the separator is inserted automatically). Each keyword is a
|
2022-06-07 16:22:03 +02:00
|
|
|
|
string provided by the user at the relevant prompt which broadly
|
|
|
|
|
describes the contents of the entry. Keywords that need to be more than
|
2022-06-11 11:20:25 +02:00
|
|
|
|
one-word-long must be written with hyphens: any other character, such as
|
2022-06-13 06:31:15 +02:00
|
|
|
|
spaces or the plus sign is automatically converted into a hyphen. So
|
|
|
|
|
when =emacs_library= appears in a file name, it is interpreted as two
|
2022-06-11 11:20:25 +02:00
|
|
|
|
distinct keywords, whereas =emacs-library= is one keyword. This is
|
|
|
|
|
reflected in how the keywords are recorded in the note ([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
|
2022-06-13 06:31:15 +02:00
|
|
|
|
While Denote supports multi-word keywords by default, the user option
|
|
|
|
|
~denote-allow-multi-word-keywords~ can be set to nil to forcibly join
|
|
|
|
|
all words into one, meaning that an input of =word1 word2= will be
|
|
|
|
|
written as =word1word2=.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-10 12:26:31 +02:00
|
|
|
|
#+vindex: denote-file-type
|
|
|
|
|
The =EXTENSION= is the file type. By default, it is =.org= (~org-mode~)
|
|
|
|
|
though the user option ~denote-file-type~ provides support for Markdown
|
2022-06-11 11:20:25 +02:00
|
|
|
|
with YAML or TOML variants (=.md= which runs ~markdown-mode~) and plain
|
|
|
|
|
text (=.txt= via ~text-mode~). Consult its doc string for the minutia.
|
|
|
|
|
While files end in the =.org= extension by default, the Denote code base
|
|
|
|
|
does not actually depend on org.el and/or its accoutrements.
|
2022-06-10 12:26:31 +02:00
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
Examples:
|
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
: 20220610T043241--initial-thoughts-on-the-zettelkasten-method__notetaking.org
|
|
|
|
|
: 20220610T062201--define-custom-org-hyperlink-type__denote_emacs_package.md
|
|
|
|
|
: 20220610T162327--on-hierarchy-and-taxis__notetaking_philosophy.txt
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
The different field separators, namely =--= and =__= introduce an
|
|
|
|
|
efficient way to anchor searches (such as with Emacs commands like
|
|
|
|
|
~isearch~ or from the command-line with ~find~ and related). A query
|
|
|
|
|
for =_word= always matches a keyword, while a regexp in the form of,
|
|
|
|
|
say, ="\\([0-9T]+?\\)--\\(.*?\\)_"= captures the date in group =\1= and
|
|
|
|
|
the title in =\2= (test any regular expression in the current buffer by
|
|
|
|
|
invoking =M-x re-builder=).
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-11 11:20:25 +02:00
|
|
|
|
[[#h:8ed2bb6f-b5be-4711-82e9-8bee5bb06ece][Extending Denote]].
|
|
|
|
|
|
|
|
|
|
While Denote is an Emacs package, notes should work long-term and not
|
|
|
|
|
depend on the functionality of a specific program. The file-naming
|
|
|
|
|
scheme we apply guarantees that a listing is readable in a variety of
|
|
|
|
|
contexts.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-11 11:19:26 +02:00
|
|
|
|
** Sluggified title and keywords
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:ae8b19a1-7f67-4258-96b3-370a72c43f4e
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Denote has to be highly opinionated about which characters can be used
|
|
|
|
|
in file names and the file's front matter in order to enforce its
|
|
|
|
|
file-naming scheme. The private variable ~denote--punctuation-regexp~
|
|
|
|
|
holds the relevant value. In simple terms:
|
|
|
|
|
|
|
|
|
|
+ What we count as "illegal characters" are converted into hyphens.
|
|
|
|
|
|
|
|
|
|
+ Input for a file title is hyphenated and downcased. The original
|
|
|
|
|
value is preserved only in the note's contents ([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
|
|
|
|
|
|
|
|
|
|
+ Keywords should not have spaces or other delimiters. If they do, they
|
|
|
|
|
are converted into hyphens. Keywords are always downcased.
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
* Points of entry
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:17896c8c-d97a-4faa-abf6-31df99746ca6
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
#+findex: denote
|
2022-06-13 14:04:08 +02:00
|
|
|
|
#+findex: denote-type
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+findex: denote-org-capture
|
2022-06-13 14:04:08 +02:00
|
|
|
|
There are three ways to write a note with Denote: invoke the ~denote~,
|
|
|
|
|
or ~denote-type~ commands, or leverage the ~org-capture-templates~ by
|
|
|
|
|
setting up a template which calls the function ~denote-org-capture~.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-13 14:04:08 +02:00
|
|
|
|
In the first case, all that is needed is to run ~denote~. It will
|
2022-06-07 16:22:03 +02:00
|
|
|
|
prompt for a title. Once it is supplied, the command will ask for
|
|
|
|
|
keywords. The resulting note will have a file name as already explained
|
|
|
|
|
([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file naming scheme]]).
|
|
|
|
|
|
|
|
|
|
#+vindex: denote-known-keywords
|
|
|
|
|
#+vindex: denote-infer-keywords
|
|
|
|
|
The keyword prompt supports minibuffer completion. Available candidates
|
|
|
|
|
are those defined in the user option ~denote-known-keywords~. More
|
|
|
|
|
candidates can be inferred from the names of existing notes, by setting
|
|
|
|
|
~denote-infer-keywords~ to non-nil (which is the case by default).
|
|
|
|
|
|
2022-06-08 11:32:52 +02:00
|
|
|
|
#+vindex: denote-sort-keywords
|
2022-06-07 16:22:03 +02:00
|
|
|
|
Multiple keywords can be inserted by separating them with a comma (or
|
|
|
|
|
whatever the value of the ~crm-indicator~ is---which should be a comma).
|
2022-06-08 11:32:52 +02:00
|
|
|
|
When the user option ~denote-sort-keywords~ is non-nil (the default),
|
|
|
|
|
keywords are sorted alphabetically (technically, the sorting is done
|
|
|
|
|
with ~string-lessp~).
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
|
|
|
|
The ~denote~ command can also be called from Lisp, in which case it
|
2022-06-07 20:29:48 +02:00
|
|
|
|
expects the =TITLE= and =KEYWORDS= arguments. The former is a string,
|
|
|
|
|
the latter a list of strings.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
2022-06-13 14:04:08 +02:00
|
|
|
|
The ~denote-type~ command is like ~denote~ except it also prompts for a
|
|
|
|
|
file type to use as a local value for ~denote-file-type~. In practical
|
|
|
|
|
terms, this lets you produce, say, a note in Markdown even though you
|
|
|
|
|
normally write in Org ([[#h:f34b172b-3440-446c-aec1-bf818d0aabfe][Notes in multiple file types]]).
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
For integration with ~org-capture~, the user must first add the relevant
|
|
|
|
|
template. Such as:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(with-eval-after-load 'org-capture
|
|
|
|
|
(require 'denote-org-capture)
|
|
|
|
|
(add-to-list 'org-capture-templates
|
|
|
|
|
'("n" "New note (with Denote)" plain
|
|
|
|
|
(file denote-last-path)
|
|
|
|
|
#'denote-org-capture
|
|
|
|
|
:no-save t
|
|
|
|
|
:immediate-finish nil
|
|
|
|
|
:kill-buffer t
|
|
|
|
|
:jump-to-captured t)))
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
[ In the future, we might develop Denote in ways which do not require such
|
|
|
|
|
manual intervation. ]
|
|
|
|
|
|
|
|
|
|
Once the template is added, it is accessed from the specified key. If,
|
|
|
|
|
for instance, ~org-capture~ is bound to =C-c c=, then the note creation
|
|
|
|
|
is initiated with =C-c c n=. After that, the process is the same as
|
|
|
|
|
with invoking ~denote~ directly, namely: a prompt for a title followed
|
|
|
|
|
by a prompt for keywords.
|
|
|
|
|
|
|
|
|
|
#+vindex: denote-org-capture-specifiers
|
|
|
|
|
Users may prefer to leverage ~org-capture~ in order to extend file
|
|
|
|
|
creation with the specifiers described in the ~org-capture-templates~
|
|
|
|
|
documentation (such as to capture the active region and/or create a
|
|
|
|
|
hyperlink pointing to the given context). Due to the particular
|
|
|
|
|
file-naming scheme of Denote, such specifiers cannot be written directly
|
|
|
|
|
in the template. Instead, they have to be assigned to the user option
|
|
|
|
|
~denote-org-capture-specifiers~, which is interpreted by the function
|
|
|
|
|
~denote-org-capture~. Example with our default value:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(setq denote-org-capture-specifiers "%l\n%i\n%?")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-10 14:04:10 +02:00
|
|
|
|
Note that ~denote-org-capture~ ignores the ~denote-file-type~: it always
|
|
|
|
|
sets the Org file extension for the created note to ensure that the
|
|
|
|
|
capture process works as intended, especially for the desired output of
|
|
|
|
|
the ~denote-org-capture-specifiers~.
|
|
|
|
|
|
2022-06-15 18:10:21 +02:00
|
|
|
|
#+findex: denote-create-note
|
|
|
|
|
#+findex: denote-create-note-using-type
|
|
|
|
|
For convencience, the ~denote~ command has a ~denote-create-note~ alias.
|
|
|
|
|
Same for ~denote-type~: ~denote-create-note-using-type~. The purpose of
|
|
|
|
|
these aliases is to provide alternative, more descriptive names of select
|
|
|
|
|
commands to aid with discoverability.
|
|
|
|
|
|
2022-06-12 04:45:28 +02:00
|
|
|
|
* Renaming files
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Denote's file-naming scheme is not specific to notes or text files: it
|
|
|
|
|
is useful for all sorts of files, such as multimedia and PDFs that form
|
|
|
|
|
part of the user's longer-term storage ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]). While
|
|
|
|
|
Denote does not manage such files, it already has all the mechanisms to
|
|
|
|
|
facilitate the task of renaming them.
|
|
|
|
|
|
|
|
|
|
#+findex: denote-dired-rename-file
|
|
|
|
|
To this end, we provide the ~denote-dired-rename-file~ command. It has
|
2022-06-12 15:44:01 +02:00
|
|
|
|
a two-fold purpose: (i) to change the name of an existing file while
|
|
|
|
|
retaining its identifier and (ii) to write a Denote-compliant file name
|
|
|
|
|
for an item that was not created by ~denote~ or related commands (such
|
|
|
|
|
as an image or PDF).
|
2022-06-12 04:45:28 +02:00
|
|
|
|
|
|
|
|
|
The ~denote-dired-rename-file~ command will target the file at point if
|
|
|
|
|
it finds one in the current Dired buffer. Otherwise it prompts with
|
|
|
|
|
minibuffer completion for a file name. It then uses the familiar
|
|
|
|
|
prompts for a =TITLE= and =KEYWORDS= the same way the ~denote~ command
|
2022-06-12 15:44:01 +02:00
|
|
|
|
does ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). As a final step, it asks for confirmation
|
2022-06-12 04:45:28 +02:00
|
|
|
|
before renaming the file at point, showing a message like:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
2022-06-12 13:01:18 +02:00
|
|
|
|
Rename sample.pdf to 20220612T052900--my-sample-title__testing.pdf? (y or n)
|
2022-06-12 04:45:28 +02:00
|
|
|
|
#+end_example
|
|
|
|
|
|
2022-06-12 16:16:31 +02:00
|
|
|
|
#+vindex: denote-dired-rename-expert
|
|
|
|
|
However, if the user option ~denote-dired-rename-expert~ is non-nil,
|
|
|
|
|
conduct the renaming operation outright---no questions asked.
|
|
|
|
|
|
2022-06-12 15:44:01 +02:00
|
|
|
|
When operating on a file that has no identifier, such as =sample.pdf=,
|
|
|
|
|
Denote reads the file properties to retrieve its last modification time.
|
|
|
|
|
If the file was from a past date like 2000-11-31 it will get an
|
|
|
|
|
identifier starting with =20001131= followed by the time component (per
|
|
|
|
|
our file-naming scheme).
|
|
|
|
|
|
2022-06-12 04:45:28 +02:00
|
|
|
|
The file type extension (e.g. =.pdf=) is read from the underlying file
|
2022-06-12 15:44:01 +02:00
|
|
|
|
and is preserved through the renaming process. Files that have no
|
|
|
|
|
extension are simply left without one.
|
2022-06-12 04:45:28 +02:00
|
|
|
|
|
|
|
|
|
Renaming only occurs relative to the current directory. Files are not
|
|
|
|
|
moved between directories.
|
|
|
|
|
|
2022-06-10 13:21:09 +02:00
|
|
|
|
* Front matter
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:13218826-56a5-482a-9b91-5b6de4f14261
|
|
|
|
|
:END:
|
|
|
|
|
|
2022-06-08 11:33:07 +02:00
|
|
|
|
Notes have their own "front matter". This is a block of data at the top
|
2022-06-10 13:21:09 +02:00
|
|
|
|
of the file, which is automatically generated at the creation of a new
|
|
|
|
|
note. The front matter includes the title and keywords (aka "tags" or
|
|
|
|
|
"filetags", depending on the file type) which the user specified at the
|
|
|
|
|
relevant prompt, as well as the date and unique identifier which are
|
|
|
|
|
derived automatically.
|
|
|
|
|
|
|
|
|
|
This is how it looks for Org mode (~denote-file-type~ is nil):
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
#+title: This is a sample note
|
|
|
|
|
#+date: 2022-06-10
|
|
|
|
|
#+filetags: denote testing
|
2022-06-10 19:27:59 +02:00
|
|
|
|
#+identifier: 20220610T202537
|
2022-06-10 13:21:09 +02:00
|
|
|
|
#+end_example
|
|
|
|
|
|
2022-06-10 19:16:11 +02:00
|
|
|
|
For Markdown with YAML, it looks like this (~denote-file-type~ has the
|
2022-06-10 16:32:24 +02:00
|
|
|
|
=markdown-yaml= value):
|
2022-06-10 13:21:09 +02:00
|
|
|
|
|
2022-06-10 19:16:11 +02:00
|
|
|
|
#+begin_example
|
2022-06-10 13:21:09 +02:00
|
|
|
|
---
|
2022-06-10 19:27:59 +02:00
|
|
|
|
title: "This is a sample note"
|
2022-06-10 13:21:09 +02:00
|
|
|
|
date: 2022-06-10
|
|
|
|
|
tags: denote testing
|
2022-06-10 19:27:59 +02:00
|
|
|
|
identifier: "20220610T202021"
|
2022-06-10 13:21:09 +02:00
|
|
|
|
---
|
2022-06-10 19:16:11 +02:00
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
|
|
For Markdown with TOML, it looks like this (~denote-file-type~ has the
|
|
|
|
|
=markdown-toml= value):
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
+++
|
|
|
|
|
title = "This is a sample note"
|
|
|
|
|
date = 2022-06-10
|
|
|
|
|
tags = ["denote", "testing"]
|
|
|
|
|
identifier = "20220610T201510"
|
|
|
|
|
+++
|
|
|
|
|
#+end_example
|
2022-06-10 13:21:09 +02:00
|
|
|
|
|
|
|
|
|
And for plain text, we have the following (~denote-file-type~ has the
|
|
|
|
|
=text= value):
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
title: This is a sample note
|
|
|
|
|
date: 2022-06-10
|
|
|
|
|
tags: denote testing
|
2022-06-10 19:27:59 +02:00
|
|
|
|
identifier: 20220610T202232
|
2022-06-10 13:21:09 +02:00
|
|
|
|
---------------------------
|
|
|
|
|
#+end_example
|
2022-06-08 11:33:07 +02:00
|
|
|
|
|
|
|
|
|
#+vindex: denote-front-matter-date-format
|
|
|
|
|
The format of the date in the front matter is controlled by the user
|
|
|
|
|
option ~denote-front-matter-date-format~:
|
|
|
|
|
|
|
|
|
|
- When the value is nil (the default), the date uses a plain
|
2022-06-11 07:33:46 +02:00
|
|
|
|
=YEAR-MONTH-DAY= notation, like =2022-06-08= (the ISO 8601 standard).
|
|
|
|
|
|
2022-06-08 11:33:07 +02:00
|
|
|
|
- When the value is the =org-timestamp= symbol, the date is recorded as
|
|
|
|
|
an inactive Org timestamp, such as =[2022-06-08 Wed 06:19]=.
|
2022-06-11 07:33:46 +02:00
|
|
|
|
|
2022-06-08 11:33:07 +02:00
|
|
|
|
- An arbitrary string value is interpreted as the argument for the
|
|
|
|
|
function ~format-time-string~. This gives the user maximum control
|
|
|
|
|
over how time is represented in the front matter.
|
|
|
|
|
|
2022-06-11 07:33:46 +02:00
|
|
|
|
When ~denote-file-type~ specifies one of the Markdown flavors, we ignore
|
|
|
|
|
this user option in order to enforce the RFC3339 specification (Markdown
|
|
|
|
|
is typically employed in static site generators as source code for Web
|
|
|
|
|
pages). However, when ~denote-front-matter-date-format~ has a string
|
|
|
|
|
value, this rule is suspended: we use whatever the user wants.
|
|
|
|
|
|
2022-06-11 08:38:13 +02:00
|
|
|
|
** Tweaking the front matter
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:f69371d5-1843-493d-9ff5-c1ab3b43024e
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
What follows is for advanced users. When in doubt, only configure
|
|
|
|
|
variables we describe as a "user option": they are declared in the
|
|
|
|
|
source code with the ~defcustom~ keyword.
|
|
|
|
|
|
|
|
|
|
Denote's code base is designed in a composable way, which lets the user
|
|
|
|
|
make precise interventions to affect the output of the relevant
|
|
|
|
|
commands. One such case is to configure the front matter, such as by
|
|
|
|
|
changing the order the keys appear in, renaming them, or adding new
|
|
|
|
|
elements.
|
|
|
|
|
|
|
|
|
|
Some examples are in order, starting with the Org file type. This is
|
|
|
|
|
what we have in =denote.el=:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defvar denote-org-front-matter
|
|
|
|
|
"#+title: %s
|
|
|
|
|
#+date: %s
|
|
|
|
|
#+filetags: %s
|
|
|
|
|
#+identifier: %s
|
|
|
|
|
\n"
|
|
|
|
|
"Org front matter value for `format'.
|
|
|
|
|
The order of the arguments is TITLE, DATE, KEYWORDS, ID. If you
|
|
|
|
|
are an avdanced user who wants to edit this variable to affect
|
|
|
|
|
how front matter is produced, consider using something like %2$s
|
|
|
|
|
to control where Nth argument is placed.")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
The default front matter is:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
#+title: This is a sample note
|
|
|
|
|
#+date: 2022-06-10
|
|
|
|
|
#+filetags: denote testing
|
|
|
|
|
#+identifier: 20220610T202537
|
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
|
|
We can add a =PROPERTIES= drawer to it, with something like this:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(setq denote-org-front-matter
|
|
|
|
|
":PROPERTIES:
|
|
|
|
|
:ID: %4$s
|
|
|
|
|
:END:
|
|
|
|
|
#+title: %1$s
|
|
|
|
|
#+date: %2$s
|
|
|
|
|
#+filetags: %3$s
|
|
|
|
|
#+identifier: %4$s
|
|
|
|
|
\n")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
The output is now formatted thus:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:ID: 20220611T092444
|
|
|
|
|
:END:
|
|
|
|
|
#+title: This is a sample note
|
|
|
|
|
#+date: 2022-06-11
|
|
|
|
|
#+filetags: denote testing
|
|
|
|
|
#+identifier: 20220611T092444
|
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
|
|
Notice how we can pass a number to the =%s= specifier. This is what
|
|
|
|
|
allows us to change the placement of the provided arguments.
|
|
|
|
|
|
|
|
|
|
For another example, we will use the plain text variant, as it differs a
|
|
|
|
|
bit from the above. By default it is formatted this way:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
title: This is a sample note
|
|
|
|
|
date: 2022-06-10
|
|
|
|
|
tags: denote testing
|
|
|
|
|
identifier: 20220610T202232
|
|
|
|
|
---------------------------
|
|
|
|
|
#+end_example
|
|
|
|
|
|
2022-06-13 07:25:32 +02:00
|
|
|
|
The line with the hyphens is the product of the fifth format specifier,
|
|
|
|
|
as documented in ~denote-text-front-matter~. Its value is stored in
|
|
|
|
|
~denote-text-front-matter-delimiter~. Say we want to have a delimiter
|
|
|
|
|
both at the top and bottom:
|
2022-06-11 08:38:13 +02:00
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(setq denote-text-front-matter
|
|
|
|
|
"%5$s
|
|
|
|
|
title: %1$s
|
|
|
|
|
date: %2$s
|
|
|
|
|
tags: %3$s
|
|
|
|
|
identifier: %4$s
|
|
|
|
|
%5$s\n\n")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
Which gives us:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
---------------------------
|
|
|
|
|
title: This is a sample note
|
|
|
|
|
date: 2022-06-11
|
|
|
|
|
tags: denote testing
|
|
|
|
|
identifier: 20220611T093252
|
|
|
|
|
---------------------------
|
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
|
|
Or we would rather use another character instead of hyphens, such as the
|
|
|
|
|
equals sign:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
2022-06-13 07:27:03 +02:00
|
|
|
|
(setq denote-text-front-matter-delimiter (make-string 27 ?=))
|
2022-06-11 08:38:13 +02:00
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
Remember that this is for advanced users. If you want to see changes
|
|
|
|
|
done on this front, you are welcome to share your thoughts and/or
|
|
|
|
|
participate in the development of Denote.
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
* Linking notes
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:fc913d54-26c8-4c41-be86-999839e8ad31
|
|
|
|
|
:END:
|
|
|
|
|
|
2022-06-15 15:52:46 +02:00
|
|
|
|
*The linking facility is the only major area that needs to be reviewed
|
2022-06-15 11:06:21 +02:00
|
|
|
|
before releasing the first stable version of Denote.*
|
|
|
|
|
|
|
|
|
|
The ~denote-link~ command inserts a link at point to an entry specified
|
|
|
|
|
at the minibuffer prompt. Links are formatted depending on the file
|
|
|
|
|
type of current note. In Org and plain text buffers, links are
|
|
|
|
|
formatted thus: =[[denote:IDENTIFIER][TITLE]]=. While in Markdown they
|
|
|
|
|
are expressed as =[TITLE](denote:IDENTIFIER)=.
|
|
|
|
|
|
|
|
|
|
How those links behave will depend on the user's preference. Denote
|
|
|
|
|
provides a simple-minded implementation for such link, which either
|
|
|
|
|
works competently with point-and-click kind of interaction or, at the
|
|
|
|
|
user's discretion, is more rudimentary and depends on Denote commands
|
|
|
|
|
and/or Emacs' standard "future history" heuristics.
|
|
|
|
|
|
|
|
|
|
#+vindex: denote-link-register-ol-hyperlink
|
|
|
|
|
+ The "just works" approach depends on Org's ability to open links it
|
|
|
|
|
recognizes regardless of the current major-mode. The command for that
|
|
|
|
|
is ~org-open-at-point-global~. User may want to bind it to a key of
|
|
|
|
|
their choosing, with =C-c o= looking like a decent choice. Denote
|
|
|
|
|
defines a custom Org hyperlink and Org handles the rest. The user
|
|
|
|
|
option ~denote-link-register-ol-hyperlink~ determines whether Denote
|
|
|
|
|
will register such a hyperlink type. Users who do not want to load
|
|
|
|
|
Org, must set the variable to nil before loading denote-link.el.
|
|
|
|
|
|
|
|
|
|
The special prefix =denote:= lets us define links with only the
|
|
|
|
|
identifier. They are robust and will work even if the file is renamed
|
|
|
|
|
(~denote-dired-rename-file~ never modifies the identifier). Otherwise
|
|
|
|
|
they are familiar Org-style links in ~org-mode~ buffers. They can be
|
|
|
|
|
followed with a mouse click or the ~org-open-at-point~ command, and
|
|
|
|
|
they may be insterted with completion via the ~org-insert-link~
|
|
|
|
|
command after selecting the =denote:= link type.
|
|
|
|
|
|
|
|
|
|
+ The "rudimentary" method does not depend on Org's hyperlink
|
|
|
|
|
infrastructure. As a general feature of Emacs, any identifier that
|
|
|
|
|
appears in a note, can be expanded into the corresponding file name at
|
|
|
|
|
the same directory by leveraging Emacs' notion of "future history"
|
|
|
|
|
(predicting what the user wants). With point over the identifier,
|
|
|
|
|
=M-x find-file= followed by =M-n= will fill the path to that file.
|
|
|
|
|
|
|
|
|
|
Whatever the user's preference, Denote establishes links using the
|
|
|
|
|
note's identifier which is always unique and will yield the expected
|
|
|
|
|
results whether the user prefers Org, plain text, or even command-line
|
|
|
|
|
utilities.
|
|
|
|
|
|
|
|
|
|
Everything that follows is independent of the user's preference on
|
|
|
|
|
whether to use the Org hyperlink infrastructure (besides, the
|
|
|
|
|
Org-specific code is less than 30 lines as of 2022-06-15 11:50 +0300).
|
2022-06-14 18:39:55 +02:00
|
|
|
|
|
|
|
|
|
#+findex: denote-link-find-file
|
2022-06-15 11:06:21 +02:00
|
|
|
|
Denote has a major-mode-agnostic mechanism to collect all linked file
|
|
|
|
|
references in the current buffer and return them as an appropriately
|
|
|
|
|
formatted list. This list can then be used in interactive commands.
|
|
|
|
|
The ~denote-link-find-file~ is such a command. It uses minibuffer
|
|
|
|
|
completion to visit a file that is linked to from the current note. The
|
|
|
|
|
candidates have the correct metadata, meaning that a package such as
|
|
|
|
|
=marginalia= will display accurate annotations, while the =embark=
|
|
|
|
|
package will be able to work its magic such as in exporting the list
|
|
|
|
|
into a filtered Dired buffer (i.e. a familiar Dired listing with only
|
|
|
|
|
the files of the current minibuffer session).
|
2022-06-14 18:39:55 +02:00
|
|
|
|
|
2022-06-15 04:17:18 +02:00
|
|
|
|
#+findex: denote-link-backlinks
|
|
|
|
|
The command ~denote-link-backlinks~ produces a bespoke buffer which
|
|
|
|
|
displays the file name of all notes linking to the current one. Each
|
|
|
|
|
file name appears on its own line and is buttonized so that it performs
|
2022-06-15 11:06:21 +02:00
|
|
|
|
the action of visiting the referenced file. [Development note:
|
|
|
|
|
currently this depends on the =find= executable. Maybe we can make it
|
|
|
|
|
work with Emacs' ~xref~ facility to work everywhere.] The backlinks'
|
|
|
|
|
buffer looks like this:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
Backlinks to "On being honest" (20220614T130812)
|
|
|
|
|
------------------------------------------------
|
|
|
|
|
|
|
|
|
|
20220614T145606--let-this-glance-become-a-stare__journal.txt
|
|
|
|
|
#+end_example
|
2022-06-15 04:17:18 +02:00
|
|
|
|
|
|
|
|
|
#+vindex: denote-link-fontify-backlinks
|
2022-06-15 11:06:21 +02:00
|
|
|
|
The backlinks' buffer is fontified by default, though the user has
|
|
|
|
|
access to the ~denote-link-fontify-backlinks~ option to disable this
|
|
|
|
|
effect by setting its value to nil.
|
2022-06-15 04:17:18 +02:00
|
|
|
|
|
|
|
|
|
#+vindex: denote-link-backlinks-display-buffer-action
|
|
|
|
|
The placement of the backlinks' buffer is subject to the user option
|
|
|
|
|
~denote-link-backlinks-display-buffer-action~. Due to the nature of the
|
2022-06-15 11:06:21 +02:00
|
|
|
|
underlying ~display-buffer~ mechanism, this inevitably is an advanced
|
|
|
|
|
feature. By default, the backlinks' buffer is displayed below the
|
|
|
|
|
current window. The doc string of our user option includes a
|
|
|
|
|
configuration that places the buffer in a left side window instead.
|
|
|
|
|
Reproducing it here for your convenience:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(setq denote-link-backlinks-display-buffer-action
|
|
|
|
|
'((display-buffer-reuse-window
|
|
|
|
|
display-buffer-in-side-window)
|
|
|
|
|
(side . left)
|
|
|
|
|
(slot . 99)
|
|
|
|
|
(window-width . 0.3)))
|
|
|
|
|
#+end_src
|
2022-06-15 04:17:18 +02:00
|
|
|
|
|
2022-06-15 06:56:31 +02:00
|
|
|
|
#+findex: denote-link-add-links
|
2022-06-15 11:06:21 +02:00
|
|
|
|
The command ~denote-link-add-links~ adds links at point matching a
|
|
|
|
|
regular expression or plain string. The links are inserted as a
|
2022-06-15 06:56:31 +02:00
|
|
|
|
typographic list, such as:
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
- link1
|
|
|
|
|
- link2
|
2022-06-15 11:06:21 +02:00
|
|
|
|
- link3
|
2022-06-15 06:56:31 +02:00
|
|
|
|
#+end_example
|
|
|
|
|
|
2022-06-15 11:06:21 +02:00
|
|
|
|
Each link is formatted according to the file type of the current note.
|
2022-06-15 06:56:31 +02:00
|
|
|
|
The current note is excluded from the matching entries (adding a link to
|
|
|
|
|
itself is pointless).
|
|
|
|
|
|
|
|
|
|
Same examples of a regular expression that can be used with this
|
|
|
|
|
command:
|
|
|
|
|
|
|
|
|
|
- =journal= match all files which include =journal= anywhere in their
|
|
|
|
|
name.
|
|
|
|
|
|
|
|
|
|
- =_journal= match all files which include =journal= as a keyword.
|
|
|
|
|
|
|
|
|
|
- =^2022.*_journal= match all file names starting with =2022= and
|
|
|
|
|
including the keyword =journal=.
|
|
|
|
|
|
2022-06-15 08:16:27 +02:00
|
|
|
|
- =\.txt= match all files including =.txt=. In practical terms, this
|
|
|
|
|
only applies to the file extension, as Denote automatically removes
|
|
|
|
|
dots (and other characters) from the base file name.
|
|
|
|
|
|
2022-06-15 06:56:31 +02:00
|
|
|
|
If files are created with ~denote-sort-keywords~ as non-nil (the
|
|
|
|
|
default), then it is easy to write a regexp that includes multiple
|
|
|
|
|
keywords in alphabetic order:
|
|
|
|
|
|
|
|
|
|
- =_denote.*_package= match all files that include both the =denote= and
|
|
|
|
|
=package= keywords, in this order.
|
|
|
|
|
|
|
|
|
|
- =\(.*denote.*package.*\)\|\(.*package.*denote.*\)= is the same as
|
|
|
|
|
above, but out-of-order.
|
|
|
|
|
|
2022-06-15 11:06:21 +02:00
|
|
|
|
Remember that regexp constructs only need to be escaped once (like =\|=)
|
|
|
|
|
when done interactively but twice when called from Lisp. What we show
|
|
|
|
|
above is for interactive usage.
|
2022-06-15 06:56:31 +02:00
|
|
|
|
|
2022-06-15 18:10:21 +02:00
|
|
|
|
#+findex: denote-link-insert-link
|
|
|
|
|
#+findex: denote-link-show-backlinks-buffer
|
|
|
|
|
#+findex: denote-link-insert-links-matching-regexp
|
|
|
|
|
For convenience, the ~denote-link~ command has an alias called
|
|
|
|
|
~denote-link-insert-link~. The ~denote-link-backlinks~ can also be used
|
|
|
|
|
as ~denote-link-show-backlinks-buffer~. While ~denote-link-add-links~
|
|
|
|
|
is aliased ~denote-link-insert-links-matching-regexp~. The purpose of
|
|
|
|
|
these aliases is to offer alternative, more descriptive names of select
|
|
|
|
|
commands.
|
|
|
|
|
|
2022-06-15 06:56:50 +02:00
|
|
|
|
** Writing metanotes
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:6060a7e6-f179-4d42-a9de-a9968aaebecc
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
A "metanote" is an entry that describes other entries who have something
|
|
|
|
|
in common. Writing metanotes can be part of a workflow where the user
|
|
|
|
|
periodically reviews their work in search of patterns and deeper
|
|
|
|
|
insights. For example, you might want to read your journal entries from
|
|
|
|
|
the past year to reflect on your experiences, evolution as a person, and
|
|
|
|
|
the like.
|
|
|
|
|
|
|
|
|
|
The command ~denote-link-add-links~, which we covered extensively in the
|
|
|
|
|
previous section, is suited for this task ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]). You will
|
|
|
|
|
create your metanote the way you use Denote ordinarily (metanotes may
|
|
|
|
|
have the =metanote= keyword), write an introduction or however you want
|
|
|
|
|
to go about it, invoke ~denote-link-add-links~ to cite the notes that
|
|
|
|
|
match the given regexp, and continue writing.
|
|
|
|
|
|
|
|
|
|
Metanotes can serve as entry points to groupings of individual notes.
|
|
|
|
|
They are not the same as a filtered list of files, i.e. what you would
|
|
|
|
|
do in Dired or the minibuffer where you narrow the list of notes to a
|
|
|
|
|
given query. Metanotes contain the filtered list plus your thoughts
|
|
|
|
|
about it.
|
|
|
|
|
|
|
|
|
|
Your future self will appreciate metanotes for the function they serve
|
|
|
|
|
in encapsulating knowledge.
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
* Fontification in Dired
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:337f9cf0-9f66-45af-b73f-f6370472fb51
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
One of the upsides of Denote's file-naming scheme is the predictable
|
|
|
|
|
pattern it establishes, which appears as a near-tabular presentation in
|
|
|
|
|
a listing of notes (i.e. in Dired). The ~denote-dired-mode~ can help
|
|
|
|
|
enhance this impression, by fontifying the components of the file name
|
|
|
|
|
to make the date (identifier) and keywords stand out.
|
|
|
|
|
|
2022-06-08 10:59:55 +02:00
|
|
|
|
There are two ways to set the mode. Either use it for all directories,
|
|
|
|
|
which probably is not needed:
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(require 'denote-dired)
|
|
|
|
|
(add-hook 'dired-mode-hook #'denote-dired-mode)
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-08 10:59:55 +02:00
|
|
|
|
#+vindex: denote-dired-directories
|
|
|
|
|
#+findex: denote-dired-mode-in-directories
|
|
|
|
|
Or configure the user option ~denote-dired-directories~ and then set up
|
|
|
|
|
the function ~denote-dired-mode-in-directories~:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(require 'denote-dired)
|
|
|
|
|
|
|
|
|
|
;; We use different ways to specify a path for demo purposes.
|
|
|
|
|
(setq denote-dired-directories
|
|
|
|
|
(list denote-directory
|
|
|
|
|
(thread-last denote-directory (expand-file-name "attachments"))
|
|
|
|
|
(expand-file-name "~/Documents/vlog")))
|
|
|
|
|
|
|
|
|
|
(add-hook 'dired-mode-hook #'denote-dired-mode-in-directories)
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-11 18:30:38 +02:00
|
|
|
|
The faces we define are:
|
|
|
|
|
|
|
|
|
|
#+vindex: denote-dired-field-date
|
|
|
|
|
#+vindex: denote-dired-field-delimiter
|
|
|
|
|
#+vindex: denote-dired-field-extension
|
|
|
|
|
#+vindex: denote-dired-field-keywords
|
|
|
|
|
#+vindex: denote-dired-field-time
|
|
|
|
|
#+vindex: denote-dired-field-title
|
|
|
|
|
+ ~denote-dired-field-date~
|
|
|
|
|
+ ~denote-dired-field-delimiter~
|
|
|
|
|
+ ~denote-dired-field-extension~
|
|
|
|
|
+ ~denote-dired-field-keywords~
|
|
|
|
|
+ ~denote-dired-field-time~
|
|
|
|
|
+ ~denote-dired-field-title~
|
|
|
|
|
|
|
|
|
|
For the time being, the =diredfl= package is not compatible with this
|
|
|
|
|
facility.
|
|
|
|
|
|
2022-06-08 10:59:55 +02:00
|
|
|
|
The ~denote-dired-mode~ does not only fontify note files that were
|
|
|
|
|
created by Denote: it covers every file name that follows our naming
|
|
|
|
|
conventions ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]). This is particularly useful for
|
|
|
|
|
scenaria where, say, one wants to organise their collection of PDFs and
|
|
|
|
|
multimedia in a systematic way (and, perhaps, use them as attachments
|
|
|
|
|
for the notes Denote produces).
|
|
|
|
|
|
2022-06-12 08:04:37 +02:00
|
|
|
|
* Minibuffer histories
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:82dc1203-d689-44b2-9a6c-b37776209651
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Denote has a dedicated minibuffer history for each one of its prompts.
|
|
|
|
|
This practically means that using =M-p= (~previous-history-element~) and
|
|
|
|
|
=M-n= (~next-history-element~) will only cycle through the relevant
|
|
|
|
|
record of inputs, such as your latest titles in the =TITLE= prompt, and
|
|
|
|
|
keywords in the =KEYWORDS= prompt.
|
|
|
|
|
|
|
|
|
|
The built-in =savehist= library saves minibuffer histories. Sample
|
|
|
|
|
configuration:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(require 'savehist)
|
|
|
|
|
(setq savehist-file (locate-user-emacs-file "savehist"))
|
|
|
|
|
(setq history-length 10000)
|
|
|
|
|
(setq history-delete-duplicates t)
|
|
|
|
|
(setq savehist-save-minibuffer-history t)
|
|
|
|
|
(add-hook 'after-init-hook #'savehist-mode)
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-11 19:06:42 +02:00
|
|
|
|
* Notes in multiple file types
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:f34b172b-3440-446c-aec1-bf818d0aabfe
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
As noted before, Denote does not have a particular preference on the
|
|
|
|
|
workflow the user wishes to follow nor does it expect a specific file
|
|
|
|
|
type. It is entirely possible to store notes in a variety of formats
|
|
|
|
|
across multiple directories and Denote will still be able to work with
|
|
|
|
|
them, provided they follow the file-naming scheme and have an identifier
|
2022-06-13 14:04:25 +02:00
|
|
|
|
in their front matter, where relevant. Here we show how to create new
|
|
|
|
|
notes that take the example of the ~denote-type~ command and take it one
|
|
|
|
|
step further.
|
2022-06-11 19:06:42 +02:00
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
Suppose you want to use the ~denote~ command to store some notes in
|
|
|
|
|
Markdown, others in Org, and others still in plain text. Maybe you also
|
|
|
|
|
want to place each of those in its own directory. Using the
|
|
|
|
|
~denote-type~ command is not sufficient, as it only operates on the
|
|
|
|
|
value of the user option ~denote-directory~. You need some small
|
|
|
|
|
wrapper functions.
|
2022-06-11 19:06:42 +02:00
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
For example:
|
2022-06-11 19:06:42 +02:00
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
+ =~/Documents/notes/= is your default and contains Org files.
|
|
|
|
|
+ =~/Documents/blog/= holds the files of your blog.
|
|
|
|
|
+ =~/Documents/random/= is where you scribble thoughts in plain text.
|
2022-06-12 20:03:40 +02:00
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
Why would you do that? It does not matter. This is for didactic
|
|
|
|
|
purposes. All you need to do is write functions that ~let~ bind the
|
|
|
|
|
~denote-directory~ and to the desired value.
|
2022-06-11 19:06:42 +02:00
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defun my-denote-markdown-toml ()
|
2022-06-13 14:04:25 +02:00
|
|
|
|
"Create Markdown+TOML note in ~/Documents/blog/."
|
2022-06-11 19:06:42 +02:00
|
|
|
|
(interactive)
|
|
|
|
|
(let ((denote-file-type 'markdown-toml)
|
2022-06-13 14:04:25 +02:00
|
|
|
|
(denote-directory "~/Documents/blog/"))
|
|
|
|
|
(call-interactively #'denote)))
|
|
|
|
|
|
|
|
|
|
(defun my-denote-plain-text ()
|
|
|
|
|
"Create plain text note in ~/Documents/random/."
|
|
|
|
|
(interactive)
|
|
|
|
|
(let ((denote-file-type 'text)
|
|
|
|
|
(denote-directory "~/Documents/random/"))
|
2022-06-11 19:06:42 +02:00
|
|
|
|
(call-interactively #'denote)))
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
You do not need a third command for the Org files, as those would be the
|
|
|
|
|
default used by regular ~denote~.
|
|
|
|
|
|
2022-06-11 19:06:42 +02:00
|
|
|
|
Given Denote's composable code, you can tweak the output however you
|
2022-06-12 20:03:40 +02:00
|
|
|
|
like, including the contents of the file ([[#h:f69371d5-1843-493d-9ff5-c1ab3b43024e][Tweaking the front matter]]).
|
2022-06-11 19:06:42 +02:00
|
|
|
|
|
2022-06-12 20:03:29 +02:00
|
|
|
|
If you do place different types of notes in their own directories,
|
|
|
|
|
consider introducing directory-local variables to keep things working
|
|
|
|
|
seamlessly. An obvious candidate for such a local variable is the
|
2022-06-13 14:04:25 +02:00
|
|
|
|
~denote-directory~: you want notes in =~/Documents/blog/= to treat their
|
|
|
|
|
directory as the canonical one; while those in =~/Documents/random/= to
|
|
|
|
|
do the same for that path. Write a =.dir-locals.el= file with the
|
|
|
|
|
following contents and place it in each of those directories:
|
2022-06-12 20:03:29 +02:00
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
;;; Directory Local Variables
|
|
|
|
|
;;; For more information see (info "(emacs) Directory Variables")
|
|
|
|
|
|
|
|
|
|
((nil . ((denote-directory . (expand-file-name default-directory)))))
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
This will allow things to work smoothly (e.g. ~denote-infer-keywords~).
|
|
|
|
|
|
2022-06-13 14:04:25 +02:00
|
|
|
|
Your default ~denote-directory~ does not need this, as it already is the
|
|
|
|
|
normal target that Denote uses.
|
|
|
|
|
|
2022-06-14 10:39:45 +02:00
|
|
|
|
Want to automate aspects of note creation ([[#h:4a6d92dd-19eb-4fcc-a7b5-05ce04da3a92][Keep a journal or diary]])?
|
2022-06-11 19:06:42 +02:00
|
|
|
|
Have more ideas? Something does not work quite right? Areas you wish
|
|
|
|
|
were more abstract in the code? Please participate in the development
|
|
|
|
|
process.
|
|
|
|
|
|
2022-06-14 10:39:45 +02:00
|
|
|
|
** Keep a journal or diary
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:4a6d92dd-19eb-4fcc-a7b5-05ce04da3a92
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
While there are subtle technical differences between a journal and a
|
|
|
|
|
diary, we will consider those equivalent in the interest of brevity:
|
|
|
|
|
they both describe a personal space that holds a record of your thoughts
|
|
|
|
|
about your experiences and/or view of events in the world.
|
|
|
|
|
|
|
|
|
|
Suppose you are committed to writing an entry every day. Unlike what we
|
|
|
|
|
demonstrated before, your writing will follow a regular naming pattern
|
|
|
|
|
([[#h:f34b172b-3440-446c-aec1-bf818d0aabfe][Notes in multiple file types]]). You know that the title of the new note
|
|
|
|
|
must always look like =Tuesday 14 June 2022= and the keyword has to be
|
|
|
|
|
=journal= or =diary=. As such, you want to automate the task instead of
|
|
|
|
|
being prompted each time, as is the norm with ~denote~ and the relevant
|
|
|
|
|
commands ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). This is easy to accomplish because ~denote~
|
|
|
|
|
can be called from Lisp and given the required arguments of =TITLE= and
|
|
|
|
|
=KEYWORDS= directly. All you need is a simple wrapper function:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defun my-denote-journal ()
|
|
|
|
|
"Create an entry tagged 'journal' with the date as its title."
|
|
|
|
|
(interactive)
|
|
|
|
|
(denote
|
|
|
|
|
(format-time-string "%A %e %B %Y") ; format like Tuesday 14 June 2022
|
|
|
|
|
"journal")) ; multiple keywords are a list of strings: '("one" "two")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
By invoking ~my-denote-journal~ you will go straight into the newly
|
|
|
|
|
created note and commit to your writing outright.
|
|
|
|
|
|
2022-06-14 13:50:50 +02:00
|
|
|
|
Of course, you can always set up the function so that it asks for a
|
|
|
|
|
=TITLE= but still automatically applies the =journal= tag:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defun denote-journal-with-title ()
|
|
|
|
|
"Create an entry tagged 'journal', while prompting for a title."
|
|
|
|
|
(interactive)
|
|
|
|
|
(denote
|
|
|
|
|
(denote--title-prompt) ; ask for title, instead of using human-readable date
|
|
|
|
|
"journal"))
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-14 10:39:45 +02:00
|
|
|
|
Sometimes journaling is done with the intent to hone one's writing
|
|
|
|
|
skills. Perhaps you are learning a new language or wish to communicate
|
|
|
|
|
your ideas with greater clarity and precision. As with everything that
|
|
|
|
|
requires a degree of sophistication, you have to work for it---write,
|
|
|
|
|
write, write!
|
|
|
|
|
|
|
|
|
|
One way to test your progress is to set a timer. It helps you gauge
|
|
|
|
|
your output and its quality. To use a timer with Emacs, consider the
|
|
|
|
|
=tmr= package:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defun my-denote-journal-with-tmr ()
|
|
|
|
|
"Like `my-denote-journal', but also set a 10-minute timer.
|
|
|
|
|
The `tmr' command is part of the `tmr' package."
|
|
|
|
|
(interactive)
|
|
|
|
|
(denote
|
|
|
|
|
(format-time-string "%A %e %B %Y")
|
|
|
|
|
"journal")
|
|
|
|
|
(tmr 10 "Practice writing in my journal")) ; set 10 minute timer with a description
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
Once the timer elapses, stop writing and review your performance.
|
|
|
|
|
Practice makes perfect!
|
|
|
|
|
|
|
|
|
|
[ As Denote matures, we may add hooks to control what happens before or
|
|
|
|
|
after the creation of a new note. We shall also document more
|
|
|
|
|
examples of tasks that can be accomplished with this package. ]
|
|
|
|
|
|
|
|
|
|
Sources for =tmr=:
|
|
|
|
|
|
|
|
|
|
+ Package name (GNU ELPA): =tmr=
|
|
|
|
|
+ Official manual: <https://protesilaos.com/emacs/tmr>
|
|
|
|
|
+ Git repo on SourceHut: <https://git.sr.ht/~protesilaos/tmr>
|
|
|
|
|
- Mirrors:
|
|
|
|
|
+ GitHub: <https://github.com/protesilaos/tmr>
|
|
|
|
|
+ GitLab: <https://gitlab.com/protesilaos/tmr>
|
|
|
|
|
+ Mailing list: <https://lists.sr.ht/~protesilaos/tmr>
|
|
|
|
|
|
2022-06-14 12:40:12 +02:00
|
|
|
|
Finally, recall what we discussed elsewhere in the manual about changing
|
|
|
|
|
the file type and target directory ([[#h:f34b172b-3440-446c-aec1-bf818d0aabfe][Notes in multiple file types]]). You
|
|
|
|
|
basically ~let~ bind the relevant variables. Such bindings are specific
|
|
|
|
|
to the function: they do not affect anything outside of it, so you can
|
|
|
|
|
keep the defaults for your regular notes and use something different for
|
|
|
|
|
your journaling. For example, the following snippet is like the
|
|
|
|
|
previous sample of writing a journal entry and setting a timer, but it
|
|
|
|
|
also uses a plain text file type and adds the new note to the
|
|
|
|
|
=~/Documents/journal/= directory:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(defun my-denote-journal-with-tmr-and-custom-type-and-dir ()
|
|
|
|
|
"Like `my-denote-journal-with-tmr' with custom type and directory."
|
|
|
|
|
(interactive)
|
|
|
|
|
(let ((denote-file-type 'text) ; it supports other file types as well: read its doc string
|
|
|
|
|
(denote-directory "~/Documents/journal/"))
|
|
|
|
|
(denote
|
|
|
|
|
(format-time-string "%A %e %B %Y")
|
|
|
|
|
"journal")
|
|
|
|
|
(tmr 10 "Practice writing in my journal")))
|
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
* Extending Denote
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:8ed2bb6f-b5be-4711-82e9-8bee5bb06ece
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Denote is a tool with a narrow scope: create notes and link between
|
|
|
|
|
them, based on the aforementioned file-naming scheme. For other common
|
|
|
|
|
operations the user is advised to rely on standard Emacs facilities or
|
|
|
|
|
specialised third-party packages.
|
|
|
|
|
|
|
|
|
|
- To search through notes, use =M-x grep=, =M-x find-name-dired=, =M-x
|
|
|
|
|
consult-find=, =M-x consult-grep=, and so on (the latter two are
|
|
|
|
|
provided by the =consult= package).
|
|
|
|
|
|
|
|
|
|
- To quickly jump to the ~denote-directory~, visit it with =M-x
|
|
|
|
|
find-file= and then make a bookmark with =M-x bookmark-set=. Access
|
|
|
|
|
bookmarks with =M-x bookmark-jump=, =M-x consult-buffer= (from
|
|
|
|
|
=consult=), and the like.
|
|
|
|
|
|
|
|
|
|
- Control the versioning of notes by turning the ~denote-directory~ into
|
|
|
|
|
a Git project. Consider the built-in project.el or the =projectile=
|
|
|
|
|
package, as well as the built-in VC framework and/or the =magit=
|
|
|
|
|
package.
|
|
|
|
|
|
|
|
|
|
- It is possible to narrow the list of notes in Dired using a regular
|
|
|
|
|
expression or literal string. Do =M-x dired-mark-files-regexp RET
|
|
|
|
|
type-regexp-here RET t k=. The =t= will toggle the match so that it
|
|
|
|
|
marks all files that do not match the regexp and =k= will remove them
|
|
|
|
|
from the buffer (restore them by reverting the buffer).
|
|
|
|
|
|
|
|
|
|
- A narrowed list of files can also be produced through the minibuffer,
|
|
|
|
|
with the help of the =embark= package. For example, =M-x find-file
|
|
|
|
|
RET path/to/denote-directory RET regexp embark-act embark-export=.
|
|
|
|
|
The final two commands, ~embark-act~ and ~embark-export~, are normally
|
|
|
|
|
bound to keys. The whole sequence will thus look like =C-x C-f path
|
|
|
|
|
RET regexp C-. E=.
|
|
|
|
|
|
|
|
|
|
* Installation
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:f3bdac2c-4704-4a51-948c-a789a2589790
|
|
|
|
|
:END:
|
|
|
|
|
#+cindex: Installation instructions
|
|
|
|
|
|
|
|
|
|
** COMMENT GNU ELPA package
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:42953f87-82bd-43ec-ab99-22b1e22955e7
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
The package is available as =logos=. Simply do:
|
|
|
|
|
|
|
|
|
|
: M-x package-refresh-contents
|
|
|
|
|
: M-x package-install
|
|
|
|
|
|
|
|
|
|
And search for it.
|
|
|
|
|
|
|
|
|
|
GNU ELPA provides the latest stable release. Those who prefer to follow
|
|
|
|
|
the development process in order to report bugs or suggest changes, can
|
|
|
|
|
use the version of the package from the GNU-devel ELPA archive. Read:
|
|
|
|
|
https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.
|
|
|
|
|
|
|
|
|
|
** Manual installation
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:d397712c-c8c0-4cfa-ad1a-ef28cf78d1f0
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
Assuming your Emacs files are found in =~/.emacs.d/=, execute the
|
|
|
|
|
following commands in a shell prompt:
|
|
|
|
|
|
|
|
|
|
#+begin_src sh
|
|
|
|
|
cd ~/.emacs.d
|
|
|
|
|
|
|
|
|
|
# Create a directory for manually-installed packages
|
|
|
|
|
mkdir manual-packages
|
|
|
|
|
|
|
|
|
|
# Go to the new directory
|
|
|
|
|
cd manual-packages
|
|
|
|
|
|
|
|
|
|
# Clone this repo, naming it "denote"
|
|
|
|
|
git clone https://git.sr.ht/~protesilaos/denote denote
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
Finally, in your =init.el= (or equivalent) evaluate this:
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
;; Make Elisp files in that directory available to the user.
|
|
|
|
|
(add-to-list 'load-path "~/.emacs.d/manual-packages/denote")
|
|
|
|
|
#+end_src
|
|
|
|
|
|
|
|
|
|
Everything is in place to set up the package.
|
|
|
|
|
|
|
|
|
|
* Sample configuration
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:5d16932d-4f7b-493d-8e6a-e5c396b15fd6
|
|
|
|
|
:END:
|
|
|
|
|
#+cindex: Package configuration
|
|
|
|
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
|
|
|
(require 'denote)
|
|
|
|
|
|
2022-06-08 06:50:36 +02:00
|
|
|
|
;; Remember to check the doc strings of those variables.
|
2022-06-07 16:22:03 +02:00
|
|
|
|
(setq denote-directory (expand-file-name "~/Documents/notes/"))
|
|
|
|
|
(setq denote-known-keywords
|
|
|
|
|
'("emacs" "philosophy" "politics" "economics"))
|
|
|
|
|
(setq denote-infer-keywords t)
|
|
|
|
|
(setq denote-sort-keywords t)
|
2022-06-10 19:16:11 +02:00
|
|
|
|
(setq denote-file-type nil)
|
2022-06-10 12:26:31 +02:00
|
|
|
|
|
2022-06-08 06:50:36 +02:00
|
|
|
|
(setq denote-front-matter-date-format 'org-timestamp)
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
|
|
|
|
(require 'denote-link)
|
|
|
|
|
(require 'denote-dired)
|
2022-06-12 16:16:31 +02:00
|
|
|
|
(setq denote-dired-rename-expert nil)
|
2022-06-08 10:59:55 +02:00
|
|
|
|
|
|
|
|
|
;; We use different ways to specify a path for demo purposes.
|
|
|
|
|
(setq denote-dired-directories
|
|
|
|
|
(list denote-directory
|
|
|
|
|
(thread-last denote-directory (expand-file-name "attachments"))
|
|
|
|
|
(expand-file-name "~/Documents/vlog")))
|
|
|
|
|
|
2022-06-09 07:33:54 +02:00
|
|
|
|
;; Generic:
|
|
|
|
|
;; (add-hook 'dired-mode-hook #'denote-dired-mode)
|
|
|
|
|
;;
|
2022-06-08 10:59:55 +02:00
|
|
|
|
;; OR better:
|
|
|
|
|
(add-hook 'dired-mode-hook #'denote-dired-mode-in-directories)
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
;; You can bind `denote' to a global key if you prefer not to use
|
2022-06-13 14:07:40 +02:00
|
|
|
|
;; `org-capture' or want an alternative. Denote does not define any key
|
|
|
|
|
;; bindings though: this is for the user to decide. For example:
|
|
|
|
|
(let ((map global-map))
|
|
|
|
|
(define-key map (kbd "C-c n") #'denote)
|
|
|
|
|
(define-key map (kbd "C-c N") #'denote-type))
|
2022-06-07 16:22:03 +02:00
|
|
|
|
|
|
|
|
|
(with-eval-after-load 'org-capture
|
|
|
|
|
(require 'denote-org-capture)
|
|
|
|
|
(setq denote-org-capture-specifiers "%l\n%i\n%?")
|
|
|
|
|
(add-to-list 'org-capture-templates
|
|
|
|
|
'("n" "New note (with denote.el)" plain
|
|
|
|
|
(file denote-last-path)
|
|
|
|
|
#'denote-org-capture
|
|
|
|
|
:no-save t
|
|
|
|
|
:immediate-finish nil
|
|
|
|
|
:kill-buffer t
|
2022-06-13 15:20:50 +02:00
|
|
|
|
:jump-to-captured t)))
|
2022-06-07 16:22:03 +02:00
|
|
|
|
#+end_src
|
|
|
|
|
|
2022-06-08 06:50:36 +02:00
|
|
|
|
* Acknowledgements
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:f8126820-3b59-49fa-bcc2-73bd60132bb9
|
|
|
|
|
:END:
|
|
|
|
|
#+cindex: Contributors
|
|
|
|
|
|
|
|
|
|
Denote is meant to be a collective effort. Every bit of help matters.
|
|
|
|
|
|
|
|
|
|
+ Author/maintainer :: Protesilaos Stavrou.
|
|
|
|
|
|
2022-06-08 18:41:15 +02:00
|
|
|
|
+ Contributions to code or the manual :: Jack Baty, Kaushal Modi.
|
2022-06-08 13:36:23 +02:00
|
|
|
|
|
2022-06-13 14:05:02 +02:00
|
|
|
|
+ Ideas and/or user feedback :: Damien Cassou, Jack Baty, Kaushal Modi,
|
|
|
|
|
Ypot, svnsbck.
|
2022-06-08 06:50:36 +02:00
|
|
|
|
|
2022-06-12 06:35:06 +02:00
|
|
|
|
Special thanks to Peter Povinec who helped refine the file-naming
|
|
|
|
|
scheme, which is the cornerstone of this project.
|
|
|
|
|
|
2022-06-07 16:22:03 +02:00
|
|
|
|
* GNU Free Documentation License
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:APPENDIX: t
|
|
|
|
|
:CUSTOM_ID: h:2d84e73e-c143-43b5-b388-a6765da974ea
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
#+texinfo: @include doclicense.texi
|
|
|
|
|
|
|
|
|
|
#+begin_export html
|
|
|
|
|
<pre>
|
|
|
|
|
|
|
|
|
|
GNU Free Documentation License
|
|
|
|
|
Version 1.3, 3 November 2008
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
|
|
|
|
<https://fsf.org/>
|
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
|
|
|
of this license document, but changing it is not allowed.
|
|
|
|
|
|
|
|
|
|
0. PREAMBLE
|
|
|
|
|
|
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
|
|
|
functional and useful document "free" in the sense of freedom: to
|
|
|
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
|
|
|
with or without modifying it, either commercially or noncommercially.
|
|
|
|
|
Secondarily, this License preserves for the author and publisher a way
|
|
|
|
|
to get credit for their work, while not being considered responsible
|
|
|
|
|
for modifications made by others.
|
|
|
|
|
|
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
|
|
|
works of the document must themselves be free in the same sense. It
|
|
|
|
|
complements the GNU General Public License, which is a copyleft
|
|
|
|
|
license designed for free software.
|
|
|
|
|
|
|
|
|
|
We have designed this License in order to use it for manuals for free
|
|
|
|
|
software, because free software needs free documentation: a free
|
|
|
|
|
program should come with manuals providing the same freedoms that the
|
|
|
|
|
software does. But this License is not limited to software manuals;
|
|
|
|
|
it can be used for any textual work, regardless of subject matter or
|
|
|
|
|
whether it is published as a printed book. We recommend this License
|
|
|
|
|
principally for works whose purpose is instruction or reference.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
|
|
|
|
|
|
|
This License applies to any manual or other work, in any medium, that
|
|
|
|
|
contains a notice placed by the copyright holder saying it can be
|
|
|
|
|
distributed under the terms of this License. Such a notice grants a
|
|
|
|
|
world-wide, royalty-free license, unlimited in duration, to use that
|
|
|
|
|
work under the conditions stated herein. The "Document", below,
|
|
|
|
|
refers to any such manual or work. Any member of the public is a
|
|
|
|
|
licensee, and is addressed as "you". You accept the license if you
|
|
|
|
|
copy, modify or distribute the work in a way requiring permission
|
|
|
|
|
under copyright law.
|
|
|
|
|
|
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
|
|
|
Document or a portion of it, either copied verbatim, or with
|
|
|
|
|
modifications and/or translated into another language.
|
|
|
|
|
|
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section of
|
|
|
|
|
the Document that deals exclusively with the relationship of the
|
|
|
|
|
publishers or authors of the Document to the Document's overall
|
|
|
|
|
subject (or to related matters) and contains nothing that could fall
|
|
|
|
|
directly within that overall subject. (Thus, if the Document is in
|
|
|
|
|
part a textbook of mathematics, a Secondary Section may not explain
|
|
|
|
|
any mathematics.) The relationship could be a matter of historical
|
|
|
|
|
connection with the subject or with related matters, or of legal,
|
|
|
|
|
commercial, philosophical, ethical or political position regarding
|
|
|
|
|
them.
|
|
|
|
|
|
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose titles
|
|
|
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
|
|
|
that says that the Document is released under this License. If a
|
|
|
|
|
section does not fit the above definition of Secondary then it is not
|
|
|
|
|
allowed to be designated as Invariant. The Document may contain zero
|
|
|
|
|
Invariant Sections. If the Document does not identify any Invariant
|
|
|
|
|
Sections then there are none.
|
|
|
|
|
|
|
|
|
|
The "Cover Texts" are certain short passages of text that are listed,
|
|
|
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
|
|
|
the Document is released under this License. A Front-Cover Text may
|
|
|
|
|
be at most 5 words, and a Back-Cover Text may be at most 25 words.
|
|
|
|
|
|
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
|
|
|
represented in a format whose specification is available to the
|
|
|
|
|
general public, that is suitable for revising the document
|
|
|
|
|
straightforwardly with generic text editors or (for images composed of
|
|
|
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
|
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
|
|
|
for automatic translation to a variety of formats suitable for input
|
|
|
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
|
|
|
format whose markup, or absence of markup, has been arranged to thwart
|
|
|
|
|
or discourage subsequent modification by readers is not Transparent.
|
|
|
|
|
An image format is not Transparent if used for any substantial amount
|
|
|
|
|
of text. A copy that is not "Transparent" is called "Opaque".
|
|
|
|
|
|
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
|
|
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
|
|
|
|
or XML using a publicly available DTD, and standard-conforming simple
|
|
|
|
|
HTML, PostScript or PDF designed for human modification. Examples of
|
|
|
|
|
transparent image formats include PNG, XCF and JPG. Opaque formats
|
|
|
|
|
include proprietary formats that can be read and edited only by
|
|
|
|
|
proprietary word processors, SGML or XML for which the DTD and/or
|
|
|
|
|
processing tools are not generally available, and the
|
|
|
|
|
machine-generated HTML, PostScript or PDF produced by some word
|
|
|
|
|
processors for output purposes only.
|
|
|
|
|
|
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
|
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
|
|
|
this License requires to appear in the title page. For works in
|
|
|
|
|
formats which do not have any title page as such, "Title Page" means
|
|
|
|
|
the text near the most prominent appearance of the work's title,
|
|
|
|
|
preceding the beginning of the body of the text.
|
|
|
|
|
|
|
|
|
|
The "publisher" means any person or entity that distributes copies of
|
|
|
|
|
the Document to the public.
|
|
|
|
|
|
|
|
|
|
A section "Entitled XYZ" means a named subunit of the Document whose
|
|
|
|
|
title either is precisely XYZ or contains XYZ in parentheses following
|
|
|
|
|
text that translates XYZ in another language. (Here XYZ stands for a
|
|
|
|
|
specific section name mentioned below, such as "Acknowledgements",
|
|
|
|
|
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
|
|
|
|
|
of such a section when you modify the Document means that it remains a
|
|
|
|
|
section "Entitled XYZ" according to this definition.
|
|
|
|
|
|
|
|
|
|
The Document may include Warranty Disclaimers next to the notice which
|
|
|
|
|
states that this License applies to the Document. These Warranty
|
|
|
|
|
Disclaimers are considered to be included by reference in this
|
|
|
|
|
License, but only as regards disclaiming warranties: any other
|
|
|
|
|
implication that these Warranty Disclaimers may have is void and has
|
|
|
|
|
no effect on the meaning of this License.
|
|
|
|
|
|
|
|
|
|
2. VERBATIM COPYING
|
|
|
|
|
|
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
|
|
|
commercially or noncommercially, provided that this License, the
|
|
|
|
|
copyright notices, and the license notice saying this License applies
|
|
|
|
|
to the Document are reproduced in all copies, and that you add no
|
|
|
|
|
other conditions whatsoever to those of this License. You may not use
|
|
|
|
|
technical measures to obstruct or control the reading or further
|
|
|
|
|
copying of the copies you make or distribute. However, you may accept
|
|
|
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
|
|
|
number of copies you must also follow the conditions in section 3.
|
|
|
|
|
|
|
|
|
|
You may also lend copies, under the same conditions stated above, and
|
|
|
|
|
you may publicly display copies.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. COPYING IN QUANTITY
|
|
|
|
|
|
|
|
|
|
If you publish printed copies (or copies in media that commonly have
|
|
|
|
|
printed covers) of the Document, numbering more than 100, and the
|
|
|
|
|
Document's license notice requires Cover Texts, you must enclose the
|
|
|
|
|
copies in covers that carry, clearly and legibly, all these Cover
|
|
|
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
|
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
|
|
|
you as the publisher of these copies. The front cover must present
|
|
|
|
|
the full title with all words of the title equally prominent and
|
|
|
|
|
visible. You may add other material on the covers in addition.
|
|
|
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
|
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
|
|
|
as verbatim copying in other respects.
|
|
|
|
|
|
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
|
|
|
legibly, you should put the first ones listed (as many as fit
|
|
|
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
|
|
|
pages.
|
|
|
|
|
|
|
|
|
|
If you publish or distribute Opaque copies of the Document numbering
|
|
|
|
|
more than 100, you must either include a machine-readable Transparent
|
|
|
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
|
|
|
a computer-network location from which the general network-using
|
|
|
|
|
public has access to download using public-standard network protocols
|
|
|
|
|
a complete Transparent copy of the Document, free of added material.
|
|
|
|
|
If you use the latter option, you must take reasonably prudent steps,
|
|
|
|
|
when you begin distribution of Opaque copies in quantity, to ensure
|
|
|
|
|
that this Transparent copy will remain thus accessible at the stated
|
|
|
|
|
location until at least one year after the last time you distribute an
|
|
|
|
|
Opaque copy (directly or through your agents or retailers) of that
|
|
|
|
|
edition to the public.
|
|
|
|
|
|
|
|
|
|
It is requested, but not required, that you contact the authors of the
|
|
|
|
|
Document well before redistributing any large number of copies, to
|
|
|
|
|
give them a chance to provide you with an updated version of the
|
|
|
|
|
Document.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
4. MODIFICATIONS
|
|
|
|
|
|
|
|
|
|
You may copy and distribute a Modified Version of the Document under
|
|
|
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
|
|
|
the Modified Version under precisely this License, with the Modified
|
|
|
|
|
Version filling the role of the Document, thus licensing distribution
|
|
|
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
|
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
|
|
|
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
|
|
|
|
from that of the Document, and from those of previous versions
|
|
|
|
|
(which should, if there were any, be listed in the History section
|
|
|
|
|
of the Document). You may use the same title as a previous version
|
|
|
|
|
if the original publisher of that version gives permission.
|
|
|
|
|
B. List on the Title Page, as authors, one or more persons or entities
|
|
|
|
|
responsible for authorship of the modifications in the Modified
|
|
|
|
|
Version, together with at least five of the principal authors of the
|
|
|
|
|
Document (all of its principal authors, if it has fewer than five),
|
|
|
|
|
unless they release you from this requirement.
|
|
|
|
|
C. State on the Title page the name of the publisher of the
|
|
|
|
|
Modified Version, as the publisher.
|
|
|
|
|
D. Preserve all the copyright notices of the Document.
|
|
|
|
|
E. Add an appropriate copyright notice for your modifications
|
|
|
|
|
adjacent to the other copyright notices.
|
|
|
|
|
F. Include, immediately after the copyright notices, a license notice
|
|
|
|
|
giving the public permission to use the Modified Version under the
|
|
|
|
|
terms of this License, in the form shown in the Addendum below.
|
|
|
|
|
G. Preserve in that license notice the full lists of Invariant Sections
|
|
|
|
|
and required Cover Texts given in the Document's license notice.
|
|
|
|
|
H. Include an unaltered copy of this License.
|
|
|
|
|
I. Preserve the section Entitled "History", Preserve its Title, and add
|
|
|
|
|
to it an item stating at least the title, year, new authors, and
|
|
|
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
|
|
|
there is no section Entitled "History" in the Document, create one
|
|
|
|
|
stating the title, year, authors, and publisher of the Document as
|
|
|
|
|
given on its Title Page, then add an item describing the Modified
|
|
|
|
|
Version as stated in the previous sentence.
|
|
|
|
|
J. Preserve the network location, if any, given in the Document for
|
|
|
|
|
public access to a Transparent copy of the Document, and likewise
|
|
|
|
|
the network locations given in the Document for previous versions
|
|
|
|
|
it was based on. These may be placed in the "History" section.
|
|
|
|
|
You may omit a network location for a work that was published at
|
|
|
|
|
least four years before the Document itself, or if the original
|
|
|
|
|
publisher of the version it refers to gives permission.
|
|
|
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
|
|
|
|
Preserve the Title of the section, and preserve in the section all
|
|
|
|
|
the substance and tone of each of the contributor acknowledgements
|
|
|
|
|
and/or dedications given therein.
|
|
|
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
|
|
|
unaltered in their text and in their titles. Section numbers
|
|
|
|
|
or the equivalent are not considered part of the section titles.
|
|
|
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
|
|
|
|
may not be included in the Modified Version.
|
|
|
|
|
N. Do not retitle any existing section to be Entitled "Endorsements"
|
|
|
|
|
or to conflict in title with any Invariant Section.
|
|
|
|
|
O. Preserve any Warranty Disclaimers.
|
|
|
|
|
|
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
|
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
|
|
|
copied from the Document, you may at your option designate some or all
|
|
|
|
|
of these sections as invariant. To do this, add their titles to the
|
|
|
|
|
list of Invariant Sections in the Modified Version's license notice.
|
|
|
|
|
These titles must be distinct from any other section titles.
|
|
|
|
|
|
|
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
|
|
|
|
nothing but endorsements of your Modified Version by various
|
|
|
|
|
parties--for example, statements of peer review or that the text has
|
|
|
|
|
been approved by an organization as the authoritative definition of a
|
|
|
|
|
standard.
|
|
|
|
|
|
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
|
|
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
|
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
|
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
|
|
|
through arrangements made by) any one entity. If the Document already
|
|
|
|
|
includes a cover text for the same cover, previously added by you or
|
|
|
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
|
|
|
you may not add another; but you may replace the old one, on explicit
|
|
|
|
|
permission from the previous publisher that added the old one.
|
|
|
|
|
|
|
|
|
|
The author(s) and publisher(s) of the Document do not by this License
|
|
|
|
|
give permission to use their names for publicity for or to assert or
|
|
|
|
|
imply endorsement of any Modified Version.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
5. COMBINING DOCUMENTS
|
|
|
|
|
|
|
|
|
|
You may combine the Document with other documents released under this
|
|
|
|
|
License, under the terms defined in section 4 above for modified
|
|
|
|
|
versions, provided that you include in the combination all of the
|
|
|
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
|
|
|
list them all as Invariant Sections of your combined work in its
|
|
|
|
|
license notice, and that you preserve all their Warranty Disclaimers.
|
|
|
|
|
|
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
|
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
|
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
|
|
|
different contents, make the title of each such section unique by
|
|
|
|
|
adding at the end of it, in parentheses, the name of the original
|
|
|
|
|
author or publisher of that section if known, or else a unique number.
|
|
|
|
|
Make the same adjustment to the section titles in the list of
|
|
|
|
|
Invariant Sections in the license notice of the combined work.
|
|
|
|
|
|
|
|
|
|
In the combination, you must combine any sections Entitled "History"
|
|
|
|
|
in the various original documents, forming one section Entitled
|
|
|
|
|
"History"; likewise combine any sections Entitled "Acknowledgements",
|
|
|
|
|
and any sections Entitled "Dedications". You must delete all sections
|
|
|
|
|
Entitled "Endorsements".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
|
|
|
|
|
|
|
You may make a collection consisting of the Document and other
|
|
|
|
|
documents released under this License, and replace the individual
|
|
|
|
|
copies of this License in the various documents with a single copy
|
|
|
|
|
that is included in the collection, provided that you follow the rules
|
|
|
|
|
of this License for verbatim copying of each of the documents in all
|
|
|
|
|
other respects.
|
|
|
|
|
|
|
|
|
|
You may extract a single document from such a collection, and
|
|
|
|
|
distribute it individually under this License, provided you insert a
|
|
|
|
|
copy of this License into the extracted document, and follow this
|
|
|
|
|
License in all other respects regarding verbatim copying of that
|
|
|
|
|
document.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
|
|
|
|
|
|
A compilation of the Document or its derivatives with other separate
|
|
|
|
|
and independent documents or works, in or on a volume of a storage or
|
|
|
|
|
distribution medium, is called an "aggregate" if the copyright
|
|
|
|
|
resulting from the compilation is not used to limit the legal rights
|
|
|
|
|
of the compilation's users beyond what the individual works permit.
|
|
|
|
|
When the Document is included in an aggregate, this License does not
|
|
|
|
|
apply to the other works in the aggregate which are not themselves
|
|
|
|
|
derivative works of the Document.
|
|
|
|
|
|
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
|
|
|
copies of the Document, then if the Document is less than one half of
|
|
|
|
|
the entire aggregate, the Document's Cover Texts may be placed on
|
|
|
|
|
covers that bracket the Document within the aggregate, or the
|
|
|
|
|
electronic equivalent of covers if the Document is in electronic form.
|
|
|
|
|
Otherwise they must appear on printed covers that bracket the whole
|
|
|
|
|
aggregate.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
8. TRANSLATION
|
|
|
|
|
|
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
|
|
|
distribute translations of the Document under the terms of section 4.
|
|
|
|
|
Replacing Invariant Sections with translations requires special
|
|
|
|
|
permission from their copyright holders, but you may include
|
|
|
|
|
translations of some or all Invariant Sections in addition to the
|
|
|
|
|
original versions of these Invariant Sections. You may include a
|
|
|
|
|
translation of this License, and all the license notices in the
|
|
|
|
|
Document, and any Warranty Disclaimers, provided that you also include
|
|
|
|
|
the original English version of this License and the original versions
|
|
|
|
|
of those notices and disclaimers. In case of a disagreement between
|
|
|
|
|
the translation and the original version of this License or a notice
|
|
|
|
|
or disclaimer, the original version will prevail.
|
|
|
|
|
|
|
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
|
|
|
|
"Dedications", or "History", the requirement (section 4) to Preserve
|
|
|
|
|
its Title (section 1) will typically require changing the actual
|
|
|
|
|
title.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
9. TERMINATION
|
|
|
|
|
|
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
|
|
|
|
except as expressly provided under this License. Any attempt
|
|
|
|
|
otherwise to copy, modify, sublicense, or distribute it is void, and
|
|
|
|
|
will automatically terminate your rights under this License.
|
|
|
|
|
|
|
|
|
|
However, if you cease all violation of this License, then your license
|
|
|
|
|
from a particular copyright holder is reinstated (a) provisionally,
|
|
|
|
|
unless and until the copyright holder explicitly and finally
|
|
|
|
|
terminates your license, and (b) permanently, if the copyright holder
|
|
|
|
|
fails to notify you of the violation by some reasonable means prior to
|
|
|
|
|
60 days after the cessation.
|
|
|
|
|
|
|
|
|
|
Moreover, your license from a particular copyright holder is
|
|
|
|
|
reinstated permanently if the copyright holder notifies you of the
|
|
|
|
|
violation by some reasonable means, this is the first time you have
|
|
|
|
|
received notice of violation of this License (for any work) from that
|
|
|
|
|
copyright holder, and you cure the violation prior to 30 days after
|
|
|
|
|
your receipt of the notice.
|
|
|
|
|
|
|
|
|
|
Termination of your rights under this section does not terminate the
|
|
|
|
|
licenses of parties who have received copies or rights from you under
|
|
|
|
|
this License. If your rights have been terminated and not permanently
|
|
|
|
|
reinstated, receipt of a copy of some or all of the same material does
|
|
|
|
|
not give you any rights to use it.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
|
|
|
|
|
|
The Free Software Foundation may publish new, revised versions of the
|
|
|
|
|
GNU Free Documentation License from time to time. Such new versions
|
|
|
|
|
will be similar in spirit to the present version, but may differ in
|
|
|
|
|
detail to address new problems or concerns. See
|
|
|
|
|
https://www.gnu.org/licenses/.
|
|
|
|
|
|
|
|
|
|
Each version of the License is given a distinguishing version number.
|
|
|
|
|
If the Document specifies that a particular numbered version of this
|
|
|
|
|
License "or any later version" applies to it, you have the option of
|
|
|
|
|
following the terms and conditions either of that specified version or
|
|
|
|
|
of any later version that has been published (not as a draft) by the
|
|
|
|
|
Free Software Foundation. If the Document does not specify a version
|
|
|
|
|
number of this License, you may choose any version ever published (not
|
|
|
|
|
as a draft) by the Free Software Foundation. If the Document
|
|
|
|
|
specifies that a proxy can decide which future versions of this
|
|
|
|
|
License can be used, that proxy's public statement of acceptance of a
|
|
|
|
|
version permanently authorizes you to choose that version for the
|
|
|
|
|
Document.
|
|
|
|
|
|
|
|
|
|
11. RELICENSING
|
|
|
|
|
|
|
|
|
|
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
|
|
|
|
|
World Wide Web server that publishes copyrightable works and also
|
|
|
|
|
provides prominent facilities for anybody to edit those works. A
|
|
|
|
|
public wiki that anybody can edit is an example of such a server. A
|
|
|
|
|
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
|
|
|
|
|
means any set of copyrightable works thus published on the MMC site.
|
|
|
|
|
|
|
|
|
|
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
|
|
|
|
|
license published by Creative Commons Corporation, a not-for-profit
|
|
|
|
|
corporation with a principal place of business in San Francisco,
|
|
|
|
|
California, as well as future copyleft versions of that license
|
|
|
|
|
published by that same organization.
|
|
|
|
|
|
|
|
|
|
"Incorporate" means to publish or republish a Document, in whole or in
|
|
|
|
|
part, as part of another Document.
|
|
|
|
|
|
|
|
|
|
An MMC is "eligible for relicensing" if it is licensed under this
|
|
|
|
|
License, and if all works that were first published under this License
|
|
|
|
|
somewhere other than this MMC, and subsequently incorporated in whole or
|
|
|
|
|
in part into the MMC, (1) had no cover texts or invariant sections, and
|
|
|
|
|
(2) were thus incorporated prior to November 1, 2008.
|
|
|
|
|
|
|
|
|
|
The operator of an MMC Site may republish an MMC contained in the site
|
|
|
|
|
under CC-BY-SA on the same site at any time before August 1, 2009,
|
|
|
|
|
provided the MMC is eligible for relicensing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ADDENDUM: How to use this License for your documents
|
|
|
|
|
|
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
|
|
|
the License in the document and put the following copyright and
|
|
|
|
|
license notices just after the title page:
|
|
|
|
|
|
|
|
|
|
Copyright (c) YEAR YOUR NAME.
|
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
|
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
|
|
|
or any later version published by the Free Software Foundation;
|
|
|
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
|
|
|
A copy of the license is included in the section entitled "GNU
|
|
|
|
|
Free Documentation License".
|
|
|
|
|
|
|
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
|
|
|
|
replace the "with...Texts." line with this:
|
|
|
|
|
|
|
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with the
|
|
|
|
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
|
|
|
|
|
|
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
|
|
|
|
combination of the three, merge those two alternatives to suit the
|
|
|
|
|
situation.
|
|
|
|
|
|
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
|
|
|
recommend releasing these examples in parallel under your choice of
|
|
|
|
|
free software license, such as the GNU General Public License,
|
|
|
|
|
to permit their use in free software.
|
|
|
|
|
</pre>
|
|
|
|
|
#+end_export
|
|
|
|
|
|
|
|
|
|
#+html: <!--
|
|
|
|
|
|
|
|
|
|
* Indices
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:CUSTOM_ID: h:dd530040-de9d-4f2b-8dfd-d8b8f14c058e
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
** Function index
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:INDEX: fn
|
|
|
|
|
:CUSTOM_ID: h:317b8c20-6dc1-4390-a20a-d01d75a48ccb
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
** Variable index
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:INDEX: vr
|
|
|
|
|
:CUSTOM_ID: h:2f69d4fe-0804-4f7f-aa57-4e03e7f20d98
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
** Concept index
|
|
|
|
|
:PROPERTIES:
|
|
|
|
|
:INDEX: cp
|
|
|
|
|
:CUSTOM_ID: h:10365e44-2fc0-4b66-a613-682fea09ee68
|
|
|
|
|
:END:
|
|
|
|
|
|
|
|
|
|
#+html: -->
|