SPFE Documentation | Collections > SPFE Development > How linking works

How linking works

• How SPFE finds topics to link to
• How SPFE identifies a topic as pertinent to a subject
• Dealing with multiple link targets
• Creating list topics for links

Linking in SPFE is done using soft linking (though you can certainly define your own vocabularies that do hard linking if you want to). The EPPO-simple schema toolkit, and schemas derived from it, support soft linking.

Briefly, soft linking means that a topic does not directly identify the topic it links to. Nor does it do indirect linking, which is when the topic points to a key, which is then mapped to a specific topic in another place. Rather, the topic simply identifies the subject is it referring to. For example, if the topic on programming mentioned the “printf()” function, it would use markup to create an annotation that specifies that the string “printf()” was the name of a function, using markup something like this:

<function-name>printf()</function-name>

In SPFE, this is called subject affinity annotation, or, more simply, subject annotation. At build time, the SPFE process finds this annotation and looks for a topic on the function named “printf()”. If it finds one, it generates a link from the annotated text to the topic on that subject.

 

How SPFE finds topics to link to

SPFE looks for topics to link to in a link catalog. The link catalog is built as part of the synthesis stage. It is the responsibility of the link catalog step to generate link catalog entries for the topics it creates. The default case is that the link catalog builds the link catalogs from the index entries that authors create in the header or each topic they write. However, depending on the sources it is working with, a synthesis stage can use any information available to it to build a link catalog.

The SPFE build process is organized so that the synthesis stage is run for all topic sets before any of the presentation steps are run. Generating links is part of the presentation process, so once the synthesis stage is complete, link catalogs are available for all topic sets in the build. Thus linking can take place across the entire content set.

In addition, SPFE is not limited to using link catalogs from the current build. You could also point it to link catalogs from other builds, or at link catalogs generated to represent external resources. The build will generate links to all these resources.

 

How SPFE identifies a topic as pertinent to a subject

In order to identify a topic suitable for linking to on a particular subject, SPFE considers several factors. Basing the link on the text of the annotated content alone might produce false links. For instance, if you annotated the word “Paris” it would not be clear if you meant the city of Paris in France, a person named Paris, or the small town in Ontario, Canada, named Paris.

To handle this problem, SPFE uses three pieces of information:

• The text of the annotated string, or the canonical version of the text specified in the annotation itself. For instance, in the annotation <actor>John Wayne</actor> the text itself, “John Wayne”, would be used. In the annotation <actor name="John Wayne">the Duke</actor>, the value of the name attribute, “John Wayne”, would be used, and the text, “the Duke” would not be used for linking, though it would be the displayed value of the linked text in the output.

• The type of the annotation, which is generally expressed by the name of the annotation tag itself, but might also be expressed by an attribute of the annotation. For example, the annotation tag for a city named Paris might be <place>Paris</place> while the annotation tag for a person named Paris might be <person>Paris</person>.

• The namespace of the annotation. Specifying a namespace is optional, but it sometimes useful to further clarify the subject being discussed. For instance, to distinguish between the city of Paris and the town of Paris, you might have an annotation like this <place region="France">Paris</place>. Alternatively, the namespace may be expressed by a more specific annotation tag. For example, rather than saying annotating the character Paris from Greek myth as <person domain="myth">Paris</person>, you might use <mythological-person>Paris</mythological-person>. Finally, the namespace may be assumed from the context established by the topic or by the overall subject matter of the content set. In a topic set about Greek mythology, for instance, the namespace for persons can be assumed to be Greek mythology and all we need to write is <person>Paris</person>.

It should be clear from the examples above that SFPE does not establish one standard way for denoting the text, type, or namespace of an annotation. Rather, it leaves it up to the individual topic type to determine which types of annotations it supports, how to express them, and how to establish their canonical values and their namespaces. EPPO-simple does provide a default annotation element that you can use if you want to, but it is usually easier for authors if you define a specific set of annotation types that they can easily choose from when writing.

Converting your local annotation elements into normalized annotations is part of the job of the resolve processing step.

 

Dealing with multiple link targets

With this mechanism, it is possible that the build system will find more than one topic on a particular subject. In this case, it has to decide which one to link to. There are two basic strategies it can use to do this: either choose one of the topics and link to it, or create a list of all the topics on that subject and link to the list. SPFE provided support for both strategies.

To support choosing one of the links, SPFE supports the concept of link priority. Out of a set of potential link targets, the target with the lowest link priority number is chosen. Link priorities can be set on both a topic type and a topic set. The value of a topic's link priority is determined by multiplying these two values. The default value for each is 1, so the default topic link priority is 1 (1*1). By setting a higher link priority number for either the topic type or the topic set, you can make topics of that type, or belonging to that set, lower link priorities. For instance, if you would prefer to have references to an API function link to the API reference rather than to a programming task topic, you can assign a topic-type link priority of 2 to the programming task topic type, or a link priority of 2 to the programming guide topic set (or both). This will lower the priority of the programming task topic relative to the API reference topics and cause links to go to the API reference for any functions it covers. (Any functions not covered in the API reference would still like to the programming task topics, since they would then be the highest priority link targets available.

 

Creating list topics for links

The other way to handle links with more than one potential target is to generate a list of all the targets and link to that list. The SPFE content set uses this technique, so you can use it as a model for your own content set. This is how it works:

1. Create a new topic set for your list topics and make it the last topic set listed in your content set configuration file. The reason it is last is that the topics sets are built in the order listed, and this topics set needs to read the link catalogs generated by all the other topics sets.

2. Create a topic set type for the list topics, and set its link-priority to 0. This will make all list topics the highest priority topics available for linking, ensuring that where there are more than one link target available, the list topic will be the one chosen.

3. Create an extract script that reads the link catalogs of all the other topic sets and find all the cases where there is more than one topic on a particular subject. Have the script generate a topic for each of those subject which lists the topics on that subject and provides links. You can use a generic topic type for this. You don't need a specific topic type. Since the SPFE-docs project already includes an extract script that does this, you may be able to just use it, or else use it as a template for developing your own.

4. Make sure that your script indexes each of the topics that it creates to identify the subjects it covers.

When you rebuild your content set, a new topic set will be created containing the topic lists. All links with multiple targets will now link to the list topics.