Debian Codegraph @

upstream/debian-unstable/man1/gpinyin.1

raw
1 '\" t
2 .TH gpinyin 1 "2026-04-22" "groff 1.24.1"
3 .SH Name
4 gpinyin \- use Hanyu Pinyin Chinese in
5 .I groff
6 documents
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright 2014-2020 Free Software Foundation, Inc.
14 .\"
15 .\" This file is part of gpinyin.
16 .\"
17 .\" gpinyin is distributed with groff, the GNU roff typesetting system.
18 .\"
19 .\" groff is free software; you can redistribute it and/or modify it
20 .\" under the terms of the GNU General Public License as published by
21 .\" the Free Software Foundation, either version 3 of the License, or
22 .\" (at your option) any later version.
23 .\"
24 .\" groff is distributed in the hope that it will be useful, but WITHOUT
25 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
26 .\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
27 .\" License for more details.
28 .\"
29 .\" You should have received a copy of the GNU General Public License
30 .\" along with this program. If not, see
31 .\" <https://www.gnu.org/licenses/>.
32 .
33 .
34 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
35 .do nr *groff_gpinyin_1_man_C \n[.cp]
36 .cp 0
37 .
38 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
39 .nr do-fallback 0
40 .if !\n(.f .nr do-fallback 1 \" mandoc
41 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
42 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
43 .if \n[do-fallback] \{\
44 . de MR
45 . ie \\n(.$=1 \
46 . I \%\\$1
47 . el \
48 . IR \%\\$1 (\\$2)\\$3
49 . .
50 .\}
51 .rr do-fallback
52 .
53 .
54 .\" ====================================================================
55 .\" Local definitions
56 .\" ====================================================================
57 .
58 .\" Define a string for the TeX logo.
59 .ie t .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
60 .el .ds TeX TeX
61 .
62 .
63 .\" ====================================================================
64 .SH Synopsis
65 .\" ====================================================================
66 .
67 .SY gpinyin
68 .RI [ file\~ .\|.\|.]
69 .YS
70 .
71 .
72 .P
73 .SY gpinyin
74 .B \-h
75 .YS
76 .
77 .SY gpinyin
78 .B \-\-help
79 .YS
80 .
81 .
82 .P
83 .SY gpinyin
84 .B \-v
85 .YS
86 .
87 .SY gpinyin
88 .B \%\-\-version
89 .YS
90 .
91 .
92 .\" ====================================================================
93 .SH Description
94 .\" ====================================================================
95 .
96 .I gpinyin
97 is a preprocessor for
98 .MR groff 1
99 that facilitates use of Hanyu Pinyin in
100 .MR groff 7
101 files.
102 .
103 Pinyin is a method for writing the Mandarin Chinese language with the
104 Latin alphabet.
105 .
106 Mandarin consists of more than four hundred base syllables,
107 each spoken with one of five different tones.
108 .
109 Changing the tone applied to the syllable generally alters the meaning
110 of the word it forms.
111 .
112 In Pinyin,
113 a syllable is written in the Latin alphabet and a numeric tone indicator
114 can be appended to each syllable.
115 .
116 .
117 .P
118 Each
119 .I input-file
120 is a file name or the character
121 .RB \[lq] \- \[rq]
122 to indicate that the standard input stream should be read.
123 .
124 As usual,
125 the argument
126 .RB \[lq] \-\- \[rq]
127 can be used in order to force interpretation of all remaining arguments
128 as file names,
129 even if an
130 .I input-file
131 argument begins with a
132 .RB \[lq] \- \[rq].
133 .
134 .B \-h
135 and
136 .B \-\-help
137 display a usage message,
138 while
139 .B \-v
140 and
141 .B \%\-\-version
142 show version information;
143 all exit afterward.
144 .
145 .
146 .\" ====================================================================
147 .SS "Pinyin sections"
148 .\" ====================================================================
149 .
150 Pinyin sections in
151 .I groff
152 files are enclosed by two
153 .B .pinyin
154 requests with different arguments.
155 .
156 The starting request is
157 .RS
158 .EX
159 \&.pinyin start
160 .EE
161 .RE
162 or
163 .RS
164 .EX
165 \&.pinyin begin
166 .EE
167 .RE
168 and the ending request is
169 .RS
170 .EX
171 \&.pinyin stop
172 .EE
173 .RE
174 or
175 .RS
176 .EX
177 \&.pinyin end
178 .EE
179 .RE
180 \&.
181 .
182 .
183 .\" ====================================================================
184 .SS Syllables
185 .\" ====================================================================
186 .
187 In Pinyin,
188 each syllable is represented by one to six letters drawn from the
189 fifty-two upper- and lowercase letters of the Unicode basic Latin
190 character set,
191 plus the letter \[lq]U\[rq] with dieresis (umlaut) in both cases\[em]in
192 other words,
193 the members of the set \[lq][a\[en]zA\[en]Z\[:u]\[:U]]\[rq].
194 .
195 .
196 .P
197 In
198 .I groff
199 input,
200 all basic Latin letters are written as themselves.
201 .
202 The \[lq]u with dieresis\[rq] can be written as
203 \[lq]\e[:u]\[rq]
204 in lowercase or
205 \[lq]\e[:U]\[rq]
206 in uppercase.
207 .
208 Within
209 .B .pinyin
210 sections,
211 .I gpinyin
212 supports the form
213 \[lq]ue\[rq]
214 for lowercase and the forms
215 \[lq]Ue\[rq]
216 and
217 \[lq]UE\[rq]
218 for uppercase.
219 .
220 .
221 .\" ====================================================================
222 .SS Tones
223 .\" ====================================================================
224 .
225 Each syllable has exactly one of five
226 .IR tones .
227 .
228 The fifth tone is not explicitly written at all,
229 but each of the first through fourth tones is indicated with a diacritic
230 above a specific vowel within the syllable.
231 .
232 .
233 .P
234 In a
235 .I gpinyin
236 source file,
237 these tones are written by adding a numeral in the range 0 to 5 after
238 the syllable.
239 .
240 The tone numbers 1 to 4 are transformed into accents above vowels in the
241 output.
242 .
243 The tone numbers 0 and 5 are synonymous.
244 .
245 .
246 .P
247 .nr gpinyin*do-table 0
248 .if t .nr gpinyin*do-table 1
249 .if n .if '\*[.T]'utf8' .nr gpinyin*do-table 1
250 .\" XXX: One hack necessitates another; since our table is conditional,
251 .\" we need to save the input line counter.
252 .nr gpinyin*.c \n[.c]
253 .ie \n[gpinyin*do-table] \{\
254 The tones are written as follows.
255 .
256 .
257 .P
258 .\" XXX: This is so gross. Why can't grops and gropdf figure this out?
259 .if t .ds a- \za\[a-]
260 .if n .ds a- \[a a-]
261 .if t .ds a< \za\[ah]
262 .if n .ds a< \[a ah]
263 .if t .ne 8 \" Try to keep the table on one page for printed output.
264 .TS
265 l l l l l.
266 Tone Description Diacritic Example Input Example Output
267 _
268 first flat \[a-] ma1 m\*[a-]
269 second rising \[aa] ma2 m\[a aa]
270 third falling-rising \[ah] ma3 m\*[a<]
271 fourth falling \[ga] ma4 m\[a ga]
272 fifth neutral (none) ma0 ma
273 \^ \^ \^ ma5 \^
274 .TE
275 .\}
276 .lf (\n[gpinyin*.c] + 25) \" XXX part 2: Restore input line counter.
277 .el \{\
278 [The tone mark table is omitted from this rendering of the man page
279 because the selected output device \[lq]\*[.T]\[rq] lacks the character
280 repertoire to display it.
281 .
282 Try another output device.]
283 .\}
284 .rm a-
285 .rm a<
286 .rr gpinyin*do-table
287 .
288 .
289 .P
290 The neutral tone number can be omitted from a word-final syllable,
291 but not otherwise.
292 .
293 .
294 .\" ====================================================================
295 .SH Authors
296 .\" ====================================================================
297 .
298 .I gpinyin
299 was written by
300 .MT groff\-bernd\:.warken\-72@\:web\:.de
301 Bernd Warken
302 .ME .
303 .
304 .
305 .\" ====================================================================
306 .SH "See also"
307 .\" ====================================================================
308 .
309 Useful documents on the World Wide Web related to Pinyin include
310 .RS 4n
311 .UR http://\:www\:.foolsworkshop\:.com/\:ptou/\:index\:.html
312 .I Pinyin to Unicode
313 .UE ,
314 .
315 .br
316 .UR http://\:www\:.mandarintools\:.com/
317 .I On-line Chinese Tools \" sic: On-line
318 .UE ,
319 .
320 .br
321 .\" XXX: Turning off adjustment like this is ugly; thanks to meter-long
322 .\" URLs we need an escape sequence that selectively disables adjustment
323 .\" at the end of a word.
324 .na
325 .UR http://\:www\:.pinyin\:.info/\:index\:.html
326 .I Pinyin.info: a guide to the writing of Mandarin Chinese in \
327 romanization
328 .UE ,
329 .\" XXX: cringe
330 .ie d AD .ad \*[AD]
331 .el .ad b
332 .
333 .br
334 .UR http://\:www\:.pinyin\:.info/\:rules/\:where.html
335 \[lq]Where do the tone marks go?\[rq]
336 .UE ,
337 .
338 .br
339 .UR http://\:git\:.savannah\:.gnu\:.org/\:gitweb/\:\
340 ?p=cjk\:.git\:;a=blob_plain\:;f=doc/\:pinyin\:.txt\:;hb=HEAD
341 .I pinyin.txt
342 from the CJK macro package for \*[TeX]
343 .UE ,
344 .br
345 .RS -4n
346 and
347 .RE
348 .
349 .br
350 .\" XXX: Same ugliness as before.
351 .na
352 .UR http://\:git\:.savannah\:.gnu\:.org/\:gitweb/\:\
353 ?p=cjk\:.git\:;a=blob_plain\:;f=texinput/\:pinyin\:.sty\:;hb=HEAD
354 .I pinyin.sty
355 from the CJK macro package for \*[TeX]
356 .UE .
357 .\" XXX: cringe
358 .ie d AD .ad \*[AD]
359 .el .ad b
360 .
361 .RE
362 .
363 .
364 .P
365 .MR groff 1
366 and
367 .MR grog 1
368 explain how to view
369 .I roff
370 documents.
371 .
372 .
373 .P
374 .MR groff 7
375 and
376 .MR groff_char 7
377 are comprehensive references covering the language elements of GNU
378 .I troff \" GNU
379 and the available glyph repertoire,
380 respectively.
381 .
382 .
383 .\" Clean up.
384 .rm TeX
385 .
386 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
387 .cp \n[*groff_gpinyin_1_man_C]
388 .do rr *groff_gpinyin_1_man_C
389 .
390 .
391 .\" Local Variables:
392 .\" fill-column: 72
393 .\" mode: nroff
394 .\" End:
395 .\" vim: set filetype=groff textwidth=72: