How the parent tool can ask for an Inter tree to be indexed.

• §1. Public API
• §4. Sessions
• §6. Private API

§1. Public API. This is a large and complex module of code, but it really only does one thing, and so it is simple to control. Other modules or tools should do this only by calling the functions below.

To produce one or more index products (see below), first open a session; then set its localisation — essentially, choose what language it should be written in; then call functions to make the actual products; and finally close the session. Note that:

• (1) If you want to index the same tree of code to two different languages, you will need to do this as two sessions. However, an Index website and an EPS map which are in the same language can both be made in the same session, and this is more efficient than using two.
• (2) The index module probably works fine if multiple sessions are open at once (and indeed is probably threadsafe), but it hasn't been tested for that or written with that in mind: a safer way to make multiple indexes simultaneously is probably to run multiple independent inter processes, each making one index.

§2. So, then, opening:

index_session *Indexing::open_session?Usage of Indexing::open_session:
Index Stage - §3(inter_tree *I) {
    return Indexing::new_session(I);
}

§3. Now localising. You can either set an existing dictionary which you happen to have to hand, or else ask to read definitions from a file. See Localisation (in html) for how all of this works.

void Indexing::set_localisation_dictionary(index_session *session, localisation_dictionary *LD) {
    Check this is an open session3.5;
    session->localisation = LD;
}

void Indexing::localise?Usage of Indexing::localise:
Index Stage - §3(index_session *session, filename *F) {
    Check this is an open session3.5;
    Localisation::stock_from_file(F, session->localisation);
}

§3.1. Now for the productive part. You can make an entire index mini-website with the following function, which may generate several hundred HTML files. This is what is used in the Inform GUI apps on every compilation.

void Indexing::generate_index_website?Usage of Indexing::generate_index_website:
Index Stage - §2(index_session *session, text_stream *structure) {
    Check this is an open session3.5;
    InterpretIndex::generate(structure, session);
}

§3.2. This is a one-off function for generating the content of an index element (without its heading, or any HTML surround): it's used for unit-testing those elements, but is never used by the Inform GUI app.

void Indexing::generate_one_element(index_session *session, text_stream *OUT, wording elt) {
    Check this is an open session3.5;
    Elements::test_card(OUT, elt, session);
}

§3.3. This is used by the Inform GUI apps to "release along with an EPS file". Essentially it makes a print-suitable version of the Map element of the index, though there are also many bells and whistles for customising the appearance of this. This is written to the stream F_alt if that is non-null, and otherwise into a text file at F (which is created in the process).

void Indexing::generate_EPS_map?Usage of Indexing::generate_EPS_map:
Index Stage - §2(index_session *session, filename *F, text_stream *F_alt) {
    Check this is an open session3.5;
    RenderEPSMap::render_map_as_EPS(F, F_alt, session);
}

§3.4. And lastly closing. The only thing this now does is to enable a new session to be opened afterwards, in fact, but that might change in future.

void Indexing::close_session?Usage of Indexing::close_session:
Index Stage - §2(index_session *session) {
    Check this is an open session3.5;
    session->session_closed = TRUE;
}

§3.5. Check this is an open session3.5 =

    if (session == NULL) internal_error("no indexing session");
    if (session->session_closed) internal_error("closed indexing session");

• This code is used in §3 (twice), §3.1, §3.2, §3.3, §3.4, §6 (three times), §7 (8 times), §8 (three times).

§4. Sessions. This is a miscellany, plain and simple, but it contains all of the workspace and caches needed to index an Inter tree.

typedef struct index_session {
    struct inter_tree *tree;
    struct tree_inventory *inv;
    struct inter_lexicon *lexicon;
    struct faux_instance_set *set_of_instances;
    struct linked_list *list_of_scenes;  of simplified_scene
    struct localisation_dictionary *localisation;
    struct linked_list *list_of_EPS_map_levels;  of EPS_map_level
    struct linked_list *list_of_submaps;  of connected_submap
    struct linked_list *list_of_pages;  of index_page
    struct map_parameter_scope global_map_scope;
    int changed_global_room_colour;
    struct index_page_data page;
    struct map_calculation_data calc;
    int story_dir_to_page_dir[MAX_DIRECTIONS];
    int session_closed;
    CLASS_DEFINITION
} index_session;

• The structure index_session is accessed in 1/is, 2/iu, 2/fi, 2/fs, 4/mc, 4/sm, 4/rhm, 4/rem and here.

§5.

index_session *Indexing::new_session?Usage of Indexing::new_session:
§2(inter_tree *I) {
    if (I == NULL) internal_error("no tree to index");
    index_session *session = CREATE(index_session);
    session->tree = I;
    session->inv = MakeSynopticModuleStage::take_inventory(I);
    session->lexicon = NULL;
    session->set_of_instances = NULL;
    session->list_of_scenes = NULL;
    session->list_of_EPS_map_levels = NEW_LINKED_LIST(EPS_map_level);
    session->list_of_submaps = NEW_LINKED_LIST(connected_submap);
    session->list_of_pages = NEW_LINKED_LIST(index_page);
    session->localisation = Localisation::new();
    session->global_map_scope = ConfigureIndexMap::global_settings();
    session->changed_global_room_colour = FALSE;
    session->calc = SpatialMap::fresh_data();
    session->session_closed = FALSE;
    for (int i=0; i<MAX_DIRECTIONS; i++)
        session->story_dir_to_page_dir[i] = i;
    return session;
}

§6. Private API. The remaining functions in this section are for use only within the index module.

inter_tree *Indexing::get_tree?Usage of Indexing::get_tree:
Faux Instances - §10
Faux Scenes - §2
Behaviour Element - §1
Card Element - §1
Commands Element - §1
Contents Element - §1
Extras Element - §1
Figures Element - §1
Grouped Element - §2
Innards Element - §1
Phrasebook Element - §1
Plot Element - §1
Tokens Element - §1(index_session *session) {
    Check this is an open session3.5;
    return session->tree;
}

localisation_dictionary *Indexing::get_localisation?Usage of Indexing::get_localisation:
Index Interpreter - §1, §2
Index Rules - §8, §11, §12, §15
The Periodic Table - §2
Alphabetic Element - §1
Arithmetic Element - §1
Behaviour Element - §1
Chart Element - §1, §6
Commands Element - §1
Contents Element - §1
Events Element - §1
Extras Element - §1
Figures Element - §1
Gazetteer Element - §1
Grouped Element - §2
Innards Element - §1
Lexicon Element - §1
Map Element - §1, §2, §3, §4, §7
Plot Element - §1
Relations Element - §1
Rules for Scenes Element - §1
Standards Element - §1
Tables Element - §1
Tokens Element - §1
Values Element - §1
Verbs Element - §1
Render HTML Map - §7, §8, §11
Render EPS Map - §1(index_session *session) {
    Check this is an open session3.5;
    return session->localisation;
}

tree_inventory *Indexing::get_inventory?Usage of Indexing::get_inventory:
Faux Instances - §8
Faux Scenes - §2
Alphabetic Element - §1
Arithmetic Element - §1
Behaviour Element - §1
Chart Element - §1
Contents Element - §1
Events Element - §1
Extras Element - §1
Figures Element - §1
Grouped Element - §1, §2
Innards Element - §1
Plot Element - §1
Relations Element - §1
Rules for Scenes Element - §1
Standards Element - §1
Tables Element - §1
Values Element - §1(index_session *session) {
    Check this is an open session3.5;
    return session->inv;
}

map_parameter_scope *Indexing::get_global_map_scope?Usage of Indexing::get_global_map_scope:
Map Configuration - §4, §5, §6, §7, §8(index_session *session) {
    return &(session->global_map_scope);
}

§7. These build up gradually:

linked_list *Indexing::get_list_of_EPS_map_levels?Usage of Indexing::get_list_of_EPS_map_levels:
Faux Instances - §10.4
Render EPS Map - §1.2.1(index_session *session) {
    Check this is an open session3.5;
    return session->list_of_EPS_map_levels;
}

void Indexing::add_EPS_map_levels?Usage of Indexing::add_EPS_map_levels:
Render EPS Map - §1.1.1, §1.1.2(index_session *session, EPS_map_level *eml) {
    Check this is an open session3.5;
    ADD_TO_LINKED_LIST(eml, EPS_map_level, session->list_of_EPS_map_levels);
}

linked_list *Indexing::get_list_of_submaps?Usage of Indexing::get_list_of_submaps:
Spatial Map - §8.26, §8.29, §8.29.1.2, §8.29.2, §41, §45(index_session *session) {
    Check this is an open session3.5;
    return session->list_of_submaps;
}

void Indexing::add_submap?Usage of Indexing::add_submap:
Spatial Map - §12(index_session *session, connected_submap *sub) {
    Check this is an open session3.5;
    ADD_TO_LINKED_LIST(sub, connected_submap, session->list_of_submaps);
}

void Indexing::empty_list_of_pages?Usage of Indexing::empty_list_of_pages:
Index Interpreter - §1(index_session *session) {
    Check this is an open session3.5;
    LinkedLists::empty(session->list_of_pages);
}

linked_list *Indexing::get_list_of_pages?Usage of Indexing::get_list_of_pages:
Index Interpreter - §1.2
Styles and Scripts - §1.1
The Periodic Table - §2(index_session *session) {
    Check this is an open session3.5;
    return session->list_of_pages;
}

void Indexing::add_page?Usage of Indexing::add_page:
Index Interpreter - §3(index_session *session, index_page *page) {
    Check this is an open session3.5;
    ADD_TO_LINKED_LIST(page, index_page, session->list_of_pages);
}

index_page *Indexing::latest_page?Usage of Indexing::latest_page:
Index Interpreter - §2.2(index_session *session) {
    Check this is an open session3.5;
    if (LinkedLists::len(session->list_of_pages) == 0) return NULL;
    return LAST_IN_LINKED_LIST(index_page, session->list_of_pages);
}

§8. These more substantial resources are calculated all in one go, but only on demand:

inter_lexicon *Indexing::get_lexicon?Usage of Indexing::get_lexicon:
Gazetteer Element - §1
Lexicon Element - §1
Verbs Element - §1(index_session *session) {
    Check this is an open session3.5;
    if (session->lexicon == NULL)
        session->lexicon = IndexLexicon::stock(session->tree, session->inv);
    return session->lexicon;
}

faux_instance_set *Indexing::get_set_of_instances?Usage of Indexing::get_set_of_instances:
Faux Instances - §10, §11, §12
Map Element - §1, §6, §7
Spatial Map - §8, §8.3, §8.19, §8.20, §43, §44
Render HTML Map - §1, §6, §7, §11, §14
Render EPS Map - §1.1, §1.2(index_session *session) {
    Check this is an open session3.5;
    if (session->set_of_instances == NULL) FauxInstances::make_faux(session);
    return session->set_of_instances;
}

linked_list *Indexing::get_list_of_scenes?Usage of Indexing::get_list_of_scenes:
Faux Scenes - §7
Plot Element - §1, §2(index_session *session) {
    Check this is an open session3.5;
    if (session->list_of_scenes == NULL) FauxScenes::list_of_faux_scenes(session);
    return session->list_of_scenes;
}