---
name: "gpinyin"
section: "1"
platform: "linux"
package: "groff"
version: "1.24.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gpinyin"
---

# gpinyin(1)

use Hanyu Pinyin Chinese in groff documents

## Name

gpinyin - use Hanyu Pinyin Chinese in *groff* documents

## Synopsis

**gpinyin** \[*file* ...\]

**gpinyin** **-h**

**gpinyin** **--help**

**gpinyin** **-v**

**gpinyin** **--version**

## Description

*gpinyin* is a preprocessor for [*groff*(1)](/groff/1.md) that facilitates use of Hanyu Pinyin in [*groff*(7)](/groff/7.md) files. Pinyin is a method for writing the Mandarin Chinese language with the Latin alphabet. Mandarin consists of more than four hundred base syllables, each spoken with one of five different tones. Changing the tone applied to the syllable generally alters the meaning of the word it forms. In Pinyin, a syllable is written in the Latin alphabet and a numeric tone indicator can be appended to each syllable.

Each *input-file* is a file name or the character “**-**” to indicate that the standard input stream should be read. As usual, the argument “**--**” can be used in order to force interpretation of all remaining arguments as file names, even if an *input-file* argument begins with a “**-**”. **-h** and **--help** display a usage message, while **-v** and **--version** show version information; all exit afterward.

### Pinyin sections

Pinyin sections in *groff* files are enclosed by two **.pinyin** requests with different arguments. The starting request is

```
.pinyin start
```

or

```
.pinyin begin
```

and the ending request is

```
.pinyin stop
```

or

```
.pinyin end
```

.

### Syllables

In Pinyin, each syllable is represented by one to six letters drawn from the fifty-two upper- and lowercase letters of the Unicode basic Latin character set, plus the letter “U” with dieresis (umlaut) in both cases—in other words, the members of the set “\[a–zA–ZüÜ\]”.

In *groff* input, all basic Latin letters are written as themselves. The “u with dieresis” can be written as “\\\[:u\]” in lowercase or “\\\[:U\]” in uppercase. Within **.pinyin** sections, *gpinyin* supports the form “ue” for lowercase and the forms “Ue” and “UE” for uppercase.

### Tones

Each syllable has exactly one of five *tones*. The fifth tone is not explicitly written at all, but each of the first through fourth tones is indicated with a diacritic above a specific vowel within the syllable.

In a *gpinyin* source file, these tones are written by adding a numeral in the range 0 to 5 after the syllable. The tone numbers 1 to 4 are transformed into accents above vowels in the output. The tone numbers 0 and 5 are synonymous.

The tones are written as follows.

| | | | | |
| --- | --- | --- | --- | --- |
| Tone | Description | Diacritic | Example Input | Example Output |
| first | flat | ¯ | ma1 | m |
| second | rising | ´ | ma2 | m |
| third | falling-rising | ˇ | ma3 | m |
| fourth | falling | \` | ma4 | m |
| fifth | neutral | (none) | ma0 | ma |
|  |  |  | ma5 |  |

The neutral tone number can be omitted from a word-final syllable, but not otherwise.

## Authors

*gpinyin* was written by Bernd Warken ⟨groff\\-bernd\\:.warken\\-72@\\:web\\:.de⟩.

## See also

Useful documents on the World Wide Web related to Pinyin include

*Pinyin to Unicode* ⟨http://\\:www\\:.foolsworkshop\\:.com/\\:ptou/\\:index\\:.html⟩,\
 *On-line Chinese Tools* ⟨http://\\:www\\:.mandarintools\\:.com/⟩,\
 *Pinyin.info: a guide to the writing of Mandarin Chinese in romanization* ⟨http://\\:www\\:.pinyin\\:.info/\\:index\\:.html⟩,\
 “Where do the tone marks go?” ⟨http://\\:www\\:.pinyin\\:.info/\\:rules/\\:where.html⟩,\
 *pinyin.txt* from the CJK macro package for TeX ⟨http://\\:git\\:.savannah\\:.gnu\\:.org/\\:gitweb/\\:?p=cjk\\:.git\\:;a=blob\_plain\\:;f=doc/\\:pinyin\\:.txt\\:;hb=HEAD⟩,\

and

*pinyin.sty* from the CJK macro package for TeX ⟨http://\\:git\\:.savannah\\:.gnu\\:.org/\\:gitweb/\\:?p=cjk\\:.git\\:;a=blob\_plain\\:;f=texinput/\\:pinyin\\:.sty\\:;hb=HEAD⟩.

[*groff*(1)](/groff/1.md) and [*grog*(1)](/grog/1.md) explain how to view *roff* documents.

[*groff*(7)](/groff/7.md) and [*groff\_char*(7)](/groff_char/7.md) are comprehensive references covering the language elements of GNU *troff* and the available glyph repertoire, respectively.