Clue

Code reading is like cracking a criminal case. You go to places, collect clues, and connect relevant ones to see the truth.

— Me

What is it?

Clue is a tool for helping you take notes while reading code.

Code reading is all about finding connections between different locations in a project. With clue, you can take notes about these connections in plain text (or your favorite markup language), and insert links to take you to these locations.

Such a code reading note may look like this:

From here:

#[/path/to/source/file:L123]
..source code..

We know that func1 calls func2...

The #[/path/to/source/file:L123] is the link generated by Clue. You can goto the location by clicking/pressing RET on it.

Installation

Clone this repository:

$ git clone https://github.com/AmaiKinono/clue.git /path/to/clue

Add the path to your load-path in your Emacs configuration:
```
(add-to-list 'load-path "/path/to/clue")
```
Require clue in your configuration:
```
(require 'clue)
```
If you want to automatically enable clue-mode for files that contains links, add this to your config:
```
(add-hook 'find-file-hook #'clue-auto-enable-clue-mode)
```

Read the Customization part for an example configuration using use-package.

Usage

Copy, paste and visit links

In a code file, type M-x clue-copy to copy the current location.

In your note file, type M-x clue-paste to paste the just-copied location. Emacs may ask you if you want to set the project root. Answer "y". You may notice something is inserted at the end of your note. It's a "metalink" and we'll explain it later.

Now, clicking or pressing RET on a link will take you that location.

`clue-mode`

By pasting a link, clue-mode is enabled. It fontifies all the links, and make them clickable. So if you just opened your note file, you need to type M-x clue-mode to visit the links, or you can add clue-auto-enable-clue-mode to find-file-hook to enable clue-mode automatically, when the file contains a link.

Metalink

When pasting a link, if Emacs ask you to set the project root, and you answer "y", your note may look like:

...
#[relative/path/to/source/file:L123]
...
#[:meta:root:/project/root/path]

A "metalink" will be inserted to the bottom of your note, and relative path will be used in the actual links. This way, if you move your project to another location, you can just edit the metalink to update the project root.

Currently the concept of metalinks is only used for the project root.

Customization

These are the customizable options:

clue-project-root-function: A function that returns project root in current buffer. By default, it uses the built-in project-current, which should work for version-controlled directories.
clue-after-jump-hook: Hook that runs after jumping to a location. By default, it recenters and blinks the current line.
clue-auto-enable-modes: Let clue-auto-enable-clue-mode work for these major modes. By default, it's (text-mode).
clue-keymap: Keymap that's enabled on the links.

An example configuration using use-package is:

(use-package clue
  :defer t
  :init
  (add-hook 'find-file-hook #'clue-auto-enable-clue-mode))
  :config
  (setq
   ;; Set this if you use project management plugin like projectile.
   clue-project-root-function #'projectile-project-root
   ;; Set like this if you only want auto-enabling citre-mode to work
   ;; for markdown files.  You can also set it to nil, then the
   ;; auto-enabling works for all files.  By default, it works for all
   ;; text-modes.
   clue-auto-enable-modes '(markdown-mode))

API

Packages for code reading may want to integrate with Clue. For example, it may show the user a list of locations, and the user may want to copy & paste one of them as a Clue link. Clue offers 2 APIs for such purpose:

clue-copy-location: Copy the location. The link to it can then be pasted by clue-paste.
clue-paste-location: Paste the location directly as a link.

Recommendation

The logo in this file is inspired by the TV series Furuhata Ninzaburoo. It's my favorite detective drama. If you haven't watch it, I seriously recommend it to you :)

mrunhap / clue