|
|
|
|
The following guidelines are intended for those who build ISIS, the people who enter items into the index. (If you just want to use ISIS, check out the terms of use page.) These guidelines are not yet set in stone, but should provide an initial basis for discussion.
ISIS will deal two kinds of files: source files and final product. Only the index builders will ever see the source files. Everyone will see the final product files. Much like source code, the source files will be "compiled" into the final product files.
Once the source files are created, the number of final product files that can be created is nearly unlimited. The idea is that software will be written to parse the source files and turn them into a variety of final formats, from ASCII text files to relational databases.
Keep in mind that ISIS will be producing three different index types: rules, personality and source. Each type of index will need to be available in each format, when appropriate.
ISIS needs to choose exactly which formats we will officially produce. The following files would likely provide the most use for people with the least effort.
Love it or loathe it, you can get a lot of mileage out of a tab-delimited text file. The intent of this format would be primarily to allow users to convert the information to their own format. To this end, it would be neat of ISIS could provide standard parser source code to users.
Because high-bit characters are not standardized for text, ISIS would need to produce different text files for various platforms, at least Windows and Macintosh.
Unicode is slowly (very slowly) starting to see regular use. ISIS should provide a standard Unicode text file (again tab delimited), mainly because generating such a file will be extremely easy, especially since we already build the text files.
This version would be tightly formatted, multi-column documents, suitable for printing. The idea would be to get the most information in the smallest space, so that people could carry the index with them during a game. The most useful way to build this will probably be programmatically, writing to Adobeıs free Acrobat API.
Since XML is the "ASCII of the future", ISIS should build an XML version. This format will probably generate more debate than the others, as there are many possible ways to use XML here. ISIS should agree on a grammar to use for the XML file. One suggestion is to use this DTD (which might make more sense if you look at the discussion about fields further down).
There are other formats that might be chosen. Many of these formats should probably be left as an exercise for the user. The primary goal of ISIS is to produce the data itself, so that should be the main focus.
Many people will be working on the index simultaneously. ISIS, therefore, needs to use a system that will allow this without a) losing information or b) causing competition for access to files. For example, say you and someone else both want to update the same file. How do you resolve the situation? How do you make sure that one person doesnıt accidentally blow away someone elseıs changes? Fortunately, this is an old problem in the software development industry and has multiple solutions, most of which go by the name "source control".
Source control has many different implementations, but ISIS will use one called CVS. CVS is described more completely on the tools page, but the basic idea is one of a town library. Consider each source file as a book in a library. In order to edit a file, you must "check out" the file. Then you, and only you, can alter it. When you are done, you check the file in. This makes it available for someone else to alter. The one non-library concept is this: at any time, anyone can get a read-only copy of the last file checked in.
Just like a library wonıt let you check out a book without a library card, CVS will only allow people with a username and password access to the source archive. So, this means that you need to have an account on the main source control server to check the source files in and out. When you initially join ISIS, you will be issued an account.
The next step is to decide exactly what the files are that will be checked in and out. ISIS will use the following scheme. A directory will be created in the source archive for each book. Inside this directory will be a file for each five pages of the book. The directory structure will look something like this:
Each file will contain entries for all three indices, mixed together. These source files will then be "compiled" into the final product formats. This will probably be done by a custom written application. Such an app would sift through the source files and use what it needed and ignore the rest.
So what will be in these source files? ISIS needs to use a format that will allow the most people to generate entries. To this end, ISIS will use tab-delimited text files as source files. Each line in these files will be a single entry in the index. These lines will not be sorted in any particular way. They are similar to records in a database. When the source files are compiled into the final indices, they will be given structure. In their source state, each file is just a pile of entries.
Each line is a tab delimited entry containing five fields. In order, these fields are:
Page: This will be the page number of the item, in Shadowrun Reference Standard format. This should be as complete as possible (down to the column and paragraph). In many indices, only the page will be used, but it will be better to have the information and not use it than to need it and not have it.
Type: The index to which this entry applies. There are only five values this field can contain: "equip", "person", "rule", "source", "ref". Of these, the last requires special mention, and is discussed below.
Topic: The primary topic of the entry. Topics are going to be tough to sort out, and are discussed at greater length below.
Subtopic: The subtopic of the entry. This can be blank, but usually wonıt be.
TertiaryTopic: The tertiary topic of the entry. This will usually be blank.
The indices produced by ISIS will be huge. Very huge. For this reason, ISIS needs to invest a bit of thought into how the topics of the index will be organized. Big indices use two tricks to make themselves more understandable.
The first trick is using hierarchy of topics, like so:
The source items to build such a hierarchy would look like this:
The hard part about using a hierarchy is to define topics that are generic enough to have subtopics, but not so generic that they arenıt useful. For example, "Foci" is probably good as a top-level topic, but "Magic" is far to generic. If you were looking in an index for rules about magical foci, youıd look under "Foci" first. Looking up "Magic" first probably would not occur to you.
Still the index will probably need a top-level entry of Magic that directs people elsewhere. This leads to the next index trick: cross-referencing.
Cross-referencing allows you to build very generic top-level indices that point to more specific information. They also allow what is effectively an infinite hierarchy, without requiring infinite nesting or duplicated entries. For example, the topic "Megacorporations" is probably far too broad, but using cross-referencing makes it useful. Like so:
Building cross-references is where the "ref" type mentioned above comes in. The source entries that build the index above would look like this:
Since top-level cross-references are "shared", a special file will be set up for them.
