summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/zhlipsum/zhlipsum-en.tex
blob: 991f7bc8782e8a0f88bb60bbd63216758ba9215b (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
%%
%% 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}