summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex
blob: 355e31a149ccd74da5ca893deff92f9abcba3137 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
%%
%% 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
% 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:
  }
% From l3doc, to make @@ -> <module> while @@@@ -> @@
\cs_set_protected:Npn \__ctxdoc_replace_at_at_aux:Nn #1#2
  {
    \tl_replace_all:Nnn #1 { \token_to_str:N @ } { @ }
    \tl_replace_all:Nnn #1 { \token_to_str:N _ } { _ }
    \tl_replace_all:Nnn #1 { @ @ @ @ } { \token_to_str:N a a }
    \tl_replace_all:Nnn #1 { _ _ @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 {   _ @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 {     @ @ } { _ _ #2 }
    \tl_replace_all:Nnn #1 { \token_to_str:N a a } { @ @ }
  }
\ExplSyntaxOff
\makeatother
\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/09/08 \quad v1.1.1%
  \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}