path: root/doc/weekschedule-doc.tex

\documentclass{ltxdoc}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{array}

% Metadata
\title{The \texttt{weekschedule} Class\\
\large A LaTeX Class for Creating Weekly Schedule Calendars}
\author{Douglas B. Rumbaugh}
\date{Version 1.0\\January 2026}

\begin{document}
\maketitle

\begin{abstract}
The \texttt{weekschedule} class provides a simple and flexible way to create
professional weekly schedule calendars in LaTeX. It supports customizable time
ranges, multiple event classes with color coding, and various display options
including 12-hour and 24-hour time formats. The class uses TikZ for rendering,
producing high-quality vector graphics suitable for both screen viewing and
printing.
\end{abstract}

\tableofcontents
\newpage

\section{Introduction}

The \texttt{weekschedule} class is designed to create clean, professional
weekly schedule calendars. It automatically handles layout, time formatting,
and event placement, allowing you to focus on your schedule content rather
than formatting details.

\subsection{Requirements}

The class requires the following packages, which are automatically loaded:
\begin{itemize}
\item \texttt{geometry} (for page layout)
\item \texttt{tikz} (for drawing the schedule)
\item \texttt{xcolor} (for color definitions)
\item \texttt{pgfmath} (for mathematical calculations)
\end{itemize}

\subsection{Installation}

Place the \texttt{weekschedule.cls} file in the same directory as your
document, or in your local TeX tree. No additional installation steps are
required.

\section{Quick Start}

Here is a minimal example to get you started:

\begin{verbatim}
\documentclass{weekschedule}

\scheduletitle{My Weekly Schedule}
\timefrom{8:00}
\timeto{17:00}
\twelvehourtime

\eventclass{Work}{255,200,200}
\event{Work}{Meeting}{Monday}{9:00}{10:00}

\begin{document}
\printschedule
\end{document}
\end{verbatim}

This creates a simple schedule with one event on Monday from 9:00 to 10:00.

\section{Command Reference}

\subsection{Basic Configuration}

\DescribeMacro{\scheduletitle}
Sets the title that appears at the top of the schedule.
\begin{verbatim}
\scheduletitle{Weekly Schedule - Spring 2026}
\end{verbatim}
Default: \texttt{Weekly Schedule}

\DescribeMacro{\scheduleauthor}
Sets the author name that appears below the title (optional).
\begin{verbatim}
\scheduleauthor{Douglas B. Rumbaugh}
\end{verbatim}
Default: empty (no author displayed)

\DescribeMacro{\timefrom}
Sets the start time for the schedule display. The time should be in
\texttt{HH:MM} format (24-hour format).
\begin{verbatim}
\timefrom{8:00}
\end{verbatim}
Default: \texttt{8:00}

\DescribeMacro{\timeto}
Sets the end time for the schedule display. The time should be in
\texttt{HH:MM} format (24-hour format).
\begin{verbatim}
\timeto{18:00}
\end{verbatim}
Default: \texttt{18:00}

\subsection{Time Format}

\DescribeMacro{\twelvehourtime}
\DescribeMacro{\twentyfourhourtime}
These commands control how times are displayed in the schedule.
\begin{verbatim}
\twelvehourtime    % Display as 9:00 AM, 2:00 PM, etc.
\twentyfourhourtime % Display as 9:00, 14:00, etc.
\end{verbatim}
Default: 12-hour format

\subsection{Week Configuration}

\DescribeMacro{\weekworkweek}
\DescribeMacro{\weekfullsunday}
\DescribeMacro{\weekfullmonday}
These commands control which days of the week are displayed.

\begin{verbatim}
\weekworkweek      % Monday through Friday (default)
\weekfullsunday    % Sunday through Saturday (Sunday first)
\weekfullmonday    % Monday through Sunday (Monday first)
\end{verbatim}

Default: work week (Monday--Friday)

\subsection{Minute Lines}

\DescribeMacro{\minutelinesoff}
\DescribeMacro{\minutelinesthirty}
\DescribeMacro{\minutelinesfifteen}
These commands control the display of dashed lines between hours.

\begin{verbatim}
\minutelinesoff      % No minute lines (default)
\minutelinesthirty   % Half-hour lines (e.g., 9:30, 10:30)
\minutelinesfifteen  % Quarter-hour lines (e.g., 9:15, 9:30, 9:45)
\end{verbatim}

Default: no minute lines

\subsection{Event Classes}

\DescribeMacro{\eventclass}
Defines an event class with a name and RGB color. Event classes are used to
categorize events and appear in the legend.

\begin{verbatim}
\eventclass{ClassName}{R,G,B}
\end{verbatim}

The color is specified as three comma-separated RGB values (0--255).
Examples:
\begin{verbatim}
\eventclass{Courses}{173,216,230}        % Light blue
\eventclass{Meetings}{255,218,185}       % Peach
\eventclass{OfficeHours}{144,238,144}    % Light green
\eventclass{Personal}{221,160,221}       % Light purple
\end{verbatim}

\subsection{Events}

\DescribeMacro{\event}
Adds an event to the schedule.

\begin{verbatim}
\event{ClassName}{Event Name}{Days}{Start}{End}
\end{verbatim}

\begin{description}
\item[\texttt{ClassName}] The name of the event class (must be defined with
  \texttt{\textbackslash eventclass} first).
\item[\texttt{Event Name}] The text to display in the event box.
\item[\texttt{Days}] Comma-separated list of days: \texttt{Monday},
  \texttt{Tuesday}, \texttt{Wednesday}, \texttt{Thursday}, \texttt{Friday},
  \texttt{Saturday}, \texttt{Sunday}. Days must match the capitalization
  exactly.
\item[\texttt{Start}] Start time in \texttt{HH:MM} format (24-hour).
\item[\texttt{End}] End time in \texttt{HH:MM} format (24-hour).
\end{description}

Examples:
\begin{verbatim}
\event{Courses}{MATH 220 01}{Tuesday,Thursday}{9:00}{10:30}
\event{Meetings}{Faculty Meeting}{Monday}{10:00}{10:30}
\event{OfficeHours}{Office Hours}{Tuesday,Thursday}{13:00}{14:30}
\end{verbatim}

\subsection{Layout Customization}

\DescribeMacro{\setpadding}
This command allows fine-tuning of the padding around events in the schedule.
It accepts a dimension in centimeters.

\begin{verbatim}
\setpadding{0.08}    % Padding around events (default: 0.08cm)
\end{verbatim}

Note: The day column width and hour row height are automatically calculated
based on the page width and number of days displayed, so they cannot be
manually overridden.

\subsection{Generating the Schedule}

\DescribeMacro{\printschedule}
This command must be called within the \texttt{document} environment to
render the schedule. It draws the grid, places all events, and displays the
legend.

\begin{verbatim}
\begin{document}
\printschedule
\end{document}
\end{verbatim}

\section{Complete Example}

Here is a complete example demonstrating many features:

\begin{verbatim}
\documentclass{weekschedule}

% Title and author
\scheduletitle{Weekly Schedule - Spring 2026}
\scheduleauthor{Douglas B. Rumbaugh}

% Time range
\timefrom{8:00}
\timeto{18:00}

% Display format
\twelvehourtime
\weekfullmonday
\minutelinesthirty

% Define Event Classes
\eventclass{Courses}{173,216,230}        % Light blue
\eventclass{Meetings}{255,218,185}       % Peach
\eventclass{OfficeHours}{144,238,144}    % Light green
\eventclass{Personal}{221,160,221}       % Light purple

% Define Events
\event{Meetings}{CIE Project Meeting}{Monday}{9:00}{9:30}
\event{Meetings}{Faculty Meeting}{Monday}{10:00}{10:30}
\event{Personal}{(Out of Office)}{Monday}{14:30}{17:00}

\event{Courses}{MATH 220 01}{Tuesday,Thursday}{9:00}{10:30}
\event{Courses}{CISC 460 01}{Tuesday,Thursday}{11:15}{12:45}
\event{OfficeHours}{Office Hours}{Tuesday,Thursday}{13:00}{14:30}

\event{Meetings}{Faculty Meeting}{Wednesday}{10:00}{11:00}
\event{Meetings}{Research Meeting}{Wednesday}{14:30}{15:30}

\event{Courses}{CISC 225 01}{Monday,Wednesday,Friday}{11:00}{12:00}
\event{Courses}{GEND 112 01}{Monday,Wednesday,Friday}{13:30}{14:30}

\begin{document}
\printschedule
\end{document}
\end{verbatim}

\section{Notes and Tips}

\subsection{Time Format}
\begin{itemize}
\item Times are always specified in 24-hour format when using
  \texttt{\textbackslash timefrom}, \texttt{\textbackslash timeto}, and
  \texttt{\textbackslash event}, regardless of the display format setting.
\item The display format (12-hour vs. 24-hour) only affects how times appear
  in the schedule labels, not how you specify them.
\end{itemize}

\subsection{Day Names}
\begin{itemize}
\item Day names are case-sensitive and must match exactly: \texttt{Monday},
  \texttt{Tuesday}, \texttt{Wednesday}, \texttt{Thursday}, \texttt{Friday},
  \texttt{Saturday}, \texttt{Sunday}.
\item When using \texttt{\textbackslash weekfullsunday} or
  \texttt{\textbackslash weekfullmonday}, you can include weekends in your
  events.
\item Days in the \texttt{\textbackslash event} command can be listed in any
  order.
\end{itemize}

\subsection{Event Placement}
\begin{itemize}
\item Events that extend beyond the time range specified by
  \texttt{\textbackslash timefrom} and \texttt{\textbackslash timeto} are
  automatically clipped to the visible range.
\item Events are drawn with rounded corners and padding for a clean
  appearance.
\item Long event names will be automatically wrapped within the event box.
\end{itemize}

\subsection{Layout}
\begin{itemize}
\item The document is automatically set to landscape orientation.
\item The schedule automatically adjusts column widths based on the number of
  days displayed.
\item The class uses a minimal page style (no page numbers or headers).
\end{itemize}

\section{Technical Details}

\subsection{Class Options}
The class is based on the \texttt{article} class with landscape orientation
and 11pt font size. These are hardcoded and cannot be changed via class
options.

\subsection{Internal Commands}
All internal commands use the \texttt{@} prefix and should not be called
directly by users. The class uses TikZ for all drawing operations and PGF
mathematics for layout calculations.

\section{Version History}

\begin{description}
\item[Version 1.0 (2026-01-11)] Initial release
  \begin{itemize}
  \item Basic schedule functionality
  \item Support for 12-hour and 24-hour time formats
  \item Multiple week configurations (work week, full week)
  \item Event classes with custom colors
  \item Minute line options
  \item Layout customization options
  \end{itemize}
\end{description}

\section{License}

Copyright \copyright{} 2026, Douglas B. Rumbaugh

This work is licensed under the Modified BSD License (also known as the
3-clause BSD License).

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

\begin{enumerate}
\item Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.

\item Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

\item Neither the name of the copyright holder nor the names of its
  contributors may be used to endorse or promote products derived from this
  software without specific prior written permission.
\end{enumerate}

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

The full license text is also available in the \texttt{LICENSE} file
distributed with this package.

\end{document}