summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-29 23:28:32 +0000
committerKarl Berry <karl@freefriends.org>2013-04-29 23:28:32 +0000
commitf39ecf357dcabe86d7841b9b1f0226ff23936bf5 (patch)
treefee982fb4da3128b566743698b2496bdc98a5b36 /Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
parent2e581c28cb4e1f20cd408c0bdc9885c7f18f9e5e (diff)
exsheets (29apr13)
git-svn-id: svn://tug.org/texlive/trunk@30166 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/exsheets/tasks_en.tex')
-rw-r--r--Master/texmf-dist/doc/latex/exsheets/tasks_en.tex564
1 files changed, 564 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
new file mode 100644
index 00000000000..7bc73eaac63
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
@@ -0,0 +1,564 @@
+% arara: pdflatex
+% arara: biber
+% arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the TASKS package
+%
+% horizontal columned lists
+%
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: https://bitbucket.org/cgnieder/exsheets/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2011-2013 Clemens Niederberger
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The tasks package is part of the exsheets bundle
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+%
+% if you want to compile this documentation you'll need the document class
+% `cnpkgdoc' which you can get here:
+% https://bitbucket.org/cgnieder/cnpkgdoc/
+% the class is licensed LPPL 1.3 or later
+%
+% use `pdflatex' and `biber' for compilation
+%
+\PassOptionsToPackage{supstfm=libertinesups}{superiors}
+\documentclass[DIV9,toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc}
+% ----------------------------------------------------------------------------
+% document layout and typographic features
+\docsetup{
+ pkg = {[more]tasks} ,
+ url = {https://bitbucket.org/cgnieder/exsheets/} ,
+ title = \Tasks ,
+ subtitle = {{\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip]create horizontal columned lists} ,
+ name = tasks ,
+ language = en ,
+ modules = true ,
+ code-box = {
+ backgroundcolor = gray!7!white ,
+ skipbelow = .6\baselineskip plus .5ex minus .5ex ,
+ skipabove = .6\baselineskip plus .5ex minus .5ex ,
+ innerleftmargin = 1.5em ,
+ innerrightmargin = 2.5em
+ } ,
+ gobble = 1
+}
+\usepackage{libertinehologopatch}
+\cnpkgusecolorscheme{friendly}
+
+\usepackage[biblatex]{embrac}[2012/06/29]
+ \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+ \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+\usepackage{microtype}
+\usepackage[multiple]{fnpct}
+
+\renewcommand*\othersectionlevelsformat[3]{\textcolor{main}{#3\autodot}\enskip}
+\renewcommand*\partformat{\textcolor{main}{\partname~\thepart\autodot}}
+
+\pagestyle{headings}
+
+\setcapindent{1.5em}
+\setkomafont{caption}{\normalfont\footnotesize\sffamily}
+\setkomafont{captionlabel}{\normalfont\footnotesize\sffamily\scshape}
+
+\usepackage{booktabs,array,ragged2e}
+
+% ----------------------------------------------------------------------------
+% code examples
+\newcommand*\Tasks{{\scshape\textcolor{main}{tasks}}\xspace}
+\newcommand*\ExSheets{{\scshape\textcolor{main}{ExSheets}}\xspace}
+
+\addcmds{
+ choice, correct,
+ DeclareInstance, DeclareTemplateInterface,
+ leftthumbsup, NewTasks,
+ s, sample, settasks, task
+}
+
+% ----------------------------------------------------------------------------
+% other packages, bibliography, index
+\usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx}
+\usepackage[accsupp]{acro}
+\DeclareAcronym{id}{
+ short = id ,
+ long = Identifier ,
+ format = \scshape ,
+ pdfstring = ID ,
+ accsupp = ID
+}
+
+\usepackage{filecontents}
+\usepackage{imakeidx}
+\begin{filecontents*}{\jobname.ist}
+ heading_prefix "{\\bfseries "
+ heading_suffix "\\hfil}\\nopagebreak\n"
+ headings_flag 1
+ delim_0 "\\dotfill\\hyperpage{"
+ delim_1 "\\dotfill\\hyperpage{"
+ delim_2 "\\dotfill\\hyperpage{"
+ delim_r "}\\textendash\\hyperpage{"
+ delim_t "}"
+ suffix_2p "\\nohyperpage{\\,f.}"
+ suffix_3p "\\nohyperpage{\\,ff.}"
+\end{filecontents*}
+\indexsetup{othercode=\footnotesize}
+\makeindex[options={-s \jobname.ist},intoc,columns=3]
+
+\usepackage{csquotes}
+\usepackage[backend=biber,style=alphabetic]{biblatex}
+
+
+% ----------------------------------------------------------------------------
+% example definitions that have to be done in the preamble:
+\usepackage{exsheets}
+\usepackage{dingbat}
+\NewTasks[style=multiplechoice]{choices}[\choice](3)
+\newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
+
+% ----------------------------------------------------------------------------
+% custom commands
+\newcommand*\Default[1]{%
+ \hfill\llap
+ {%
+ \ifblank{#1}%
+ {(initially~empty)}%
+ {Default:~\code{#1}}%
+ }%
+ \newline
+}
+\newcommand*\required{\hfill\llap{required}\newline}
+\newcommand*\optional{\hfill\llap{optional}\newline}
+
+\newcommand*\nooption[2]{\item[\code{\textcolor{key}{#1} = #2}] \cnpkgdocarrow\ }
+
+\newcommand*\unexpsign{$\RHD$}
+\newcommand*\expsign{\textcolor{red}{$\rhd$}}
+\renewcommand*\cnpkgdoctriangle{\unexpsign}
+\newcommand*\expandable{%
+ \def\cnpkgdoctriangle{%
+ \expsign
+ \gdef\cnpkgdoctriangle{\unexpsign}}}
+
+\usepackage{marginnote}
+\makeatletter
+\newcommand*\sinceversion[1]{%
+ \@bsphack
+ \marginnote{%
+ \footnotesize\sffamily\RaggedRight
+ \textcolor{black!75}{Introduced in version~#1}}%
+ \@esphack}
+\newcommand*\changedversion[1]{%
+ \@bsphack
+ \marginnote{%
+ \footnotesize\sffamily\RaggedRight
+ \textcolor{black!75}{Changed in version~#1}}%
+ \@esphack}
+\makeatother
+
+\pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}}
+
+% ----------------------------------------------------------------------------
+% title page
+% \TitlePicture{%
+% \parbox{.8\linewidth}{%
+% }%
+% }
+
+\def\s{This is some sample text we will use to create a somewhat
+ longer text spanning a few lines.}
+\def\sample{\s\ \s\par\s}
+
+\begin{document}
+
+\section{Motivation}\secidx{Motivation}
+\noindent\changedversion{0.7}Originally \Tasks has been an integral part of
+\ExSheets. However, users told me that it indeed could be useful to have it as a
+stand-alone package not having to load the whole \ExSheets beast just for having
+the \code{tasks} environment available. Since I agree with this the environment
+has been extracted into a package if its own, \Tasks.
+
+The reason for the \code{tasks} environment is an unwritten agreement in German
+maths textbooks (in (junior) high school, especially) to organize exercises in
+columns counting horizontally rather than vertically. That is what \code{tasks}
+primarily is for. If you don't need this feature you're better off using traditional
+\LaTeX{} lists and the \paket{enumitem} package for customization.
+\secidx*{Motivation}
+
+\section{License and Requirements}\label{sec:license}\secidx{Requirements}
+\Tasks is placed under the terms of the \LaTeX{} Project Public License,
+version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}). It has the
+status ``maintained.''
+
+\Tasks requires packages \paket{l3kernel} ,\paket{xparse}, \paket{l3keys2e},
+\paket{epic}, \paket*{cntformats}\footnote{Part of the \ExSheets bundle},
+\paket{xtemplate} and \paket{environ}.
+\secidx*{Requirements}
+
+\section{How it works}
+\subsection{The Basics}
+The \code{tasks} environment is similar to a list like \code{enumerate} but not
+the same:
+\begin{itemize}
+ \item The first difference: there is no pagebreak possible inside an item but
+ only between items.
+ \item The second difference: the enumeration default is a), b), c) \ldots
+ \item The third difference: there is a split at \emph{every} occurrence of the
+ item separator. For this reason the default separator is not \cmd*{item} but
+ \cmd{task} so it is unique to this environment only.
+ \item The fourth difference: the \code{tasks} environment cannot be nested. You
+ can, however, use an \code{itemize} environment or something in it.
+ \item The fifth difference: verbatim material cannot be used in it. You'll
+ have to use \cmd*{string}, \cmd*{texttt} or \cmd*{detokenize}. If this won't
+ suffice then don't use \code{tasks}.
+\end{itemize}
+
+\begin{beschreibung}
+ \Umg{tasks}[<options>]{\unskip\da{<num of columns>} \cmd{task}\ldots}
+\end{beschreibung}
+Let's see an example:
+\begin{beispiel}[code only]
+ % \sample is defined to contain some sample text:
+ % \def\s{This is some sample text we will use to create a somewhat
+ % longer text spanning a few lines.}
+ % \def\sample{\s\ \s\par\s}
+ Some text before the list.
+ \begin{tasks}
+ \task \sample
+ \task \sample
+ \task \sample
+ \end{tasks}
+ And also some text after it.
+\end{beispiel}
+Some text before the list.
+\begin{tasks}
+ \task \sample
+ \task \sample
+ \task \sample
+\end{tasks}
+And also some text after it.
+
+The environment takes the optional argument \da{<num of columns>} with which the
+number of columns used by the environment is specified.
+\begin{beispiel}[code only]
+ \begin{tasks}(2)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}(2)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+\end{tasks}
+
+\subsection{Introducing a New Row}
+\noindent\sinceversion{0.9}Sometimes it may come in handy if the current
+row of items could be terminated and a new one is started. This is possible
+with the following command:
+\begin{beschreibung}
+ \Befehl{startnewitemline}
+\end{beschreibung}
+\begin{beispiel}[code only]
+ \begin{tasks}(4)
+ \task the first
+ \task the second
+ \task the third
+ \task the fourth
+ \task \rlap{the fifth item is way too long for this so we start a new row} \startnewitemline
+ \task the sixth
+ \task the seventh
+ \task \rlap{the eighth item also is too long} \startnewitemline
+ \task the nineth
+ \task the tenth
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}(4)
+ \task the first
+ \task the second
+ \task the third
+ \task the fourth
+ \task \rlap{the fifth item is way too long for this so we start a new row} \startnewitemline
+ \task the sixth
+ \task the seventh
+ \task \rlap{the eighth item also is too long} \startnewitemline
+ \task the nineth
+ \task the tenth
+\end{tasks}
+
+\section{Available Options}\secidx{Options}\label{sec:tasks:options}
+The \Tasks package has one package option which also is called when you load
+\ExSheets with the \key{load-tasks} option.
+\begin{beschreibung}
+ \Option{more}\newline
+ load additional instances for the \code{tasks} object, details are explained
+ later in section~\ref{sec:tasks:instances}.
+\end{beschreibung}
+
+The environment itself has some more options, namely these:
+\begin{beschreibung}
+ \Option{style}{<instance>}\Default{}
+ Choose the instance to be used. Read more on this in section~\ref{sec:tasks}.
+ \Option{counter-format}{<counter specs>}\Default{}
+ \sinceversion{0.9}Sets a custom label. The letters \code{tsk} are replaced
+ with the task-counter. An optional argument directly following these letters
+ specifies the counter format: \code{1}: \cmd{arabic}, \code{a}: \cmd{alph},
+ \code{A}: \cmd{Alph}, \code{r}: \cmd{roman} and \code{R}: \cmd{Roman}.
+ \Option{label-format}{<code>}\Default{}
+ \changedversion{0.9}Can be used to apply a formatting like, \emph{e.g.},
+ \cmd*{bfseries} to the labels.
+ \Option{label}{<code>}\Default{}
+ \changedversion{0.9}Overwrite the automatic label to a custom one.
+ \Option{label-width}{<dim>}\Default{1em}
+ Sets the width of the item labels.
+ \Option{label-offset}{<dim>}\Default{.3333em}
+ \sinceversion{0.7}Sets the offset, \emph{i.e.}, the distance between label and item.
+ \Option{item-indent}\Default{2.5em}
+ \sinceversion{0.9a}The indent of an item, \textit{i.e.}, the horizontal space
+ available for both label and label-offset. If \code{indent = label-width + label=offset}
+ the label will align with the textblock above (if \key{label-align}{left} is
+ set).
+ \Option{label-align}{left|right|center}\Default{left}
+ \sinceversion{0.7}Determines how the labels are aligned within the label-box
+ whose width is set with \key{label-width}
+ \Option{before-skip}{<skip>}\Default{0pt}
+ Sets the skip before the list.
+ \Option{after-skip}{<skip>}\Default{0pt}
+ Sets the skip after the list.
+ \Option{after-item-skip}{<skip>}\Default{1ex plus 1ex minus 1ex}
+ \sinceversion{0.9}This vertical skip is inserted between rows of items.
+ \Option{resume}{\default{true}|false}\Default{false}
+ The enumeration will resume from a previous \code{tasks} environment. In order
+ to use this option properly you shouldn't mix different \code{tasks} environments
+ that both count their items.
+\end{beschreibung}
+These options can also be set using a setup command:
+\begin{beschreibung}
+ \Befehl{settasks}{<options>}
+\end{beschreibung}
+
+Now the same list as above but with three columns and a different label:
+\begin{beispiel}[code only]
+ \begin{tasks}[counter-format=(tsk[r]),label-width=4ex](3)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}[counter-format=(tsk[r]),label-width=4ex](3)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+\end{tasks}
+
+Let's use it inside a question, \textit{i.e.}, inside \ExSheets' \code{question}
+environment:
+\begin{beispiel}
+ % since settings are local the following ones will be lost
+ % outside this example;
+ \settasks{
+ counter-format = qu.tsk ,
+ item-indent = 2em ,
+ label-width = 2em ,
+ label-offset = 0pt
+ }
+ \begin{question}[type=exam]{4}
+ I have these two tasks for you. Shall we begin?
+ \begin{tasks}(2)
+ \task The first task: easy!
+ \task The second task: even more so!
+ \end{tasks}
+ \end{question}
+ \begin{solution}[print]
+ Now, let's see\ldots\ ah, yes:
+ \begin{tasks}
+ \task This is the first solution. Told you it was easy.
+ \task This is the second solution. And of course you knew that!
+ \end{tasks}
+ \end{solution}
+\end{beispiel}
+\secidx*{Options}
+
+\section{Available Instances}\label{sec:tasks:instances}
+When you use the package option \key{more} of the \Tasks package or load \ExSheets
+with the \key{load-tasks} option there are currently three additional instances
+for the \code{tasks} object available:
+\begin{description}
+ \item[itemize] uses \cmd{labelitemi} as labels.
+ \item[enumerate] enumerates the items with 1., 2., \ldots
+ \item[multiplechoice] a --~well~-- `multiple choice' list.
+\end{description}
+\begin{beispiel}
+ \begin{tasks}[style=itemize](2)
+ \task that's just how\ldots
+ \task \ldots we expected
+ \end{tasks}
+ \begin{tasks}[style=enumerate](2)
+ \task that's just how\ldots
+ \task \ldots we expected
+ \end{tasks}
+ \begin{tasks}[style=multiplechoice](2)
+ \task that's just how\ldots
+ \task \ldots we expected
+ \end{tasks}
+\end{beispiel}
+
+\section{Custom Labels}\secidx{Custom Labels}
+If you want to change a single label inside a list, you can use the optional
+argument of \cmd{task}. This will temporarily overwrite the default label.
+\begin{beispiel}
+ \begin{tasks}[style=itemize]
+ \task a standard item
+ \task another one
+ \task[+] a different one
+ \task and another one
+ \end{tasks}
+\end{beispiel}
+\secidx*{Custom Labels}
+
+\section{New Tasks}\secidx{Own Environments}
+It is possible to add custom environments that work like the \code{tasks} environment.
+\begin{beschreibung}
+ \Befehl{NewTasks}[<options>]{<name>}\oa{<separator}\da{<cols>}\newline
+ Define environment \ma{<name>} that uses \code{<separator>} to introduce a
+ new item. Default for \code{<separator>} is \cmd{task}, default for
+ \code{<cols>} is \code{1}. The \code{<options>} are the ones described in
+ section~\ref{sec:tasks:options}.
+ \Befehl{RenewTasks}[<options>]{<name>}\oa{<separator}\da{<cols>}\newline
+ Renew environment previously defined with \cmd{NewTasks}.
+\end{beschreibung}
+The \code{tasks} environment is defined as follows:
+\begin{beispiel}[code only]
+ \NewTasks{tasks}
+\end{beispiel}
+
+The separator does not have to be a control sequence:
+\begin{beispiel}
+ % preamble:
+ % \usepackage{dingbat}
+ \NewTasks[label=\footnotesize\leftthumbsup,label-width=1.3em]{done}[*]
+ \begin{done}
+ * First task
+ * Second Task
+ \end{done}
+\end{beispiel}
+Although this might seem handy or even nice I strongly advice against using
+something different than a command sequence. Remember that the items will be
+split at \emph{every} occurrence of the separator. So in order to use the
+separator (here for example for a starred variant of a command) within an item
+it has to be hidden in braces. This is avoided of you use a command sequence
+which even doesn't have to be defined.
+
+Let's say you want a \code{choices} environment that has three columns in its
+default state. You could do something like this:
+\begin{beispiel}
+ % preamble:
+ % \NewTasks[style=multiplechoice]{choices}[\choice](3)
+ % \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
+ %
+ % \PrintSolutionsTF and the {question} environment are provided
+ % by the ExSheets package
+ \begin{question}
+ \begin{choices}
+ \choice First choice
+ \choice Second choice
+ \choice[\correct] Third choice
+ \end{choices}
+ \end{question}
+ \begin{solution}[print]
+ \begin{choices}
+ \choice First choice
+ \choice Second choice
+ \choice[\correct] Third choice
+ \end{choices}
+ \end{solution}
+\end{beispiel}
+
+The last example shows you two additional commands:
+\begin{beschreibung}
+ \Befehl{choicebox} \choicebox
+ \Befehl{checkedchoicebox} \checkedchoicebox
+\end{beschreibung}
+\secidx*{Own Environments}
+
+\section{Styling \Tasks}
+Equivalent to the styling of \ExSheets{} \Tasks uses \paket{xtemplate} to
+declare additional instances for the lists.
+
+\subsection{The \code{tasks} Object}\label{sec:tasks}\secidx{The `tasks' Object}
+The object that's defined by \Tasks is the `tasks' object.
+This time there are four instances available for the one template (again
+`default') that was defined.
+
+\subsubsection{Available Options}
+This section only lists the options that can be used when defining an instance
+of the `default' template. The following subsections will give some examples
+of their usage.
+
+\begin{beispiel}[code only]
+ \DeclareTemplateInterface{tasks}{default}{3}
+ {
+ % option : type = default
+ enumerate : boolean = true ,
+ label : tokenlist ,
+ indent : length = 2.5em ,
+ counter-format : tokenlist = tsk[a]) ,
+ label-format : tokenlist ,
+ label-width : length = 1em ,
+ label-offset : length = .3333em ,
+ after-item-skip : skip = 1ex plus 1ex minus 1ex
+ }
+\end{beispiel}
+
+\subsubsection{Predefined Instances}
+This is rather brief this time:
+\begin{beispiel}[code only]
+ % ALPHABETIZE: a) b) c)
+ \DeclareInstance{tasks}{alphabetize}{default}{}
+ % available when `load-tasks=true':
+ % ITEMIZE:
+ \DeclareInstance{tasks}{itemize}{default}
+ {
+ enumerate = false ,
+ label-width = 1.125em
+ }
+ % ENUMERATE:
+ \DeclareInstance{tasks}{enumerate}{default}
+ { counter-format = tsk. }
+ % MULTIPLECHOICE:
+ \DeclareInstance{tasks}{multiplechoice}{default}
+ {
+ enumerate = false ,
+ label = \choicebox ,
+ }
+\end{beispiel}
+\secidx*{The `tasks' Object}
+
+\printindex
+
+\end{document}