A .index file can be somewhat complicated in that is can hold a fair bit of detailed information and does so in a very strict format. To ease the maintenance of a .index file a developer will most likely want to "source" the file from other data sources, rather than maintain the file manually. Indexer supports a number of ways to do this.

A README can be used as an index source by using HTML microformats. Index microformats are designated by using a class name starting with the letter i and completed by the name of the field. For instance a title can be designated using:

  <h1 class="ititle">Hello World</h1>

While a more complex entry such as an author can be marked-up with sub-entries. e.g.

  <div class="iauthor vcard">
     <span class="nickname">Thomas T. Thomas</span>
     <a class="email" href="mailto:[email protected]">[email protected]</a>
  </div>

Notice this entry is also a valid vcard.

This is a relatively new approach to sourcing, and as such the formats are still being refined. But in general they work as described and work well enough. You can always look at Indexer's own README.md file for good examples of this approach.

A YAML file can serve as a .index source. The YAML file will be processed via the versatile Indexer::Metadata class making it much easier to write. Conventionally the file can be called Index.yml. However the actual name isn't important, and can be anything that a project maintainer think's most suitable.

An snippet of an example YAML file looks like this:

    ---
    name: foo
    version: 1.2.3
    copyrights:
      - 2011 Guy Fox (MIT)

Note the use of --- at the top of the file. This is required for the file to be recognized as YAML when the file's extension is not .yml or .yaml.

Another alternate for an index source is a a Ruby script, which will be passed through a simple #method_missing DSL mapping method invocations to field assignments. An small snippet of such a file might look like:

    require_relative 'lib/foo/version.rb'

    name "foo"
    version Foo::VERSION
    copyrights ['2011 Guy Fox (MIT)']

Conventionally such a file is called Index.rb or Indexfile, mimicking the file naming scheme started by Rake with it's Rakefile. But again, it can be anything.

An index file can even be sourced from a directory of files. Each file in the directory will be taken to be a field assignment. If a file starts with three dashes (---) it is passed through YAML.load before assignment. For example,

$ cat metadata/name
foo
$ cat metadata/version
1.2.3
$ cat metadata/copyrights
---
- 2011 Guy Fox (MIT)

This might seem a strange way to do things, but it does have some advantages. In particular, if some one piece of a project's metadata were to change then only one file containing this single piece of information need be effected. This makes it very easy to script without worrying about nasty human-readability issues caused by YAML emitters.

Like the file names above, this directory can be called anything. But of course, index makes sense. Yet var is perhaps a more interesting choice as a place to store "build variables".

NOTE: While not yet been implemented, because the exact design is still a question, eventually there will be a feature to specify whether a file in the directory should or should not be included in the .index file.

It is not recommended that an index file be sourced from a gemspec file, though it can be done. The functionality is provided because it can be useful in seeding an initial index file for a project that already has a .gemspec file, so one can get up and running quickly.

The recommended approach is instead to install Indexer's gemspec file ($ index -g gemspec) which will dynamically construct a Gem::Specificaiton by reading the .index file on the fly.

Although there are some limitations, the index specification almost completely constitutes a superset of the gem specification. So fairly thorough and completely usable gemspecs can be constructed in this way.