%%
%% This is file `zhlipsum-en.tex',
%% generated with Lua script `get-doc-en.lua'.
%%
%% The original source files were:
%%
%% zhlipsum.dtx
%% 
%%     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
%%     version 1.3c 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 Xiangdong Zeng.
%% 
%%     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}
\usepackage{multirow}
\setCJKmonofont{FangSong}[ItalicFont=KaiTi]
\hypersetup{%
  pdftitle={zhlipsum: Chinese dummy text},
  pdfauthor={Xiangdong Zeng},
  bookmarksnumbered=true
}
\ctexset{%
  section={name={}, format+=\raggedright},
  subsubsection/tocline={\CTEXnumberline{#1}#2}
}
\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:
  {
    \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:
  }
\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/04/08 \quad v1.1.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 typesetting dummy text
(i.e.\ ``\emph{Lorem ipsum}'') as \pkg{lipsum},
\pkg{kantlipsum}, \pkg{blindtext} etc., but for Chinese
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 typeset Chinese properly, \pkg{zhlipsum}
should be used with \pkg{CJK} package or \CTeX{} bundle.

\section{User's guide} \label{sec:user-guide}

\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{} and
  \upLaTeX{}, \opt{gbk} / \opt{big5} encodings are invalid and
  \opt{utf8} will be used forcibly.
\end{function}

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-04-08]{\zhlipsum}
  \begin{syntax}
    \cs{zhlipsum}\oarg{paragraph}\oarg{options}
    \cs{zhlipsum*}\oarg{paragraph}\oarg{options}
  \end{syntax}
  Produce dummy text. Both arguments \meta{paragraph} and
  \meta{options} are optional. Note that spaces are not allowed
  between the arguments.
\end{function}

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.

The first optional argument \meta{paragraph} should be a comma
list. It can be specified as the following:

\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. Supported options are the listed below.

\begin{function}[added=2018-03-24]{name}
  \begin{syntax}
    name = \meta{name}
  \end{syntax}
  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} 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}
