#Ten 典

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

#Overview

Ten 典 lets you make a file (or files) that serve as a dictionary or glossary, where you write down definitions and descriptions of terms and phrases. Once you've done that, Ten will automatically highlight (fontify) these terms and phrases in your plaint-text notes buffers as you write. No special markup or syntax is required in your notes, and you are free to use any file extensions and major modes including markdown-, org-, and text-mode.

When a term is fontified, you can jump to its definition. Simply place your cursor on a term and call the xref-find-definitions command (by default bound to "M-."). The command xref-go-back ("M-,") will take you back where you jumped from. Fontification and jumping features also apply to other modes such as EWW and EPUB (via nov.el) as long as the texts are displayed in plain-text (and thus, PDF files are not supported).

#Setting up Ten 典

1. Download ten.el and so.el in the repository, for example in your ~/src/ directory.

2. Optionally, You can also download some sample dictionary / glossary files under test/ subdirectory. These are collection of terms I crafted from Wikipedia's glossary pages. Use them to test drive Ten.

3. Put the following configuration in your init file to test-drive Ten 典. Modify the configuration for your own use.

(use-package ten
  :load-path ("~/src/ten/")
  ;; `ten-font-lock-mode' is a local minor mode to fontify ("font-lock") the
  ;; terms. By doing so, Global `ten-mode' gets enabled as well.  Enabling
  ;; `ten-font-lock-mode' for `text-mode' does so 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.
  :hook ((text-mode eww-mode nov-mode) . ten-font-lock-mode)
  :custom
  ;; Below I am listing two specific glossary files in the `test/`
  ;; subdirectory as an example. 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-glossary-file-extensions' and excludes files and those in
  ;; directories that match the list of regexps `ten-glossary-exclude-regexps'.
  (ten-glossary-files-and-directories
   '("~/src/ten/test/Glossary-video-game-terms.txt"
     "~/src/ten/test/Glossary-biology.txt"))
  (ten-glossary-file-extensions '("org" "md" "txt"))
  (ten-glossary-exclude-regexps '("/\\."))
  ;; The TAGS file is generated by the \'etags\' command-line program. It
  ;; serves as an index file that records the location of each term in the
  ;; glossary file(s). Only one at a time can be active but you can switch
  ;; between more than one of them with `ten-select-tags-file'.
  (ten-tags-file-default "~/src/ten/test/ten-TAGS"))

#How to use Ten 典

1. Write definitions of terms and phrases.

   To write definitions, use the <<this is a term>> syntax. You can have only one term per line. If two or more terms exist in a single line, only the first one is recognized as a term. For aliases and variations -- e.g. singular and plural of the same term -- place them in different lines. See example glossary files available in this repository under the test/ subdirectory. You can use any extensions for glossary files. Simply list them with user option ten-glossary-file-extensions. You can have definitions in your journals, bibliographic notes, etc. You are free to organize your glossary files in your own way and create as many of them as you wish [^2] -- a single big file that contain all definitions across genres or split definitions per theme or genre, etc. Simply list the glossary file(s) or containing directories in user option ten-glossary-files-and-directories.

2. Call the command ten-tags-create.

   This gets Ten to collect definitions of terms and phrases from ten-glossary-files-and-directories and to create / update the special index file ten-tags-file-default (conventionally called "TAGS" file ) that contains the location of all the definitions across the glossary files.

3. Enable ten-font-lock-mode in a buffer such as text-mode or org-mode.

   The terms in your glossary will be automatically fontified.

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

5. When you add a new term to the dictionary or change the location of the definitions, call ten-update-all command.

   This calls the underlying etags program (shell command) to update the TAGS file by re-creating it. It will then refresh font-lock in all buffers that have ten-font-lock-mode enabled.

#More technical details of Ten 典

Ten uses the built-in etags--xrefs as an Xrefs backend for searching and jumping to definitions and back. Automatic highlighting is done through adding a list of regexps to font-lock-keywords per buffer. This is enabled by the local minor mode ten-font-lock-mode. Ten constructs the regexps from a list of terms, generated through the built-in etags command-line program included in Emacs[^3]. With the ten-tags-create command, Ten prepares the files and serves them to the etags program,which scans through pre-defined files for these targets of terms and create ten-tags-file-default, making it trivial to maintain the TAGS file ready for use for writing, such as text-mode, org-mode, and markdown-mode.

Ten itself does not do much other than interfacing with Xref to let you search terms in the TAGS file (xref-find-definitions), with font-lock-keywords for fontification, and with the etags command-line program (which comes with Emacs) to generate a TAGS file. For completion-at-point for terms, you can use the built-in complete-tag command.

I am currently extending the basic features of Ten 典 with the use of Consult (minibuffer completion with preview of terms) and Eldoc (on-the-fly display of terms for the term at point). I use them everyday, but they are only provided as an early preview version at the moment. They will change. See consult-ten.el and ten-eldoc.el.

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 my other tiny Emacs package Ren 連.

[^1]: Use two angled brackets. Using three, the same as Org's radio target syntax, is possible but not recommended when you have many definitions in one Org file. This is because initializing radio targets is part of activation of org-mode (function org-update-radio-target-regexp) and may slow down opening Org files when there are 100s of definitions in a single org buffer.

[^2]: Note, though, you will need to call ten-update-all every time you change the location of the terms. If you are modifying these journals and other notes often with the definitions of terms, consider having a dedicated glossary file to avoid having to constantly calling ten-update-all.

[^3]: For Windows, you need to add a path to the environmental variable PATH. The path must be to the bin folder within the Emacs folder. For example, in my installation, I have added the following C:\ProgramFiles\Emacs\emacs-29.2\bin.