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.