NAME

       gpinyin - use Hanyu Pinyin Chinese in roff

SYNOPSIS

       gpinyin [input-file ...]

       gpinyin -h
       gpinyin --help

       gpinyin -v
       gpinyin --version

DESCRIPTION

       gpinyin  is  a preprocessor for groff(1) that facilitates use of the Hanyu Pinyin groff(7)
       files.  Pinyin is a method for writing the Chinese language with the Latin alphabet.   The
       Chinese  language  consists  of  more  than  four hundred syllables, each with one of five
       different tones.  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 hyphen-minus character “-” to indicate that standard
       input 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 the hyphen-minus character.

   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
       The spoken Chinese language is based on about 411 syllables; see ⟨http://en.wikipedia.org/
       wiki/Pinyin_table⟩.

       In Pinyin, each syllable consists of one to six letters from  the  Latin  alphabet;  these
       letters  comprise the fifty-two upper- and lowercase letters from the ASCII 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 ASCII 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  following table summarizes the tones.  Some output devices will not be able to render
       every output example.

       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.

OPTIONS

       -h
       --help Print usage information and exit.

       -v
       --version
              Print version information and exit.

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” (Wikipedia) ⟨http://en.wikipedia.org/wiki/Pinyin⟩,
           “Pinyin table” (Wikipedia) ⟨http://en.wikipedia.org/wiki/Pinyin_table⟩,
           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?” (Pinyin.info) ⟨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), grog(1), and groffer(1) explain how to view roff documents.

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