duckuments (2sep18)

git-svn-id: svn://tug.org/texlive/trunk@48545 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 328 insertions, 118 deletions

diff --git a/Master/texmf-dist/source/latex/duckuments/duckuments.dtx b/Master/texmf-dist/source/latex/duckuments/duckuments.dtx
index 20cb8550c35..815f3b13d4d 100644
--- a/Master/texmf-dist/source/latex/duckuments/duckuments.dtx
+++ b/Master/texmf-dist/source/latex/duckuments/duckuments.dtx
@@ -40,8 +40,9 @@ This work is "maintained" (as per LPPL maintenance status) by
 
 This work consists of the file  duckuments.dtx
 and the derived files           duckuments.pdf,
-                                duckuments.sty and
-                                example-image-duck.tex
+                                duckuments.sty,
+                                example-image-duck.tex and
+                                example-image-duck-portrait.tex
 
 \endpreamble
 % stop docstrip adding \endinput
@@ -49,6 +50,7 @@ and the derived files           duckuments.pdf,
 \endpostamble
 \generate{\file{duckuments.sty}{\from{duckuments.dtx}{pkg}}}
 \generate{\file{example-image-duck.tex}{\from{duckuments.dtx}{eid}}}
+\generate{\file{example-image-duck-portrait.tex}{\from{duckuments.dtx}{eidp}}}
 \ifx\fmtname\nameofplainTeX
   \expandafter\endbatchfile
 \else
@@ -58,10 +60,13 @@ and the derived files           duckuments.pdf,
 %
 %<*driver|pkg>
 \RequirePackage{xparse,letltxmacro,l3keys2e}
+\def\duckuments@version{v0.4}
+\def\duckuments@date{2018/09/02}
 %</driver|pkg>
 %
 %<*driver>
-\ProvidesFile{duckuments.dtx}[2018/03/13 minimal working duckuments]
+\ProvidesFile{duckuments.dtx}
+  [\csname duckuments@date\endcsname\ minimal working duckuments]
 \documentclass{l3doc}
 \usepackage{duckuments}
 \usepackage{enumitem}
@@ -84,9 +89,18 @@ and the derived files           duckuments.pdf,
 \end{document}
 %</eid>
 %
+%<*eidp>
+\documentclass[tikz,multi]{standalone}
+
+\usepackage{tikzducks}
+\usepackage{duckuments}
+
+\begin{document}
+\duckumentsDrawRandomDucks*
+\end{document}
+%</eidp>
+%
 %<*pkg>
-\def\duckuments@version{v0.3}
-\def\duckuments@date{2018/03/19}
 \ProvidesExplPackage
   {duckuments}          {\duckuments@date}
   {\duckuments@version} {minimal working duckuments}
@@ -103,7 +117,7 @@ and the derived files           duckuments.pdf,
 %
 % \begin{documentation}^^A>>>
 %
-% \section{Introduction}^^A>>>
+% \section{Introducktion}^^A>>>
 %
 % This package was inspired by the question
 % \href{https://tex.stackexchange.com/questions/419751}
@@ -113,12 +127,14 @@ and the derived files           duckuments.pdf,
 % simple alternative to the \pkg{blindtext} package.
 %
 % It is written as a docstrip file: executing |latex duckuments.dtx| generates
-% the \file{duckuments.sty} and \file{example-image-duck.tex} file and typesets
-% this duckumentation; execute |tex duckuments.dtx| to only generate the files
-% \file{duckuments.sty} and \file{example-image-duck.tex}.
-%
-% For its functionality \file{example-image-duck.tex} must be compiled at least
-% once. The sources are hosted on
+% the \file{duckuments.sty}, \file{example-image-duck.tex}, and
+% \file{example-image-duck-portrait.tex} file and typesets this duckumentation;
+% execute |tex duckuments.dtx| to only generate the files \file{duckuments.sty},
+% \file{example-image-duck.tex}, and \file{example-image-duck-portrait.tex}.
+%
+% For its functionality \file{example-image-duck.tex} and
+% \file{example-image-duck-portrait.tex} must be compiled at least once. The
+% sources are hosted on
 % \href{https://github.com/Skillmon/ltx_duckuments}{github}.
 %
 % \textbf{The package does currently only work on \pdfTeX, \LuaTeX, and \XeTeX}.
@@ -126,7 +142,7 @@ and the derived files           duckuments.pdf,
 %
 % \section{Duckumentation}^^A>>>
 %
-% \subsection{Dummy content}^^A>>>
+% \subsection{Ducky content}^^A>>>
 %
 % \begin{function}{\duckument}^^A>>>
 %   \begin{syntax}
@@ -180,29 +196,31 @@ and the derived files           duckuments.pdf,
 %
 % \subsection{Other Macros}^^A>>>
 %
-% \begin{function}{\duckumentsCreateExampleFile}^^A>>>
-%   Creates the file \file{example-image-duck.tex} in the current working
-%   directory.
+% \begin{function}{\duckumentsCreateExampleFiles}^^A>>>
+%   Creates the files \file{example-image-duck.tex} and
+%   \file{example-image-duck-portrait.tex} in the current working directory.
 % \end{function}^^A<<<
 %
 % \begin{function}{\duckumentsDrawRandomDucks}^^A>>>
 %   \begin{syntax}
-%     \cs{duckumentsDrawRandomDucks}\oarg{count}
+%     \cs{duckumentsDrawRandomDucks}\meta{*}\oarg{count}
 %   \end{syntax}
 %   Draws \meta{count} random \pkg{tikzducks} using
 %   \pkg{Ti\textit{k}Z}. \meta{count} defaults to \cs{duckuments@randoms}.
 %   Note that \pkg{duckuments} doesn't load \pkg{Ti\textit{k}Z}, this macro is
-%   for the use in \file{example-image-duck.tex}.
+%   for the use in \file{example-image-duck.tex} and
+%   \file{example-image-duck-portrait.tex}. If the optional star is given, the
+%   images will be drawn in portrait orientation else in landscape.
 % \end{function}^^A<<<
 %^^A<<<
 %
 % \subsection{Patches}^^A>>>
 %
-% The package patches \cs{includegraphics} if it is defined at the time the
-% patch is applied (see \autoref{sec:keys}, |immediate|). The patch changes the
-% behaviour if |example-image-duck| is used. If that is the case, a random page
-% of that document is used. There shouldn't be any change in behaviour if other
-% files are used.
+% The package patches \cs{includegraphics} if \pkg{graphicx} is loaded at the
+% time the patch is applied (see \autoref{sec:keys}, |immediate|). The patch
+% changes the behaviour if the used image file is \file{example-image-duck}. If
+% that is the case, a random page of that document is used. There shouldn't be
+% any change in behaviour if other files are used.
 %
 % The random page is chosen with |\int_random:nn| in \pdfTeX\ and \LuaTeX. If
 % \XeTeX\ is used, the package implements a RC4 pseudo-random generating
@@ -219,10 +237,13 @@ and the derived files           duckuments.pdf,
 % The package and commands which take a \oarg{key=value} accept the following
 % options. Some of which only make sense as package options. The
 % \textbf{\texttt{bold}} printed value is the one used if you don't specify a
-% value. The \textit{\texttt{italic}} printed value is the default.
+% value. The \textit{\texttt{italic}} printed value is the initial one.
 % \begin{options}
 %   \item[toc=\textbf{true}$\vert$\textit{false}]
-%     If |true| the \cs{duckument} contains a ToC.
+%     If |true| the \cs{duckument} contains a ToC. During package load time the
+%     key doesn't throw errors but only warnings for values other than |true|
+%     and |false|. This is done for compatibility reasons with classes which
+%     take a non-boolean |toc| option (like those of KOMA-script).
 %   \item[maths=\textbf{both}$\vert$inline$\vert$display$\vert$\textit{none}]
 %     If |both| the \cs{blindduck} (which is also used by \cs{duckument})
 %     contains both inline and displayed math. With |inline| and |display| the
@@ -230,26 +251,29 @@ and the derived files           duckuments.pdf,
 %   \item[full]
 %     This typesets the full range of \cs{blindduck}. Don't use this as a
 %     package option.
+%   \item[all]
+%     synonym for |full|.
 %   \item[immediate=\textbf{true}$\vert$\textit{false}]
 %     If |true| \cs{includegraphics} is patched during package load time, else
 %     the patching is done \cs{AtBeginDocument}.
 % \end{options}
 % Additionally \cs{blindduck} and \cs{duckument} accept another key which must
 % match one of the following patterns and doesn't get any value. Patterns:
+% \bgroup
+% \def\num#1{\texttt{\meta{num#1}}}%
 % \begin{description}[style=nextline,font=\normalfont\ttfamily]
-%   \def\num#1{\texttt{\meta{num#1}}}%
-%   \item[\meta{num1}] The paragraph \num{1} is used instead of the first.
-%   \item[\meta{num1-}] Like the above but after the paragraph a \cs{par} is
-%     inserted
-%   \item[\meta{-num2}] The paragraphs from one after the last time \num{1}
-%     or \num{2} was used as an argument (the latter if both) up to
-%     \num{2} are printed. A \cs{par} is inserted after it.
+%   \item[\meta{num1}] The paragraph \num{1} is printed.
+%   \item[\meta{num1-}] Like the above
+%   \item[\meta{-num2}] The paragraphs up to \num{2} are printed.
 %   \item[\meta{num1-num2}] The paragraphs from \num{1} up to \num{2}
-%     are printed. A \cs{par} is inserted after it.
-%   \item[\meta{-}] The next paragraph after the last time \num{1} or
-%     \num{2} was used (the latter if both) is printed. A \cs{par} is
-%     inserted after it.
+%     are printed.
+%   \item[\meta{-}] The next paragraph is printed.
 % \end{description}
+% If the used pattern includes a ``|-|'' a \cs{par} is used after each
+% paragraph. If any pattern is used the next pattern that doesn't include a
+% \num{1} starts with the paragraph after the last used paragraph, cycling back
+% to the first after the last available paragraph.
+% \egroup
 %^^A<<<
 %^^A<<<
 %
@@ -284,7 +308,12 @@ and the derived files           duckuments.pdf,
         LuaTeX,~and~XeTeX!
       }
       {
-        Sorry~for~that.
+        \ ~_____________________________\\
+        \ (Quack!~Sorry~for~that.~Quack!)\\
+        \ ~"""""""""""""""""""""""""""""\\
+        \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\string\ \\
+        \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\ ~>()_\\
+        \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\ ~\ ~(__)__
       }
     \msg_error:nn { duckuments } { incompatible }
     \endinput
@@ -295,25 +324,53 @@ and the derived files           duckuments.pdf,
 \file_if_exist:nF { example-image-duck.pdf }
   {%>>>
 %    \end{macrocode}
-% If the current \cs{jobname} doesn't match \file{example-image-duck} throw a
-% warning.
+% If the current \cs{jobname} doesn't match \file{example-image-duck} throw an
+% error.
 %    \begin{macrocode}
     \str_if_eq:VnF \c_sys_jobname_str { example-image-duck }
       {
-        \msg_new:nnnn { duckuments } { missing-file }
-        {
-          The~file~`#1`~can't~be~found.~Make~sure~to~create~it
-          \tl_if_empty:nF{#2}{~#2}.
-        }
-        { Sorry~for~the~inconvenience.~#3 }
-        \msg_error:nnnnn { duckuments } { missing-file }
+        \msg_new:nnnn { duckuments } { missing~file }
+          {
+            The~file~`#1`~can't~be~found.~Make~sure~to~create~it
+            \tl_if_empty:nF{#2}{~#2}.
+          }
+          { Sorry~for~the~inconvenience.~#3 }
+        \msg_error:nnnnn { duckuments } { missing~file }
           { example-image-duck.pdf }
           {
             by~compiling~example-image-duck.tex~at~least~once
           }
           {
             If~you~don't~find~the~file~on~your~machine~you~can~use~
-            `\duckumentsCreateExampleFile`~in~your~document~to~produce~a~copy~
+            `\duckumentsCreateExampleFiles`~in~your~document~to~produce~a~copy~
+            in~the~current~working~directory.
+          }
+      }
+  }%<<<
+%    \end{macrocode}^^A<<<
+% And do the same for \file{example-image-duck-portrait.pdf}.
+%    \begin{macrocode}^^A>>>
+\file_if_exist:nF { example-image-duck-portrait.pdf }
+  {%>>>
+    \str_if_eq:VnF \c_sys_jobname_str { example-image-duck-portrait }
+      {
+        \msg_if_exist:nnF { duckuments } { missing~file }
+          {
+            \msg_new:nnnn { duckuments } { missing~file }
+              {
+                The~file~`#1`~can't~be~found.~Make~sure~to~create~it
+                \tl_if_empty:nF{#2}{~#2}.
+              }
+              { Sorry~for~the~inconvenience.~#3 }
+          }
+        \msg_error:nnnnn { duckuments } { missing~file }
+          { example-image-duck-portrait.pdf }
+          {
+            by~compiling~example-image-duck-portrait.tex~at~least~once
+          }
+          {
+            If~you~don't~find~the~file~on~your~machine~you~can~use~
+            `\duckumentsCreateExampleFiles`~in~your~document~to~produce~a~copy~
             in~the~current~working~directory.
           }
       }
@@ -394,7 +451,12 @@ and the derived files           duckuments.pdf,
 %   Regex against which the patch of \cs{includegraphics} is testing.
 %    \begin{macrocode}
 \regex_const:Nn \c_duckuments_example_regex
-  { example-image-duck|example-image-duck.pdf }
+  {
+    example-image-duck
+    |example-image-duck.pdf
+    |example-image-duck-portrait
+    |example-image-duck-portrait.pdf
+  }
 %    \end{macrocode}
 % \end{variable}^^A<<<
 %
@@ -413,33 +475,39 @@ and the derived files           duckuments.pdf,
 %
 % \begin{variable}{\c_duckuments_example_pages_int}^^A>>>
 %    \begin{macrocode}
-\str_if_eq:VnF \c_sys_jobname_str { example-image-duck }
+\bool_if:nTF
   {
-    \file_if_exist:nTF { example-image-duck.pdf }
-      {
-        \sys_if_engine_pdftex:T
-          {
-            \pdfximage{example-image-duck.pdf}
-            \int_const:Nn \c_duckuments_example_pages_int
-              { \the\pdflastximagepages }
-          }
-        \sys_if_engine_luatex:T
-          {
-            \saveimageresource{example-image-duck.pdf}
-            \int_const:Nn \c_duckuments_example_pages_int 
-              { \lastsavedimageresourcepages }
-          }
-        \sys_if_engine_xetex:T
-          {
-            \group_begin:
-              \int_gset:Nn \l_tmpa_int
-                { \XeTeXpdfpagecount "example-image-duck.pdf" }
-              \int_const:Nn \c_duckuments_example_pages_int { \l_tmpa_int }
-            \group_end:
-          }
-      }
+    \str_if_eq_p:Vn \c_sys_jobname_str { example-image-duck }
+    || \str_if_eq_p:Vn \c_sys_jobname_str { example-image-duck-portrait }
   }
   { \int_const:Nn \c_duckuments_example_pages_int { 1 } }
+  {
+    \group_begin:
+      \sys_if_engine_pdftex:T
+        {
+          \pdfximage{example-image-duck.pdf}
+          \int_set:Nn \l_tmpa_int { \the\pdflastximagepages }
+          \pdfximage{example-image-duck-portrait.pdf}
+          \int_set:Nn \l_tmpb_int { \the\pdflastximagepages }
+        }
+      \sys_if_engine_luatex:T
+        {
+          \saveimageresource{example-image-duck.pdf}
+          \int_set:Nn \l_tmpa_int { \lastsavedimageresourcepages }
+          \saveimageresource{example-image-duck-portrait.pdf}
+          \int_set:Nn \l_tmpb_int { \lastsavedimageresourcepages }
+        }
+      \sys_if_engine_xetex:T
+        {
+          \int_set:Nn \l_tmpa_int
+            { \XeTeXpdfpagecount "example-image-duck.pdf" }
+          \int_set:Nn \l_tmpb_int
+            { \XeTeXpdfpagecount "example-image-duck-portrait.pdf" }
+        }
+      \int_const:Nn \c_duckuments_example_pages_int
+        { \int_min:nn { \l_tmpa_int } { \l_tmpb_int } }
+    \group_end:
+  }
 %    \end{macrocode}
 % \end{variable}^^A<<<
 %^^A<<<
@@ -460,6 +528,22 @@ and the derived files           duckuments.pdf,
     \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~(__)__
   }
 %    \end{macrocode}^^A<<<
+%    \begin{macrocode}^^A duckuments non-boolean~toc >>>
+\msg_new:nnnn { duckuments } { non-boolean~toc }
+  {
+    A~non-boolean~value~`#1`~was~received~for~the~`toc`~option~during~package~
+    load~time.~It~is~assumed~this~was~given~to~\string\documentclass\ and~
+    therefore~ignored.
+  }
+  { 
+    \ ~__________________________________\\
+    \ (Quack!~Nothing~here,~sorry.~Quack!)\\
+    \ ~""""""""""""""""""""""""""""""""""\\
+    \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\string\ \\
+    \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~>()_\\
+    \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~(__)__
+  }
+%    \end{macrocode}^^A<<<
 %    \begin{macrocode}^^A duckuments out~of~range >>>
 \msg_new:nnnn { duckuments } { out~of~range }
   {
@@ -483,10 +567,10 @@ and the derived files           duckuments.pdf,
     \cs_set:Nn \msg_see_documentation_text:n
       {
         \\\\
-        See~the~\str_if_eq:nnTF { ##1 } { LaTeX } { LaTeX3~documentation }
+        See~the~\str_if_eq:nnTF { ##1 } { duckuments } { duckumentation }
           {
-            \str_if_eq:nnTF { ##1 } { duckuments } { duckumentation }
-              { ##1~documentation }
+            \str_if_eq:nnTF { ##1 } { LaTeX } { LaTeX3~ } { ##1~ }
+            documentation
           }~for~further~information.
       }
   }%<<<
@@ -501,8 +585,9 @@ and the derived files           duckuments.pdf,
   {%>>>
     ,immediate .bool_set:N = \l_duckuments_immediate_bool
     ,immediate .default:n = true
-    ,full .code:n =
+    ,full  .code:n =
       \duckuments_blindduck_range_test:n { 1-\c_duckuments_blindduck_pars_int }
+    ,all   .meta:n = { full }
     ,maths .choice:
     ,maths / both    .code:n =
       {
@@ -517,15 +602,28 @@ and the derived files           duckuments.pdf,
         \bool_set_false:N \l_duckuments_math_display_bool
       }
     ,maths .default:n = both
-    ,toc   .bool_set:N = \l_duckuments_toc_bool
-    ,toc   .default:n = true
+    ,toc   .code:n =
+      {
+        \str_case:nnF { #1 }
+          {
+            { true  } { \bool_set_true:N  \l_duckuments_toc_bool }
+            { false } { \bool_set_false:N \l_duckuments_toc_bool }
+          }
+          {
+            \msg_warning:nnn { duckuments } { non-boolean~toc } { #1 }
+          }
+      }
+    ,toc     .default:n = true
     ,unknown .code:n =
       { \msg_error:nnx { duckuments } { option~unknown } { \l_keys_key_tl } }
   }%<<<
 \ProcessKeysOptions { duckuments }
 \keys_define:nn { duckuments }
   {%>>>
-    unknown .code:n = \duckuments_blindduck_range_test:V \l_keys_key_tl
+    ,toc     .undefine:
+    ,toc     .bool_set:N = \l_duckuments_toc_bool
+    ,toc     .default:n = true
+    ,unknown .code:n = \duckuments_blindduck_range_test:V \l_keys_key_tl
   }%<<<
 \bool_if:NTF \l_duckuments_immediate_bool
   { \AtEndOfPackage { \duckuments_patch_includegraphics: } }
@@ -619,9 +717,10 @@ and the derived files           duckuments.pdf,
 %    \end{macrocode}
 % \end{macro}^^A<<<
 %
-% \begin{macro}{\duckumentsCreateExampleFile}^^A>>>
+% \begin{macro}{\duckumentsCreateExampleFiles}^^A>>>
+% Create example-image-duck.tex
 %    \begin{macrocode}
-\newcommand*\duckumentsCreateExampleFile
+\newcommand*\duckumentsCreateExampleFiles
   {%>>>
     \iow_new:N \duckuments_example_file_iow
     \iow_open:Nn \duckuments_example_file_iow { example-image-duck.tex }
@@ -638,22 +737,34 @@ and the derived files           duckuments.pdf,
     \iow_now:Nn \duckuments_example_file_iow
       { \end{document} }
     \iow_close:N \duckuments_example_file_iow
+%    \end{macrocode}
+% Create example-image-duck-portrait.tex
+%    \begin{macrocode}
+    \iow_open:Nn \duckuments_example_file_iow
+      { example-image-duck-portrait.tex }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \documentclass[tikz,multi]{standalone} }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \usepackage{tikzducks} }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \usepackage{duckuments} }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \begin{document} }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \duckumentsDrawRandomDucks* }
+    \iow_now:Nn \duckuments_example_file_iow
+      { \end{document} }
+    \iow_close:N \duckuments_example_file_iow
   }%<<<
 %    \end{macrocode}
 % \end{macro}^^A<<<
 % \begin{macro}{\duckumentsDrawRandomDucks}^^A>>>
 %    \begin{macrocode}
-\newcommand*\duckumentsDrawRandomDucks[1][\duckuments@randoms]
+\newcommand*\duckumentsDrawRandomDucks
   {%>>>
-    \foreach\x in {1,2,...,#1}
-      {\begin{tikzpicture}
-        \draw[black,fill=gray!50] (0,0) rectangle (6,4);
-          \draw[gray,thin] (0,0) -- (6,4);
-          \draw[gray,thin] (0,4) -- (6,0);
-          \draw[gray,thin] (3,0) -- (3,4);
-          \draw[gray,thin] (0,2) -- (6,2);
-          \node at (3,2) {\tikz\randuck;};
-      \end{tikzpicture}}
+    \@ifstar
+      {\duckumentsDrawRandomDucks@portrait}
+      {\duckumentsDrawRandomDucks@landscape}%
   }%<<<
 %    \end{macrocode}
 % \end{macro}^^A<<<
@@ -723,11 +834,56 @@ and the derived files           duckuments.pdf,
 %
 % \begin{macro}{\duckuments@enquote}^^A>>>
 %    \begin{macrocode}
-\newcommand*\duckuments@enquote [1]
+\NewDocumentCommand \duckuments@enquote { s +m }
+  {%>>>
+    \IfBooleanTF { #1 }
+      {
+        \cs_if_exist_use:NTF
+          \enquote { * { #2 } }
+          { `#2' }
+      }
+      {
+        \cs_if_exist_use:NTF
+          \enquote { { #1 } }
+          {``#1''}
+      }
+  }%<<<
+%    \end{macrocode}
+% \end{macro}^^A<<<
+%
+% \begin{macro}{\duckumentsDrawRandomDucks@landscape}^^A>>>
+%    \begin{macrocode}
+\newcommand*\duckumentsDrawRandomDucks@landscape[1][\duckuments@randoms]
   {%>>>
-    \cs_if_exist_use:NTF
-      \enquote { #1 }
-      {``#1''}
+    \foreach\x in {1,2,...,#1}
+      {\duckumentsDrawRandomDucks@draw{6.47214}{4}{3.23607}{2}}
+  }%<<<
+%    \end{macrocode}
+% \end{macro}^^A<<<
+%
+% \begin{macro}{\duckumentsDrawRandomDucks@portrait}^^A>>>
+%    \begin{macrocode}
+\newcommand*\duckumentsDrawRandomDucks@portrait[1][\duckuments@randoms]
+  {%>>>
+    \foreach\x in {1,2,...,#1}
+      {\duckumentsDrawRandomDucks@draw{1.8541}{3}{.92705}{1.5}}
+  }%<<<
+%    \end{macrocode}
+% \end{macro}^^A<<<
+%
+% \begin{macro}{\duckumentsDrawRandomDucks@draw}^^A>>>
+%    \begin{macrocode}
+\newcommand*\duckumentsDrawRandomDucks@draw[4]
+  {%>>>
+    \begin{tikzpicture}
+      \draw[fill=gray!50,use~as~bounding~box] (0,0) rectangle (#1,#2);
+      \draw[gray,thin] (0,0) -- (#1,#2);
+      \draw[gray,thin] (0,#2) -- (#1,0);
+      \draw[gray,thin] (#3,0) -- (#3,#2);
+      \draw[gray,thin] (0,#4) -- (#1,#4);
+      \node at (#3,#4) {\tikz\randuck;};
+      \draw[black] (0,0) rectangle (#1,#2);
+    \end{tikzpicture}
   }%<<<
 %    \end{macrocode}
 % \end{macro}^^A<<<
@@ -736,24 +892,29 @@ and the derived files           duckuments.pdf,
 %    \begin{macrocode}
 \cs_new_protected_nopar:Nn \duckuments_patch_includegraphics:
   {%>>>
-    \cs_if_exist:NT \includegraphics
+    \@ifpackageloaded { graphicx }
       {
         \LetLtxMacro\duckuments@includegraphicsBAK\includegraphics
         \RenewDocumentCommand \includegraphics
-          { >{\duckuments_starred:n}s O{} m }
+          { >{\duckuments_starred:n}s O{} o m }
           {
-            \regex_match:NnTF \c_duckuments_example_regex { ##3 }
+            \IfValueTF { ##3 }
+              { \duckuments@includegraphicsBAK##1[##2][##3]{##4} }
               {
-                \duckuments_get_random_page:
-                \duckuments@includegraphicsBAK##1
-                  [page=\duckuments_random_page:,##2]
-                  { ##3 }
-              }
-              {
-                \duckuments@includegraphicsBAK##1[##2]{##3}
+                \regex_match:NnTF \c_duckuments_example_regex { ##4 }
+                  {
+                    \duckuments_get_random_page:
+                    \duckuments@includegraphicsBAK##1
+                      [page=\duckuments_random_page:,##2]
+                      { ##4 }
+                  }
+                  {
+                    \duckuments@includegraphicsBAK##1[##2]{##4}
+                  }
               }
           }
       }
+      {}
   }%<<<
 %    \end{macrocode}
 % \end{macro}^^A<<<
@@ -770,7 +931,7 @@ and the derived files           duckuments.pdf,
             \cs_set:Npn \duckuments@blindduck@text
               {
                 \duckuments_blindduck_single_par:n { #1 } 
-                \int_gset:Nn \g_duckuments_blindduck_start_int { #1 + \c_one }
+                \duckuments_blindduck_set_next_start:n { #1 }
               }
           }
           {
@@ -798,10 +959,8 @@ and the derived files           duckuments.pdf,
           }
       }
       {
-        \group_begin:
-          \exp_args:NnnV
-            \msg_error:nnn { duckuments } { option~unknown } \l_keys_key_tl
-        \group_end:
+        \exp_args:NnnV
+          \msg_error:nnn { duckuments } { option~unknown } \l_keys_key_tl
       }
   }%<<<
 \cs_generate_variant:Nn \duckuments_blindduck_range_test:n { V }
@@ -816,13 +975,23 @@ and the derived files           duckuments.pdf,
       {
         \int_step_function:nnnN { #1 } { \c_one } { #2 }
           \duckuments_blindduck_par_loop:n
-        \int_gset:Nn \g_duckuments_blindduck_start_int { #2 + \c_one }
+        \duckuments_blindduck_set_next_start:n { #2 }
       }
   }%<<<
 \cs_generate_variant:Nn \duckuments_blindduck_set_text:nn { xx }
 %    \end{macrocode}
 % \end{macro}^^A<<<
 %
+% \begin{macro}{\duckuments_blindduck_set_next_start:n}^^A>>>
+%    \begin{macrocode}
+\cs_new:Nn \duckuments_blindduck_set_next_start:n
+  {%>>>
+    \int_gset:Nn \g_duckuments_blindduck_start_int
+      { \int_mod:nn { #1 } { \c_duckuments_blindduck_pars_int } + \c_one }
+  }%<<<
+%    \end{macrocode}
+% \end{macro}^^A<<<
+%
 % \begin{macro}{\duckuments_blindduck_single_par:n}^^A>>>
 %    \begin{macrocode}
 \cs_new:Nn \duckuments_blindduck_single_par:n
@@ -1032,14 +1201,23 @@ and the derived files           duckuments.pdf,
   }%<<<
 \newcommand*\duckuments@blindduck@text@iv
   {%>>>
-    Before the first sunlight the underduckling woke. He didn't have the feeling
-    of being well rested. But nonetheless he knew that this was the day he
-    should leave. Except saying goodbye to his beloved ones there was nothing
-    holding him back. His duck had sent him on the most important mission a five
-    weeks old inexperienced underduckling was ever sent. He bid farewell to his
-    mother, all his brothers and sisters, and finally from his duck. The bag was
+    Before dawn the underduckling woke. He didn't have the feeling of being well
+    rested. But nonetheless he knew that this was the day he should leave.
+    Except saying goodbye to his beloved ones there was nothing holding him
+    back. His duck had sent him on the most important mission a five weeks old
+    inexperienced underduckling was ever sent on. He bid farewell to his mother,
+    all his brothers and sisters, and finally from his duck. The bag was
     shouldered, the boots were tied, the underduckling left.%
   }%<<<
+\newcommand*\duckuments@blindduck@text@v
+  {%>>>
+    As the underduckling went along he saw a tree. It was so tall he couldn't
+    even approximate its height. Oh, how small he felt. What should he, a small
+    duckling whose plumage was still fluffy, achieve in this vast, gigantic
+    world? He stuck his trembling wings under the straps of his backpack to calm
+    his shaking limbs. Where should he start his search? How should he survive
+    in the hostile nature surrounding the sheltered pond of his community?
+  }%<<<
 %    \end{macrocode}
 % \end{macro}^^A<<<
 %
@@ -1134,8 +1312,40 @@ and the derived files           duckuments.pdf,
 %</pkg>
 %    \end{macrocode}
 %
+% \clearpage
 % \section{The story of the duck}^^A>>>
 %
-% \blindduck[full]^^A<<<
+% \bgroup
+% \ExplSyntaxOn
+% \newcount\duckuments_count_for_duckumentation_only
+% \cs_set:Nn \duckuments_blindduck_par_loop:n
+%   {^^A>>>
+%     \advance\duckuments_count_for_duckumentation_only1
+%     \llap
+%       {
+%         \group_begin:
+%         \driver_color_gray:n { 0.5 }
+%         \rlap
+%           {
+%             \smash
+%               {
+%                 \parbox[t]{2cm}
+%                   {
+%                     \scriptsize\raggedright
+%                     paragraph~\the\duckuments_count_for_duckumentation_only
+%                   }
+%               }
+%           }
+%         \hspace{\dimexpr\marginparsep+2cm\relax}
+%         \group_end:
+%       }
+%     \vspace{-\baselineskip}
+%     \duckuments_blindduck_single_par:n { #1 }
+%     \par
+%   }^^A<<<
+% \ExplSyntaxOff
+% \blindduck[full]
+% \egroup^^A<<<
+%
 %
 ^^A vim: fdm=marker foldmarker=>>>,<<<