% metaphor-doc.tex
\documentclass{article}
\usepackage[index]{metaphor}
\usepackage{hyperref}
\hypersetup{
    linkcolor=blue,
    urlcolor=blue,
    colorlinks=true
}
\usepackage[margin=1in]{geometry}
\usepackage{listings}
\lstset{
    language=[LaTeX]TeX,
    basicstyle=\ttfamily\small,
    % numbers=left,
    % numberstyle=\tiny,
    % stepnumber=1, 
    % numbersep=5pt,
    breaklines=true
}

\title{The \texttt{metaphor} Package}
\author{Andrew W. Lounsbury, \texttt{alounsbury8@gmail.com}}
\date{v1.0, 2026/03/25}

\begin{document}
\maketitle
\tableofcontents
\bigskip

\section{Introduction}
This package is licensed with \href{https://ctan.org/license/lppl1.3c}{LPPL 1.3c}, and provides commands that typeset conceptual metaphors and their mappings. 

\section{Dependencies}
This package requires \href{https://ctan.org/pkg/imakeidx}{imakeidx}, \href{https://ctan.org/pkg/kvoptions}{kvoptions}, and \href{https://ctan.org/pkg/tabularx}{tabularx}. 

\section{Package Options}
\begin{description}
  \item[\texttt{index}] Defines an index named \texttt{metaphors} of all metaphors and metonyms in the document made using the commands in \S\ref{subsec:metaphor} and \S\ref{subsec:metonym}. 
  \begin{lstlisting}
    \makeindex[name=metaphors,title=Index of Metaphors and Metonyms]
  \end{lstlisting}
  Print the index with
  \begin{lstlisting}
    \printindex[metaphors]
  \end{lstlisting}
  and add the index to the table of contents with
  \begin{lstlisting}
    \addcontentsline{toc}{<secunit>}{Index of Metaphors and Metonyms}
  \end{lstlisting}
  \item[\texttt{indextitle=<title>}] Sets the title of the Metaphor/Metonymy index. Default: \texttt{Index of Metaphors and Metonyms}. Note that curly braces \{\dots\} are required for index titles with spaces. 
  \item[\texttt{borders}] Enables table borders.
  
  Default:

  \metaphor{love is a journey}\footnote{\cite[p.~9]{kovecses2010}}
  \begin{metaphormapping}{journey}{love}
    \map{the travelers}{the lovers}
    \map{the vehicle}{the love relationship itself}
    \map{the distance covered}{the progress made}
    \map{the obstacles encountered}{the difficulties experienced}
    \map{decisions about which way to go}{choices about what to do}
    \map{the destination of the journey}{the goal(s) of the relationship}
  \end{metaphormapping}
  with borders:

  \makeatletter
  \metaphor@borderstrue
  \makeatother
  \metaphor{love is a journey}
  \begin{metaphormapping}{journey}{love}
    \map{the travelers}{the lovers}
    \map{the vehicle}{the love relationship itself}
    \map{the distance covered}{the progress made}
    \map{the obstacles encountered}{the difficulties experienced}
    \map{decisions about which way to go}{choices about what to do}
    \map{the destination of the journey}{the goal(s) of the relationship}
  \end{metaphormapping}

  \item[\texttt{thickness=<length>}] Sets border thickness. Default: \texttt{0.4pt}

  Example: \texttt{thickness=1.5pt}
  \makeatletter
  {
  \renewcommand*\metaphor@thickness{1.5pt}
  
  \metaphor{love is a journey}
  \begin{metaphormapping}{journey}{love}
    \map{the travelers}{the lovers}
    \map{the vehicle}{the love relationship itself}
    \map{the distance covered}{the progress made}
    \map{the obstacles encountered}{the difficulties experienced}
    \map{decisions about which way to go}{choices about what to do}
    \map{the destination of the journey}{the goal(s) of the relationship}
  \end{metaphormapping}
  }
  \makeatletter
  \metaphor@bordersfalse
  \makeatother

  \item[\texttt{rowheight=<factor>}] Controls vertical spacing between rows. 
  
  Default: \texttt{1.0}

  \metaphor{ideas are food}\footnote{\cite[p.~83]{kovecses2010}}
  \begin{metaphormapping}{ideas}{food}
    \map{cooking}{thinking}
    \map{swallowing}{accepting}
    \map{chewing}{considering}
    \map{digesting}{understanding}
    \map{nourishment}{mental well-being}
  \end{metaphormapping}
  \newpage
  Example: \texttt{rowheight=2.0}

  \makeatletter
  {
  \metaphor{ideas are food}
  \renewcommand*\metaphor@rowheight{2.0}
  \begin{metaphormapping}{ideas}{food}
    \map{cooking}{thinking}
    \map{swallowing}{accepting}
    \map{chewing}{considering}
    \map{digesting}{understanding}
    \map{nourishment}{mental well-being}
  \end{metaphormapping}
  }
  \makeatother
  \item[\texttt{small} and \texttt{footnotesize}] Respectively apply the \texttt{\textbackslash{}small} and \texttt{\textbackslash{}footnotesize} font sizes. 
  
  Default:

  \metaphor{social organizations are plants}\footnote{\cite[p.~10]{kovecses2010}}
  \begin{metaphormapping}{plant}{social organization}
    \map{the whole plant}{the entire organization}
    \map{a part of the plant}{a part of the organization}
    \map{growth of the plant}{development of the organization}
    \map{removing a part of the plant}{reducing the organization}
    \map{the root of the plant}{the origin of the organization}
    \map{the flowering}{the best stage, the most successful stage}
    \map{the fruits or crops}{the beneficial consequences}
  \end{metaphormapping}
  \texttt{small}: 

  \makeatletter
  \metaphor@smalltrue
  \metaphor{social organizations are plants}
  \begin{metaphormapping}{plant}{social organization}
    \map{the whole plant}{the entire organization}
    \map{a part of the plant}{a part of the organization}
    \map{growth of the plant}{development of the organization}
    \map{removing a part of the plant}{reducing the organization}
    \map{the root of the plant}{the origin of the organization}
    \map{the flowering}{the best stage, the most successful stage}
    \map{the fruits or crops}{the beneficial consequences}
  \end{metaphormapping}
  \metaphor@smallfalse
  \makeatother
  \texttt{footnotesize}: 

  \makeatletter
  \metaphor@footnotesizetrue
  \metaphor{social organizations are plants}
  \begin{metaphormapping}{plant}{social organization}
    \map{the whole plant}{the entire organization}
    \map{a part of the plant}{a part of the organization}
    \map{growth of the plant}{development of the organization}
    \map{removing a part of the plant}{reducing the organization}
    \map{the root of the plant}{the origin of the organization}
    \map{the flowering}{the best stage, the most successful stage}
    \map{the fruits or crops}{the beneficial consequences}
  \end{metaphormapping}
  \metaphor@footnotesizefalse
  \makeatother

  \item[\texttt{xcols}] Converts the table from a \texttt{tabular} environment to a \texttt{tabularx} environment with columns of type \texttt{X} and with a table width of $\langle$\textit{table-width}$\rangle \cdot$\texttt{\textbackslash{}textwidth}: 
  
  Default:

  \metaphor{a target is a source}
  \begin{metaphormapping}[0.5]{source}{target}
      \map{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}
  \end{metaphormapping}
    \begin{lstlisting}
\documentclass{article}
\usepackage[xcols]{metaphor}

\begin{document}
    \metaphor{a target is a source}
    \begin{metaphormapping}[<table-width>]{source}{target}
        \map{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}
    \end{metaphormapping}
\end{document}
\end{lstlisting}
Example: \texttt{table-width=0.5}

\metaphor{a target is a source}
\makeatletter
\metaphor@xcolstrue
\begin{metaphormapping}[0.5]{source}{target}
    \map{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}{Lorem ipsum dolor sit amet, consectetur adipiscing elit.}
\end{metaphormapping}
\metaphor@xcolsfalse
\makeatother
\end{description}

\section{Commands and Environments}
\subsection{The \texttt{metaphor} command} \label{subsec:metaphor}
\begin{lstlisting}
\NewDocumentCommand{\metaphor}{m}{%
    \ifmetaphor@index
        \index[metaphors]{\textsc{#1}}%
        \textsc{#1}
    \else
        \textsc{#1}
    \fi
}
\end{lstlisting}
Example: \metaphor{time is money}

\subsection{The \texttt{metonym} command} \label{subsec:metonym}
\begin{lstlisting}
\NewDocumentCommand{\metonym}{m}{%
    \ifmetaphor@index
        \index[metaphors]{\textsc{#1}}%
        \textsc{#1}
    \else
        \textsc{#1}
    \fi
}
\end{lstlisting}
Example: \metonym{a part for the whole}

\subsection{The \texttt{metaphormapping} environment and the \texttt{map} command}
\begin{lstlisting}
\documentclass{article}
\usepackage{metaphor}

\begin{document}
    \metaphor{a target is a source}
    \begin{metaphormapping}{source}{target}
        \map{hello world}{lorem ipsum dolor sit amet}
    \end{metaphormapping}
\end{document}
\end{lstlisting}
\metaphor{a target is a source}
\begin{metaphormapping}{source}{target}
    \map{hello world}{lorem ipsum dolor sit amet}
\end{metaphormapping}

\begin{lstlisting}
\documentclass{article}
\usepackage{metaphor}

\begin{document}
    \metaphor{anger is a hot fluid in a container}
    \begin{metaphormapping}
        {hot fluid in a container}{anger}
        \map{the physical container}{the angry person's body}
        \map{the top of the container}{the rational self of the angry person}
        \map{the hot fluid inside the container}{the anger}
        \map{the degree of fluid heat}{the intensity of anger}
        \map{the cause of increase in fluid heat}{the cause of anger}
    \end{metaphormapping}
\end{document}
\end{lstlisting}
\metaphor{anger is a hot fluid in a container}\footnote{\cite[p.~123]{kovecses2010}}
\begin{metaphormapping}{hot fluid in a container}{anger}
    \map{the physical container}{the angry person's body}
    \map{the top of the container}{the rational self of the angry person}
    \map{the hot fluid inside the container}{the anger}
    \map{the degree of fluid heat}{the intensity of anger}
    \map{the cause of increase in fluid heat}{the cause of anger}
\end{metaphormapping}

\printindex[metaphors]
\addcontentsline{toc}{section}{Index of Metaphors and Metonyms}

\begin{thebibliography}{9}
\bibitem{kovecses2010}
Zolt\'an K\"ovecses,
\textit{Metaphor: A Practical Introduction},
Oxford University Press, 2010.
\end{thebibliography}
\end{document}