Initial commit

1 files changed, 385 insertions, 0 deletions

diff --git a/macros/latex/contrib/tlc-article/tlc-article.tex b/macros/latex/contrib/tlc-article/tlc-article.tex
new file mode 100644
index 0000000000..dae2f37ab4
--- /dev/null
+++ b/macros/latex/contrib/tlc-article/tlc-article.tex
@@ -0,0 +1,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}