Table of Contents

Definitions and Glossary

Coursage build a glossary for the site from <‌def>def tags<‌/def> in documents, if any are present.

Coursage build a glossary for the site from def tags in documents, if any are present.

A <‌def> highlights a location where the surrounding text introduces, explains, defines, or refines an important term. Multiple def tags can mark the same term in multiple places / multiple documents — and that is fine as long as all of those occurrences do truly help provide the meaning of the term.

Note that this the def tag is not a way to emphasize an important term where it is used but not defined; use **bold** or <‌highlight> for that. The def tag is strictly for explanations, not mentions.

  • The penguin is a flightless aquatic bird. ← ✅ Is a definition
  • We encountered this before when learned about the penguin. ← ❌ Not a definition
  • We encountered this before when learned about the penguin. ← ✅ Not a definition

Remember: the purpose of the def tag is to build the glossary, and clicks on glossary entries will take the reader to def tag occurrences. Use them only when text answers the question, “What is that?”

<‌definition-callout>
  If you want to highlight an important definition, you can use a <‌def>definition callout<‌/def>. Note that the important term is still marked with a def tag.
<‌/definition-callout>

If you want to highlight an important definition, you can use a definition callout. Note that the important term is still marked with a def tag.

Def tags support several options for handling the mismatch between how a term appears in the source text and how it should appear in the glossary index:

This markdown…

…produces this glossary entry

Java has <‌def term="variable">variables<‌/def>.

Java has variables.

  • variable

Purpose: Because of pluralization / conjugation / etc., the term should have a different appearance in the glossary than it does in the text.

<‌def lowercase>Refactoring<‌/def> means…

Refactoring means…

  • refactoring

Purpose: The term is capitalized in the text, but should be lowercase in the glossary. The example above is a shortcut for <‌def term="refactoring">​Refactoring​</span>.

Java calls this a <‌def entry="closure">lambda<‌/def>.

Java calls this a lambda.

  • closure
  • lambda

Purpose: This is an alternative for some other term, and should appear together with it in the glossary rather than having its own separate entry.

The <‌def term="map (stream operation)">map<‌/def> method on a stream…

The map method on a stream…

  • map (stream operation)

Purpose: Distinct concepts use the same word, but should have separate glossary entries.