View source for Template:Glossary link/doc

{{Documentation subpage|[[Template:Glossary link]] and [[Template:Glossary link internal]]}}
{{High-use}}
<!----Please place categories where indicated at the bottom of this page---->
{{Template shortcut|gli}}

== Usage ==
The template '''{{tlx|glossary link}}''' and its variant '''{{tlx|glossary link internal}}''' ('''{{tlx|gli}}''' for short) are templates for creating structured links to particular entries in topical glossaries.

* {{tlx|Glossary link}} is a <em>meta-template</em> for creating templates for specific major glossary articles (e.g. the {{tlx|cuegloss}} template for [[Glossary of cue sports terms]]); it is not usually used directly in an article. Please categorize any derived, topical glossary link templates that use this meta-template into [[:Category:Glossary link templates]] (this is usually done at the bottom of the template's /doc page, so that the category is not inside the template itself and it not accidentally transcluded into the articles that use the template).
* {{tlx|gli}} {{em|is}} usually used directly in the glossary article itself, and is not a meta-template.

The documentation below explains how to use them for your topic's [[MOS:GLOSSARIES|template-structured glossary]]. Like the {{tlx|dfn}} wrapper, and the glossary {{tlx|term}} template, it uses the {{tag|dfn|o}} HTML element properly. (Note that {{tnull|glossary link internal}} necessarily does not use it; {{tag|dfn|o}} should only be used once per term on a single page, at the defining appearance of it, and is used by {{tlx|term}} inside the glossary.)

{{tlx|Glossary link}} creates a normal blue link. To prevent the "[[MOS:SEAOFBLUE|sea of blue]]" effect, {{tlx|Glossary link internal}} uses the light dashed underline style that has become a {{lang|la|de facto}} Web standard for definitional markup.{{efn|This style is exemplified by TechScribe, an online resource for technical writers, and can been seen on most of their pages, e.g. [https://www.techscribe.co.uk/ta/structured-writing-is-partly-structured.htm this one], where blue linking, like Wikipedia's, is used for major topics, while faint underlining is used for definitional links to the site's glossary.}}

Tech detail: By using an internal {{tag|span}} with its own independent <code>title</code> attribute for a tool tip, it sets this up in a way that does not violate the very geeky and backasswards HTML5 specs on the handing of the <code>title</code> attribute of {{tag|dfn|o}}, which is the exact term defined, not its definition.

Due to lack of what would be a pretty sophisticated facility in the [[MediaWiki]] parser, there is no way to have the definition in the glossary be pulled into a pop-up tooltip on mouseover, which would be really cool. [[phab:T102280|Maybe someday.]] For now, it shows the glossary article title (if on another page) and what the entry's name is, as specified by the template, which is where the reader will go if they click on the glossary link. This replaces the default Wikipedia tooltip for such a link, which would only give the article title.

===Syntax (basic use cases)===
;Linking from regular article prose to glossary entries:
*Use a term as it appears in a separate glossary article: {{tlx|glossary link|glossary{{=}}Glossary of botanical terms|utricle}} &ndash; gives: {{glossary link|glossary=Glossary of botanical terms|utricle}}
*Use an alternative term, linking to the related term in a separate glossary article: {{tlx|glossary link|glossary{{=}}Glossary of botanical terms|utricle|utricular}} &ndash; gives: {{glossary link|glossary=Glossary of botanical terms|utricle|utricular}}
*Use a partially piped link: <code><nowiki>{{</nowiki>'''glossary link'''<nowiki>|glossary</nowiki>{{=}}<nowiki>Glossary of botanical terms|utricle}}s</nowiki></code> &ndash; gives: {{glossary link|glossary=Glossary of botanical terms|utricle}}s<br />&nbsp;
*{{strong|Link targets are converted to lower case}} by this template and the corresponding {{tlx|term}} in the glossary (the original version as specified in {{tlc|term}}, even if it's "uTriCle", it will also work): {{tlx|glossary link|glossary{{=}}Glossary of botanical terms|Utricle}} &ndash; gives: {{glossary link|glossary=Glossary of botanical terms|Utricle}} (note the link target). In other words, <code>{{dc|1=<nowiki>{{glossary link|glossary=Glossary of botanical terms|utricle|Utricle}}</nowiki>}}</code> is not necessary.
**This means that for entries that begin with (or otherwise contain) upper case, a lower-case anchor must exist. {{tlx|Term}} does this automatically, but if the target glossary is not template-structured, a manual {{tlx|anchor}} or {{tlx|vanchor}} will be need to be added.
**If there is some circumstance in which this is not practical/desirable for a particular term, the lower-casing can be turned off with {{para|lc|no}}: {{tnull|glossary link|Amelia P. Steiner|lc{{=}}no}}<br />&nbsp;
*Use a term as it appears in the glossary section of the same article: {{tlx|glossary link|chicken nugget}} &ndash; gives: {{glossary link|chicken nugget}}
*Same but less visually intrusive: {{tlx|glossary link internal|chicken nugget}} or {{tlx|gli|chicken nugget}} &ndash; gives: {{glossary link internal|chicken nugget}}
*Use an alternative term, linking to a related term in the glossary section of the same article: {{tlx|glossary link|chicken nugget|Compressed and breaded poultry snacks}} &ndash; gives: {{glossary link|chicken nugget|Compressed and breaded poultry snacks}}
*Same but less visually intrusive: {{tlx|glossary link internal|chicken nugget|Compressed and breaded poultry snacks}} or {{tlx|gli|chicken nugget|Compressed and breaded poultry snacks}} &ndash; gives: {{glossary link internal|chicken nugget|Compressed and breaded poultry snacks}}
Normally this is done with a derived, glossary-specific wrapper template. For example, {{tlx|glossary link|glossary{{=}}Glossary of cue sports terms|massé}} can be done simply with {{tlx|cuegloss|massé}}.

;Linking between glossary entries on the same page:
We use the {{tlx|glossary link internal}} (short name: {{tlx|gli}}) variant to not [[WP:SEAOFBLUE|plaster the page with blue links]]; ones that go to full articles on terms will thus stand out from links to other short definitions in the same glossary:
*Use a term as it appears within the same glossary page: {{tlx|gli|Example code}} &ndash; gives: {{gli|Example code}}
*Use an alternative term, linking to the related term within the same glossary page: {{tlx|gli|Example code|some examples}} &ndash; gives: {{gli|Example code|some examples}}<br />&nbsp;
*Use a term as it appears on a different page of the same multi-page glossary: {{tlx|gli|glossary{{=}}Glossary of education terms (M–O)|MEB}} &ndash; gives: {{gli|glossary=Glossary of education terms (M–O)|MEB}}
*Use an alternative term, linking to the related term on a different page of the same multi-page glossary: {{tlx|gli|glossary{{=}}Glossary of education terms (M–O)|MEB|Master's in European Business}} &ndash; gives: {{gli|glossary=Glossary of education terms (M–O)|MEB|Master's in European Business}}
Normally this is done with the {{tlx|gli}} shortcut; {{tlx|glossary link internal|Example code}} and {{tlx|gli|Example code}} are equivalent. However, in an especially long page, if you run into the [[Help:Template limits|template transclusion limit]], you can use a plain-wikicode link to the entry, e.g. <code><nowiki>[[#utricle|utricle]]</nowiki></code>.

Because {{tlx|gli}} is short, simple, and requires no {{para|glossary{{=}}{{var|PageName}}}} parameter, there is no need or use for a wrapper template for a specific glossary (e.g., do not create a {{tlx|cueglossi}} to go along with {{tlx|cuegloss}}).

===Syntax (geeky version)===
:{{tlx|glossary link|glossary{{=}}<var>glossary article</var>|term{{=}}<var>term in glossary</var>}}&nbsp; results in:&nbsp; {{glossary link|glossary=glossary article|term=term in glossary}}
:{{tlx|glossary link|glossary{{=}}<var>glossary article</var>|<var>term in glossary</var>}}&nbsp; results in:&nbsp; {{glossary link|glossary=glossary article|term in glossary}}
:{{tlx|glossary link|glossary{{=}}<var>glossary article</var>|term{{=}}<var>term in glossary</var>|text{{=}}<var>text in article</var>}}&nbsp; results in:&nbsp; {{glossary link|glossary=glossary article|term=term in glossary|text=text in article}}
:{{tlx|glossary link|glossary{{=}}<var>glossary article</var>|<var>term in glossary</var>|<var>text in article</var>}}&nbsp; results in:&nbsp; {{glossary link|glossary=glossary article|term in glossary|text in article}}
:{{tlx|glossary link|<var>term in glossary</var>}}&nbsp; results in:&nbsp; {{glossary link|term in glossary}}
:{{tlx|glossary link|<var>term in glossary</var>|<var>text in article</var>}}&nbsp; results in:&nbsp; {{glossary link|term in glossary|text in article}}
The {{tnull|glossary link internal}} variant works exactly the same, but is used inside the glossary itself to provide cross-references between entries, and is also used when the same term is linked twice in other articles (e.g. because the article is very long). Its only difference from {{tnull|glossary link}} is that it does not use {{tag|dfn|o}}, since it is only supposed to be used once per page per term, and it does not blue-link the link, since we don't want to create a "[[MOS:SEAOFBLUE|sea of blue]]" link mess.
:{{tlx|glossary link internal|<var>term in glossary</var>}}&nbsp; results in:&nbsp; {{glossary link internal|term in glossary}}
:{{tlx|glossary link internal|<var>term in glossary</var>|<var>text in article</var>}}&nbsp; results in:&nbsp; {{glossary link internal|term in glossary|text in article}}

===Parameters<span class="anchor" id="parameters"><!--anchor for template demo--></span>===
Each version of the template takes up to three parameters for its data:

* {{para|glossary|{{var|the title of the glossary article to be linked to}}}}
** This is part of the URL to be generated; it {{strong|cannot contain any link brackets, styling, templates, HTML, or other markup.}}
** It is case-sensitive in that it has to resolve to the actual article page in the same way as a <code><nowiki>[[...]]</nowiki></code> wikilink.
* {{para|term|{{var|the term entry in the glossary to be linked <strong>to</strong>}}}} &nbsp;(or any {{tlx|anchor}} for it)
** This is part of the URL to be generated; it {{strong|cannot contain any <code>#</code> anchor indicator, styling, templates, HTML, or other markup.}}
** {{strong|A double quote (") character {{em|must}} be escaped as <code>&amp;quot;</code> or the tooltip will break.}} Glossary-specific templates based on this meta-template need to mention this prominently in their documentation.
** This parameter can also be done as {{para|1}} or the first unnamed parameter. It {{strong|must not}} be unnamed when creating a glossary-specific wrapper template from the meta-template, because you cannot guarantee that input will not contain a {{kbd|1==}} character.
** It is not case-sensitive and will be reduced to lower-case (that behavior can be turned off with {{para|lc|{{kbd|no}}}} below, e.g. for proper names that do not have any reason to have a lowercase anchor).
* {{para|text|{{var|the actual text in the article to be linked <strong>from</strong>}}, {{var|if different from the term linked {{em|to}}}}}}.
** This parameter can be styled, templated, etc. (though cannot contains links – it's going to become the link). Styling can also be applied before and after the entire template, of course.
** This is case-sensitive, in that it's going to display whatever you put into it.
<strong>Limitations</strong>: The {{var|glossary}} and {{var|term}} parameters cannot have any HTML or wiki markup; they are basically parts of URLs (namely <code><nowiki>https://</nowiki>en.wikipedia.org/wiki/{{var|glossary}}#{{var|term}}</code>).

A {{para|color}} parameter allows the color of the text to be changed. This should {{em|only}} be done when the rest of the text is also another color for some reason, e.g. because of white text in a dark-background table cell in a [[WP:NAVBOX|navbox]] or [[WP:INFOBOX|infobox]]. The parameter will accept established HTML/CSS color names (e.g. <code>white</code>) and hex values (e.g. <code>#FFFFFF</code>), and is spelled "<code>color</code>" since this is the spelling used by HTML and CSS.

Some little-used parameters that are there just in case:

*{{para|lc|{{kbd|no}}}} (or any other value like {{kbd|n}}, {{kbd|false}}, {{kbd|0}}) – a switch to turn off the automatic lower-casing of the <code>#target</code> anchor derived from the {{para|1}} or {{para|term}} entry, if that target content has no all-lowercase anchor defined at it (by {{tlx|term}} automatically or by a manually added {{tlx|anchor}}) and creating one is not desirable (e.g. because it would be something unituitive and otherwise useless like "jane w. smith" for a biographical entry)
*{{para|id|{{var|an_ID}}}} – an anchor ID (no spaces, must begin with alphabetic letter) for #linking and possibly other purposes
*{{para|style|{{var|arbitrary:css;}}}} – CSS directives for custom-styling the instance
*{{para|class|{{var|css_class}}}} – a CSS class or classes (separated by spaces not commas if more than one); by default it already includes <code>glossary-link</code> or <code>glossary-link-internal</code> (in the template with the respectively matching name) for custom [[Help:User CSS|user CSS]].

===Glossary entry formatting===

===Example code===
The template {{tlx|cuegloss}} for [[cue sports]]:
<syntaxhighlight lang="wikitext">
{{glossary link
|glossary=Glossary of cue sports terms
|term={{{1}}}
|text={{{2|}}}
|lc={{{lc|}}}
}}
</syntaxhighlight>

The {{tlx|glossary link internal}} variant is used (as {{tlx|gli}}) {{em|inside}} such an article as [[Glossary of cue sports terms]]:
<syntaxhighlight lang="wikitext">
{{gli |{{{1}}} |{{{2|}}} }}
</syntaxhighlight>

<code><nowiki>{{{1}}}</nowiki></code> is the glossary entry's link anchor. The optional <code><nowiki>{{{2|}}}</nowiki></code> is the displayed text of the link. Examples: {{tlx|gli|obstetrics and gynaecology}} or {{tlx|gli|obstetrics and gynaecology|obstetrics and gyn[a]ecology (OB-GYN)}}

Fuller syntax of {{tlx|gli}} is:
<syntaxhighlight lang="wikitext">
{{gli|glossary=Glossary of cue sports terms|term={{{1}}}|text={{{2|}}}}}
</syntaxhighlight>
Here, it is specifying a glossary page, which is needed if a large glossary has been split across multiple pages; and uses named parameters, which would be necessary if the input into them contained an {{kbd|{{=}}}} character.

For real-use application, see [[Template:Cuegloss/doc]], the [[Glossary of cue sports terms]] article, and articles like [[Nine-ball]] that use the template to link to terms in the glossary.

==See also==
*{{tlx|glossary}}, {{tlx|glossary end}}, {{tlx|term}}, and {{tlx|defn}}, the glossary structure templates
*{{tlx|dfn}} the more general <code>&lt;dfn&gt;</code> template
*{{tlx|glossary term}}, for adding a flush-right box containing a link to a term in the [[Wikipedia:Glossary]]
*[[Wikipedia:Manual of Style/Glossaries]]

==Notes==
{{notelist}}

<includeonly>{{Sandbox other|
| <!----Categories below this line, please:---->
[[Category:Glossary templates]]
[[Category:Glossary link templates| ]]
}}</includeonly>