Hint

Hints annotate a word, phrase or media file with short explanatory, advisory or other supplementary information. A hint can be used to spell out the whole text of an abbreviation for example, to credit a photographer of an image, to provide an explanation for a technical term or directions on how to pronounce a foreign name.

Hints are usually implemented in browsers as a tooltip which is shown when the cursor hovers over the annotated text or media file.

How to

Mark the start of the hint with a left curly bracket { and the end of the hint with a right curly bracket } as in the examples below. The hint must be written directly after the word or string of words which it annotates. There may be no whitespace before the hint.

Hints can also be attached to some linked files: images, video and audio files.

The hint is expected to contain plain text. No phrase markup except for the backslash is interpreted inside a hint.

Examples

The UN{United Nations} were founded in 1945.

The UN were founded in 1945.

The hint in the example above is used to spell out the meaning of an abbreviation. In the next example, the hint annotates a gently emphasized scientific name of an animal species with its English name:

Send more ~Vulpes vulpes~{red fox} videos!

Send more Vulpes vulpes videos!

The third example shows a linked image file where a copyright notice is attached as a hint. Some photographers may require to make their authorship known in a less subtle way for a permission to use their work.

[i:bench on a levee]->/stuff/bench.jpg{© 2014 Martin Janecke}
bench on a levee

For developers

When Aneamal is translated to HTML, a hint which annotates a word or string is turned into a title attribute on a span element. Hence the first two examples become

The <span title='United Nations'>UN</span> were founded in 1945.
Send more <span title='red fox'><i>Vulpes vulpes</i></span> videos!

A hint which annotates an image, video or audio file is also translated into a HTML title attribute, but the attribute is on the img or video element respectively. The third example becomes

<img src='/stuff/bench.jpg' width='800' height='400' alt='bench on a levee' title='© 2014 Martin Janecke'>

Normally browsers do not indicate the presence of a title attribute by default, but you can use CSS such as the following to do it.

span[title] {
	cursor: help;
	text-decoration: dotted underline;
}

Mind that some computers may not offer their users means to easily access the title attribute, for instance when they lack a device to move a cursor on the screen over annotated text. CSS can be applied to mitigate this accessibility concern by always showing the content of the title attribute:

span[title]::after {
	content: ' (' attr(title) ')';
	font-size: smaller;
}

Authors of East Asian texts may prefer to use Aneamal hints for ruby annotations. Browser support for ruby features in CSS is lacking as of mid 2022, but a little JavaScript such as the following can transform the HTML span elements with title attributes into ruby and rt elements instead.

window.addEventListener('load', function() {
	document.querySelectorAll('span[title]').forEach(function(i) {
		var r = document.createElement('rt');
		r.textContent = i.title;
		i.outerHTML = '<ruby>' + i.innerHTML + r.outerHTML + '</ruby>';
	});
});