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 hun-
     dred base syllables, each spoken with one of five different tones.	  Chang-
     ing  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 char-
     acter set, plus the letter "U" with dieresis  (umlaut)  in	 both  cases--in
     other words, the members of the set "[a-zA-ZuU]".

     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  upper-
     case.   Within  .pinyin sections, gpinyin supports the form "ue" for lower-
     case and the forms "Ue" and "UE" for uppercase.

   Tones
     Each syllable has exactly one of five tones.  The fifth tone is not explic-
     itly written at all, but each of the first through fourth	tones  is  indi-
     cated 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  trans-
     formed  into  accents above vowels in the output.	The tone numbers 0 and 5
     are synonymous.

     [The tone mark table is omitted from this rendering of the man page because
     the selected output device "ascii" lacks the character repertoire	to  dis-
     play it.  Try another output device.]

     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 romaniza-
	 tion,
	 "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  lan-
     guage  elements  of  GNU  troff and the available glyph repertoire, respec-
     tively.

groff 1.24.1			   2026-03-14			      gpinyin(1)