Controlling Linking
Controlling Linking
1 Introduction
Noosphere’s automatic linking system handles most inter-entry linking instances properly. However, a small fraction of the time, it does not have enough information based on concept label metadata (titles, synonyms, defines) and classification metadata to resolve ambiguous links. In these cases, something extra must be done to correct linking.
There are two families of methods to accomplish this. The first involves improving the metadata, beyond concept labels and classification. We introduce linking policy metadata to accomplish this.
The second family of methods involves pseudo-LaTeX commands to steer the linking. We call this the in-situ method.
In-situ controls should be considered a last resort, as it is much more elegant and labor-effective to separate link controls from the text. For example, consider a situation where someone points out a problem with a link in your entry, entry . The errant link is due to a term defined in entry . This problem could be fixed if the author of improved its linking policy, or if you used an in-situ link steering command in . However, assume that the same linking problem is also present in 100 other entries, all of which link to . Rather than fixing the 100 entries with in-situ commands, it makes much more sense for the author of to modify its linking policy once, solving all 100 errant link instances.
The two families of methods are described below.
2 Linking Policy
The linking policy of an entry is a text field containing a set of directives, one per line. The currently-supported directives are described below.
2.1 Link Priority
This directive has the following syntax:
priority <N> [LABEL]
where <N> is a number and [LABEL] is an optional concept label defined by the entry. The default priority is 100, and integer values from 0 to 32767 are accepted. Smaller numbers mean higher priority. Examples are:
priority 10 normal priority 200 "mapping function"
This directive is used as a tie-breaker when classification directives and category-based link steering fail to find a unique destination. Setting the priority higher than normal (closer to zero) results in an entry (or concept) being linked to “by default”. Setting it lower (above 100) would result in the entry or concept being linked to automatically only when the categorization of the other entry overlaps.
3 In-Situ Link Controls
The in-situ methods involve pseudo-LaTeX commands you can put in your entry to steer linking. As mentioned before, they should be considered a last resort, with proper concept labels, classification, and linking policy as the first lines of defense.
3.1 Link Suppression
Sometimes it makes sense to block linking entirely for a portion of an entry, rather than simply steering a link to a different target. Below are a number of commands to do this:
- \PMlinkescapetext
-
Usage: \PMlinkescapetext{text} or {\PMlinkescape text}
This will result in “text” appearing rendered verbatim with no reference link processing applied to it. Note that these only act upon the single body of “text” given. - \PMlinkescapeword
-
Usage: \PMlinkescapeword{word}
This will result in “word” being exempt from reference link processing anywhere it occurs, separated from other text by blanks, in the object. This tag can appear anywhere inside the text of the article (including at the end of the object, but not inside the preamble). Note that this tag produces no output. - \PMlinkescapephrase
-
Usage: \PMlinkescapephrase{phrase}
Results in the series of words “phrase” being exempt from reference link processing anywhere they occur in the object. In fact, this tag is currently implemented the same as \PMlinkescapeword. However, it is conceivable that words and phrases may be treated differently at some point, so one should keep this in mind when deciding which command to use. Note that this tag produces no output.
Warning: If you put \PMlinkescapeword in your preamble, it may or may not work, and it may or may not cause random breakage of other things in your document. Do not do this!
As an example, suppose I have an entry that looks like this:
Fix a prime $p$. Then $p$ is odd if and only if $p\neq 2$.
As it stands, the word “fix” will be autolinked to an entry on fixed points. This is not appropriate here. So we have two choices:
\PMlinkescapetext{Fix} a prime $p$.
Then $p$ is odd if and only if $p\neq 2$.
or
\PMlinkescapeword{Fix}
\PMlinkescapeword{fix}
Fix a prime $p$.
Then $p$ is odd if and only if $p\neq 2$.
In the first case, if “fix” occurs again in the document, it will be autolinked, even though the first occurrence is not. This is appropriate if the second occurrence is actually using it in the technical sense. In the second case, the word “fix” is never autolinked; if you do use it in the technical sense, you should use one of the commands below to link it.
Both capitalizations are included in the entry above because the autolink suppression is very simple: it only suppresses links from identical text. So in order to prevent autolinking on “fix” as well as “Fix”, we have to explicitly specify both.
3.2 Link Steering
Using classification and linking policy, automatic linking can usually pick the correct destination for a link when there are multiple
possibilities. However, when it fails, one might have to use a link steering command instead.
- \PMlinkid
-
Usage: \PMlinkid{anchor}{id}
This links text “anchor” to the PlanetMath encyclopedia object with id “id”. You can find out an object’s id when you view it. Produces a single instance of “anchor” hyperlinked where the command is issued. - \PMlinkname
-
Usage: \PMlinkname{anchor}{name}
This links “anchor” text to the PlanetMath encyclopedia object with name “name”. Note that name is a PlanetMath canonical name. You can also find this out by viewing the object. Produces a single instance of “anchor” hyperlinked where the command is issued.
3.3 Manual Linking
There are instances where entirely ad hoc links are desired, such as to an external object on the web, or to a file box. For these instances, a manual linking pseudo-LaTeX command is necessary. These commands are described below:
- \PMlinkexternal
-
Usage: \PMlinkexternal{anchor}{url}
This allows you link to any arbitrary URL on the web within your object. “anchor” is the text which will appear in your rendered object. URL is the address you want to point to. This corresponds to <a href="url">anchor</a>. - \PMlinktofile
-
Usage: \PMlinktofile{anchor}{filename}
This links “anchor” text to “filename” in the object’s filebox. One caveat: when previewing a new object, the URL generated for this command will not work.
3.4 Notes
Since there is no sophisticated parsing of the pseudo-LaTeX commands, you can’t put anything “fancy” inside the brackets for them. That is, plain text only. You cannot do something like \PMlinkescapetext{\emph{function}}, you’d have to do \emph{\PMlinkescapetext{function}}.
These commands are implemented entirely in the code for PlanetMath, during the preprocessing that happens before the LaTeX content is sent to the rendering back-end. They were modeled after LaTeX commands in order to keep the overall content representation paradigm consistent.
There is a package pmath.sty that allows one to process the above commands if either of the following packages is used: hyperref, html, url. If no such package is used, then no hyperlinks are created.
All links are implemented using the actual LaTeX html package, with the \htmladdnormallink command.
| Title | Controlling Linking |
|---|---|
| Canonical name | ControllingLinking1 |
| Date of creation | 2013-03-11 19:20:14 |
| Last modified on | 2013-03-11 19:20:14 |
| Owner | mathwizard (128) |
| Last modified by | (0) |
| Numerical id | 1 |
| Author | mathwizard (0) |
| Entry type | Definition |