zhlipsum (4apr18)

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

7 files changed, 239 insertions, 193 deletions

diff --git a/Master/texmf-dist/doc/latex/zhlipsum/README.md b/Master/texmf-dist/doc/latex/zhlipsum/README.md
index fd97171db25..64b8c0b8ccb 100644
--- a/Master/texmf-dist/doc/latex/zhlipsum/README.md
+++ b/Master/texmf-dist/doc/latex/zhlipsum/README.md
@@ -11,8 +11,8 @@ Basic usage
 -----------
 
     \zhlipsum
-    \zhlipsum*[1-5]
-    \zhlipsum[6-10][script=trad]
+    \zhlipsum*{1-5}
+    \zhlipsum{6-10,18}[name=trad]
 
 More information can be found in the package documentation
 [zhlipsum.pdf](http://mirrors.ctan.org/macros/latex/contrib/zhlipsum/zhlipsum.pdf)
@@ -50,4 +50,4 @@ version.
 
 -----
 
-Copyright (C) 2017, 2018 by Xiangdong Zeng <pssysrq@163.com>.
+Copyright (C) 2017, 2018 by Xiangdong Zeng <xdzeng96@gmail.com>.
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-big5.tex b/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-big5.tex
deleted file mode 100644
index 67e7707748e..00000000000
--- a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-big5.tex
+++ /dev/null
@@ -1,38 +0,0 @@
-%%
-%% This is file `zhlipsum-example-big5.tex',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% zhlipsum.dtx  (with options: `example,big5')
-%% 
-\documentclass{article}
-\usepackage{CJK}
-\usepackage[encoding=big5]{zhlipsum}
-\begin{document}
-\begin{CJK*}{Bg5}{bsmi}
-\def\parcmd{\texttt{\textbackslash par}}
-\section{Basic}
-\zhlipsum
-\section{Simplified / traditional}
-\subsection{Simplified}
-\zhlipsum[1-3][script=simp]
-\subsection{Traditional}
-\zhlipsum*[1-3][script=trad]
-\subsection{Simplified}
-\zhlipsum[4-5]
-\section{Single paragraph}
-\zhlipsum[55]
-\section{With `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum[0-2]
-Some text after lorem ipsum.
-\section{Without `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum*[0-500]
-Some text after lorem ipsum.
-\end{CJK*}
-\end{document}
-%% 
-%%
-%% End of file `zhlipsum-example-big5.tex'.
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-gbk.tex b/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-gbk.tex
deleted file mode 100644
index d8d02462691..00000000000
--- a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-gbk.tex
+++ /dev/null
@@ -1,40 +0,0 @@
-%%
-%% This is file `zhlipsum-example-gbk.tex',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% zhlipsum.dtx  (with options: `example,gbk')
-%% 
-\documentclass[GBK]{ctexart}
-\usepackage[encoding=gbk]{zhlipsum}
-\begin{document}
-\def\parcmd{\texttt{\textbackslash par}}
-\section{Basic}
-\zhlipsum
-\section{Simplified / traditional}
-\subsection{Simplified}
-\zhlipsum[1-3][script=simp]
-\subsection{Traditional}
-\zhlipsum*[1-3][script=trad]
-\subsection{Simplified}
-\zhlipsum[4-5]
-\section{Different fonts}
-{\songti   \zhlipsum[1]} \par
-{\heiti    \zhlipsum[2]} \par
-{\fangsong \zhlipsum[3]} \par
-{\kaishu   \zhlipsum[4]} \par
-\section{Single paragraph}
-\zhlipsum[55]
-\section{With `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum[0-2]
-Some text after lorem ipsum.
-\section{Without `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum*[0-500]
-Some text after lorem ipsum.
-\end{document}
-%% 
-%%
-%% End of file `zhlipsum-example-gbk.tex'.
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-utf8.tex b/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-utf8.tex
deleted file mode 100644
index 2132a604a03..00000000000
--- a/Master/texmf-dist/doc/latex/zhlipsum/example/zhlipsum-example-utf8.tex
+++ /dev/null
@@ -1,40 +0,0 @@
-%%
-%% This is file `zhlipsum-example-utf8.tex',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% zhlipsum.dtx  (with options: `example,utf8')
-%% 
-\documentclass[UTF8]{ctexart}
-\usepackage[encoding=utf8]{zhlipsum}
-\begin{document}
-\def\parcmd{\texttt{\textbackslash par}}
-\section{Basic}
-\zhlipsum
-\section{Simplified / traditional}
-\subsection{Simplified}
-\zhlipsum[1-3][script=simp]
-\subsection{Traditional}
-\zhlipsum*[1-3][script=trad]
-\subsection{Simplified}
-\zhlipsum[4-5]
-\section{Different fonts}
-{\songti   \zhlipsum[1]} \par
-{\heiti    \zhlipsum[2]} \par
-{\fangsong \zhlipsum[3]} \par
-{\kaishu   \zhlipsum[4]} \par
-\section{Single paragraph}
-\zhlipsum[55]
-\section{With `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum[0-2]
-Some text after lorem ipsum.
-\section{Without `\parcmd'}
-Some text before lorem ipsum.
-\zhlipsum*[0-500]
-Some text after lorem ipsum.
-\end{document}
-%% 
-%%
-%% End of file `zhlipsum-example-utf8.tex'.
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.pdf b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.pdf
index 6f88ed94b31..25f8ab1ff42 100644
--- a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.pdf
+++ b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.pdf
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex
index 991f7bc8782..5d86d83bf62 100644
--- a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex
+++ b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex
@@ -6,7 +6,7 @@
 %%
 %% zhlipsum.dtx
 %% 
-%%     Copyright (C) 2017, 2018 by Xiangdong Zeng <pssysrq@163.com>
+%%     Copyright (C) 2017, 2018 by Xiangdong Zeng <xdzeng96@gmail.com>
 %% 
 %%     This work may be distributed and/or modified under the
 %%     conditions of the LaTeX Project Public License, either
@@ -22,132 +22,296 @@
 %% 
 %%     The Current Maintainer of this work is Xiangdong Zeng.
 %% 
-%%     This work consists of the file zhlipsum.dtx,
-%%              and the derived files zhlipsum.ins,
-%%                                    zhlipsum.sty,
-%%                                    zhlipsum-utf8.def,
-%%                                    zhlipsum-gbk.def,
-%%                                    zhlipsum-big5.def,
-%%                                    zhlipsum-example-utf8.tex,
-%%                                    zhlipsum-example-gbk.tex,
-%%                                    zhlipsum-example-big5.tex,
-%%                                    zhlipsum-en.tex,
-%%                                    zhlipsum.pdf,
-%%                                    zhlipsum-en.pdf,
-%%                                and README.md.
+%%     This work consists of the files zhlipsum.dtx,
+%%                                     zhlipsum-text.dtx,
+%%               and the derived files zhlipsum.ins,
+%%                                     zhlipsum.sty,
+%%                                     zhlipsum-utf8.def,
+%%                                     zhlipsum-gbk.def,
+%%                                     zhlipsum-big5.def,
+%%                                     zhlipsum-en.tex,
+%%                                     zhlipsum.pdf,
+%%                                     zhlipsum-en.pdf,
+%%                                 and README.md.
 %% 
 \PassOptionsToPackage{scheme=plain, linespread=1.1}{ctex}
 \documentclass{ctxdoc}
-\hypersetup{
-  pdftitle          = {zhlipsum: Chinese dummy text},
-  pdfauthor         = {Xiangdong Zeng},
-  bookmarksnumbered = true
+\usepackage{multirow}
+\setCJKmonofont{FangSong}[ItalicFont=KaiTi]
+\hypersetup{%
+  pdftitle={zhlipsum: Chinese dummy text},
+  pdfauthor={Xiangdong Zeng},
+  bookmarksnumbered=true
 }
-\geometry{
-  ignoremp,
-  hmargin   = {2.00 in, 1.00 in},
-  vmargin   = {1.25 in, 1.00 in},
-  marginpar = 1.75 in
+\ctexset{%
+  section={name={}, format+=\raggedright},
+  subsubsection/tocline={\CTEXnumberline{#1}#2}
 }
-\ctexset
+\pagestyle{headings}
+% Use `!` for comment in `ctexexam`.
+\makeatletter
+\catcode`!=\active
+\RecustomVerbatimEnvironment{ctexexam}{Verbatim}{%
+  frame=single, framesep=10pt,
+ gobble=2,
+ label=\rule{0pt}{12pt}\textnormal{\bfseries Example \arabic{ctexexam}},
+  listparameters=%
+    \setlength\topsep{\bigskipamount}%
+    \refstepcounter{ctexexam}\ctexexamlabelref
+    \appto\FV@EndList{\nointerlineskip},
+  defineactive=\def!{\color{gray}\itshape\%}}
+\preto\ctexexam{\catcode`!=\active}
+\preto\endctexexam{\catcode`!=12}
+\catcode`!=12
+\makeatother
+% Do not add hyperlink for `TF`, and do not change color.
+\ExplSyntaxOn
+\cs_set_protected:Npn \__codedoc_typeset_TF:
   {
-    section = {name = {}, format+ = \raggedright},
-    subsubsection/tocline = {\CTEXnumberline{#1}#2}
+    \group_begin:
+      \exp_args:No \__codedoc_if_macro_internal:nT \l__codedoc_tmpa_tl
+        { \color[gray]{0.5} }
+      \itshape TF
+      \makebox[0pt][r]
+        {
+          \color{red}
+          \underline{\phantom{\itshape TF} \kern-0.1em}
+        }
+    \group_end:
   }
-\pagestyle{headings}
-
+\ExplSyntaxOff
+\RenewDocumentEnvironment{arguments}{}%
+  {\enumerate[label={\texttt{\#\arabic*:~}},
+    leftmargin=2em, labelsep=0pt, nolistsep]}%
+  {\endenumerate}
 \title{\textbf{The \pkg{zhlipsum} Package: Chinese Dummy Text}}
 \author{Xiangdong Zeng}
-\date{2018/01/06 \quad v0.5%
+\date{2018/04/03 \quad v1.0.0%
   \thanks{\url{https://github.com/Stone-Zeng/zhlipsum}.}}
 
 \begin{document}
 
+\newgeometry{%
+  hmargin={2.0in, 0.8in},
+  vmargin={1.2in, 1.0in},
+  marginpar=1.8in
+}
+
 \maketitle
 
 \section{Introduction}
 
-The \pkg{zhlipsum} package is used for typing in dummy text
+The \pkg{zhlipsum} package is used for typesetting dummy text
 (i.e.\ ``\emph{Lorem ipsum}'') as \pkg{lipsum},
 \pkg{kantlipsum}, \pkg{blindtext} etc., but for Chinese
-language. Dummy text will be useful when testing the effect of
-page style.
+language. Dummy text will be pretty useful, for example, when
+testing fonts or page styles.
 
 \pkg{zhlipsum} supports UTF-8, GBK and Big5 encodings. Packages
 \pkg{expl3}, \pkg{xparse} and \pkg{l3keys2e} in the \LaTeX3{}
-Project are required. To type Chinese properly, \pkg{zhlipsum}
+Project are required. To typeset Chinese properly, \pkg{zhlipsum}
 should be used with \pkg{CJK} package or \CTeX{} bundle.
 
-\section{User's guide}
+\section{User's guide} \label{sec:user-guide}
 
-\begin{function}[added=2017-09-16,updated=2018-01-05]{encoding}
+\begin{function}[added=2017-09-16,updated=2018-04-01]{encoding}
   \begin{syntax}
     encoding = <(utf8)|gbk|big5>
   \end{syntax}
   Package option for selecting encoding. Default value is
-  \opt{utf8}. For Unicode engines as \XeLaTeX{}, \LuaLaTeX{} ands \XeLaTeX{}, \LuaLaTeX{} and
+  \opt{utf8}. For Unicode engines as \XeLaTeX{}, \LuaLaTeX{} and
   \upLaTeX{}, \opt{gbk} / \opt{big5} encodings are invalid and
   \opt{utf8} will be used forcibly.
 \end{function}
 
-In \CTeX{} bundle, the correspoding options are \opt{UTF8} and
-\opt{GBK}. Note that all the options in \pkg{zhlipsum} are in
-\emph{lowercase}.
+If you have loaded \CTeX{} bundle, then the encoding will be
+selected automatically according to \CTeX{}. Note that in \CTeX{}
+bundle, the correspoding options are \opt{UTF8} and \opt{GBK},
+while the options in \pkg{zhlipsum} are all in \emph{lowercase}.
 
-\begin{function}[updated=2018-01-05]{\zhlipsum}
+\begin{function}[updated=2018-03-23]{\zhlipsum}
   \begin{syntax}
-    \cs{zhlipsum}\oarg{paragraph}\oarg{options}
-    \cs{zhlipsum*}\oarg{paragraph}\oarg{options}
+    \cs{zhlipsum}\Arg{paragraph}\oarg{options}
+    \cs{zhlipsum*}\Arg{paragraph}\oarg{options}
   \end{syntax}
-  Insert dummy text. Each fragment will be typed as single
-  paragraph (inserting \tn{par} in between) by default. If you
-  want get a big chunk of text without \tn{par}, please use
-  \cs{zhlipsum*}. In both situations, \tn{par} will be inserted
-  before and after the whole dummy text.
+  Produce dummy text. Both arguments \meta{paragraph} and
+  \meta{options} are optional. Note that spaces are not allowed
+  between the arguments.
 \end{function}
 
-The first optional argument \meta{paragraph} can be specified
-as the following:
+By default, the \cs{zhlipsum} command will insert \tn{par} before,
+after and between dummy text paragraphs, while \cs{zhlipsum}|*|
+will not give any extra processing. To change the default
+behavior, you can use the \opt{before}, \opt{after} and
+\opt{inter} options described below.
 
-\begin{itemize}
-  \item Only one integer, then \cs{zhlipsum} will produce the
-    correspoding paragraph.
-  \item Two integers linked with ``|-|'', then all the
-    paragraphs between will be produced.
- \item Bare \cs{zhlipsum} will lead to paragraphs 1 to 3 by
-    default.
-\end{itemize}
+The first optional argument \meta{paragraph} should be a comma
+list. It can be specified as the following:
 
-At present, \pkg{zhlipsum} can provide 50 paragraphs. Numbers
-larger than 50 will not be considered. For example,
-|\zhlipsum[51]| produces paragraph 50, and |\zhlipsum[48-55]|
-produces 48--50 paragraphs.
+\begin{ctexexam}
+  ! Suppose the dummy text has 50 paragraphs.
+  \zhlipsum{2-4}          ! Can be specified as a-b
+  \zhlipsum{4,12,3-8}     ! A single number is also acceptable
+  \zhlipsum{-10,40-}      ! Produce paragraphs 1-10 and 40-50
+  \zhlipsum{-}            ! Produce all paragraphs, i.e. 1-50
+  \zhlipsum               ! Default value is 1-3
+  \zhlipsum{48-52}        ! Numbers larger than 50 will not be considered
+                          ! i.e. only paragraphs 48-50 are produced
+\end{ctexexam}
 
 The second optional argument \meta{options} should be a
-key-value list. If you need set the options, \meta{paragraph}
-must be specified explicitly. Supported options are the
-following.
+key-value list. Supported options are the listed below.
 
-\begin{function}[added=2018-01-05]{script}
+\begin{function}[added=2018-03-24]{name}
   \begin{syntax}
-    script = <simp|trad>
+    name = \meta{name}
   \end{syntax}
-  Use simplified Chinese (\opt{simp}) or traditional Chinese
-  text (\opt{trad}). Default value is \opt{simp} except for Big5
-  encoding, since this encoding only supports traditional
-  Chinese.
+  Select the name of the dummy text. There are 6 pre-defined
+  dummy texts described in table~\ref{tab:pre-defined-dummy-text}.
+  The default text is |simp| when |encoding=utf8| or |gbk|, but
+  |trad| when |encoding=big5|.
+\end{function}
+
+\begingroup
+\def\B{\bullet}
+\def\M#1{\multirow{2}*{\textbf{#1}}}
+\def\T#1{\textbf{#1}}
+\begin{table}[htb]
+  \caption{Pre-defined dummy texts} \label{tab:pre-defined-dummy-text}
+  \centering\scriptsize
+  \begin{tabular}{cccccccc}
+    \toprule
+      \M{Name} & \T{Paragraph} & \T{Simplified /} & \M{Description} &
+        \multicolumn{3}{c}{\T{Encodings' support}} \\
+      & \T{numbers} & \T{traditional} & & |utf8| & |gbk| & |big5| \\
+    \midrule
+      |simp|        &  50 & S & Random dummy text                         & \B & \B &    \\
+      |trad|        &  50 & T & Random dummy text                         & \B & \B & \B \\
+      |nanshanjing| &  43 & T & \emph{Shanhaijing: Nanshanjing}           & \B &    &    \\
+      |xiangyu|     &  45 & T & \emph{Shiji: Xiang Yu Benji} by Sima Qian & \B & \B & \B \\
+      |zhufu|       & 110 & S & \emph{Zhufu} by Lu Xun                    & \B & \B &    \\
+      |aspirin|     &  66 & S & Wikipedia: \emph{Aspirin}                 & \B & \B &    \\
+    \bottomrule
+  \end{tabular}
+\end{table}
+\endgroup
+
+You can use \cs{newzhlipsum} command to define new dummy text
+as well.
+
+\begin{function}[added=2018-03-29]{before,after,inter}
+  \begin{syntax}
+    name  = \meta{content}
+    after = \meta{content}
+    inter = \meta{content}
+  \end{syntax}
+  Insert contents before, after or between dummy text paragraphs.
+  Note that the \tn{par} command inserted when using \cs{zhlipsum}
+  will be overridden by the settings here.
+\end{function}
+
+\begin{function}[added=2018-03-29]{\newzhlipsum}
+  \begin{syntax}
+    \cs{newzhlipsum}\Arg{name}\Arg{paragraphs list}
+  \end{syntax}
+  Declare new dummy text. The \meta{name} is case sensitive and
+  the \meta{paragraphs list} is a comma list. An example is
+  shown below:
+\end{function}
+
+\begin{ctexexam}
+  ! Fullwidth comma `，' is used in Chinese language.
+  ! Normal comma `,' is used as separator.
+  \newzhlipsum{jingyesi}{!
+    {床前明月光，}, {疑是地上霜。}, {举头望明月，}, {低头思故乡。}}
+
+  \zhlipsum*{-}[name=jingyesi]  ! Print all the four sentences without `\par'
+\end{ctexexam}
+
+\section{Programming interface}
+
+Usually, the commands provided in section~\ref{sec:user-guide}
+are sufficient for users. For programmers professional users,
+however, the programming interface is also necessary and provided
+here. \LaTeX3 syntax should be opened when using them.
+
+\begin{variable}{\g_zhlipsum_seq}
+  A sequence of dummy text names.
+\end{variable}
+
+\begin{function}{\zhlipsum_use:nn}
+  Produce some dummy text paragraphs.
+  \begin{arguments}
+    \item Name
+    \item Comma list of aragraph numbers.
+  \end{arguments}
+\end{function}
+
+\begin{function}[TF]{\zhlipsum_if_exist:n}
+  Test whether the name has been used for dummy text。
+  \begin{arguments}
+    \item Name
+  \end{arguments}
+\end{function}
+
+\begin{function}{\zhlipsum_new:nn}
+  Declare dummy text.
+  \begin{arguments}
+    \item Name.
+    \item Comma list of texts.
+  \end{arguments}
+\end{function}
+
+\section{Compatibility information}
+
+The following option exists in the beta version of \pkg{zhlipsum}
+package, but has become deprecated after version 1.0.0. It is
+reserved only for compatibility and may be removed in the future.
+
+\begin{function}{script}
+  Deprecated option. Now it's the same as \opt{name}.
 \end{function}
 
 \section{Known issues}
 
+Dummy text |nanshanjing| and |xiangyu| have some rarely used
+characters. To display them correctly, you can use the \pkg{xeCJK}
+package and set SimSun-ExtB or Hanazono Mincho as the fallback
+font. Refer to the \pkg{xeCJK}'s user guide for specific methods
+(only for UTF-8 encoding and \XeLaTeX{} engine).
+
 GBK and Big5 encodings do not escape the ASCII range in the
 second byte, so the second byte of some Chinese characters may
 have the same encoding as special characters in ASCII like |{|,
 |}|, |\| etc., which will lead to compilation failure. The
-\file{.def} files in \pkg{zhlipsum} have been converted into
-a safer form. Please do not modify them manually.
+\file{.def} files in \pkg{zhlipsum} are created with special
+techniques. Please do not modify them.
 
 If there is no special requirement, UTF-8 encoding and Unicode
 engines as \XeLaTeX{} and \LuaLaTeX{} are always recommended.
 
+In special cases, if you must use GBK or Big5 encoding and need
+to declare new dummy text, the following method can be taken in
+order to avoid the problem temporarily.
+
+\begin{ctexexam}
+  ! File encoding should be Big5.
+  ! \usepackage[encoding=big5]{zhlipsum}
+
+  ! Using `\newzhlipsum{big5}{許蓋功, 蓋功許, 功許蓋}' directly will
+  ! lead to an error.
+  ! Use <, >, + to replace {, } and \, and set the original {, } and \
+  ! to be `other' category (i.e. catcode=12).
+  \begingroup
+    \catcode`\<=1
+    \catcode`\>=2
+    \catcode`\+=0
+    \catcode`\{=12
+    \catcode`\}=12
+    \catcode`\\=12
+    +newzhlipsum<big5><許蓋功, 蓋功許, 功許蓋>
+  +endgroup
+  \zhlipsum[name=big5]
+\end{ctexexam}
+
 \end{document}
diff --git a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum.pdf b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum.pdf
index 0ca9c8d0c1e..7f9e49c2da0 100644
--- a/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum.pdf
+++ b/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum.pdf