# gpinyin

## 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 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) 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.
    


* * *