[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[update] linkd.el 1.31 (alpha release 2)

From: David O'Toole
Subject: [update] linkd.el 1.31 (alpha release 2)
Date: Tue, 16 Jan 2007 02:46:20 -0500
User-agent: Gnus/5.110006 (No Gnus v0.6) Emacs/22.0.50 (gnu/linux)

I am pleased to announce the updated linkd.el. This is a second
alpha release. I have attached the source code and a preliminary
version of the manual in plain-text format. 

My thanks to everyone who has submitted bug reports, feature requests,
and feedback. 

the linkd homepage is here:
the icons are here:


This is a plain text version of the linkd manual for version 1.31 of

linkd-mode is a hypertext system for organizing and interlinking all
resources available to GNU Emacs. It can be used to make a "personal
web" out of all your text files---regardless of file format or major

linkd-mode is not another publishing mode or personal information
management system. Instead it is designed to be used alongside the
modes of your choice. Download links, instructions, and more
screenshots are below.


The user of linkd-mode may:

  - Delimit and name regions of text called "blocks" in any type of
    text file. (The delimiters are the yellow-on-red stars in the
    above screenshot.)
  - Insert links to blocks, files, pictures, pdfs, manual pages, web
    pages, and more.
  - Send blocks to other programs (i.e. bash) for processing
  - Identify concepts with "tags" and navigate to other instances of
    the concept
  - Optionally use icons so that links can be distinguished from each
    other by color and shape

Quite soon, linkd-mode will:

  - Search and index blocks.
  - Analyze and summarize links between blocks.
  - Manufacture links related to the current context (a la
  - Unify the linking schemes used by different emacs packages (for
    example, eev, planner, howm, org)


In designing linkd-mode I have drawn on EevMode and HowmMode, among
other things. Special thanks to Eduardo Ochs for writing eev and for
many years of fruitful discussions, to Richard Stallman for feedback
and suggestions regarding golisp-mode, and to Michael Olson for coming
up with the name and contributing ideas.

the icons are here:



Installation and configuration

NOTE: Linkd requires Emacs 22.

Download linkd.el and put it in your load-path. Then add

 (require 'linkd)

to your emacs initialization file, and execute the sexp with C-x C-e.

If you want cool graphical icons, download the icon collection and
unpack it in some suitable folder. Then add the following to your
emacs initialization file:

 (setq linkd-use-icons t)
 (setq linkd-icons-path "~/.linkd-icons") ;; or wherever you put it

You can set up linkd-mode to turn on automatically whenever you enter
certain major modes. Here is an example that causes linkd-mode to
activate whenever you open an Emacs Lisp, Common Lisp, shell-script,
or text-mode file:

 (add-hook 'emacs-lisp-mode-hook 'linkd-mode)
 (add-hook 'lisp-mode-hook 'linkd-mode)
 (add-hook 'sh-mode-hook 'linkd-mode)
 (add-hook 'text-mode-hook 'linkd-mode)

Linkd-mode's keybindings follow the standard conventions for minor
modes: C-c followed by one of a set of reserved punctuation
characters. For speed, I rebind some of them as follows:

 (global-set-key [(control \&)] 'linkd-follow-on-this-line)
 (global-set-key [(control f3)] 'linkd-process-block)
 (global-set-key (kbd "M-[") 'linkd-previous-link)
 (global-set-key (kbd "M-]") 'linkd-next-link)
 (global-set-key (kbd "M-RET") 'linkd-follow-at-point)


To use the features of linkd, you must turn on linkd-mode by issuing
the command M-x linkd-mode RET. This will fontify the links and
establish key bindings for linkd-mode's commands.

Basics of links

Links look like this:

 (@file :path "/etc/fstab")

or sometimes just

 (@> "font locking") 

They are typically embedded in the comments of source code files or
configuration files.

Here are a few examples:

 (@file :path "/etc/fstab")
 (@file :path "~/e/dtox.e" :to "ardour2") 
 (@file :path "~/e/rlx.el")
 (@file :path "~/org/" :to "* Tasks")
 (@file :path "~/e/cl-frame.lisp")
 (@man :page "fvwm" :to "ButtonStyle") 
 (@> "font locking")
 (@man :page "conky") 
 (@file :path "~/org/")
 (@info :file "elisp" :node "Display Property")

Try typing a few into a scratch buffer where linkd-mode is turned
on. The moment you type the closing parenthesis, the link should
fontify (and display an icon, if you have icons turned on.)

To follow a link, place point on the link and press C-c '. This runs
the command (linkd-follow-at-point). If there is only one link on that
line, you can just place point anywhere in the line and press C-c
{period} to run the command (linkd-follow-on-this-line).

To edit a link, put point at the end of the link, and press backspace
to delete the closing parenthesis---the link will turn back into plain

Of course, you don't actually have to insert and edit links
manually. It's cumbersome and in most cases unnecessary. See the
section "Creating and editing links" below.

Blocks and stars

Certain special links delimit regions of a file. These regions are
called blocks and the delimiters are called stars. A block looks like

 (@* "block name")
 ... content of block

The key C-c {asterisk} executes the command (linkd-process-block),
which triggers an action on the block containing point. The action
taken is controlled by the buffer-local variable
linkd-process-block-function, whose value is the function that
processes the block. An example of this is below in the section
"Example Usages."


Tags are special links that may appear multiple times in a file. They
look like this:

 (@> "topic name")

Following a tag navigates the next instance of the tag with the same
name. Repeatedly hitting C-c ' will cycle through all instances of the
tag in the file, also stopping at any blocks with the same name.

Creating and editing links

There are several commands to insert new links. For most links you can
use C-c {comma} {comma}. This runs the command (linkd-insert-link)

For stars and tags, you can use C-c , s (linkd-insert-star) and C-c ,
t (linkd-insert-tag) respectively.

You can interactively edit a link with C-c , e which runs the command

If you use these functions to create and edit links, you can
effectively ignore the link syntax.


An interactive self-documenting installer script

My other project DTOX revolves around an interactive
installation/configuration script. It is a bash script split into
named blocks by linkd stars. The blocks contain commentary and active
links to related documentation and configuration files.

(image missing)

The local variables in the script set linkd-process-block-function to
the value linkd-send-block-to-shell, which pops up an emacs shell
window to execute the commands in the block.

So the user can inspect the blocks, edit them if necessary, choose
which blocks are to be executed, and watch the output of the
commands. The user may also follow the links to learn more, or to
tweak a configuration file after it has been installed.

Concept-oriented navigation in lisp source code

When writing a program, I often want to jump to related pieces of
code. But I usually don't just want to jump to a function definition
from one of its callers---more often I want to find pieces of code
that are related in some more abstract sense.

I use linkd-mode's tags and stars to relate pieces of code to one
another and to navigate through related code.  First I gather related
functions and variables and put them in their own block, and name the
block after the concept they embody. (Remember that stars are used to
delimit and name blocks.) If I am writing an object-oriented program
with CLOS, I will usually put a class and most of its methods in one

Then I place tags wherever a piece of code is related to the block in
some sense. You can think of following a link as jumping between
related ideas, because it will move point to the next tag or star with
the same concept name (and back to the first when you reach the end of
the file.)

(image missing)

I use linkd-mode to organize my lisp programs, be they 80 lines or
8,000. If you'd like to try out such a file with linkd-mode, you can
download rlx.el (part of the RLX Project) and follow the links in the
file. There is even an index of program concepts that one can use to
get an overview of the program's structure.

I also insert links to pages of relevant documentation---for example
the Emacs Lisp Manual or the ANSI Common Lisp Standard.

Creating a wiki-like personal "hyperweb"

 - This section is under construction, as is the functionality

Many people use wikis as personal notebooks. They organize their
knowledge, develop ideas, and keep web bookmarks in their wikis. With
linkd-mode, any text file on your system can be a wiki page, including
system configuration files. Wiki pages can link to any kind of
resource, not just other pages. They can be in any major-mode you
choose. And your wiki pages can contain interactive scripts (see the
section about DTOX above.)

(image missing)

First you should create a directory called ~/linkd-wiki (or set
linkd-wiki-directory to your preferred location.) This is the default
location for new wiki pages.

For fast access, I set a global key that navigates instantly to the
wiki's FrontPage:

 (global-set-key [(meta f8)] '(lambda () (interactive)
                                (linkd-wiki-find-page "FrontPage")))

You can use C-c , w to create a link to a wiki page.

Attachment: linkd.el
Description: application/emacs-lisp

David O'Toole 

reply via email to

[Prev in Thread] Current Thread [Next in Thread]