\documentclass[12pt]{tlc-article}

% {{{ Begin document

\begin{document}

% -------------------------------------------------------------------------- }}}
% {{{ Abstract and Table of Contents

\tlcTitlePageAndTableOfContents
  {tlc-article Getting Started Guide}
  {Gary Allan Howard}
  {The \tlcA\ ``Getting Started Guide'' explains how to install and use \tlcA,
   customize its layout, use its public commands, and identify its package
   dependencies.}

% -------------------------------------------------------------------------- }}}
% {{{ Installation

\section{Installation}
Install \tlcA\ with your \TeX\ distribution's package manager whenever
possible. You can instead copy the class into an individual document project
when you need a local installation or want to test a development version.

% -------------------------------------------------------------------------- }}}
% {{{ Prerequisites

\subsection{Distribution installation}
\TeX\ Live users can install \tlcA\ with \texttt{tlmgr}:

\begin{lstlisting}[language=bash]
tlmgr install tlc-article
\end{lstlisting}

MiK\TeX\ users can install \tlcA\ with the MiK\TeX\ Console. Your distribution
will place the class in the appropriate \TeX\ tree and maintain its filename
database.

% -------------------------------------------------------------------------- }}}
% {{{ Local installation

\subsection{Local installation}
Download the release archive or clone the repository, then copy
\texttt{tlc-article.cls} next to your document's \texttt{.tex} file. \LaTeX\
searches the current directory before installed package trees.

\begin{lstlisting}[language=bash]
cp tlc-article.cls /path/to/document/
\end{lstlisting}

\tlcVspace

\tlcNote\ The files in the optional \texttt{data/} directory customize the
class. Copy the directory into your document project when you want to use or
adapt those examples.

% -------------------------------------------------------------------------- }}}
% {{{ General Use Case

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

\tlcVspace

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

% -------------------------------------------------------------------------- }}}
% {{{ Document Class

\subsection{Document Class \tlcA}
\tlcA\ extends the article document class.  \tlcA\ provides 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}

% -------------------------------------------------------------------------- }}}
% {{{ Title, Author, and Abstract

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

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

% -------------------------------------------------------------------------- }}}
% {{{ Table of Contents

\subsection{Table of Contents}
The table of contents begins on the page after the title and abstract. Its links
are dark blue, and dotted leaders separate section titles from page numbers.

% -------------------------------------------------------------------------- }}}
% {{{ Header and Footer

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

\tlcVspace

\tlcNote\ \tlcA\ ignores \tlcVE\ when \tlcHF\ is defined.

% -------------------------------------------------------------------------- }}}
% {{{ Header

\subsubsection*{Header}
\begin{description}
  \item[Left] When \tlcLG\ is found, the logo.
  \item[Center] The document title.
  \item[Right] When \tlcVE\ is present, the status, date, and version.
\end{description}

% -------------------------------------------------------------------------- }}}
% {{{ Footer

\subsubsection*{Footer}
\begin{description}
  \item[Left] When \tlcVE\ is present, the institution.
  \item[Center] When \tlcVE\ is present, the permission or license.
  \item[Right] The current and total page count.
\end{description}

% -------------------------------------------------------------------------- }}}
% {{{ Rule width

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

% -------------------------------------------------------------------------- }}}
% {{{ Customization

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

\tlcVspace

\tlcNote\ \tlcA\ consumes \tlcAL\ and \tlcHF\ while processing the preamble.

% -------------------------------------------------------------------------- }}}
% {{{ data/additional-layout.tex

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

% -------------------------------------------------------------------------- }}}
% {{{ data/header-footer.tex

\subsection{\tlcHF}
In the absence of \tlcHF, \tlcA\ has a built-in header and footer strategy that
is based on \textit{fancyhdr}, \textit{titling}, and \textit{lastpage} \LaTeX\
packages. The default implementation is shown below:

\begin{lstlisting}[basicstyle=\tiny]

\IfFileExists{\tlc@headerFooter}%
{% use the custom header and footer defined by \tlc@headerfooter
  \input{\tlc@headerFooter}%
}%
{% Else: use default header and footer
  \useDefaultHeaderFooter%
}%

\newcommand{\useDefaultHeaderFooter}{%
  \useLogoFile%              Typeset Logo in the left side of the header.
  \useTitle%                 Typeset the title in the center of the header.
  \useVersionFile%           Typeset version info in right side of the header.
  \useRuler%                 Typeset header and footer with a ruler.
}%

\newcommand{\useLogoFile}{%
  \IfFileExists{\tlc@logoFile}%
  {%
    \fancyhead[L]{\includegraphics[width=3cm,height=1cm]{\tlc@logoFile}}%
  }%
  {%
   % Else: no operation because tlc@logoFile does not exist.
  }%
}%

\newcommand{\useVersionFile}{%
  \IfFileExists{\tlc@versionFile}%
  {%
   % document status, document date and document version.
    \fancyhead[R]{\tiny \tlc@status \\ \tlc@date \\ \tlc@version}%
   %
   % document owner.  This may be a person or company name.
    \fancyfoot[L]{\tiny \tlc@institution}%
   %
   % document license. This may be a license or a word like confidential.
    \fancyfoot[C]{\tiny \tlc@permission}%
  }%
  {%
   % Else: no operation because tlc@versionFile does not exist.
  }%
}%

\newcommand{\useRuler}{%
  \renewcommand{\headrulewidth}{0.1pt}%
  \setlength\headheight{34.0pt}%
  \fancyfoot[R]%
    {\tiny%
      {Page \thepage~of~\pageref{LastPage}}%
    }%
  \renewcommand{\footrulewidth}{0.1pt}%
}%

\newcommand{\useTitle}{%
  \fancyhead[C]{\large{\thetitle}}%
}%

\end{lstlisting}

The default implementation can be overridden by defining \tlcHF.

\tlcNote\ When \tlcHF\ exists and is empty, the document uses the header and
footer defaults inherited from the \tlcDarkblue{article} class.

% -------------------------------------------------------------------------- }}}
% {{{ data/version.csv

\subsection{\tlcVE} \label{sec:version}
\tlcA\ will populate the built-in header and footer with information extracted
from \tlcVE\ when it is present. \tlcVE\ is a tabular text file that uses the
pipe character as its field delimiter and has the following column names:

\begin{description}[style=nextline]
  \item[version] The version value is typeset in the right header. This field is
    used to convey the document version when it reached its
    current state.

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

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

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

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

\end{description}

The extraction 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=\institution,
      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@institution{\tlcVersionPart{\institution}}
    \def\tlc@permission{\tlcVersionPart{\permission}}
  }
  {% Else: no operation because tlc@versionFile does not exist.
  }
\end{lstlisting}

% -------------------------------------------------------------------------- }}}
% {{{ data/logo.png

\newpage
\subsection{\tlcLG}
\tlcA\ will place \tlcLG\ in the left header when it is present. Make sure your
logo's height is not larger than 34pt to avoid the ``Package Fancyhdr Warning:
\\headheight is too small'' warning.

\tlcVspace

\tlcA\ file-check is shown below:

\begin{lstlisting}[basicstyle=\tiny]
% Typeset the logo in the left side of the document header.  Otherwise no
% operation because tlc@logoFile does not exist.

\newcommand{\useLogoFile}{%
  \IfFileExists{\tlc@logoFile}%
  {%
    \fancyhead[L]{\includegraphics[width=3cm,height=1cm]{\tlc@logoFile}}%
  }%
  {%
   % Else: no operation because tlc@logoFile does not exist.
  }%
}%
\end{lstlisting}

% -------------------------------------------------------------------------- }}}
% {{{ Definitions and Commands

\section{Definitions \& Commands}

% -------------------------------------------------------------------------- }}}
% {{{ tlcBeginLandscape

\subsection{\tlcBL}
Page layout is rotated 90\textdegree\ clockwise resulting in a landscape page
orientation.  Landscape orientation remains active until \tlcEL.

% -------------------------------------------------------------------------- }}}
% {{{ tlcEndLandscape

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

% -------------------------------------------------------------------------- }}}
% {{{ tlcDarkblue

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

% -------------------------------------------------------------------------- }}}
% {{{ tlcTitlePageAndTableOfContents

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

\tlcVspace

\tlcTOC\ command is shown below:

\begin{lstlisting}[basicstyle=\tiny]
% Each document uses the same author name, title page and table of contents.
%
% Arguments:
%   1 - the title
%   2 - the author
%   3 - the abstract

\newcommand{\tlcTitlePageAndTableOfContents}[3]{%
  \ifthenelse{\equal{#1}{}}{% title check
    \title{}%
  }{% Else: title
    \title{#1}%
  }%
  \ifthenelse{\equal{#2}{}}{% author check
    \author{}%
  }{% Else: author
    \author{#2}%
  }%
  \maketitle%
  \ifthenelse{\equal{#3}{}}{% abstract check
  }{% Else: abstract
    \begin{abstract}#3\end{abstract}%
  }%
  \thispagestyle{empty}%
  \clearpage%
  \tableofcontents%
  \clearpage%
}%

\end{lstlisting}


% -------------------------------------------------------------------------- }}}
% {{{ newcolumntype type: L, C and R

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

\tlcVspace

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

% -------------------------------------------------------------------------- }}}
% {{{ data/additional-layout.tex

\subsection{\tlcAL}
\tlcAL\ is an architectural hook the author can use to provide packages and
commands not provided by \tlcA\, and to design implementations that are specific
to your document.

\tlcVspace

\tlcNote\ \url{https://github.com/Traap/autodoc} is a documentation framework
that extends \tlcA.


% -------------------------------------------------------------------------- }}}
% {{{ data/header-footer.tex

\subsection{\tlcHF}
\tlcHF\ is an architectural hook the author should use to completely override
header and footer layouts provided by \tlcA.

% -------------------------------------------------------------------------- }}}
% {{{ data/version.csv

\subsection{\tlcVE}
\tlcVE\ is used by \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 defined.  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}

% -------------------------------------------------------------------------- }}}
% {{{ data/logo.png

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

% -------------------------------------------------------------------------- }}}
% {{{ debugging

\subsection{\tlcDebug}
The \tlcDebug\ command can assist you when you encounter compilation errors using
\tlcA.

\tlcVspace

\begin{lstlisting}[basicstyle=\tiny]
% We define tlcDebug to aid our users when they are debugging their document.
% tlcDebug should be placed at the end of your document to allow LaTeX to
% fully expand all macros and definitions.

\newcommand{\tlcDebug}{%
  \clearpage%
  \section{tlc-article Debug}%
  \subsection{tlc-article default files}%
  \begin{description}[align=right,labelindent=5cm]%
    \item[tlc@location:]\tlc@location%
    \item[tlc@additionalLayout:]\tlc@additionalLayout%
    \item[tlc@headerFooter:]\tlc@headerFooter%
    \item[tlc@logoFile:]\tlc@logoFile%
    \item[tlc@versionFile:]\tlc@versionFile%
  \end{description}%
  %
  \subsection{tlc-article file hooks}%
  \begin{description}[align=right,labelindent=5cm]%
    \item [tlc@additionalLayout:]\tlcIsDefined{\tlc@additionalLayout}%
    \item [tlc@headerFooter:]\tlcIsDefined{\tlc@headerFooter}%
    \item [tlc@logoFile:]\tlcIsDefined{\tlc@logoFile}%
    \item [tlc@versionFile:]\tlcIsDefined{\tlc@versionFile}%
  \end{description}%
  %
  \subsection{tlc-article header and footer hooks}%
  \begin{description}[align=right,labelindent=5cm]%
    \item[tlc@version:] \tlc@version%
    \item[tlc@date:] \tlc@date%
    \item[tlc@status:] \tlc@status%
    \item[tlc@institution:] \tlc@institution%
    \item[tlc@permission:] \tlc@permission%
  \end{description}%
}%
\end{lstlisting}


% -------------------------------------------------------------------------- }}}
% {{{ Required Packages

\clearpage
\section{Required Packages}
This section documents the dependencies required by \tlcA. Package names are
listed in alphabetical order. Search \url{https://ctan.org/} for complete
package descriptions and documentation.

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

% -------------------------------------------------------------------------- }}}

\end{document}