%%
%% 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 <pssysrq@163.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 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.
%% 
\PassOptionsToPackage{scheme=plain, linespread=1.1}{ctex}
\documentclass{ctxdoc}
\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}
  }
\pagestyle{headings}

\title{\textbf{The \pkg{zhlipsum} Package: Chinese Dummy Text}}
\author{Xiangdong Zeng}
\date{2018/01/06 \quad v0.5%
  \thanks{\url{https://github.com/Stone-Zeng/zhlipsum}.}}

\begin{document}

\maketitle

\section{Introduction}

The \pkg{zhlipsum} package is used for typing in 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.

\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}
should be used with \pkg{CJK} package or \CTeX{} bundle.

\section{User's guide}

\begin{function}[added=2017-09-16,updated=2018-01-05]{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
  \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}.

\begin{function}[updated=2018-01-05]{\zhlipsum}
  \begin{syntax}
    \cs{zhlipsum}\oarg{paragraph}\oarg{options}
    \cs{zhlipsum*}\oarg{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.
\end{function}

The first optional argument \meta{paragraph} can be specified
as the following:

\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}

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.

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.

\begin{function}[added=2018-01-05]{script}
  \begin{syntax}
    script = <simp|trad>
  \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.
\end{function}

\section{Known issues}

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.

If there is no special requirement, UTF-8 encoding and Unicode
engines as \XeLaTeX{} and \LuaLaTeX{} are always recommended.

\end{document}
