diff options
author | Karl Berry <karl@freefriends.org> | 2013-07-17 22:11:15 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-07-17 22:11:15 +0000 |
commit | f4ee7dde5f0c6c40a915cab1611912f70c73df3f (patch) | |
tree | 80d5f553c3f85a2f5d9af7ecce621016a8045753 /Master/texmf-dist/doc/latex/exsheets | |
parent | ab68c2c47235b190265d422222a53f0c338212ab (diff) |
exsheets (17jul13)
git-svn-id: svn://tug.org/texlive/trunk@31218 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/exsheets')
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/README | 8 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf | bin | 639328 -> 638882 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex | 106 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/tasks_en.tex | 133 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/translations_en.pdf | bin | 425157 -> 0 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/translations_en.tex | 394 |
6 files changed, 95 insertions, 546 deletions
diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README index ccb7a57df5a..c679481cec6 100644 --- a/Master/texmf-dist/doc/latex/exsheets/README +++ b/Master/texmf-dist/doc/latex/exsheets/README @@ -3,8 +3,6 @@ EXSHEETS 2013/06/28 bundled packages: the EXSHEETS package v0.9h Yet another package for the creation of exercise sheets -the TRANSLATIONS package v0.10 - a simple translator the CNTFORMATS package v0.5 A different way to read counters. the TASKS package v0.9d @@ -37,12 +35,6 @@ The exsheets bundle consists of the files - tasks.sty, tasks.cfg, tasks_en.tex, task_en.pdf - - translations.sty, translations_en.tex, translations_en.pdf, - translations-basic-dictionary-english.trsl, - translations-basic-dictionary-french.trsl, - translations-basic-dictionary-german.trsl, - translations-basic-dictionary-spanish.trsl - - cntformats.sty, cntformats_en.tex, cntformats_en.pdf - README diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf Binary files differindex 5805105ab7f..43e3d50d569 100644 --- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf +++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex index deb80de722d..338a78b0912 100644 --- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex @@ -1,6 +1,6 @@ % arara: pdflatex -% arara: biber -% arara: pdflatex +% !arara: biber +% !arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- % the EXSHEETS package @@ -33,12 +33,6 @@ % % - tasks.sty, tasks.cfg, tasks_en.tex, task_en.pdf % -% - translations.sty, translations_en.tex, translations_en.pdf, -% translations-basic-dictionary-english.trsl, -% translations-basic-dictionary-french.trsl, -% translations-basic-dictionary-german.trsl, -% translations-basic-dictionary-spanish.trsl -% % - cntformats.sty, cntformats_en.tex, cntformats_en.pdf % % - README @@ -63,8 +57,7 @@ url = {https://bitbucket.org/cgnieder/exsheets/} , title = the ExSheets bundle , subtitle = {% - the packages \ExSheets, \href{tasks_en.pdf}{\Tasks}, - \href{translations_en.pdf}{\translations} and + the packages \ExSheets, \href{tasks_en.pdf}{\Tasks} and \href{cntformats_en.pdf}{\cntformats}\\ \emph{or}\\ Yet another package for the creation of exercise sheets and exams.% @@ -82,14 +75,11 @@ gobble = 1 } \makeatletter -\edef\trnsltversion{\@trnslt@version} \edef\cntfmtsversion{\@cntfmts@version} \edef\tasksversion{v\@tasks@version} \makeatother -% this messes with the solutions headings in the appendix: -% \usepackage{libertinehologopatch} -% => figure out why +\usepackage{libertinehologopatch} \cnpkgusecolorscheme{friendly} @@ -132,21 +122,6 @@ variant, vary } -% translations: -\newcommand*\translations{{\scshape\textcolor{main}{translations}}\xspace} -\addcmds{ - cuisine, - DeclareDictTranslation, DeclareLanguage, DeclareLanguageAlias, - DeclareLanguageDialect, DeclareTranslation, - GetTranslation, GetTranslationFor, - kitchen, - LoadDictionary, LoadDictionaryFor, - NewTranslation, - ProvideDictionaryFor, - RenewTranslation, - SaveTranslation, SaveTranslationFor, selectlanguage -} - % cntformats: \newcommand*\cntformats{{\scshape\textcolor{main}{cntformats}}\xspace} \addcmds{ @@ -171,6 +146,13 @@ pdfstring = ID , accsupp = ID } +\DeclareAcronym{ctan}{ + short = ctan , + long = Comprehensive \TeX\ Archive Network , + format = \scshape , + pdfstring = CTAN , + accsupp = CTAN +} \usepackage{filecontents} \usepackage{imakeidx} @@ -296,13 +278,6 @@ \NewTasks[style=multiplechoice]{choices}[\choice](3) \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}} -\DeclareTranslation{English}{Kueche}{kitchen} -\DeclareTranslation{German}{Kueche}{K\"uche} -\DeclareTranslation{Spanish}{Kueche}{cocina} -\DeclareTranslation{French}{Kueche}{cuisine} -\DeclareTranslation{English}{foo}{foo} -\DeclareTranslation{British}{foo}{bar} - \usepackage{alphalph} \NewPatternFormat{aa}{\alphalph} \NewCounterPattern{testa}{ta} @@ -311,16 +286,6 @@ \robustify\code % ---------------------------------------------------------------------------- -% 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} @@ -334,22 +299,6 @@ \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{*}} % ---------------------------------------------------------------------------- @@ -429,14 +378,17 @@ wider usage. At the time of writing (\today) there still are probably lots of rough edges let alone bugs so I am very interested in all kinds of feedback. \section{Additional Packages} -\ExSheets actually bundles four packages: \ExSheets, \Tasks, \translations and -\cntformats. \Tasks is described in part~\ref{part:tasks}, \translations is -described in part~\ref{part:translations} and \cntformats in +\ExSheets actually bundles three packages: \ExSheets, \Tasks\ and \cntformats. +\Tasks is described in part~\ref{part:tasks} and \cntformats in part~\ref{part:cntformats}. These packages provide functionality that is used by \ExSheets. They can, however, be used independently from \ExSheets. -The packages \translations and \cntformats both aren't really useful on a -user-level but maybe for package writers. +The package \cntformats\ is probably not really useful on a user-level but +maybe for package writers. + +\changedversion{0.9i}\ExSheets\ used to bundle the \paket*{translations} +package, too, but doesn't any more. You can find the \paket*{translations} +package as a package of it's own on the \ac{ctan}. \section{Installation and Documentation}\secidx[Installation]{Preliminary} If you install \ExSheets manually beware to put the files @@ -446,9 +398,9 @@ If you install \ExSheets manually beware to put the files \end{itemize} in the same directory as the \code{exsheets.sty} file\footnote{That is, a directory like \code{texmf-local/tex/latex/exsheets}, probably}. You -\emph{can} install the other packages, \Tasks, \translations and \cntformats, -in different locations but since they belong to \ExSheets they probably should -be placed in the same directory. +\emph{can} install the other packages, \Tasks and \cntformats, in different +locations but since they belong to \ExSheets they probably should be placed in +the same directory. You should put the file \code{tasks.cfg} in the same directory as the \code{tasks.sty} file. @@ -482,8 +434,7 @@ I am very sorry for any inconvenience! I am trying to keep such changes as minimal and rare as possibly. However, it is not always avoidable when a package is new and still a child. It will grow up eventually. -\ExSheets' other packages -- \href{tasks_en.pdf}{\Tasks}, -\href{translations_en.pdf}{\translations} and +\ExSheets' other packages -- \href{tasks_en.pdf}{\Tasks} and \href{cntformats_en.pdf}{\cntformats} -- have gotten their own documentation which are essentially extracted from this very document you're reading now. They still will be documented in the main documentation (this document), @@ -807,8 +758,8 @@ for Danish) and try if it works: {Opl\o{}sning} \end{beispiel} If this isn't working it means that the language you're using is unknown to -the \translations package (see part~\ref{part:translations}). In this case -please notify me, too. You then can still use the \key{name} options. +the \paket*{translations} package. In this case please notify me, too. You +then can still use the \key{name} options. \secidx*{Language Settings} @@ -1970,6 +1921,7 @@ The following examples use a sample text defined as follows: A `runin-nr' heading. \sample \end{question} +\newpage \subsubsection{The `runin-fixed-nr' Instance} \begin{beispiel}[code only] \DeclareInstance{exsheets-heading}{runin-fixed-nr}{default} @@ -2229,12 +2181,6 @@ will be loaded \cmd*{AtBeginDocument}. \noindent\sinceversion{0.9a}The \Tasks package has got its own documentation -- \url{tasks_en.pdf}. Please read that file for details on the package. -\part{The \translations package (\trnsltversion)} -\label{part:translations}\secidx{\translations}[translations] -\section{About the Documentation} -\noindent\sinceversion{0.9a}The \translations package has got its own documentation -- -\url{translations_en.pdf}. Please read that file for details on the package. - \part{The \cntformats package (\cntfmtsversion)} \label{part:cntformats}\secidx{\cntformats}[cntformats] \section{About the Documentation} diff --git a/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex index 7bc73eaac63..62967bad831 100644 --- a/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex @@ -47,7 +47,12 @@ 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} , + subtitle = {% + {\small + part of the \href{exsheets_en.pdf}{\ExSheets} bundle% + }\\[\baselineskip] + create horizontal columned lists% + } , name = tasks , language = en , modules = true , @@ -175,12 +180,6 @@ \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} @@ -189,22 +188,23 @@ \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. +\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.'' +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}, @@ -214,19 +214,20 @@ status ``maintained.'' \section{How it works} \subsection{The Basics} The \code{tasks} environment is similar to a list like \code{enumerate} but not -the same: +the same. Here are some of the differences: \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}. +\item A first difference: there is no pagebreak possible inside an item but + only between items. +\item A second difference: the enumeration default is a), b), c) \ldots +\item A 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 A fourth difference: the \code{tasks} environment cannot be nested. + You can, however, use an \code{itemize} environment or something in it. +\item A 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}. +\item A sixth difference: %footnotes \end{itemize} \begin{beschreibung} @@ -254,8 +255,8 @@ Some text before the list. \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. +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 @@ -275,7 +276,7 @@ number of columns used by the environment is specified. \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 +row of items could be terminated and a new one is started. This is possible with the following command: \begin{beschreibung} \Befehl{startnewitemline} @@ -319,12 +320,14 @@ The \Tasks package has one package option which also is called when you load 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}. + 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}. + \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. @@ -333,15 +336,16 @@ The environment itself has some more options, namely these: \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. + \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). + \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} + \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} @@ -349,9 +353,9 @@ The environment itself has some more options, namely these: \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. + 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} @@ -376,8 +380,8 @@ Now the same list as above but with three columns and a different label: \task \s\par\s \end{tasks} -Let's use it inside a question, \textit{i.e.}, inside \ExSheets' \code{question} -environment: +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; @@ -405,9 +409,9 @@ environment: \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: +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 @@ -442,12 +446,13 @@ argument of \cmd{task}. This will temporarily overwrite the default label. \secidx*{Custom Labels} \section{New Tasks}\secidx{Own Environments} -It is possible to add custom environments that work like the \code{tasks} environment. +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 + 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}. @@ -469,13 +474,13 @@ The separator does not have to be a control sequence: \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 +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 +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: +default state. You could do something like this: \begin{beispiel} % preamble: % \NewTasks[style=multiplechoice]{choices}[\choice](3) @@ -511,13 +516,13 @@ 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. +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 the `default' template. The following subsections will give some examples of their usage. \begin{beispiel}[code only] diff --git a/Master/texmf-dist/doc/latex/exsheets/translations_en.pdf b/Master/texmf-dist/doc/latex/exsheets/translations_en.pdf Binary files differdeleted file mode 100644 index a22816860e0..00000000000 --- a/Master/texmf-dist/doc/latex/exsheets/translations_en.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/exsheets/translations_en.tex b/Master/texmf-dist/doc/latex/exsheets/translations_en.tex deleted file mode 100644 index 5d7f0feaf46..00000000000 --- a/Master/texmf-dist/doc/latex/exsheets/translations_en.tex +++ /dev/null @@ -1,394 +0,0 @@ -% arara: pdflatex -% arara: pdflatex -% -------------------------------------------------------------------------- -% the TRANSLATIONS package -% -% a simple translator -% -% -------------------------------------------------------------------------- -% 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 translations 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' for compilation -% -\PassOptionsToPackage{supstfm=libertinesups}{superiors} -\documentclass[DIV9,toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc} -% ---------------------------------------------------------------------------- -% document layout and typographic features -\docsetup{ - pkg = {translations} , - url = {https://bitbucket.org/cgnieder/exsheets/} , - subtitle = {{\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip]a simple translator} , - 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 -\addcmds{ - cuisine, - DeclareDictTranslation, DeclareLanguage, DeclareLanguageAlias, - DeclareLanguageDialect, DeclareTranslation, DeclareTranslationFallback, - GetTranslation, GetTranslationFor, - kitchen, - LoadDictionary, LoadDictionaryFor, - mypackage@title, - NewTranslation, - ProvideDictionaryFor, - RenewTranslation,RequirePackage, - SaveTranslation, SaveTranslationFor, selectlanguage -} - -% ---------------------------------------------------------------------------- -% 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: -\DeclareTranslation{English}{Kueche}{kitchen} -\DeclareTranslation{German}{Kueche}{K\"uche} -\DeclareTranslation{Spanish}{Kueche}{cocina} -\DeclareTranslation{French}{Kueche}{cuisine} -\DeclareTranslation{English}{farbe}{color} -\DeclareTranslation{British}{farbe}{colour} - -% ---------------------------------------------------------------------------- -% custom commands -\newcommand*\ExSheets{{\scshape\textcolor{main}{ExSheets}}\xspace} -\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}{% -% }% -% } - -\begin{document} - -\section{Motivation}\secidx{Motivation} -This package provides means for package authors to have an easy interface for -internationalization of their packages. The functionality of this package is -in many parts also covered by the package \paket*{translator} (part of the -\paket{beamer} bundle). Internationalization is also possible with -\paket{babel} and it's \cmd*{addto}\cmd{captions<language>} mechanism or -\KOMAScript's \cmd{providecaptionname}. However, I believe that \translations -is more flexible than all of these. Unlike \paket*{translator} it detects the -used (\paket{babel} or \paket{polyglossia}) language itself and provides -expandable retrieving of the translated key. \translations also provides -support for language dialects which means package authors can distinguish -between British, Australian, Canadian and US English, say. -\secidx*{Motivation} - -\section{License and Requirements}\label{sec:license}\secidx{Requirements} -\translations 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.'' - -\translations requires the \paket{etoolbox} package. -\secidx*{Requirements} - -\section{Usage}\secidx{Usage} -\subsection{Available Commands} -Below the commands provided by \translations are explained. The symbol \expsign{} -means that the command is expandable, \unexpsign{} means that it isn't. -\begin{beschreibung} - \Befehl{DeclareLanguage}{<lang>}\newline - Declare a language that can be used by \translations. If the language already - exists it will be silently redefined. This command can only be used in the preamble. - \Befehl{DeclareLanguageAlias}{<lang2>}\ma{<lang1>}\newline - Declares \code{<lang2>} to be an alias of \code{<lang1>}. If \code{<lang1>} - doesn't exist yet a warning will be raised and it will be defined. This command - can only be used in the preamble. - \Befehl{DeclareLanguageDialect}{<dialect>}\ma{<lang>}\newline - Declares \code{<dialect>} to be a dialect of language \code{<lang>}. If a - translation for \code{<dialect>} is provided it is used by the translation - macros. If there is none the corresponding translation for \code{<lang>} is - used instead. - \Befehl{NewTranslation}{<lang>}\ma{<key>}\ma{<translation>}\newline - Defines a translation of key \code{<key>} for the language \code{<lang>}. - An error will be raised if a translation of \code{<key>} already exists. - This command can only be used in the preamble. - \Befehl{RenewTranslation}{<lang>}\ma{<key>}\ma{<translation>}\newline - Redefines a translation of key \code{<key>} for the language \code{<lang>}. - An error will be raised if no translation of \code{<key>} exists. - This command can only be used in the preamble. - \Befehl{DeclareTranslation}{<lang>}\ma{<key>}\ma{<translation>}\newline - Defines a translation of key \code{<key>} for the language \code{<lang>}. - No error will be raised if a translation of \code{<key>} already exists. - This command can only be used in the preamble. - \Befehl{DeclareTranslationFallback}{<key>}\ma{<fallback>}\newline - Defines a fallback translation for key \code{<key>} that is used in case no - translation of \code{<key>} for the currently active language has been provided. - No error will be raised if a fallback for \code{<key>} already exists. - This command can only be used in the preamble. - \expandable\Befehl{GetTranslationFor}{<lang>}\ma{<key>}\newline - Fetches and prints the translation of \code{<key>} for the language \code{<lang>}. - This command is expandable. - \expandable\Befehl{GetTranslation}{<key>}\newline - Fetches and prints the translation of \code{<key>} for the currently active - language (as for example set by \paket{babel}). This command is expandable. - \Befehl{SaveTranslationFor}{<cmd>}\ma{<lang>}\ma{<key>}\newline - Fetches and saves the translation of \code{<key>} for the language \code{<lang>} - in the macro \code{<cmd>}. - \Befehl{SaveTranslation}{<cmd>}\ma{<key>}\newline - Fetches and saves the translation of \code{<key>} for the currently active - language (as for example set by \paket{babel}) in the macro \code{<cmd>}. - \Befehl{LoadDictionary}{<name>}\newline - Loads a file named \code{<name>-<lang>.trsl} where \code{<lang>} corresponds - to the lowercase name of the current language as defined with - \cmd{DeclareLanguage}. This file should contain the translations for the - specified language. - \Befehl{LoadDictionaryFor}{<lang>}\ma{<name>}\newline - Loads a file named \code{<name>-<lang>.trsl}. - \Befehl{DeclareDictTranslation}{<key>}\ma{<translation>}\newline - This command is to be used in a dictionary file and picks up the language - of that file, see section~\ref{sec:dictionaries} for an example. -\end{beschreibung} -Quite a number of languages already are defined, either directly or via an alias. -So, before you define a language you should take a look at -section~\ref{sec:languages} if the language doesn't already exist. - -\subsection{A Small Example} -This section demonstrates with two short examples how the macros are used. -The first example covers the basics: dlaring of translations and then -retrieving and typesetting them. - -\begin{beispiel} - % in the preamble: - % \DeclareTranslation{English}{Kueche}{kitchen} - % \DeclareTranslation{German}{Kueche}{K\"uche} - % \DeclareTranslation{Spanish}{Kueche}{cocina} - % \DeclareTranslation{French}{Kueche}{cuisine} - - \GetTranslation{Kueche} - \SaveTranslation\kitchen{Kueche} - \SaveTranslationFor\cuisine{french}{Kueche} - - \selectlanguage{ngerman} - \GetTranslation{Kueche} \kitchen\ \GetTranslationFor{spanish}{Kueche} - \cuisine -\end{beispiel} - -The next example demonstrates the use of dialects and how they fall back to -the translation for the main language if no extra translation was declared: - -\begin{beispiel} - % in the preamble: - % \DeclareTranslation{English}{farbe}{color} - % \DeclareTranslation{British}{farbe}{colour} - - \GetTranslationFor{English}{farbe} \\ - \GetTranslationFor{British}{farbe} \\ - \GetTranslationFor{American}{farbe} -\end{beispiel} - -\subsection{Usage in Packages} -A typical usage in a package would look as follows: -\begin{beispiel}[code only] - \RequirePackage{translations} - \DeclareTranslationFallback{mypackage-title}{Nice Title} - \DeclareTranslation{English}{mypackage-title}{Nice Title} - \DeclareTranslation{French}{mypackage-title}{Beau Titre} - \DeclareTranslation{German}{mypackage-title}{Sch\"{o}ner Titel} - ... - \def\mypackage@title{\GetTranslation{mypackage-title}} -\end{beispiel} - -That is, a package defines some unique key for an expression and at least -defines a fallback translation. Additionally translations for as many -languages as the author wants are defined. A user then may add -\cmd{DeclareTranslation}\ma{<language>}\ma{<translation>} if they find their -translation missing. - -\subsection{Dictionaries}\label{sec:dictionaries} -A typical dictionary file should look as follows: -\begin{beispiel}[code only] - % this is file housing-german.trsl - \ProvideDictionaryFor{German}{housing}[<version info>] - \DeclareDictTranslation{kitchen (housing)}{K\"uche} - \DeclareDictTranslation{bathroom (housing)}{Bad} - \DeclareDictTranslation{living room (housing)}{Wohnzimmer} - \DeclareDictTranslation{bedroom (housing)}{Schlafzimmer} - ... - \endinput -\end{beispiel} - -The usage is similar to the one in a package: unique keys are given -translations, this time for the language the dictionary file is declared for -only. - -\secidx*{Usage} - -\section{Defined Languages}\label{sec:languages}\secidx{Languages} -\translations currently has these languages defined, ``fallback'' being a -dummy language used for fallback translations: - -\begin{quote} - \makeatletter\raggedright - \def\comma{\gdef\comma{,\quad}}% - \def\do#1{\comma #1}% - \dolistloop\@trnslt@languages -\end{quote} - -To every one of these languages at least one alias exists, the uppercase -variant. This is due to the fact that it is common to write language names -uppercased. The defined aliases are these (in parentheses the base language -name is given): - -\begin{quote} - \makeatletter\raggedright - \def\comma{\gdef\comma{,\quad}} - \def\aliases#1#2{\comma #1 (#2)} - \def\do#1{\aliases#1} - \dolistloop\@trnslt@aliases@pair -\end{quote} - -\translations also defines a few dialects. The language to which the dialect -belongs to is given in paretheses: - -\begin{quote} - \makeatletter\raggedright - \def\comma{\gdef\comma{,\quad}} - \def\aliases#1#2{\comma #1 (#2)} - \def\do#1{\aliases#1} - \dolistloop\@trnslt@dialects@pair -\end{quote} -\secidx*{Languages} - -These languages should cover all languages which are currently covered by -\paket{babel} and \paket{polyglossia}. - -\section{Implementation}\index{Implementation@\textbf{Implementation}} -In the following code the lines 1--30 have been omitted. They only repeat the -license statement which has already been mentioned in section~\ref{sec:license}. - -\implementation[linerange={31-1000},firstnumber=31] - -\indexprologue{\noindent Section titles are indicated \textbf{bold}, packages -\textsf{sans serif}, commands \code{\textbackslash\textcolor{code}{brown}} - and options \textcolor{key}{\code{yellow}}.\par\bigskip} - -\printindex - -\end{document} |