Debian Codegraph @

upstream/debian-trixie/man1/gpinyin.1

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