[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/denote b313dfccaa 7/9: Update backlinks' buffer documen
From: |
ELPA Syncer |
Subject: |
[elpa] externals/denote b313dfccaa 7/9: Update backlinks' buffer documentation in the manual |
Date: |
Wed, 26 Oct 2022 23:57:37 -0400 (EDT) |
branch: externals/denote
commit b313dfccaacaa466cca76186644aa3ffc599b604
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>
Update backlinks' buffer documentation in the manual
This consolidates all the recent changes.
Read the discussion on the mailing list about the refactoring of the
backlinks' buffer, with the participation of Noboru Ota:
<https://lists.sr.ht/~protesilaos/denote/%3C86r0yvzm12.fsf%40nobiot.com%3E>.
Also check the recent commit log for the relevant changes, including
patches from Noboru.
---
README.org | 76 +++++++++++++++++++++++++++++++++-----------------------------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/README.org b/README.org
index 5c4093a16a..8034d9622c 100644
--- a/README.org
+++ b/README.org
@@ -1350,18 +1350,31 @@ this end, Denote provides two convenience commands:
:CUSTOM_ID: h:c73f1f68-e214-49d5-b369-e694f6a5d708
:END:
-[ Refactored as part of {{{development-version}}} to show the context
- of links. ]
+[ Refactored as part of {{{development-version}}} to optionally show
+ the context of links. ]
#+findex: denote-link-backlinks
The command ~denote-link-backlinks~ produces a bespoke buffer which
displays backlinks to the current note. A "backlink" is a link back
to the present entry.
-The backlinks' buffer is desinged to display the file name of the note
-linking to the current entry, as well as the context of each link.
+By default, the backlinks' buffer is desinged to display the file name
+of the note linking to the current entry. Each file name is presented
+on its own line, like this:
-It looks like this:
+#+begin_example
+Backlinks to "On being honest" (20220614T130812)
+------------------------------------------------
+
+20220614T145606--let-this-glance-become-a-stare__journal.txt
+20220616T182958--feeling-butterflies-in-your-stomach__journal.txt
+#+end_example
+
+#+vindex: denote-backlinks-show-context
+When the user option ~denote-backlinks-show-context~ is non-nil, the
+backlinks' buffer displays the line on which a link to the current
+note occurs. It also shows multiple occurances, if present. It looks
+like this (and has the appropriate fontification):
#+begin_example
Backlinks to "On being honest" (20220614T130812)
@@ -1376,18 +1389,31 @@ Backlinks to "On being honest" (20220614T130812)
Note that the width of the lines in the context depends on the
underlying file. In the above example, the lines are split at the
-~fill-column~. Long lines will show up just fine.
+~fill-column~. Long lines will show up just fine. Also note that the
+built-in user option ~xref-truncation-width~ can truncate long lines
+to a given maximum number of characters.
[[#h:893eec49-d7be-4603-bcff-fcc247244011][Speed up backlinks' buffer
creation?]]
-#+vindex: denote-link-fontify-backlinks
-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. The default style is handled by
-Denote, to highlight the components of each file. A nil value means
-that the fontification will be performed by the underlying =xref=
-mechanism (generic style such as the one used by the output of the
-built-in command ~project-find-regexp~).
+#+findex: denote-backlinks-mode
+#+vindex: denote-backlinks-mode-map
+The backlinks' buffer runs the major-mode ~denote-backlinks-mode~. It
+binds keys to move between links with =n= (next) and =p= (previous).
+These are stored in the ~denote-backlinks-mode-map~ (use =M-x
+describe-mode= (=C-h m=) in an unfamiliar buffer to learn more about
+it). When the user option ~denote-backlinks-show-context~ is non-nil,
+all relevant Xref key bindings are fully functional: again, check
+~describe-mode~.
+
+The backlinking facility uses Emacs' built-in Xref infrastructure. On
+some operating systems, the user may need to add certain executables
+to the relevant environment variable.
+
+[[#h:42f6b07e-5956-469a-8294-17f9cf62eb2b][Why do I get "Search failed with
status 1" when I search for backlinks?]]
+
+Backlinks to the current file can also be visited by using the
+minibuffer completion interface with the ~denote-link-find-backlink~
+command ([[#h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4][Visiting linked files via
the minibuffer]]).
#+vindex: denote-link-backlinks-display-buffer-action
The placement of the backlinks' buffer is subject to the user option
@@ -1407,28 +1433,6 @@ Reproducing it here for the sake of convenience:
(window-width . 0.3)))
#+end_src
-#+findex: denote-backlinks-mode
-#+vindex: denote-backlinks-mode-map
-The backlinks' buffer runs the major-mode ~denote-backlinks-mode~, which
-is derived from ~special-mode~. It binds keys to move between links
-with =n= (next) and =p= (previous). These are stored in the
-~denote-backlinks-mode-map~ (use =M-x describe-mode= (=C-h m=) in an
-unfamiliar buffer to learn more about it).
-
-[ The above paragraph is no longer accurate since 2022-10-26 06:44
- +0300, on {{{development-version}}}. We are making refinements to
- it and shall update the documentation accordingly. ]
-
-Note that the backlinking facility uses Emacs' built-in Xref
-infrastructure. On some operating systems, the user may need to add
-certain executables to the relevant environment variable.
-
-[[#h:42f6b07e-5956-469a-8294-17f9cf62eb2b][Why do I get "Search failed with
status 1" when I search for backlinks?]]
-
-Backlinks to the current file can also be visited by using the
-minibuffer completion interface with the ~denote-link-find-backlink~
-command ([[#h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4][Visiting linked files via
the minibuffer]]).
-
** Writing metanotes
:PROPERTIES:
:CUSTOM_ID: h:6060a7e6-f179-4d42-a9de-a9968aaebecc
- [elpa] externals/denote updated (3b9bc00659 -> ee69daee74), ELPA Syncer, 2022/10/26
- [elpa] externals/denote bdc94d3369 2/9: Add user option to use original backlinks buffer or with context, ELPA Syncer, 2022/10/26
- [elpa] externals/denote bbdcc498a2 1/9: Fix 'denote-link-find-backlink', ELPA Syncer, 2022/10/26
- [elpa] externals/denote 7c22231457 8/9: Update minimum required Emacs version to 28.1, ELPA Syncer, 2022/10/26
- [elpa] externals/denote d304d79593 3/9: Reword denote--retrieve-files-in-xrefs doc string, ELPA Syncer, 2022/10/26
- [elpa] externals/denote 9b6cf70026 6/9: Add wrapper motions for backlinks' buffer, ELPA Syncer, 2022/10/26
- [elpa] externals/denote b313dfccaa 7/9: Update backlinks' buffer documentation in the manual,
ELPA Syncer <=
- [elpa] externals/denote 3da08eac52 4/9: Reword denote-backlilnks-show-context docstring, ELPA Syncer, 2022/10/26
- [elpa] externals/denote f90f79f788 5/9: Make denote-link-fontify-backlinks obsolete, ELPA Syncer, 2022/10/26
- [elpa] externals/denote ee69daee74 9/9: Update sample configuration, per b313dfc, ELPA Syncer, 2022/10/26