improve and document \blank macro

cgnieder · Apr 28, 2017 · 0da1de7 · 0da1de7
1 parent f273d41
commit 0da1de7
Show file tree

Hide file tree

Showing 7 changed files with 90 additions and 22 deletions.
diff --git a/README b/README
@@ -1,5 +1,5 @@
 --------------------------------------------------------------------------
-XSIM 2017/04/27 v0.6
+XSIM 2017/04/28 v0.6a
 
   eXercise Sheets IMproved
 

diff --git a/code/xsim.blanks.code.tex b/code/xsim.blanks.code.tex
@@ -25,7 +25,7 @@
 % If you have any ideas, questions, suggestions or bugs to report, please
 % feel free to contact me.
 % ----------------------------------------------------------------------------
-\XSIMmodule{blanks}{basic functionality of the package}
+\XSIMmodule{blanks}{add blanks, cloze}
 
 \bool_new:N \l__xsim_blank_width_bool
 \bool_new:N \l__xsim_blank_linespread_bool
@@ -36,13 +36,22 @@
 \dim_new:N  \l__xsim_blank_line_minimum_length_dim
 \box_new:N  \l__xsim_blank_box
 
-\cs_new_protected:Npn \xsim_write_blank:n #1 {#1}
+\cs_new_protected:Npn \xsim_write_cloze_blank:n #1 {#1}
+\cs_new_protected:Npn \xsim_write_cloze_filled:n #1 {#1}
 
 \keys_define:nn {xsim/blank}
   {
-    style               .code:n    =
-      \cs_set_protected:Npn \xsim_write_blank:n {#1} ,
-    style               .initial:n = \underline ,
+    blank-style         .code:n    =
+      \cs_set_protected:Npn \xsim_write_cloze_blank:n ##1 {#1} ,
+    blank-style         .initial:n = \underline {#1} ,
+    filled-style        .code:n    =
+      \cs_set_protected:Npn \xsim_write_cloze_filled:n ##1 {#1} ,
+    filled-style        .initial:n = \underline {#1} ,
+    style               .meta:n    =
+      {
+        blank-style = #1 ,
+        filled-style = #1
+      } ,
     scale               .tl_set:N  = \l__xsim_blank_scale_tl ,
     scale               .initial:n = 1 ,
     width               .code:n    =
@@ -67,7 +76,7 @@
       { \hbox_set:Nn \l__xsim_blank_box { $ \m@th \mathpalette{}{#1} $ } }
       { \hbox_set:Nn \l__xsim_blank_box {#1} }
     \xsim_if_inside_solution:TF
-      { \xsim_write_blank:n {#1} }
+      { \xsim_write_cloze_filled:n {#1} }
       {
         \bool_if:NTF \l__xsim_blank_width_bool
           { \__xsim_blank_skip:V \l__xsim_blank_dim }
@@ -88,23 +97,27 @@
       { \l__xsim_tmpa_dim > \l__xsim_blank_line_minimum_length_dim }
       {
         \mode_if_math:TF
-          { \xsim_write_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
+          { \xsim_write_cloze_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
           {
             \dim_do_while:nn { \l__xsim_tmpa_dim > \c_zero_dim }
               {
+                % I wonder what the correct l3 way would be -- if there is
+                % one, yet:
+                \tex_hfil:D
                 \tex_penalty:D \hyphenpenalty
+                \tex_hfilneg:D
                 \dim_compare:nTF
                   { \l__xsim_tmpa_dim < \l__xsim_blank_line_increment_dim }
-                  { \xsim_write_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
+                  { \xsim_write_cloze_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
                   {
-                    \xsim_write_blank:n
+                    \xsim_write_cloze_blank:n
                       { \skip_horizontal:N \l__xsim_blank_line_increment_dim }
                   }
                 \dim_sub:Nn \l__xsim_tmpa_dim { \l__xsim_blank_line_increment_dim }
               }
           }
       }
-      { \xsim_write_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
+      { \xsim_write_cloze_blank:n { \skip_horizontal:N \l__xsim_tmpa_dim } }
   }
 \cs_generate_variant:Nn \__xsim_blank_skip:n { V }
 

diff --git a/code/xsim.interface.code.tex b/code/xsim.interface.code.tex
@@ -426,13 +426,12 @@
       \IfNoValueF {#2} { \keys_set:nn {xsim/blank} {#2} }
       \mode_if_vertical:TF
         {
-          \IfBooleanF {#1} { \noindent }
-          \xsim_blank:n {#3}
-          \IfBooleanF {#1}
+          \IfBooleanTF {#1}
+            { \xsim_blank:n {#3} }
             {
               \bool_if:NT \l__xsim_blank_linespread_bool
                 { \linespread { \l__xsim_blank_linespread_tl } \selectfont }
-              \par
+              \noindent \null \xsim_blank:n {#3} \par
             }
         }
         { \xsim_blank:n {#3} }

diff --git a/code/xsim.sty b/code/xsim.sty
@@ -29,10 +29,10 @@
 
 \ExplSyntaxOn
 
-\tl_const:Nn \c_xsim_date_tl                 {2017/04/27}
+\tl_const:Nn \c_xsim_date_tl                 {2017/04/28}
 \tl_const:Nn \c_xsim_version_major_number_tl {0}
 \tl_const:Nn \c_xsim_version_minor_number_tl {6}
-\tl_const:Nn \c_xsim_version_subrelease_tl   {}
+\tl_const:Nn \c_xsim_version_subrelease_tl   {a}
 \tl_const:Nx \c_xsim_version_number_tl
   {
     \c_xsim_version_major_number_tl .
@@ -136,3 +136,4 @@ v0.5a 2017/04/15 - fix wrong translation of the `default-heading'
 v0.5b 2017/04/16 - add \SetExerciseProperty
 v0.6  2017/04/27 - official interface for grade distributions
                  - refine hook management (environment module)
+v0.6a 2017/04/28 - refine \blank command, add documentation for said command
diff --git a/doc/xsim-manual.cls b/doc/xsim-manual.cls
@@ -54,6 +54,7 @@
     AddtoExerciseGoalPrint ,
     AddtoExerciseTypeGoal ,
     AddtoExerciseTypeGoalPrint ,
+    blank ,
     collectexercises ,
     collectexercisestype ,
     collectexercisesstop ,
@@ -166,9 +167,11 @@
     NewDocumentEnvironment ,
     numberofcolumns ,
     numberofproblems ,
+    pkg ,
     tcolorbox ,
     toprule ,
-    whileboolexpr
+    whileboolexpr ,
+    xsim
   } ,
   pre-output = { \let\marginpar\marginnote } ,
   add-listings-options = {

diff --git a/doc/xsim_manual.pdf b/doc/xsim_manual.pdf
diff --git a/doc/xsim_manual.tex b/doc/xsim_manual.tex
@@ -1635,13 +1635,65 @@ \section{Exercise Translations}\label{sec:exerc-transl}
     \translationtable
 \end{longtable}
 
-\section{Other Commands}
+\section{Cloze Tests and Blank Lines}
 
-% \blank
+Similar to \pkg{exsheets} \xsim\ provides a command \cs{blank}:
+\begin{commands}
+  \command{blank}[\sarg\oarg{options}\marg{text to be filled in}]
+    Creates a blank in normal text or in an exercise but fills the text of its
+    argument if inside a solution.  If used at the \emph{begin of a paragraph}
+    \cs{blank} will do two things: it will set the linespread according to an
+    option explained below and will insert \cs*{par} after the lines.  If you
+    don't want that use the starred version.
+\end{commands}
 
-% \printexercise
+Those are the options for customization:
+\begin{options}
+  \keyval{blank-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}}
+    Instructions for typesetting the blank cloze.  Refer to the filled in
+    space with \code{\#1}.
+  \keyval{filled-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}}
+    Instructions for typesetting the filled cloze.  Refer to the filled in text
+    with \code{\#1}
+  \keyval{style}{code}
+    Shortcut for setting both \option{blank-style} and \option{filled-style}
+    at once.
+  \keyval{scale}{decimal number}\Module{blank}\Default{\code{1}}
+    Scales the blank to \meta{decimal number} times its natural width.
+  \keyval{width}{dim}\Module{blank}\Default
+    Sets the blank to a width of \meta{dim}.  This takes precendence over
+    \option{scale}.
+  \keyval{linespread}{decimal number}\Module{blank}\Default{\code{1}}
+    Set the linespread for the blank lines. This only has an effect if
+    \cs{blank} is used at the begin of a paragraph.
+  \keyval{line-increment}{dim}\Module{blank}\Default{\code{1pt}}
+    The blank line is built in multiples of this value.  If the value is too
+    large you may end up with uneven lines.  If the value is too small you may
+    end up with a non-ending compilation.  Experiment with values to find the
+    suiting one for your use case.
+  \keyval{line-minimum-length}{dim}\Module{blank}\Default{\code{2em}}
+     The minimal length a line must have before it is built step by step.
+\end{options}
 
-% \printsolution
+\begin{example}
+  This is a \blank{blank} outside in normal text.
+  \begin{exercise}
+    Try to fill in \blank[width=4cm]{these} blanks.  All of them
+    \blank{are created} by using the \cs{blank} \blank{command}.
+  \end{exercise}
+  \xsimsetup{blank/filled-style=\textcolor{red}{#1}}
+  \begin{solution}[print]
+    Try to fill in \blank[width=4cm]{these} blanks.  All of them
+    \blank{are created} by using the \cs{blank} \blank{command}.
+  \end{solution}
+\end{example}
+A number of empty lines are easily created by setting the \option{width}
+option:
+\begin{example}
+  Write up the pros and cons of \xsim\ over \pkg{exsheets}:
+
+  \blank[width=4.8\linewidth,linespread=1.5]{}
+\end{example}
 
 \edef\lastsection{\arabic{section}}