summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-02-08 21:52:29 +0000
committerKarl Berry <karl@freefriends.org>2015-02-08 21:52:29 +0000
commita26b9ff90e587a4678f1c9d38a1d87f04d14c633 (patch)
treebbc2b403b13efd16413e888ee6cd6d6e28b0fd83 /Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex
parent0ab502f9af9ef6849cd94d45fe17d88bda544056 (diff)
jslectureplanner (8feb15)
git-svn-id: svn://tug.org/texlive/trunk@36235 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex')
-rw-r--r--Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex247
1 files changed, 138 insertions, 109 deletions
diff --git a/Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex b/Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex
index 86da67de7d5..eace8e47c81 100644
--- a/Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex
+++ b/Master/texmf-dist/doc/latex/jslectureplanner/jslectureplanner.tex
@@ -29,7 +29,7 @@
\author{Jürgen Spitzmüller%
\thanks{Please report issues via \protect\url{https://github.com/jspitz/jslectureplanner}.}}
-\date{Version 0.8, 2015/01/17}
+\date{Version 0.9, 2015/02/08}
\maketitle
@@ -39,19 +39,19 @@
I have written this package in order to facilitate (and somewhat systematize)
the planning of my university courses. The basic idea of this package
-is that you write all general data of a course (date, semester, type,
-course title, session titles, general information etc.) into a central
-tex file (e.\,g., \emph{metadata.tex}), and then input this file
-into all documents related to the course (course program, bibliography,
-scripts, handouts, beamer presentations, exercises etc.), in order
-to re-use the data. This is particularly helpful if you have standard
-courses which are held every other semester: instead of changing the
-data in every single file, you just need to change it once, in the
-metadata file.
+is that you record all general data of a course (date, semester, type,
+course title, session titles, general information etc.) in a central
+tex file and then input this file to all documents related to the
+course (such as the course program, bibliography, scripts, handouts, beamer
+presentations, exercises etc.), in order to re-use the recorded data.
+This is particularly helpful if you have standard courses which
+are held every other semester: instead of changing the data in every
+single file, you just need to change it once, in the metadata file.
To further facilitate the planning, the package is able to calculate
-the session dates of a whole semester, if the course is held weekly.
-You only need to set the date of the first lecture, the package does
+the session dates of a whole semester, if the sessions of the course
+follow at regular intervals.
+You only need to set the date of the first session, the package does
the rest. Moreover, the package can be used to generate a sectioned
bibliography for the course via \textsf{biblatex}.
@@ -63,9 +63,9 @@ formats are German. However, it is possible to customize them to some
degree, particularly to translate them to other languages. This is
described later in this manual.
-This manual describes the basic user interface of the package. You
-might want to have a look at the example file included in the package
-in order to see how it is supposed to be used.
+This manual describes the basic user interface of the package. Please
+also refer to the example files included in the package in order to
+see how it is supposed to be used ``in practice''.
\section{Requirements}
@@ -79,12 +79,17 @@ The following packages are required: \textsf{etoolbox}, \textsf{advdate},
The general idea goes as follows:
\begin{itemize}
\item Set up a \emph{metadata.tex} file (or whatever name you prefer) and
-insert all meta information of the course there (as described in sec.~\ref{sec:course-metadata}
+record all meta information of the course in it (as described in sec.~\ref{sec:course-metadata}
and \ref{sec:lecplan}).
\item In your documents, load the package (\jcsmacro{usepackage\{jslectureplanner\}})
-and then input the metadata file (\jcsmacro{input\{metadata.tex\}}).
-\item Then use the macros described below (sec.~\ref{sec:general-course-info}
-and \ref{sec:session-specific-info}) to retrieve the respective data.
+and/or%
+\footnote{If you prefer to record the data via package options
+(see sec.~\ref{sub:package-options}) instead of macros (see sec.~\ref{sec:via-macros}),
+you need to load the package in the metadata file itself.}
+ input the metadata file (\jcsmacro{input\{metadata.tex\}}).
+\item Finally, use the macros described in sec.~\ref{sec:general-course-info}
+and \ref{sec:session-specific-info} to retrieve the respective data and re-use
+the recorded information in your documents.
\end{itemize}
The procedure is detailed in the following sections.
@@ -98,6 +103,7 @@ or via specific macros (see sec.~\ref{sec:via-macros}).
\subsection{Via package options\label{sub:package-options}}
+\jcsmacro{usepackage[<comma-separated options>]\{jslectureplanner\}}
\subsubsection{Course classification\label{sec:lecture-classification}}
@@ -107,31 +113,30 @@ to a verbose string (such as ``Seminar''), a short form (such as
``SE'') and a form that is used to denote individual sessions (as
in ``the second \emph{session} of this course'').
\begin{description}
-\item [{type=<type>,}] where \joption{<type>} is one of
+\item [{type=<type>}] Defines the course type. Possible values:
\begin{itemize}
-\item \joption{vl}: a lecture (verbose form: ``Vorlesung''\footnote{Sec.~\ref{sec:customizing-strings}
+\item \joption{vl}: A lecture (verbose form: ``Vorlesung''\footnote{Sec.~\ref{sec:customizing-strings}
explains how to customize these strings.}, short form: ``VL'', session form: ``Vorlesung'')
-\item \joption{ps}: undergraduate seminar (verbose form: ``Proseminar'',
+\item \joption{ps}: Undergraduate seminar (verbose form: ``Proseminar'',
short form: ``PS'', session form: ``Sitzung'')
-\item \joption{se}: seminar (verbose form: ``Seminar'', short form: ``SE'',
+\item \joption{se}: Seminar (verbose form: ``Seminar'', short form: ``SE'',
session form: ``Sitzung'')
-\item \joption{ue}: practical course (verbose form: ``Übung'', short
+\item \joption{ue}: Practical course (verbose form: ``Übung'', short
form: ``UE'', session form: ``Sitzung'')
-\item \joption{ko}: colloquium (verbose form: ``Kolloquium'', short form:
+\item \joption{ko}: Colloquium (verbose form: ``Kolloquium'', short form:
``KO'', session form: ``Sitzung'')
-\item \joption{pv}: research seminar (verbose form: ``Privatissimum'',
+\item \joption{pv}: Research seminar (verbose form: ``Privatissimum'',
short form: ``PV'', session form: ``Sitzung'')
\end{itemize}
\end{description}
\subsubsection{Course title}
\begin{description}
-\item [{title=<title>}] Title of the course
+\item [{title=<title>}] Main title of the course
\item [{titlesep=<separator>}] Separator between title and subtitle
\item [{subtitle=<subtitle>}] Subtitle of the course
-\item [{shorttitle=<shorttitle>}] Short title of the course (for headings
-etc.)
+\item [{shorttitle=<shorttitle>}] Short title of the course (for headings etc.)
\end{description}
\subsubsection{Date and place\label{sec:date-and-place}}
@@ -139,29 +144,30 @@ etc.)
\item [{semester=<term>,}] where \joption{<term>} is one of
\begin{itemize}
-\item \joption{fs}: spring term (``Frühjahrssemester'', short form: ``FS'')
-\item \joption{hs}: fall term (``Herbstsemester'', short form: ``HS'')
-\item \joption{ss}: summer term (``Sommersemester'', short form: ``SoSe'')
-\item \joption{ws}: winter term (``Wintersemester'', short form: ``WS'')
+\item \joption{fs}: Spring term (``Frühjahrssemester'', short form: ``FS'')
+\item \joption{hs}: Fall term (``Herbstsemester'', short form: ``HS'')
+\item \joption{ss}: Summer term (``Sommersemester'', short form: ``SoSe'')
+\item \joption{ws}: Winter term (``Wintersemester'', short form: ``WS'')
\end{itemize}
\item [{year=<year>}]~
\item [{uni=<university>}]~
\item [{institute=<institute>}]~
\item [{room=<room>}]~
\item [{startdate=<startdate>}] Date of the first session (argument\emph{
-must} have the form DD/MM/YYYY).
+must} have the form DD/MM/YYYY). If no startdate is given, \jfcsmacro{today} is used.
+\item [{interval=<interval>}] Interval (in days) between two sessions.
+ The preset interval is 7 (=~weekly courses).
\end{description}
\subsubsection{Additional information}
\begin{description}
-\item [{platform=<url>}] information (e.g., URL) of the e-learning platform
-\item [{officehours=<data>}] date of the office hours
+\item [{platform=<data>}] Information (e.\,g., URL) of the e-learning platform
+\item [{officehours=<data>}] Date of your office hours
\end{description}
\subsection{Via macros\label{sec:via-macros}}
-The following macros provide an alternative interface to set up the course metadata described in the previous
-subsection.
+The following macros provide an alternative interface to set up the course metadata.
\subsubsection{Course classification}
\begin{itemize}
@@ -170,127 +176,144 @@ subsection.
description.}
\begin{itemize}
-\item \joption{vl}: lecture (\emph{Vorlesung})
-\item \joption{ps}: undergraduate seminar (\emph{Proseminar})
-\item \joption{se}: seminar (\emph{Seminar})
-\item \joption{ue}: practical course (\emph{Übung})
-\item \joption{ko}: colloquium (\emph{Kolloquium})
-\item \joption{pv}: research seminar (\emph{Privatissimum})
+\item \joption{vl}: Lecture (\emph{Vorlesung})
+\item \joption{ps}: Undergraduate seminar (\emph{Proseminar})
+\item \joption{se}: Seminar (\emph{Seminar})
+\item \joption{ue}: Practical course (\emph{Übung})
+\item \joption{ko}: Colloquium (\emph{Kolloquium})
+\item \joption{pv}: Research seminar (\emph{Privatissimum})
\end{itemize}
\end{itemize}
\subsubsection{Course title}
\begin{itemize}
-\item \jcsmacro{LecTitle{[}<options>{]}\{<title>\}}: Set
-course title; \joption{<options>} might be any set of package options
-described in sec.~\ref{sub:package-options}
-\item \jcsmacro{LecTitleSep\{<title separator>\}}: Set course
-title-subtitle separator
-\item \jcsmacro{LecSubTitle\{<subtitle>\}}: Set course subtitle
+\item \jcsmacro{LecTitle[<package options>]\{<title>\}}: Record course title and options;
+\joption{<package options>} might be any set of package options described
+in sec.~\ref{sub:package-options} (except for \joption{title} itself),
+so this macro can actually be used to record all metadata.
+\item \jcsmacro{LecTitleSep\{<title separator>\}}: Specify course
+title-subtitle separator (e.\,g., ``. '' or `` -- '')
+\item \jcsmacro{LecSubTitle\{<subtitle>\}}: Record course subtitle
\end{itemize}
\subsubsection{Date and place}
\begin{itemize}
-\item \textbackslash{}\jmacro{LecYear\{<term>\}\{<year>\}}, Set term and
+\item \textbackslash{}\jmacro{LecYear\{<term>\}\{<year>\}}, Record term and
year of the course; \joption{<term>} is one of\footnote{See above sec.~\ref{sec:date-and-place} for a detailed
description.}
\begin{itemize}
-\item \joption{fs}: spring term (\emph{Frühjahrssemester})
-\item \joption{hs}: fall term (\emph{Herbstsemester})
-\item \joption{ss}: summer term (\emph{Sommersemester})
-\item \joption{ws}: winter term (\emph{Wintersemester})
+\item \joption{fs}: Spring term (\emph{Frühjahrssemester})
+\item \joption{hs}: Fall term (\emph{Herbstsemester})
+\item \joption{ss}: Summer term (\emph{Sommersemester})
+\item \joption{ws}: Winter term (\emph{Wintersemester})
\end{itemize}
-\item \jcsmacro{LecUni\{<university>\}}: Set the name of
+\item \jcsmacro{LecUni\{<university>\}}: Record the name of
your university
-\item \jcsmacro{LecInstitute\{<institute>\}}: Set your institute
-name
-\item \jcsmacro{LecRoom\{<room>\}}: Set the room where the course takes place
+\item \jcsmacro{LecInstitute\{<institute>\}}: Record your institute's name
+\item \jcsmacro{LecRoom\{<room>\}}: Record the room where the course takes place
\item \jcsmacro{LecStartDate\{<startdate>\}}: Set date of
-the first session (argument\emph{ must} have the form DD/MM/YYYY).
+the first session (argument\emph{ must} have the form DD/MM/YYYY)
+\item \jcsmacro{LecInterval\{<interval>\}}: Adjust the interval (in days) between two sessions.
+ The preset interval is 7 (=~weekly courses).
\end{itemize}
\subsubsection{Additional information}
\begin{itemize}
-\item \jcsmacro{SetOfficeHours\{<office hours>\}}: Set date
-of your office hours
-\item \jcsmacro{SetPlatform\{<platform information>\}}: Set
-information (e.g., URL) of the e-learning platform
+\item \jcsmacro{SetOfficeHours\{<office hours>\}}: Record date of your office hours
+\item \jcsmacro{SetPlatform\{<platform information>\}}: Record information
+(e.\,g., URL) of the e-learning platform
\end{itemize}
-\section{Setting up a course plan\label{sec:lecplan}}
+\clearpage
-In the metadata file, you can setup a plan for the course by entering
+\section{Setting up a course schedule\label{sec:lecplan}}
+
+In the metadata file, you can set up a schedule for the course by entering
session information in chronological order. This is done via the following
macro:
\begin{itemize}
-\item \jcsmacro{NewSession{[}<options>{]}\{Session title\}}
+\item \jcsmacro{NewSession[<options>]\{Session title\}}
-\joption{<options>} include:
+Valid \joption{<options>}:
\begin{itemize}
\item \joption{titlesep=<separator>}: Separator between session title and
-subtitle
+ subtitle
\item \joption{subtitle=<subtitle>}: Subtitle of the session
\item \joption{shorttitle=<shorttitle>}: Short title of the session (for
-headings etc.)
-\item \joption{room=<room>}: Specific room for this session (if it differs)
+ headings etc.)
+\item \joption{room=<room>}: Specific room for this session (if it differs
+ from the usual course room)
\item \joption{bibsec=<keyword>}: Session keyword for the bibliography
-(see below sec.~\ref{sub:bibliographies})
-\item \joption{cancel=<true|false>}: Whether this session takes place.
-If you specify \joption{cancel=true}, the program will mark the
-session as ``canceled''. For instance,
-
-
-\jcsmacro{NewSession{[}cancel=true{]}\{Dies Academicus\}}
+ (see below sec.~\ref{sub:bibliographies} for its use)
+\item \joption{cancel=<true|false>}: Marks this session as ``canceled''.
+ If you specify \joption{cancel=true}, the session will be printed
+ in the program in bold type and appended by a verbal comment.
+ For example,
+\jcsmacro{NewSession[cancel=true]\{Dies Academicus\}}
-will output something like
+will expand to
\begin{quote}
\textbf{15.\,05.: Dies Academicus -- keine Sitzung}
\end{quote}
-(i.\,e., ``Dies Academicus -- no session'')
+(i.\,e., ``Dies Academicus -- no session'').
-\end{itemize}
-\item \jcsmacro{SetBreak{[}<span>{]}\{Reason\}}: Add a semester
-break (e.g., holidays). This increments the counter for one week and
-outputs in the program
+Furthermore, a canceled session is not counted in the session counter
+that is used to retrieve session-specific information
+(see below sec.~\ref{sec:session-specific-info}).
+\end{itemize}
+\item \jcsmacro{SetBreak[<span>]\{Break\}}: Add a semester break
+(e.\,g., holidays) that affects one session. The macro increments
+the internal counters respectively and expands in the program to
\begin{center}
-\textbf{(<span>: Reason)}
+\textbf{(Break)}
\par\end{center}
-
-E.\,g., \jcsmacro{SetBreak{[}28.05.-{}-3.06.{]}\{Whitsun holidays\}}
-expands to
-
+By means of the optional argument, the real time span of the break
+might be given if you want to print it on the program. If you pass
+an optional argument \joption{<span>}, the macro will expand to
\begin{center}
-\textbf{(28.05.--3.06.: Whitsun holidays)}
+\textbf{(<span>: Break)}
\par\end{center}
-\item \jcsmacro{SetBreaks{[}<options>{]}\{Reason\}}: Add
-a semester break (e.g., holidays) that is longer than one week. This
-increments the counter respectively, and outputs in the program
+E.\,g., \jcsmacro{SetBreak[28.05.-{}-3.06.]\{Whitsun holidays\}}
+expands to
\begin{center}
-\textbf{(<span>: Reason)}
+\textbf{(28.05.--3.06.: Whitsun holidays)}
\par\end{center}
+\item \jcsmacro{SetBreaks[<options>]\{Break\}}: Add
+a semester break that affects more than one session (e.\,g., two-week holidays).
+The output in the program is identical to the \jcsmacro{SetBreak} macro,
+but the counter incrementation can be adjusted to the needed time span.
-\jmacro{<options>} include:
+Possible \jmacro{<options>} are:
\begin{itemize}
-\item \joption{weeks=<int>}: Number of weeks the break takes (to increment
-the internal counter that is used to calculate the session dates)
-\item \joption{span=<time span>}: time span (to be output on the program)
+\item \joption{units=<n>}: Number of interval units the break takes. One \emph{unit}
+ is the number of days as specified by the \joption{interval} option (one week by
+ default\footnote{The former option \joption{weeks} is deprecated as of v. 0.9,
+ since the interval can be adjusted now.}).
+ This value is needed in order to increment the internal counter that is used to
+ calculate the session dates. If \joption{units} is not specified, the counter is
+ incremented by one.\footnote{That is: \jcsmacro{SetBreak\{Break\}} =
+ \jcsmacro{SetBreaks\{Break\}} = \jcsmacro{SetBreaks[units=1]\{Break\}}.}
+ <n> must be a positive integer.
+\item \joption{span=<span>}: Real time span (verbally output on the program)
\end{itemize}
+\item \jcsmacro{SetLecOffset\{<n>\}}: Shift the date of all subsequent sessions by <n> days.
+ <n> can also be negative.
\item \jcsmacro{SetBeamerFrameBreak}: Add a frame break in
-the beamer program at this position. This also increments the frame
-counter which is used for subsequent program frame titles. Note that
-you can insert maximally 3 breaks.
+the beamer program at this position (more precisely, start a new frame).
+This also increments the frame counter which is used for subsequent program
+frame titles. Note that you can insert maximally 3 breaks.
\item \jcsmacro{SetBeamerHook\{<code>\}}: Add arbitrary \LaTeX{}
code to the beamer program
\item \jcsmacro{begin\{SessionBlock\}\{<Block title>\}}\\
@@ -303,7 +326,7 @@ are nested inside this block.
\section{Retrieving general course information\label{sec:general-course-info}}
Once the metadata file is set up as documented above and input to
-your document(s), you can retrieve the recorded as well as concatenated
+your document(s), you can retrieve the recorded as well as some concatenated
information by means the following macros.
@@ -336,18 +359,18 @@ of the term type (e.\,g., ``Wintersemester'')
the semester (e.\,g., ``WS 2014'')
\item \jcsmacro{lecsemesterverb}: Outputs the verbose version
of the semester (e.\,g., ``Wintersemester 2014'')
-\item \jcsmacro{lecuniversity}: Outputs the university name
-\item \jcsmacro{lecinstitute}: Outputs the institute name
-\item \jcsmacro{lecroom}: Outputs the room
+\item \jcsmacro{lecuniversity}: Outputs the university's name
+\item \jcsmacro{lecinstitute}: Outputs the institute's name
+\item \jcsmacro{lecroom}: Outputs the course room
\item \jcsmacro{lecplatform}: Outputs information on the
e-learning platform
\item \jcsmacro{officehours}: Outputs the office hours
\end{itemize}
-\subsection{Generating lecture programs}
+\subsection{Generating course programs}
\label{sec:lecprog}
\begin{itemize}
-\item \jcsmacro{makeprogram}: Generates a lecture program
+\item \jcsmacro{makeprogram}: Generates a course program
from the metadata in the form
@@ -366,7 +389,7 @@ from the metadata in the form
The \jmacro{labeling} environment is defined by the KOMA classes.
The package provides a fallback, however, if another class is used.
-\item \jcsmacro{makebeamerprogram{[}<options>{]}}: Generates
+\item \jcsmacro{makebeamerprogram[<options>]}: Generates
a beamer-suited lecture program from the metadata in the form
@@ -422,6 +445,7 @@ So if you specify your session with a keyword via the \joption{bibsec}
option, and tag your Bib\TeX{} database entries with that keyword,
you will get a list of session-specific literature.
+\clearpage
\section{Retrieving session-specific information\label{sec:session-specific-info}}
@@ -432,7 +456,7 @@ to the current session. This is done as follows.
\subsection{Setting the current session}
Use \jcsmacro{ThisSession\{<nr>\}} to tell the package
-which session is current. \joption{<nr>} is an integer value, e.g.
+which session is current. \joption{<nr>} is an integer value, e.\,g.
\jcsmacro{ThisSession\{3\}} for the 3rd session of
the lecture.
@@ -579,6 +603,11 @@ them for inclusion to the package.
\section{History}
\begin{itemize}
+\item 2015/02/08 (v. 0.9): Add a way to adjust the interval between two sessions
+ (\joption{interval} package option and \jcsmacro{LecInternal} macro); add a way to shift
+ session dates from the regular interval (\jcsmacro{SetLecOffset}); rename option \joption{weeks}
+ of the \jcsmacro{SetBreaks} macro to \joption{units} (\joption{weeks} still works, but is
+ marked deprecated).
\item 2015/01/17 (v. 0.8): Fix corruption of \jfcsmacro{today};
add framework for different styles;
add option and macro to set a room for the course as well as a session-specific room;