summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/association-matrix/association-matrix.tex
blob: bea65f80ced51a0f15c8994402f7f1a94b5e57a1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
%% association-matrix.sty
%% Copyright 2020 Whisperity
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Whisperity.
%
% This work consists of the files association-matrix.sty
% and association-matrix.tex.
%
\documentclass{article}
\usepackage{association-matrix} % Own package! :3

\usepackage{etoolbox}
\usepackage{hyperref}
    \hypersetup{
        pdftitle={The 'association-matrix' Package},    % title
        pdfauthor={Whisperity},     % author
        pdfsubject={An easy and clear assocation matrix generator},   % subject of the document
        pdfnewwindow=true,      % links in new window
        hidelinks,              % disable link borders
        %colorlinks=false,       % false: boxed links; true: colored links
    }
\usepackage[capitalize]{cleveref}
\usepackage{minted}
    \usemintedstyle{borland}
    \setminted{autogobble}
\usepackage{xcolor}

\newrobustcmd{\release}[3]{%
    \subsection{\emph{#1}: \texttt{#2} - #3}\label{release-#2}%
}

\newrobustcmd{\command}[3]{%
    \paragraph{\textsf{#1}} \textbf{\color{blue} \texttt{#2}}

    #3
}

% Turn off the execution of \amxgenerate.
% This is used internally in the document to prevent code examples from firing the matrix when loaded.
\newrobustcmd{\amxDisable}{%
    \let\theOldAMX\amxgenerate%
    \def\amxgenerate{}%
}
\newrobustcmd{\amxEnable}{%
    \let\amxgenerate\theOldAMX
}

% Escaped special characters for \texttt and the \write calls.
% (via http://tex.stackexchange.com/a/223089)
\def\atchar#1{}
\edef\atchar{\expandafter\atchar\string\@}
\def\bslchar#1{}
\edef\bslchar{\expandafter\bslchar\string\\}
\def\spchar#1{}
\edef\spchar{\expandafter\spchar\string\ }
\def\lbchar#1{}
\edef\lbchar{\expandafter\lbchar\string\{}
\def\rbchar#1{}
\edef\rbchar{\expandafter\rbchar\string\}}
\def\hschar#1{}
\edef\hschar{\expandafter\hschar\string\#}

\newwrite\tempfile

\begin{document}

\vspace*{0in}
\begin{center}
    \LARGE The \textsf{association-matrix} Package \\
    \small \rule{0in}{1em} An easy and clear association matrix generator \\
    \large \rule{0in}{2em} Whisperity \\
    % \\
    \rule{0em}{2em}\amxDate \\
    Version \amxVersion
\end{center}

\tableofcontents


\section{Introduction}\label{intro}
The \textsf{association-matrix} package allows the convenient creation of association matrices.
The package aims to automate the generation, without the user having to manually write the table's code and have to deal with the inefficiency of copy-pasting information.
The package's interface is simple, the user needs to define the table's contents (\cref{define}) and then can generate the table (\cref{tablegen}).

Note that it is important to have \emph{every} necessary row entries and column headings defined \textbf{before} the first call to a table generation, otherwise, only a partial table will be generated.

\subsection{Association matrix}\label{association-mx}
At the author's University, it is customary for Ph.D.\ students to write their doctoral dissertation organised into individual \emph{theses} (corresponding to chapters), and to provide a breakdown on which of their publications are ``proof'' behind the thesis (chapter).
Originally, the package \textsc{theses-vs-publications} had been devised, but then we turned it to a more generic solution.

Commonly, the dissertation's \emph{``Introduction''} and \emph{``Summary''} chapters will provide the full table.
In addition, at the end of each individual thesis chapters will provide a table with the current thesis's row in the table \emph{highlighted}.

An example usage and association matrix is provided in \cref{example}.

\subsection{Licence}
Copyright \textcopyright\ 2020 Whisperity.
Permission is granted to copy, distribute and\slash or modify this software under the terms of the \emph{\LaTeX{} Project Public License}, version \emph{1.3c} or newer.\footnote{%
    \url{http://www.latex-project.org/lppl}%
}

\subsection{Example}\label{example}
The definitions (\cref{define}) should be done early in the document, but at least before the first table render (\cref{tablegen}) call.

\immediate\openout\tempfile=assoc-mx-example.aux
    \immediate\write\tempfile{\bslchar amxrow{association-matrix}{Association Matrices}}
    \immediate\write\tempfile{\bslchar amxrow{latex}{\bslchar LaTeX}}
    \immediate\write\tempfile{}
    \makeatletter
       \immediate\write\tempfile{\@percentchar\spchar Using the bibliography at the end of document!}
    \makeatother
    \immediate\write\tempfile{\bslchar amxcol{amxdoc}{\bslchar cite{associationmatrix}}}
    \immediate\write\tempfile{\bslchar amxcol{latexdoc}{\bslchar cite{latex}}}
    \immediate\write\tempfile{\bslchar amxcol{etoolboxdoc}{\bslchar cite{etoolbox}}}
    \immediate\write\tempfile{}
    \immediate\write\tempfile{\bslchar amxassociate{amxdoc}{association-matrix}}
    \immediate\write\tempfile{\bslchar amxassociate{etoolboxdoc}{association-matrix}}
    \immediate\write\tempfile{\bslchar amxassociate{latexdoc}{latex}}
    \immediate\write\tempfile{\bslchar amxassociate{etoolboxdoc}{latex}}
    \immediate\write\tempfile{}
    \immediate\write\tempfile{\detokenize{\amxgenerate}}
\immediate\closeout\tempfile

\amxDisable
\input{assoc-mx-example.aux}
\amxEnable
\begin{figure}[H]
    \centering
    \inputminted{latex}{assoc-mx-example.aux}
    \amxgenerate
\end{figure}

\clearpage
\section{Commands}\label{commands}
\subsection{Registering entries}\label{define}

\command{amxrow}{\bslchar amxrow\lbchar <key>\rbchar\lbchar <text>\rbchar}{%
Registers the row entry named \texttt{<key>} with the given \texttt{<text>}.
The \emph{title} of the entry is printed in the first cell of the row, \textbf{in the order of} \texttt{\bslchar amxrow} calls.
}

\command{amxcol}{\bslchar amxcol\lbchar <key>\rbchar\lbchar <text>\rbchar}{%
Registers the column named \texttt{<key>} with the given \texttt{<text>}.
The contents of \emph{body} is printed as the column headings of the table, \textbf{in the order of} \texttt{\bslchar amxcol} calls.
}

\command{amxassociate}{\bslchar amxassociate\lbchar <col-key>\rbchar\lbchar <row-key>\rbchar}{%
Registers the association between \texttt{<col-key>} and \texttt{<row-key>}.
The cells at the intersection of the row and the column will have a \textbullet{}, indicating the relevancy.
}

\subsection{Queries}\label{query}

\command{amxrows}{\bslchar amxrows}{%
    Returns the number of rows defined.
}

\command{amxcols}{\bslchar amxcols}{%
    Returns the number of columns defined.
}

\command{amxrowtext}{\bslchar amxrowtext\lbchar <key>\rbchar}{%
    Returns the registered \emph{text} for the \textbf{row} registered with \texttt{<key>}.
}

\command{amxcoltext}{\bslchar amxcoltext\lbchar <key>\rbchar}{%
        Returns the registered \emph{text} for the \textbf{column} registered with \texttt{<key>}.
}

\subsection{Table generator: \texttt{amxgenerate}}\label{tablegen}

\command{amxgenerate}{\bslchar amxgenerate[<row>]}{%
    Generates the full table incorporating the previously registered data.
    Internally, a \texttt{tabular} environment is created with the table's data generated by the package.
    It is the user's responsibility to wrap this into a floating \texttt{table}, if they so wish.
    
    If \texttt{[<row>]} is given a row's \emph{key}, the row for that key will be \textbf{highlighted}.
    Highlighting is done by typesetting the row's \emph{text} in \textbf{bold face}, and changing every \textbullet{} in the \emph{other} rows to \textopenbullet{}.
    
    \begin{figure}[H]
        \centering
        \amxgenerate[latex]
    \end{figure}
}


% Let's use an example of 2×2 matrix for the customisations.
\newcommand{\docExampleResetTableTwoByTwo}{%
    \amxReset%
    \amxrow{sample}{Sample}%
    \amxrow{simple}{Simple}%
    \amxcol{x}{x}%
    \amxcol{y}{y}%
    \amxassociate{x}{sample}%
    \amxassociate{y}{simple}%
}
\newcommand{\loadAndRenderResettingExample}[2][0]{%
    \begin{figure}[H]
        \centering
        \inputminted{latex}{#2}

        \docExampleResetTableTwoByTwo
        \input{#2}
        \amxgenerate[#1]
    \end{figure}%
}

\subsection{Customisation}\label{customise}
All aspects on how the individual elements in the table are rendered can be customised by setting \emph{renderer} control sequences.

\makeatletter
    \def\defaultTopCorner{\amx@Renderer@Default@TopCorner}
\makeatother
\command{amxsetTopCorner}{\bslchar amxsetTopCorner\lbchar <new-heading>\rbchar}{%
    Sets the rendered table's top left cell value (by default, ``\emph{\defaultTopCorner}'') to the given \texttt{<new-heading>} value.

    \immediate\openout\tempfile=settopcorner-example.aux
        \immediate\write\tempfile{\bslchar amxsetTopCorner{Correlations}}
    \immediate\closeout\tempfile
    \loadAndRenderResettingExample{settopcorner-example.aux}
}

\command{amxsetColumnHeading}{\bslchar amxsetColumnHeading\lbchar<render-command>\rbchar}{%
    Sets the rendered table's top row's cells to be rendered via passing the column heading's text (see \cref{query}) to the given \texttt{<render-command>}.
    This command must be a command that takes \textbf{1} argument, defined by the user earlier.

    \immediate\openout\tempfile=setcolheading-example.aux
        \immediate\write\tempfile{\bslchar newcommand{\bslchar ttColHead}[1]{\bslchar texttt{\hschar1}}}
        \immediate\write\tempfile{\bslchar amxsetColumnHeading{\bslchar ttColHead}}
    \immediate\closeout\tempfile
    \loadAndRenderResettingExample{setcolheading-example.aux}
}

\command{amxsetRowFormat}{\bslchar amxsetRowFormat(Highlighted)\lbchar<render-command>\rbchar}{%
    Sets the rendered table's left cells' to be rendered via passing the row's index and text (see \cref{query}) to the given \texttt{<render-command>}.
    This command must be a command that takes \textbf{2} arguments, defined by the user earlier.
    The \texttt{Highlighted} version sets the renderer for the highlighted row, if highlighted rendering (see \cref{tablegen}) is done.

    \immediate\openout\tempfile=setrowformat-example.aux
        \immediate\write\tempfile{\bslchar newcommand{\bslchar parenRow}[2]{(\hschar1) \bslchar emph{\hschar2}}}
        \immediate\write\tempfile{\bslchar newcommand{\bslchar parenRowBl}[2]{!\hschar1! \bslchar texttt{\hschar2}}}
        \immediate\write\tempfile{\bslchar amxsetRowFormat{\bslchar parenRow}}
        \immediate\write\tempfile{\bslchar amxsetRowFormatHighlighted{\bslchar parenRowBl}}
    \immediate\closeout\tempfile
    \loadAndRenderResettingExample[simple]{setrowformat-example.aux}
}

\clearpage
\makeatletter
    \def\defaultIndicator{\amx@Renderer@Default@Indicator}
\makeatother
\command{amxsetIndicator}{\bslchar amxsetIndicator\lbchar<indicator>\rbchar}{%
    Sets the indicators of association in the matrix in \emph{non-highlighting} mode to the result of the \texttt{<indicator>}.
    The default indicator is: \defaultIndicator{}.

    \immediate\openout\tempfile=setindicator-example.aux
        \immediate\write\tempfile{\bslchar amxsetIndicator{a}}
    \immediate\closeout\tempfile
    \loadAndRenderResettingExample{setindicator-example.aux}
}

\makeatletter
    \def\defaultIndicatorHC{\amx@Renderer@Default@Indicator@Highlighted@Current}
    \def\defaultIndicatorHO{\amx@Renderer@Default@Indicator@Highlighted@Other}
\makeatother
\command{amxsetIndicatorHighlighted}{\linebreak\bslchar amxsetIndicatorHighlighted\lbchar<hl-indicator>\rbchar\lbchar<ot-indicator>\rbchar}{%
    Sets the indicators of association in the matrix in \emph{highlighting} mode to the result of the \texttt{<hl-indicator>} for the \textbf{highlighted row} and \texttt{<ot-indicator>} for every other row.
    The default indicators are: \defaultIndicatorHC{} and \defaultIndicatorHO{}, respectively.

    \immediate\openout\tempfile=setindicator-hl-example.aux
        \immediate\write\tempfile{\bslchar amxsetIndicatorHighlighted{c}{o}}
    \immediate\closeout\tempfile
    \loadAndRenderResettingExample[simple]{setindicator-hl-example.aux}
}

\subsection{Multiple distinct tables: \texttt{amxReset}}

\command{amxReset}{\bslchar amxReset}{%
    Clears \textbf{all} internal data structures and customisations for the package, allowing the user to later typeset a different, independent matrix.
    The previously defined entries are lost, and in case the ``previous'' matrix is needed, it must be set up again with a sequence of definition commands (see \cref{define}).
    
    For example, putting the code in \cref{example} and the one below into the same source file will create the smaller matrix at the second invocation of \texttt{\bslchar amxgenerate}.
    
    \immediate\openout\tempfile=reset-example.aux
        \immediate\write\tempfile{\bslchar amxReset}
        \immediate\write\tempfile{\bslchar amxrow{sample}{Sample}}
        \immediate\write\tempfile{\bslchar amxcol{x}{x}}
        \immediate\write\tempfile{\bslchar amxassociate{x}{sample}}
        \immediate\write\tempfile{\detokenize{\amxgenerate}}
    \immediate\closeout\tempfile
    
    \amxDisable
    \input{reset-example.aux}
    \amxEnable
    
    \begin{figure}[H]
        \centering
        \inputminted{latex}{reset-example.aux}
        \amxgenerate
    \end{figure}
}

\clearpage
\section{Development}
The development of \textsf{association-matrix} is done on GitHub: \url{http://github.com/whisperity/association-matrix}.
Please report issues and submit patches here.

Note that this document acts as a \textbf{test file} to the package, not only a user-facing documentation.
Any new command or change should be supplemented with appropriate documentation, and the check of the rendered examples.
If there is a discrepancy or regression in the looks of \emph{this document} that is not explained by the changes, it should be investigated!

\section{Changelog}\label{changelog}
\release{2020/10/25}{v1.0}{Initial release}
\begin{itemize}
    \item Basic functionality of defining entries, rendering tables, and customising the renderers are implemented.
\end{itemize}

\begin{thebibliography}{3}
\bibitem{associationmatrix}
Whisperity. \textit{The \textsf{association-matrix} Package -- An easy and clear association matrix generator}.
Online, \url{http://ctan.org/pkg/association-matrix} (accessed 2020/10/25), 2020.

\bibitem{latex} 
Leslie B.\ Lamport, Donald E.\ Knuth et al. 
\textit{\LaTeX{} -- A document preparation system}. 
Online, \url{http://latex-project.org/} (accessed 2020/10/25), 1984.

\bibitem{etoolbox} 
Philipp Lehman, Joseph Wright.
\textit{The \textsf{etoolbox} Package -- An e-\TeX{} Toolbox for Class and Package Authors}
Online, \url{http://ctan.org/pkg/etoolbox} (accessed 2020/10/25), 2007.
\end{thebibliography}

\end{document}