\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}