~nobiot/ten

Ten 典: A tiny Emacs library that lets you list definitions of terms. It fontifies the terms and lets you jump to their definitions like a wiki for plain-text documents
fix: Enable complete-tag & completion-at-point
docs: Minor fix a docstring
docs: Adding back test/definitions.txt to show different format

refs

main
browse  log 

clone

read-only
https://git.sr.ht/~nobiot/ten
read/write
git@git.sr.ht:~nobiot/ten

You can also use your local clone with git send-email.

I realize that this package is mentioned in Emacs news for 2024-04-29. I appreciate this.

I don't think I have written enough documentation to get you started easily, and I notice some usability issues here and there -- Ten should just work. A simple procedure should be something like this:

  1. Customize Ten like the example below.

  2. Call ten-tags-create, which will create a dictionary file (TAGS file).

  3. Enable ten-mode, which is a global minor mode, then create a new note in a text file in the major mode enabled for Ten (part of the configuration below). The terms in the dictionary should be automatically fontified. If you visit an existing buffer before calling ten-mode, you will need to call the major mode again to get the ten-mode's fontification to work (because Ten adds to the major mode's font-lock keywords via major-mode hook).

  4. To jump to the definition, call xref-find-definitions (M-. by default).

  5. When you add a new term to the dictionary, run ten-tags-create command again (underlying etags program updates the TAGS file by re-creating it). Then re-activate major-mode in each buffer you are editing (this is one of the usability issues I want to resolve; it's fine with me but I realize it's not good).

I would like to take things slowly and I am still tweaking things a lot (because I like it this way). You are welcome to take a peak at what I am doing and try to see what the code does, but at this stage you may be in for a struggle.

I use it everyday and it works great for my own note-taking workflow -- this is especially true at work where I need to quickly retrieve records of information, meeting logs, etc.

#Ten 典

Ten is part of my tiny-emacs-packages project.

Ten is a tiny Emacs library design to let you create wiki-style document files. With Ten, you do not use a syntactic construct like "[[wiki link]]" in your documents; you write naturally and Ten will automatically highlight (fontify) terms that you have definitions for. You can easily jump to the location of the definitions and back to the document where you have come from. To jump to the definition, place your cursor on a fontified term and call the xref-find-definitions command (by default bound to "M-."). You will jump to the buffer where the definition is. xref-go-back ("M-,") will take you back where you jumped from.

Technically, the automatic highlighting is done through adding a list of regexps to font-lock-keywords. Ten constructs the regexps from a list of terms. The list is created through the built-in etags program [^1]. With it, you create a TAGS file that lists definitions of terms. For the terms, we use the <<this is a term>> syntax[^2]. With the ten-tags-create command, you call the etags program, which scans through pre-defined files for these targets of terms and create a TAGS file. The idea is that you have a single TAG file to serve multiple documents across different directories.

Ten prepares the files for the etags program and makes it trivial to set the TAGS file ready for use in certain modes you use for writing, such as text-mode, org-mode, and markdown-mode. You can then use the built-in etags--xrefs as the Xrefs backend for searching and jumping to definitions and back. Ten itself does not do much other than interfacing with font-lock-keywords for highlighting, with the etags program to generate a TAGS file, and with Xref to let you search terms in the TAGS file (xref-find-definitions). For completion-at-point for terms, you can use the built-in complete-tag command.

Ten 典 connects with xref-find-definitions to search the definitions of terms, but not with xref-find-references for where the terms are used. For this, Ten works well with Ren 連. The configuration to get Ten and Ren work together looks like this example below.

(use-package ten
  :load-path ("~/src/ten/")
  :hook emacs-startup
  :custom
  ;; Enabling `ten' in text-mode and other major modes that inherit it,
  ;; such as `org-mode' and `markdown-mode'. If you wish to be more
  ;; specific, remove `text-mode' and add other more specific modes to
  ;; the list.
  (ten-enabled-modes '(text-mode))
  ;; I am listing two specific dictionary files in the `test/`
  ;; subdirectory as an example below. You can list the
  ;; `~/src/ten/test/' directory to let Ten to search files recursively
  ;; in the directory and subdirectories in it. There are about 5,000
  ;; terms in total and I don't experience any perfomance issue on my
  ;; old Lenovo Thinkpad laptop. Ten looks for files with an extension
  ;; listed in `ten-file-extensions' and excludes files and those in
  ;; directories that match the list of regexps `ten-exclude-regexps'.
  (ten-files-and-directories
   '("~/src/ten/test/Glossary-video-game-terms.txt"
     "~/src/ten/test/Glossary-biology.txt"))
  (ten-file-extensions '("org" "txt"))
  (ten-exclude-regexps '("/\\."))
  ;; The dictionary file (only one at a time can be active through
  ;; `etags', but you can switch between more than one of them if you
  ;; need to. The switching experience is not intuitive and it's a TODO
  ;; to improve it.)
  (ten-tags-file-default "~/src/ten/test/ten-TAGS"))

(use-package ren
  :load-path ("~/src/ren/")
  :hook emacs-startup
  :custom
  (ren-enabled-modes '(text-mode kotl-mode))
  ;; The following are to get Ren to work with Ten for searching
  ;; definitions
  (ren-xref-use-etags-backend-in-this-mode 'ten-mode)
  (ren-id-at-point-function 'ten-id-at-point)
  [... other settings ...])

[^1]: For Windows, you need to add to PATH to the bin folder within the Emacs folder. For example, in my installation, I have added the following C:\Program Files\Emacs\emacs-29.2\bin.

[^2]: Use two angled brackets. Using three, the same as Org's radio target syntax, is possible but not recommended. I will explain the reason in another update.