Skip to content

Latest commit

 

History

History
183 lines (129 loc) · 5.91 KB

README.org

File metadata and controls

183 lines (129 loc) · 5.91 KB
Raw

org-index

A personal adaptive index for org.

org-index is a package for org-mode within emacs.

Read below for a description.

The current version is 7.4.5.

Visit http://2484.de/org-index.html for a Screencast.

Table of Contents

About this Package

Purpose

Fast search for selected org-nodes and things outside.

`org-index’ (package and interactive function) helps to create and update an index-table with keywords; each line either points to a heading in org, references a folder outside of org or carries an url or a snippet of text. When searching the index, the set of matching lines is updated with every keystroke; results are sorted by usage count and date, so that frequently or recently used entries appear first in the list of results.

Please note, that org-index uses org-id throughout and therefore adds an id-property to all nodes in the index.

In addition to the index table, org-index introduces the concept of references: These are decorated numbers (e.g. ‘R237’ or ‘–455–’); they are well suited to be used outside of org, e.g. in folder names, ticket systems or on printed documents. Use of references is optional.

On first invocation org-index will assist you in creating the index table. The index table is a normal org table, that needs to be stored in a dedicated node anywhere within your org files.

To start using your index, invoke the subcommand ‘add’ to create index entries and ‘occur’ to find them. The first call to ‘add’ will trigger the one-time assistant to create the index table.

The set of columns within the index-table is fixed (see variable `oidx–all-columns’) but can be arranged in any order you wish; just edit the index table. The number of columns shown during occur is determined by `org-index-occur-columns’. Using both features allows to ignore columns during search.

Setup

  • org-index can be installed with package.el
  • Invoke `org-index’; on first run it will assist in creating your index table.
  • Optionally invoke `M-x org-customize’, group ‘Org Index’, to tune its settings.

Further Information

  • Watch the screencast at http://2484.de/org-index.html.
  • See the documentation of `org-index’, which can also be read by invoking `org-index’ and typing ‘help’.

Files

Implementation

org-index.el
The complete lisp source

Building

Rakefile
Helpful Ruby-Tasks for building

Tests

In subdir tests.

oidx.el
ert-tests for org-index
test.bat
Windows command file to start a specifically prepared emacs for the tests
test-init.el
Customizations for the tests

Screencasts

In subdir screencast.

These files have been used to produce the screencast on http://2484.de/org-index.html:

screencast.bat
Windows command file to start a specifically prepared emacs for the screencast
screencast.el
The lisp code used to play the screencast
screencast-init.el
Customizations for screencast
screencast.org
Internal Notes about the screencast

Custom merge-driver for git

In subdir merge-driver.

merge-org-index.rb
Simple ruby script to aid during git merges of your index table; see the comments within the file for instructions

Releasing a new version

Testing and checking

  • rake test
  • (byte-compile-file “org-index.el”)
  • elint-current-buffer
  • checkdoc
  • package-lint-current-buffer ;; ignore messages about oidx-prefix

Preparing

  • Update Version number in org-index.el
  • Update Change Log in org-index.el
  • Check and update Commentary in org-index.el
  • Run rake to:
    • copy those pieces of information into README.org and ChangeLog.org
    • run tests
  • git add/commit as appropriate
  • v=x.y.z ; git tag -a -m $v $v ; git push ; git push –tags

Latest Change Log

See ChangeLog.org for older entries.

7.4

  • Index checks now find largest cells for each column
  • Documented and enhanced special treatment for yank-column
  • Check for unwanted shortening of the index table
  • Fix for sorting
  • Fix for parsing index table
  • Fill column last-accessed if empty
  • Negotiated with checkdoc, package-lint and byte-compile-file
  • Interpret ‘[[’ in yank text as org-mode links
  • Fix for index-maintainance
  • Simpler handling, if index table cannot be found

7.3

  • Reworked index-maintainance:
    • checks no runs all the read-only stuff into a buffer
    • retire allows to shorten index according to simple criterias
  • Using <M-return> instead of <S-return>

7.2

  • Allow to add inline-Tasks to the index
  • Optional hl-line-mode in occur-buffer
  • Renamed command `details’ to `view’
  • Better messages
  • Fixes

7.1

  • Added flag-column in occur
  • Wrap org-id-find and org-id-goto
  • Offer org-id-update-id-locations in certain cases
  • Fixes

7.0

  • A release of much rewriting and removal
  • Rewrote the occur command to reduce complexity
  • Only one sorting strategy is supported now, removed `org-index-sort-by’
  • Removed background sorting
  • Disallowed custom columns (starting wit a dot ‘.’)
  • Sorting now only relates to index table (not arbitrary regions)
  • Removed commands ping, column, find-ref and highlight
  • Simplified command node: It now only works from within index
  • Command details now works from within index too
  • Document columns of index table and their purpose
  • Remove ability to search for refererence under cursor
  • Prefix arguments no longer allowed
  • Removed interface for lisp functions, e.g. org-index-new-line;