% !TEX TS-program = LuaLaTeX-shell-escape
\documentclass[
	a4paper,
]{article}

\usepackage{genealogy-profiles.preamble}

\title{Genealogical Profiles for \LaTeX}
\author{Mikkel Eide Eriksen\\%
\href{mailto:mikkel.eriksen@gmail.com}{\texttt{mikkel.eriksen@gmail.com}}}

\begin{document}

\maketitle

\section*{Preface} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This package enables the presenstation of individual \emph{profiles}, which may be useful for genealogical or local history treatises.

Each profile is typeset using key/value-configurable environments, and a number of macros are provided to enable formatting, references, and floruit (lifespan) calculations.

In order to provide an ergonomic interface for document authors, extra care has been taken to enable automatic and configurable parsing of names.

Issues can be reported at\\\null\hfill\url{https://github.com/mikkelee/latex-genprofile/issues}

%\begin{multicols}{2}
%\begingroup
%\hypersetup{pdfborder=0 0 0}
%\makeatletter
%\renewcommand{\tableofcontents}{\@starttoc{toc}} % no "Contents" heading
%\makeatother
%\tableofcontents
%\endgroup
%\end{multicols}

\begin{figure}
\begingroup
\gprKeys{
	name type = given and surname,
	surname style = \scshape,
	layout preset = tcolorbox,
	begin life events = \small,
}
\begin{gprProfile}{Wolfgang_Amadeus Mozart}[
	birth = {1756-01-27}{Getreidegasse 9, Salzburg},
	death = {1791-12-05}{Vienna}
]
	Had a complex relationship with his rival \gprRef{Antonio Salieri}.
\end{gprProfile}
\begin{gprProfile}{Antonio Salieri}[
	birth = {1750-08-18}{Legnago, Republic of Venice},
	death = {1825-05-07}{Vienna}
]
	Was falsely accused of poisoning \gprRef[WM1]{_ Mozart}.
\end{gprProfile}
\endgroup
\end{figure}

\clearpage
\section{Configuration} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The package is configured in the following manner:

\begin{docCommand}
	{usepackage}
	{\brackets{genealogy-profiles}}

	Loads the package and sets some sensible defaults as further described in \cref{sec:genconf,sec:profopts}.

\end{docCommand}

\begin{docCommand}
	{gprKeys}
	{\marg{general options}}

	Can be used to set options globally (in the preamble) or locally (in a group). See \cref{sec:genconf} for possible keys/values.

\end{docCommand}

\section{Usage} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Environments} %---------------------------------------------------------------


\begin{docEnvironment}
	{gprProfile}
	{\oarg{profile options}\marg{full name}\oarg{life events}}

	Typesets its contents according to the configured layout (see \cref{sec:structure}). For possible profile options, see \cref{sec:profopts}.

	The \meta{full name} will be parsed according to the current \refKey{name part order} (see \cref{sec:nameparsing} for discussion) and styled according to \refKey{nameparts:style} etc.

	Each profile must have an \meta{id}, either supplied by the author via the \refKey{id} profile option key or automatically generated via the general \refKey{auto id} key (the latter being the default).

	The \refKey{life events} will be parsed as a database by the \refPkg{genealogytree} package.
	
\end{docEnvironment}

\begin{docEnvironment}
	{gprProfile*}
	{\marg{profile options}\oarg{life events}}

	The \refEnv*{gprProfile*} environment provides more control at the expense of convenience, by requiring the name part(s) be set explicitly as profile options. See \refKey{given name} etc.
	
\end{docEnvironment}

\clearpage
\subsection{Commands} %-------------------------------------------------------------------

\begin{docCommands}[
		doc name = {gprName}
	]
	{
		{ doc parameter = {\marg{name}}},
		{ doc parameter = {\sarg\marg{name}}},
	}

	Typesets a name, styled according to configured name styles (see \refKey{nameparts:style}), without attempting to link to a profile.

	The regular version adds the name to any configured indices, the starred version does not.
	
\end{docCommands}


\begin{docCommands}[
		doc name = {gprRef}
	]
	{
		{ doc parameter = {\oarg{id}\marg{name}}},
		{ doc parameter = {\sarg\oarg{id}\marg{name}}},
	}

	Typesets a reference to a profile according to \refKey{reference style}.

	The \meta{id} is optional, in case it is not known or available at the time of writing. However, if the name is unique to the document, the reference should automatically be recognized.

	If it is not possible for the package to identify the intended reference, either via \meta{id} or unique name, warnings will be emitted in the log as well as in the document (the latter can be configured via \refKey{unknown reference style}).

	When using an \meta{id}, the name parameter can be left empty, or alternatively be used to override the by-default displayed full name, eg. to change case to genitive, etc.

	The regular version adds the reference to configured indices, the starred version does not.

	When used inside a profile, the package will emit a warning if the referenced profile does not refer back to the originating profile, in order to allow the author to check referential integrity (if they so wish).

	These commands require two runs to account for forward references.
\end{docCommands}


\begin{docCommands}[
		doc name = {gprLifeEvents}
	]
	{
		{ doc parameter = {\marg{id}}},
		{ doc parameter = {\sarg\marg{od}}},
	}

	Typesets the stored \refKey{life events} for a given \meta{id}.

	Requires \refKey{life events storage} to be either \docValue{memory} or \docValue{file}.
\end{docCommands}

\begin{docCommand}
	{gprTreeContentInterpreter}
	{}

	This command is used with the \docAuxKey{content interpreter} key of \refPkg{genealogytree}.

	When used, it handles tree node content in the follow way:

	\begin{itemize}
		\item If the node content is wrapped in \marg{brackets}, it is interpreted as a profile \meta{id}, and the name and life events are passed to \refPkg{genealogytree} to typeset.

		\item If the node content is not wrapped, it is interpreted as a regular \refPkg{genealogytree} database, and will be typeset per its settings.
	\end{itemize}

	See example in \cref{sec:example:inter}.
\end{docCommand}

\subsection{Layout} %---------------------------------------------------------------------

\label{sec:structure}
The typeset profiles are laid out according to the following structure. See also \refKey{layout preset}.

\begin{enumerate}

\item The contents of \refKey{begin profile}

\item If \refKey{auto header} is \docValue*{true}:
	\begin{enumerate}[noitemsep]
	\item The contents of \refKey{begin header}
	\item The contents of \refKey{header format}
	\item The contents of \refKey{end header}
	\end{enumerate}

\item If \refKey{include life events} is \docValue{before content}, and \refKey{life events} and/or \refCom{gprYear}(s) were used:
	\begin{enumerate}[noitemsep]
	\item The contents of \refKey{begin life events}.
	\item The events formatted according to the database format configured via the \refPkg{genealogytree} package.
	\item The contents of \refKey{end life events}
	\end{enumerate}

\item The contents of \refKey{begin content}
\item The content provided to the environment by the author.
\item The contents of \refKey{end content}

\item If \refKey{include life events} is \docValue{after content}, and \refKey{life events} and/or \refCom{gprYear}(s) were used:
	\begin{enumerate}[noitemsep]
	\item The contents of \refKey{begin life events}.
	\item The events formatted according to the database format configured via the \refPkg{genealogytree} package.
	\item The contents of \refKey{end life events}
	\end{enumerate}

\item The contents of \refKey{end profile}

\end{enumerate}


\section{Names} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\label{sec:nameparsing}
Names are parsed according to the configured \refKey{name part order} (some presets are provided via \refKey{name type}), in a left-to-right evaluation.

In order for single name parts to include multiple separate tokens (eg. multiple given names), underscores can be used to combine them. For example, \docValue*{Wolfgang\_Amadeus Mozart} will, with the default \docValue{given and surname} name type, be parsed as the given name(s) \docValue*{Wolfgang Amadeus} and the surname \docValue*{Mozart}.

If the \refKey{name part order} has more parts than the supplied value, the right-most parts will be empty. If this is not desired, one may mark empty name parts with a single underscore; for example, using the \docValue{nordic historical} name type, \docValue*{Jens _ Smed} will parse as the given name \docValue*{Jens}, no patronymic, and the byname \docValue*{Smed} (ie. blacksmith).

Inside a profile environment, a number of shortcuts are provided to access the available name parts, as well as the \meta{id} and a full name styled according to the individual name part style keys (see \cref{sec:promac}).

\clearpage
\subsection{Creating and Using Name Parts} %----------------------------------------------

\begin{docCommand}
	{gprCreateNamePart}
	{\marg{name part}\oarg{macro name}}

	If the supplied default name part types are not sufficient, new types can be created. They must be included in the \refKey{name part order} to be properly recognized during name parsing and indexing.

	Creating a \meta{name part} results in:
	\begin{itemize}
	\item \refKey{nameparts:key} key in profile options for manually setting the name part in profiles.
	\item \refKey{nameparts:style} key in general options for styling the name part.
	\item \refKey{nameparts:index} key in general options for which index to use for the name part.
	\item \refCom{nameparts:macro} macro for typesetting the styled name part within a profile.
	\item \refCom{nameparts:macrostar} macro for typesetting the unstyled name part within a profile.
	\item \refCom{nameparts:macrostyle} macro for typesetting arbitrary text in the configured name part style.
	\end{itemize}

	By default, the generated commands will be CamelCased (eg. \docAuxKey*{given name} results in \docAuxCommand*{gprGivenName...}), but this can be overridden by supplying your own base name as the optional argument.

	The name parts \docAuxKey*{given name}, \docAuxKey*{patronymic}, \docAuxKey*{surname}, and \docAuxKey*{byname} have been pregenerated, along with their associated style/index keys and commands (see \cref{sec:promac,key:given name}).

\end{docCommand}


\section{Profile Macros} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{sec:promac}

A number of extra macros are available inside profiles to allow accessing some key values, as well as gather years for floruit calculations.

\begin{docCommand}
	{gprHeader}
	{\brackets{}}

	A header styled according to \refKey{header format}.

	If \refKey{auto header} is \docValue*{false}, one may wish to use \refCom{gprHeader} to manually insert the header at the desired location (see \cref{sec:structure} for layout structure and \cref{sec:examples} for an example).

\end{docCommand}


\begin{docCommands}[
		doc parameter = {\brackets{}}
	]
	{
		{ doc name = gprID },
		{ doc name = gprID* },
		{ doc name = gprFullName },
		{ doc name = gprFullName* }
	}

	Typesets the \meta{id} and full name according to configured styles (see \refKey{id style} and \refKey{nameparts:style}). The starred versions of the commands are unstyled.

\end{docCommands}


\begin{docCommands}[
		doc parameter = {\brackets{}}
	]
	{
		{ doc name = gprGivenName },
		{ doc name = gprGivenName* },
		{ doc name = gprPatronymic },
		{ doc name = gprPatronymic* },
		{ doc name = gprSurname },
		{ doc name = gprSurname* },
		{ doc name = gprByname },
		{ doc name = gprByname* },
		{
			doc name = gpr\meta{NamePart},
			doc label = nameparts:macro,
		} ,
		{
			doc name = gpr\meta{NamePart}*,
			doc label = nameparts:macrostar,
		}
	}

	Typesets individual name parts according to configured styles (see \refKey{nameparts:style}). The starred versions of the commands are unstyled.

	More can be created using \refCom{gprCreateNamePart}.
\end{docCommands}


\begin{docCommands}[
		doc parameter = {\marg{text}}
	]
	{
		{ doc name = gprIDStyle },
		{ doc name = gprGivenNameStyle },
		{ doc name = gprPatronymicStyle },
		{ doc name = gprSurnameStyle },
		{ doc name = gprBynameStyle },
		{
			doc name = gpr\meta{NamePart}Style,
			doc label = nameparts:macrostyle,
		},
	}

	Styles given text according to the configured name style (see \refKey{nameparts:style}).

	More can be created using \refCom{gprCreateNamePart}.
\end{docCommands}


\begin{docCommands}[
		doc name = {gprYear}
	]
	{
		{ doc parameter = {\marg{year}}},
		{ doc parameter = {\sarg\marg{year}}},
	}

	All tagged years in a profile will be gathered and inserted as a \docValue*{floruit} range under \refKey{life events}, which will by default only be displayed if there is no defined lifespan (ie. birth or baptism \emph{and} death or burial).
	
	The starred version does not typeset anything, and can thus be used to add \enquote{hidden} years to the floruit event.

	These commands require two runs.
\end{docCommands}


\begin{docCommands}[
		doc name = {gprYears}
	]
	{
		{ doc parameter = {\marg{year range}}},
		{ doc parameter = {\sarg\marg{year range}}},
	}

	Adds two years to the \docValue*{floruit} event, by splitting at one or more hyphens.

	Values such as \docValue*{1750--1755} or \docValue*{1750--55} will both be parsed as the two years \docValue*{1750} and \docValue*{1755} and typeset as the expected 1750--1755 or 1750--55, respectively.

	Like \refCom{gprYear}, the starred version produces no output, and two runs are required.
\end{docCommands}

\section{Option Keys} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{General Options} %------------------------------------------------------------

\label{sec:genconf}
These are used with the \refCom{gprKeys} command, either globally in the preamble or locally in a group.

\begin{docKey}
	{auto header}
	{=\meta{true/false}}
	{initially \docValue*{false}}

	Automatically inserts a header using \refKey{header format} at the beginning of profiles. See \cref{sec:structure}.
\end{docKey}

\begin{docKey}
	{auto id}
	{=\meta{true/false}}
	{initially \docValue*{true}}

	Automatically generates an \meta{id} for each profile if no \refKey{id} is supplied. They are built from the initials of each the name part (empty parts replaced by a dash) combined with a number to ensure uniqueness.

	If a profile has no \meta{id} set, whether automatically or manually, an error is emitted.
\end{docKey}

\begin{docKey}
	{auto id prefix}
	{=\meta{...}}
	{initially not set}

	Prefixes auto-generated \meta{id}s with a string, which may be useful for works containing multiple logically or temporally separate chapters or sections.
\end{docKey}

\begin{docKeys}
	[
		doc parameter = {=\meta{...}},
		doc description = {initially not set},
	]
	{
		{
			doc name = begin profile,
		},
		{
			doc name = begin header,
		},
		{
			doc name = end header,
		},
		{
			doc name = begin life events,
		},
		{
			doc name = end life events,
		},
		{
			doc name = begin content,
		},
		{
			doc name = end content,
		},
		{
			doc name = end profile,
		},
	}

	These keys allow configuring arbitrary \LaTeX{} code to be inserted before/during/after the typeset \refEnv{gprProfile} and \refEnv{gprProfile*} environments (see \cref{sec:structure} for layout structure).

\end{docKeys}

\begin{docKey}
	{clear name styles}
	{=\meta{true/false}}
	{initially not set}

	Clears all \refKey{nameparts:style} keys in the current \refKey{name part order}.
\end{docKey}

\begin{docKey}
	{header format}
	{=\meta{...}}
	{initially \brackets{\docValue*{\cs{gprFullName}\brackets{}\cs{hfill}\cs{gprID}\brackets{}}}}

	Formats a profile header, which will be available as \refCom{gprHeader}, and is automatically inserted if \refKey{auto header} is \docValue*{true}. See \cref{sec:promac} for available macros.
\end{docKey}

\begin{docKeys}
	[
		doc parameter = {=\meta{...}},
		doc description = {initially not set},
	]
	{
		{
			doc name = id index,
		},
		{
			doc name = full name index,
		},
		{
			doc name = given name index,
		},
		{
			doc name = patronymic index,
		},
		{
			doc name = surname index,
		},
		{
			doc name = byname index,
		},
		{
			doc name = \meta{name part} index,
			doc label = nameparts:index,
		},
	}

	Setting these keys will cause usage of \refEnv{gprProfile}, \refCom{gprName}, and \refCom{gprRef} to emit index data to the named index unless disabled using \refKey{no index}. The index must be created with eg. \texttt{imakeidx} before usage.

	Multiple keys can point to the same index. For example, you can use the same index for patronymics, surnames, and/or bynames --- which has in fact been configured for this document (see final page).

	At the end of the document, \docAuxCommand*{printindex} can then be used for each configured index as normal.

	More can be created using \refCom{gprCreateNamePart}.
\end{docKeys}

\begin{docKeys}
	[
		doc parameter = {=\meta{...}},
		doc description = {initially not set},
	]
	{
		{
			doc name = id style,
		},
		{
			doc name = given name style,
		},
		{
			doc name = patronymic style,
		},
		{
			doc name = surname style,
		},
		{
			doc name = byname style,
		},
		{
			doc name = \meta{name part} style,
			doc label = nameparts:style,
		},
	}

	These keys set the styling for the \meta{id} and name parts, which will be used when typesetting the name parts with the \refCom{nameparts:macro} commands, and can also be applied to arbitrary strings using the \refCom{nameparts:macrostyle} commands.
	
	The styled name parts will together be available as the \refCom{gprFullName}.

	More can be created using \refCom{gprCreateNamePart}.
\end{docKeys}

\begin{docKey}
	{id in index entries}
	{=\meta{true/false}}
	{initially not set}

	Causes index entries to include the \meta{id} in parentheses, which is especially useful in documents with profiles for several identically named persons.
\end{docKey}

\begin{docKeys}
	[
		doc parameter = {=\meta{true/false}},
		doc description = {initially not set},
	]
	{
		{
			doc name = include unknown in index,
		},
		{
			doc name = include ambiguous in index,
		},
	}

	Causes the indexes to include mentions (\refCom{gprRef} and \refCom{gprName}) of persons with unknown \meta{id}s or ambiguous names, which can be used for correcting drafts.

\end{docKeys}\begin{docKey}
	{include life events}
	{=\meta{...}}
	{initially \docValue{before content}}

	\begin{itemize}
		\item \docValue{false}: Life events will not be automatically included in the typeset profiles.
		\item \docValue{before content}: Life events will be typeset before the main content of the profile (the default).
		\item \docValue{after content}: Life events will be typeset after the main content of the profile.
	\end{itemize}

	See \cref{sec:structure}.
\end{docKey}

\begin{docKey}
	{layout preset}
	{=\meta{...}}
	{initially not set}

	Sets a preconfigured layout style. Currently, two options are available:

	\begin{itemize}
		\item \docValue{clear} will blank out all the layout keys (see \refKey{begin profile} etc).

		\item \docValue{tcolorbox} sets the following keys:

		\begin{tcblisting}{listing only}
			\gprKeys{
				auto header = false,
				begin profile = {\begin{tcolorbox}[title=\gprHeader]},
				end life events = {\tcblower},
				end profile = {\end{tcolorbox}}
			}
		\end{tcblisting}

		The box can be further configured via \docAuxCommand*{tcbset} as per the \refPkg{tcolorbox} documentation.

	\end{itemize}

	Suggestions for more presets are welcome.

\end{docKey}

\begin{docKey}
	{life events storage}
	{=\meta{...}}
	{initially \docValue{none}}

	Configures stored life events, enabling the use of \refCom{gprLifeEvents} and \refCom{gprTreeContentInterpreter}.

	\begin{itemize}
		\item \docValue{none}: Life events will not be stored (the default).

		\item \docValue{memory}: Life events will be stored in memory, meaning they can only be accessed after the profile has been typeset.

		\item \docValue{file}: Life events will be cached in the .aux file, enabling use anywhere in a document (requires two runs to ensure full sync).
	\end{itemize}
\end{docKey}

\begin{docKey}
	{main index entry style}
	{=\meta{...}}
	{initially not set}

	Adds formatting to the \enquote{main} index entry page numbers (ie. the ones pointing to the actual profile), leaving the ones that are merely referenced with \refCom{gprRef} untouched; for example \docValue*{textbf} will bold the main entry.
\end{docKey}

\begin{docKeys}
	[
		doc parameter = {=\meta{...}},
	]
	{
		{
			doc name = name part order,
			doc description = {initially \brackets{\docValue*{given name, surname}}}
		},
		{
			doc name = name type,
			doc description = {initially \docValue{given and surname}}
		},
	}

	The \refKey*{name part order} is used for splitting a \refKey{full name} to its constituent parts for the configured styling, indexing, and autogenerated \meta{id}s (see \cref{sec:nameparsing}).

	New name parts must be created with \refCom{gprCreateNamePart} before inclusion in the name part order.

	Using the \refKey*{name type} key provides access to a number of preconfigured \refKey*{name part order}s:

	\begin{itemize}
		\item \docValue{given and surname} will set the \refKey*{name part order} key to \brackets{\docValue*{given name, surname}} (the default).
		\item \docValue{nordic historical} will set the \refKey*{name part order} key to \brackets{\docValue*{given name, patronymic, byname}}, which was traditionally used in Scandinavia and the rest of the nordic countries.
	\end{itemize}

	If no preset \refKey*{name type} exists for the intended use case, the \refKey*{name part order} can be set directly (suggestions for other \refKey*{name type}s are welcome).
\end{docKeys}

\begin{docKey}
	{nest index entries}
	{=\meta{true/false}}
	{initially not set}

	Causes index entries to be nested under the various patronymics/surnames/bynames.
\end{docKey}

\begin{docKey}
	{page reference style}
	{=\meta{...}}
	{initially \docValue*{p.\cs{nobreakspace}\#1}}

	Formats page references. The value is expanded with the argument \docValue*{\#1} being the page number.
\end{docKey}

\begin{docKey}
	{reference style}
	{=\meta{...}}
	{see below}

	Formats references to known profiles. The value is expanded with the arguments \docValue*{\#1} being the name, \docValue*{\#2} being the \meta{id}, and \docValue*{\#3} being the formatted page reference as per \refKey{page reference style}.

	The default is to present these as the name followed by combined super- and subscripts (see page 1 for the default, also \cref{sec:examples} for another style).

	The result is wrapped in a \refPkg{hyperref} link to the referenced profile.
\end{docKey}

\begin{docKey}
	{unknown reference style}
	{=\meta{...}}
	{see below}

	Formats references to unknown profiles. The value is expanded with the arguments \docValue*{\#1} being the supplied name, and \docValue*{\#2} being a short description of the reason.

	The default is to present the name as red text with the reason (unknown/ambiguous) following in parentheses.

	Note that forward references will appear unknown on the first run.
\end{docKey}

\begin{docKey}
	{use styles in index}
	{=\meta{true/false}}
	{initially not set}

	Causes index entries to be styled according to the various \refKey{nameparts:style} keys.

	The index at the end of this file shows it in use.
\end{docKey}


\subsection{Profile Options} %------------------------------------------------------------

\label{sec:profopts}
These are used in the first argument of the \refEnv{gprProfile} and \refEnv{gprProfile*} environments.

\begin{docKey}
	{id}
	{=\meta{...}}
	{initially not set}

	Sets an \meta{id} for the profile. If none is specified and \refKey{auto id} is \docValue*{true}, one will be generated from name initials combined with a number to ensure uniqueness.

	Not specifying an \meta{id} while \refKey{auto id} is \docValue*{false} will cause an error.

	Likewise, if an already used \meta{id} is specified, an error will be emitted.
\end{docKey}

\begin{docKey}
	{full name}
	{=\marg{...}}
	{initially not set}

	Sets the full name of the person. If it is specified, the configured \refKey{name part order} will be used to determine the individual name parts.

	If it is not specified, one will be generated by combining the given name parts according to the configured \refKey{name part order}, using the below keys. See \cref{sec:nameparsing} for further details.
	
	This key is set by the mandatory argument of \refEnv{gprProfile}. In the starred version of the environment, either the \refKey{full name} or individual \refKey{nameparts:key} keys must be set.
\end{docKey}

\clearpage
\begin{docKeys}
	[
		doc parameter = {=\meta{...}},
		doc description = {initially not set},
	]
	{
		{
			doc name = given name,
		},
		{
			doc name = patronymic,
		},
		{
			doc name = surname,
		},
		{
			doc name = byname,
		},
		{
			doc name = \meta{name part},
			doc label = nameparts:key,
		},
	}

	Sets individual name parts, to be used with \refEnv{gprProfile*}, if one prefers not to use the auto-parsing of \refEnv{gprProfile}.

	More name parts can be created using \refCom{gprCreateNamePart}.
\end{docKeys}

\begin{docKey}
	{life events}
	{=\meta{...}}
	{initially not set}

	Populates a \refPkg{genealogytree} database, which will be typeset using \docAuxCommand{gtrPrintDatabase}, according to the settings of that package; refer to its documentation for configuration.

	The default provided by \texttt{genealogy-profiles} simply lists life events separated by commas, skipping \docValue*{floruit} if there is a defined lifespan (ie. birth or baptism \emph{and} death or burial). Note that marriage is not included in the default, but can be enabled by changing the \refPkg{genealogytree} \docAuxKey{database format} key.

	For convenience, this key can be set with the final optional argument of the \refEnv{gprProfile} and \refEnv{gprProfile*} environments.

	See also \refKey{life events storage}, \refCom{gprLifeEvents}, and \refCom{gprTreeContentInterpreter}.
\end{docKey}

\begin{docKey}
	{no index}
	{=\meta{true/false}}
	{initially not set}

	If set, no index entries will be emitted for this profile.
\end{docKey}

\clearpage
\section{Examples} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\label{sec:examples}

\subsection{Using \docValue*{tcolorbox} \& \docValue*{nordic historical}}

A simple example to show name parsing and use of \refCom{gprRef} and \refCom{gprYear}.
\begin{dispExample}
\gprKeys{
	name type = nordic historical,
	patronymic style = \itshape,
	byname style = \scshape,
	layout preset = tcolorbox,
}

\begin{gprProfile}{Jens Hansen}[ birth = {1790}{Denmark} ]
	Wife: \gprRef{Anne_Marie Olsdatter}.

	Let's also tag some years:
	\gprName{Jens} is mentioned in the censuses of 
	\gprYear{1801}, \gprYear{1834}, and \gprYear{1840}.
\end{gprProfile}

\begin{gprProfile}{Anne_Marie Olsdatter}[ birth = {1795}{Denmark} ]
	Husband: \gprRef{Jens Hansen}.
\end{gprProfile}

\begin{gprProfile}{Jens Hansen Smed}
	An unrelated person with a byname.

	Not to be confused with \gprName{Jens _ Smed} of Neighbouring Town.
\end{gprProfile}

\end{dispExample}

\clearpage
\subsection{Using Custom Layout \& \docValue*{given and surname}}

A simple example to show different layout and reference styles.

\begin{dispExample}
\newcommand\spacedrule{\vspace*{5pt}\hrule\vspace*{5pt}}
\gprKeys{
	name type = given and surname,
	surname style = \scshape,
	auto header,
	begin profile = \spacedrule,
	end life events = \spacedrule,
	end profile = {\spacedrule\vspace*{\baselineskip}},
	reference style = {#1\footnote{#2,~#3}}
}

\begin{gprProfile}{George Washington}[
	birth = {1732-02-22}{Popes Creek, Virginia Colony},
	death = {1799-12-14}{Mount Vernon, Virginia, U.S.}
]
	Attended the first \gprRef[WM1]{_ Mozart} performance
	in America in \gprYear{1784}.
\end{gprProfile}

This sentence demonstrates that references work even outside
profiles: \gprRef[GW1]{_ Washington} was the first president
of the United States.
\end{dispExample}

\clearpage
\subsection{Using \refCom{gprTreeContentInterpreter}}

A simple example to show the use of stored life events in a \refPkg{genealogytree}. This requires setting the \refKey{life events storage} key.
\label{sec:example:inter}

\begin{dispExample}
\gprKeys{
	name type = nordic historical,
}
\begin{tikzpicture}
\genealogytree[
	content interpreter=\gprTreeContentInterpreter,
	database format=full,
	node size=4cm,
	level size=1.25cm
]{
	child{
		g{{JH-1}}
		p{{AO-1}}
		child{
			g{ name = {Child 1}, birth- = {1820} }
			c{ name = {Grandchild}, birth- = {1845} }
		}
		c{ name = {Child 2}, birth- = {1825} }
	}
}
\end{tikzpicture}
\end{dispExample}

\clearpage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\small % because index format=off
\printindex

\clearpage
\gprKeys{name type=nordic historical}
\indexprologue{This index was created by setting the keys \docAuxKey*{patronymic index}, \docAuxKey*{surname index}, and \docAuxKey*{byname index} to identical values. Notice that \gprName{Jens Hansen Smed} is listed both under his patronymic \gprPatronymicStyle{Hansen} and his byname \gprBynameStyle{Smed}.}
\printindex[gpr-surnames]

\end{document}