Sometimes the short version of a name is ambiguous, and you need to add some extra text to make both its title and ID unique.
For example, the word "Python" could either refer to:
The disambiguate name argument, which is automatically defined for all macros, helps you deal more neatly with such problems.
Have a look at this example:
My favorite snakes are \x[python-genus]{p}!

My favorite programming language is \x[python-programming-language]!

\x[python-genus]{full}

\x[python-programming-language]{full}

= Python
{disambiguate=genus}
{parent=h-disambiguate-argument}

= Python
{c}
{disambiguate=programming language}
{parent=h-disambiguate-argument}
{title2=.py}
{wiki}
which renders as:
My favorite snakes are pythons!
My favorite programming language is Python!
from which we observe how disambiguate:
  • gets added to the ID after conversion following the same rules as automatic ID from title
  • shows up on the header between parenthesis, much like Wikipedia, as well as in full cross references
  • does not show up on non-full references. This makes it much more likely that you will be able to reuse the title automatically on a cross reference without content: we wouldn't want to say "My favorite programming language is Python (programming language)" all the time, would we?
  • gets added to the default \H wiki argument inside parenthesis, following Wikipedia convention, therefore increasing the likelihood that you will be able to go with the default Wikipedia value
Besides disambiguating headers, the disambiguate argument has a second related application: disambiguating IDs of images. For example:
\x[image-the-title-of-my-disambiguate-image]{full=0}

\x[image-the-title-of-my-disambiguate-image-2]{full=0}

\x[image-the-title-of-my-disambiguate-image]{full}

\x[image-the-title-of-my-disambiguate-image-2]{full}

\Image[Tank_man_standing_in_front_of_some_tanks.jpg]
{title=The title of my disambiguate image}

\Image[Tank_man_standing_in_front_of_some_tanks.jpg]
{title=The title of my disambiguate image}
{disambiguate=2}
which renders as:
Figure 4. The title of my disambiguate image.
Figure 5. The title of my disambiguate image.
Note that unlike for headers, disambiguate does not appear on the title of images at all. It serves only to create an unique ID that can be later referred to. Headers are actually the only case where disambiguate shows up on the visible rendered output. We intend on making this application obsolete however with:
This use case is even more useful when title-from-src is enable by default for the media-providers entry, so you don't have to repeat titles several times over and over.

Ancestors