man > GPINYIN

gpinyin(1)                             General Commands Manual                            gpinyin(1)

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)  that facilitates use of Hanyu Pinyin in groff(7)
       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 dif‐
       ferent 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 in‐
       dicator 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 interpreta‐
       tion 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 spe‐
       cific vowel within the syllable.

       In a gpinyin source file, these tones are written by adding a numeral in the range 0 to 5 af‐
       ter 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.

See also
       Useful documents on the World Wide Web related to Pinyin include
           Pinyin to Unicode,
           On-line Chinese Tools,
           Pinyin.info: a guide to the writing of Mandarin Chinese in romanization,
           “Where do the tone marks go?”,
           pinyin.txt from the CJK macro package for TeX,
       and
           pinyin.sty from the CJK macro package for TeX.

       groff(1) and grog(1) explain how to view roff documents.

       groff(7) and groff_char(7) are comprehensive references covering the language elements of GNU
       troff and the available glyph repertoire, respectively.

groff 1.23.0                                31 March 2024                                 gpinyin(1)