Indexes allow you to quickly access files by their name without using a standard open/save dialog, and without having to type the file extension every time. Every file in an index must have a unique name, even if they are in different directories within a directory structure.

KI-STYLE INDEXES

Let me start off by talking about Ki-style indexes. These allow you to pick a base directory. Then you can quickly access and create files within that entire directory structure (each file must have a unique name; they all have a set file extension unless you actually specify the extension).

If a key doesn't exist, you will be prompted to specify/accept a directory path within your chosen base directory structure wherein it will be created. The directory of the last key to be opened (or the base directory) will be filled in by default.

Differences between Ki-style indexes and the others mentioned below include these:
- Ki-style indexes search directories recursively. The others do not.
- The other indexes allow for aliases. Ki-style indexes do not. The aforementioned aliases only work within a Shule/Python/Wikiweb context. They're not saved as text files like the regular keys are.
- Ki-style indexes are independent. The others are indexes for a file or directory.
- You can add Ki-style keys to favorites. You can't for the others.
- With Ki-style indexes, you can open keys with different file extensions by manually typing them in. Again, there's only one file extension for the other indexes.
- Ki-style indexes use Ki. The others utilize Wikiweb (not very much of it, however; there's a lot of room for expansion).
- It's easy to find where your index keys are in a Ki-style index. You have to go through a bunch of directories to find them with the others.
- Ki-style indexes allow sub-directories within the index. The others would ignore those directories if you made them.
- You can safely edit Ki-style indexes outside of Shule. If you edit the other indexes (such as if you delete files) that might mess stuff up in the other indexes (since the structure is technically in the Wikiweb database; it's not just the text files in the directory).
- Middle-clicking will open selected text in a Ki-style index, while right-clicking selected text will open the other style of index.

In Shule you only have one base directory at a time, and it's always the default one (and you only need one). However, on the command-line when using a normal version of Ki, you can have as many as you want. If you want to understand that better, I recommend downloading Ki and reading its documentation. A base directory is the root of a directory structure that contains your unique index keys throughout that structure. When searching for a key, if base directories are even enabled, then Ki will search from the entire base directory, no matter where you are in it (rather than just from the current directory downward).

I added this feature to Shule so I wouldn't have to use Ki from the command-line all the time, since I use Ki a lot, but opening Shule from the command-line with Ki is kind of slow and requires a lot of window shifting. So, I integrated it to make it fast.

WARNINGS:
• For Ki-style directories in Shule, you shouldn't make a base directory that is within another directory that you sometimes use as a base directory unless you know what you're doing. You could make duplicate keys on accident.
• Don't try to open a Ki-style index key from a base directory with zillions of irrelevant files within it, or it could take a really long time to open a key. The index should probably be dedicated for your index. Using your entire home directory as a base directory is probably a very bad idea.


THE REST OF THIS FILE IS ABOUT FILE INDEXES AND DIRECTORY INDEXES:

An index is a group of files for a file or directory. Think of a file index much as a glossary to a book, and think of a folder index much as a glossary to a set of books. Your file is the book (or your files in the folder are the books). The index is the glossary. Your index is comprised of keys/words with definitions (text of arbitrary length).

Indexes are contained within a subdirectory called `indexes.directory` in your folder, whether they are file indexes or folder indexes. You may edit the text of the keys in any text editor. However, if you save new keys, delete keys, rename keys or such, you should only do it in this editor, and not in a file manager or another text editor—otherwise things like aliases won’t work properly. Rename and delete keys the same way you rename and delete regular files.

Index keys may have aliases to open them.

If your index project.pkl file becomes corrupted somehow, you still have the text for each key.

The index functionality uses the Wikiweb software. This means (when I program it) you’ll be able to do complex, text-only data entry. You’ll be able to create relations (with context) between keys, export your index to HTML, and so forth.

SHORTCUTS:

In addition to the shortcuts already mentioned in the menu, there are a couple more:

• Right-click text selection: If you right-click on a text selection, if a local index key with that name exists, it will open it. If it does not exist, it will prompt you if you want to create it.
• Ctrl+right-click text selection: If you hold the control key and right-click on a text selection, if a directory index key with that name exists, it will open it. If it does not exist, it will prompt you if you want to create it.

HYPERTEXT FICTION

Indexes may be used to create such as hypertext fiction (and other hypertext projects). Further functionality is planned (such as allowing global renaming of keys to be reflected in the text rather than just in the index structure), but here’s how it works for now:

• Index keys are hyperlinked files.
• To follow a link, highlight the text and right-click. (To quickly do this with a single word, double-click and then right-click.)
• You may want to give cues to your reader that something is an index key at least the first time you want them to realize following a link is an option, since this is plain text. (e.g. put some symbol by it, like *myKey)

You may be wondering why the left-click button has such functionality as I mentioned in the shortcuts section. The regular menu can already be used via the mouse for typical context menu functionality, and I ran into some difficulties while coding the context menu (plus, accidentally bringing up context menus is kind of annoying—and I’m using the Menu key as a compose key already anyway): So, I decided to use the left-click to further my goals at allowing a simple, easy, and effective way to do hypertext fiction. I needed some way to allow for quick hyperlinks.

Just for the record, index projects are Wikiweb projects. So, you could load them and do data entry Wikiweb-style (data entry does not pertain to the content of the .key files). Wikiweb is a way to relate data to other data bidirectionally.

WIKIWEB DATA ENTRY

Wikiweb is not exactly ready for prime time, yet, but you can use Shule to do data entry with it. You can also use Shule to export Wikiweb projects to HTML. Wikiweb is a separate entity than Shule, but Shule can interface with it (and also uses it for making file and directory indexes; see File->Index). You can use the following compose key codes to access Wikiweb:
• wde (if you don’t select text, it will parse the contents of the whole file; parse the text-only data entry, and run the commands on the project; you will be prompted for a directory; be sure to enter one that doesn’t already exist or it won’t work.)
• whe (export to HTML)

See Wikiweb’s documentation for information about how to do the text-only data entry. See .../shule/wikiweb/documentation.txt (it may be at the following path, if you used the installation file to install Shule: /opt/shule/wikiweb/documentation.txt ).

