summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tlc-article/tlc-article.tex
blob: dae2f37ab4496b47cc001c80e59a5be24b58a344 (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
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
\documentclass[12pt]{tlc-article}

% ------------------------------------------------------------------------------
\begin{document}

% ------------------------------------------------------------------------------
\tlcTitlePageAndTableOfContents
  {tlc-article}
  {Gary Allan Howard}
  {The \tlcA\ `Getting Started Guide' covers how to install \tlcA\ both globally
   and locally, describes the general use case, how to customize your \tlcA\
   environment, describes the commands \tlcA\ implements, and reveals the
   packages \tlcA\ depends upon.}

% ------------------------------------------------------------------------------
\section{Installation}
This section describes how to install \tlcA\ either globally to make it
available to your \LaTeX\ environment or locally to the document you are
authoring.  And, this section identifies the prerequisites you must meet in
order to clone a repository from GitHub.com and install software on your
computer.

% ------------------------------------------------------------------------------
\subsection{Prerequisites}
The following prerequisites are needed.
\begin{description}[style=nextline]
  \item[Administrative privilege] You will need administrative privileges to
    install \tlcA\ globally because `sudo' is used.

  \item[SSH key] You will need your private key to access \gitHub.  Please refer
    to \url{http://help.github.com/articles/generating-an-ssh-key} for
    instructions on `Generating an SSH key'.

  \item[Enable your SSH key] The following instructions enable your SSH key so
    you to not have to enter the passphrase for each git command.
\end{description}

\begin{lstlisting}[language=bash]
eval \$(ssh-agent -s)
ssh-add ~/.ssh/your-private-key
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{Local installation}
A local installation is done by installing \tlcA\ into
/the/path/to/your/document.  Assuming your document is located at \tlcMyDoc\ the
following shell commands will make \tlcA\ available to your document.

\begin{lstlisting}[language=bash]
cd $HOME
git clone git@GitHub.com:Traap/tlc-article.git
cd tlc-article
mkdir $HOME/mydoc
cp -v tlc-article.cls $HOME/mydoc/.
\end{lstlisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{Global installation}
A global installation is done by installing \tlcA\ into your /path/to/your/texmf
directory.  Assuming a TexLive installation exists at \texDist\ the following
shell commands will make \tlcA\ available to your \LaTeX\ environment.

\begin{lstlisting}[language=bash]
cd $HOME
git clone git@GitHub.com:Traap/tlc-article.git
cd tlc-article
sudo mkdir -p $(kpsewhich -var-value TEXMFLOCAL)/tex/latex/tlc-article
sudo cp -v tlc-article.cls $(kpsewhich -var-value TEXMFLOCAL)/tex/latex/tlc-article/.
sudo mktexlsr $(kpsewhich -var-value TEXMFLOCAL)
\end{lstlisting}

\bigskip

\todo[inline]{%
  \tlcNote: You may remove your local installation by removing \tlcA.%
}%

% ------------------------------------------------------------------------------
\clearpage
\section{General Use Case}
The goal of \tlcA\ is to simplify document layout.  \tlcA\ orchestrates a
logical arrangement for document header, footer, author, abstract, table of
contents, and margins.  The following sections outline the default
implementation for each part \tlcA\ organizes.

\tlcNote\ This document was typeset using the instructions provided throughout
this section.

\subsection{Document Layout}
\begin{figure}[h]
  \centering
  \includegraphics{images/titlepage.png}
  \caption{Document Layout}
  \label{fig:layout}
\end{figure}

% ------------------------------------------------------------------------------
\subsection{documentclass \tlcA}
\tlcA\ extends the article document class.  \tlcA\ provide options directly to
the article document class.  As an example, the Author can specify the font as
follows:

\begin{lstlisting}[basicstyle=\tiny]
  \documentclass[12pt]{tlc-article}
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{Title, Author \& Abstract} \label{sec:TAA}
\tlcA\ has a macro \tlcTOC\ that can be used to set the document title, document
author, document abstract, and establish the Table of Contents.  The sample
below reveals how to use \tlcTOC.

\begin{lstlisting}[basicstyle=\tiny]
  \tlcTitlePageAndTableOfContents
     {Document Title}
     {Document Article}
     {Document Abstract}
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{Table of Contents}
The Table of Contents immediately follows the document abstract on page 1, uses
dark blue for content, dots separate table of contents sections and page number,
and uses roman numerals.

% ------------------------------------------------------------------------------
\subsection{Header \& Footer}
fancyhdr is used to render the header and footer.  The Author can override the
\tlcA\ by providing an implementation in \tlcHF\, or augment \tlcA\
application by providing \tlcVE. The sections below show the placement \tlcA\
uses when writing objects, and where the objects are defined.

\bigskip

\todo[inline]{%
  \tlcNote: \tlcA\ ignores \tlcVE\ when \tlcHF\ is defined.
}%



% ------------------------------------------------------------------------------
\subsubsection*{Header}
\begin{description}
  \item[lhead] When \tlcLG\ is found, logo.
  \item[chead] Document Title
  \item[rhead] When \tlcVE\ is present, status, date, and version columns.
\end{description}

% ------------------------------------------------------------------------------
\subsubsection*{Footer}
\begin{description}
  \item[lfoot] When \tlcVE\ is present, institution column.
  \item[cfoot] When \tlcVE\ is present, permission column.
  \item[rfoot] Page 1 of N.
\end{description}

% ------------------------------------------------------------------------------
\subsubsection*{Rule width}
A 0.1pt rule width is placed below the document header and above the document
footer.

% ------------------------------------------------------------------------------
\clearpage
\section{Customization}
This section describes how \tlcA\ can be customized by using the file-hooks
\tlcA\ check for.  \tlcA\ default implementation will be used when the
file-hooks are not found.

\bigskip

\todo[inline]{%
  \tlcNote: \tlcA\ consumes \tlcAL\ \& \tlcHF\ during the preamble compilation
  phase.
}%

% ------------------------------------------------------------------------------
\subsection{\tlcAL}
\tlcA\ will use whatever \LaTeX\ definitions are found in \tlcAL\ when it
exists.  The file-check is shown
below:

\begin{lstlisting}[basicstyle=\tiny]
  \IfFileExists{data/additional-layout.tex}
    {\input{data/additional-layout.tex}}
    {}
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{\tlcHF}
In the absence of \tlcAL\, \tlcA\ has a builtin header and footer strategy that
is base on \textit{fancyhdr}, \textit{titling}, and \textit{lastpage} \LaTeX\
packages. The default implementation is show below:

\begin{lstlisting}[basicstyle=\tiny]
\IfFileExists{\tlc@headerFooter}%
{ % use the customer header and footer defined by \tlc@headerfooter
 \input{\tlc@headerFooter}%
}%
{ % Else : header and footer applied to all pages.
  \IfFileExists{\tlc@logoFile}%
  { % Typeset the logo in the left side of the document header.
    \lhead{\includegraphics[width=3cm,height=1cm]{\tlc@logoFile}}%
  }%
  {% Else: no operation because tlc@logoFile does not exist.
  }%
  %
  % Typeset the title in the center of the document header.
  %
  \chead{\large{\thetitle}}%
  %
  % Typeset version information in the right side of the document header.
  %
  \IfFileExists{\tlc@versionFile}%
  {%
    % document status, document date and document version.
    \rhead{\tiny \tlc@status \\ \tlc@date \\ \tlc@version}%
    % document owner.  This maybe a person or company name.
    \lfoot{\tiny \tlc@institution}%
    % document license. This maybe a license or word like confidential.
    \cfoot{\tiny \tlc@permission}%
  }%
  {% Else: no operation because tlc@versionFile does not exist.
  }%
  \renewcommand{\headrulewidth}{0.1pt}%
  % Eliminate head height too small warning, which is occurring because
  % we are using multiple lines in our header.
  \setlength\headheight{34.0pt}%
  % footer applied to all pages.
  \rfoot{\tiny{Page \thepage~of~\pageref{LastPage}}}%
  \renewcommand{\footrulewidth}{0.1pt}%
}%
\end{lstlisting}

The default implementation can be overridden by defining \tlcHF.

\tlcVspace

\todo[inline]{%
  \tlcNote: When \tlcHF\ exists and is empty, your document will be typeset with
  the defaults from document-class \tlcDarkblue{article}.
}%

% ------------------------------------------------------------------------------
\clearpage
\subsection{\tlcVE} \label{sec:version}
\tlcA\ will populate the builtin header and footer with information extracted
from \tlcVE\ when it is present.  \tlcVE\ is a comma-separated-variable file
that uses the pipe character as the field delimiter.  \tlcVE\ uses the following
column names:

\begin{description}[style=nextline]
  \item[version] The version value is typeset in the rhead area.  This field is
    used to convey the version the document was at the date it reached its
    current state.

  \item[date] The date value is typeset in the rhead area.  This field is used
    to communicate when the document transitioned into its current state.

  \item[status] The status value is typeset in the rhead area.  This field is
    used to convey the document state such as Approved, Draft, Effective, or
    Obsolete.

  \item[instatution] The institution value is typeset in the lfoot area.  This
    field is used to tell the reader the author name or company name.

  \item[permission]  The permission value is typeset in the cfoot area.  This
    field is used to identify confidentiality or a particular license.

\end{description}

The exaction methods are shown below.
\begin{lstlisting}[basicstyle=\tiny]
  % Extract document status, document date and document version from
  % \tlc@versionFile.
  % Argument:
  %   1 - the column name to extract from the data file.
  \newcommand{\tlcVersionPart}[1]{
    \csvreader[separator=pipe]
    {\tlc@versionFile}{
      1=\version,
      2=\date,
      3=\status,
      4=\instatution,
      5=\permission
    }{#1}
  }%

  % Define extractions macros when \tlc@versionFile exists.
  \IfFileExists{\tlc@versionFile}
  {
    \def\tlc@version{\tlcVersionPart{\version}}
    \def\tlc@date{\tlcVersionPart{\date}}
    \def\tlc@status{\tlcVersionPart{\status}}
    \def\tlc@instatution{\tlcVersionPart{\version}}
    \def\tlc@permission{\tlcVersionPart{\version}}
  }
  {% Else: no operation because tlc@versionFile does not exist.
  }
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{\tlcLG}
\tlcA\ will typeset the lhead area with \tlcLG\ when it is present. Make sure
your logo's height is not larger than 34pt to avoid `Package Fancyhdr Warning:
\\headheight is to small' warning.

% ------------------------------------------------------------------------------
\clearpage
\section{Definitions \& Commands}
\subsection{\tlcBL}
Page layout is rotated 90\textdegree\ clockwise resulting in a landscape page
orientation.  Landscape orientation remains active until \tlcEL.

% ------------------------------------------------------------------------------
\subsection{\tlcEL}
Page layout is returned to portrait orientation when \tlcEL\ is reached.

% ------------------------------------------------------------------------------
\subsection{\tlcDB}
\tlcDB\ is used throughout this document to render text using rbg\{0,0,0.5\}.
\tlcDB\ is safe to use within your document.

% ------------------------------------------------------------------------------
\subsection{\tlcTOC}
\tlcTOC\ creates the document layout shown in Figure \ref{fig:layout}.  Section
\ref{sec:TAA} shows an example implementation.

% ------------------------------------------------------------------------------
\subsection{\tlcNCT}
New \tlcNCT\ are Left, Center, and Right, respectively are
designed to use with longtable.  Data is wrapped within a table cell.   The
parameter defines the column width.  As an example, L{2cm} yields a Left
aligned, ragged right, wrapped text within a 2cm wide cell.

\begin{lstlisting}[basicstyle=\tiny]
\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash}p{#1}}
\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash}p{#1}}
\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash}p{#1}}
\end{lstlisting}

% ------------------------------------------------------------------------------
\subsection{\tlcAL}
\tlcAL\ is an architectural hook the Author should use when it becomes necessary
to use packages not provided by \tlcA\, and to design commands that are specific
to your document.

% ------------------------------------------------------------------------------
\subsection{\tlcHF}
\tlcHF\ is an architectural hook the Author should use to completely override
the document layout \tlcA\ implements.

% ------------------------------------------------------------------------------
\clearpage
\subsection{\tlcVE}
\tlcVE\ is by used \tlcA\ to populate the document header \& footer.  Refer to
section \ref{sec:version} for \tlcVE\ definitions. \tlcVE\ is not
used by \tlcA\ when \tlcHF\ is define.  However, you might want to use the
version hook by defining \tlcVE\ and using the commands below to extract data
from \tlcVE\ in your \tlcHF.
\begin{enumerate}
  \item \tlcVC\
  \item \tlcDC\
  \item \tlcSC\
  \item \tlcIC\
  \item \tlcPC\
\end{enumerate}

% ------------------------------------------------------------------------------
\subsection{\tlcLG}
\tlcA\ places \tlcLG\ in your header when defined.

% ------------------------------------------------------------------------------
\clearpage
\section{Required Packages}
This section documents the dependencies of the required package tlc-article has.
Package names are listed in alphabetical order. A complete description of each
package is found at \url{http://www.ctan.org/}. At this writing, you can type in
the package name and press the search button to learn more about each package.

% Render pckFile using pckStyle as a longtable.
\csvreader[tlcPkgStyle, separator=pipe]{\tlcPkgFile}{}{\name & \description}
% ------------------------------------------------------------------------------

\end{document}