[groff] 01/01: gpinyin(1): Make many editorial fixes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cbcabe4acecb6bb327762ec8484784c45efc14ef
Author: G. Branden Robinson <address@hidden>
Date:   Fri Jun 22 10:00:00 2018 -0400

    gpinyin(1): Make many editorial fixes.
    
    * Improve summary with more keywords.
    * Kill off nearly meaningless phrase "European-like" in favor of
      more informative references to romanization and the Latin alphabet.
    * Put all operation modes in SYNOPSIS section.
    * Remove unnecessary suppression of hyphenation from .SY/.YS regions.
    * Borrow string definition for TeX logo from other groff man pages,
      since TeX is mentioned.
    * Relocate most of the description of the preprocessor to the
      Description section.
    * Relocate the OPTIONS section to follow the main discussion of the
      preprocessor.
    * Fix incorrect escape in examples.
    * Use quotation marks instead of boldface for most literals in running
      prose.  Generally, typographers agree that boldface should be used
      sparingly.
    * Recast most of the English prose.
    * Add descriptions of the first four tones.
    * Change description of the fifth tone from "no-tone" to "neutral";
      every resource in English that I have seen uses the latter term.
    * Move discussion of the tones into a table, to eliminate repeated
      syntactically-parallel sentences.
    * Eliminate non-ASCII characters from input.  Update Emacs settings.
    * Comment out dead URL in SEE ALSO section.
    * Put Pinyin-related Web resources first in the SEE ALSO section,
      followed by man page cross references.
    * Follow bibliographic conventions more closely when identifying
      external resources; only work titles belong in italics.  Names of
      articles or pages at specific sites are usually simply quoted.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 contrib/gpinyin/gpinyin.1.man | 366 +++++++++++++++++++-----------------------
 1 file changed, 164 insertions(+), 202 deletions(-)

diff --git a/contrib/gpinyin/gpinyin.1.man b/contrib/gpinyin/gpinyin.1.man
index 84aa80d..b8d821c 100644
--- a/contrib/gpinyin/gpinyin.1.man
+++ b/contrib/gpinyin/gpinyin.1.man
@@ -1,12 +1,11 @@
+'\" t
 .TH GPINYIN @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH NAME
-gpinyin \- Chinese European-like writing within groff
+gpinyin \- use Hanyu Pinyin Chinese in roff
 .
 .SH "SYNOPSIS"
 .\" The .SH was moved to this place in order to appease 'apropos'.
 .
-.\" TODO: This page needs a thorough edit by a native English speaker.
-.
 .\" ====================================================================
 .\" Legalese
 .\" ====================================================================
@@ -24,14 +23,16 @@ gpinyin \- Chinese European-like writing within groff
 .\" <http://www.gnu.org/licenses/gpl-2.0.html>.
 .
 .\" ====================================================================
-.\" Characters
+.\" Local definitions
 .\" ====================================================================
 .
+.\" Define a string for the TeX logo.
+.ie t .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el   .ds TeX TeX
+.
+.\" Define a string for an ellipsis.
 .ie t .ds EL \f[S]\N'188'\f[P]\"
 .el .ds EL \&.\|.\|.\&\"
-.\" ie t .char \[Ellipsis] \f[S]\N'188'\f[P]
-.\" el .char \[Ellipsis] \&.\|.\|.\&\
-.\" called with \[Ellipsis]
 .
 .
 .\" ====================================================================
@@ -39,257 +40,215 @@ gpinyin \- Chinese European-like writing within groff
 .\" ====================================================================
 .
 .SY gpinyin
-.OP \-
-.OP \-\-
-.OP "\%filespec \*(EL"
+.RI [ input-file
+\*(EL]
 .YS
 .
-.BR "gpinyin \-h" | \-\-help
-.br
-.BR "gpinyin \-v" | \-\-version
+.SY gpinyin
+.B \-h
+.SY gpinyin
+.B \-\-help
+.YS
+.
+.SY gpinyin
+.B \-v
+.SY gpinyin
+.B \-\-version
+.YS
 .
 .
 .\" ====================================================================
 .SH DESCRIPTION
 .\" ====================================================================
 .
-This is a preprocessor for
-.BR \%groff (@MAN1EXT@).
-.
-It allows use of the Chinese European-like language
-.I Pinyin
-into
+.B gpinyin
+is a preprocessor for
+.BR \%groff (@MAN1EXT@)
+that facilitates use of the Hanyu Pinyin
 .BR groff (7)
 files.
 .
+Pinyin is a method for writing the Chinese language with the Latin
+alphabet.
 .
-.\" ====================================================================
-.SH "OPTIONS"
-.\" ====================================================================
-.
-.\" ====================================================================
-.SS "Breaking Options"
-.\" ====================================================================
-.
-An option is
-.IR breaking ,
-when the program just writes the information that was asked for and
-then stops.
-.
-All other arguments will be ignored by that.
-.
-The
-.I breaking
-options are here
-.
-.TP
-.B \-h\~\fR|\fB\~\-\-help
-Print help information with a short explanation of options to standard
-output.
-.
-.
-.TP
-.B \-v\~\fR|\fB\~\-\-version
-Print version information to standard output.
+The Chinese language consists of more than four hundred syllables,
+each with one of five different tones.
 .
-.
-.\" ====================================================================
-.SS "Filespec Options"
-.\" ====================================================================
-.
-So far, there are only
-.I filespec
-and
-.I breaking
-options.
+In Pinyin,
+a syllable is written in the Latin alphabet and a numeric tone indicator
+can be appended to each syllable.
 .
 .
 .P
-.I filespec
-arguments are file names or the minus sign
-.B \-
-for standard input.
+Each
+.I input-file
+is a file name or the hyphen-minus character \[lq]\-\[rq] to indicate
+that standard input should be read.
 .
-As usual, the argument
-.B \-\-
-can be used in order to let all following arguments mean file names,
-even if the names begin with a minus character
-.BR \- .
+As usual,
+the argument \[lq]\-\-\[rq] can be used in order to force interpretation
+of all remaining arguments as file names,
+even if an
+.I input-file
+argument begins with the hyphen-minus character.
 .
 .
 .\" ====================================================================
-.SH "PINYIN PARTS"
+.SS "Pinyin Sections"
 .\" ====================================================================
 .
-.I Pinyin
-parts in
-.I groff files
-are enclosed by two
+Pinyin sections in
+.I groff
+files are enclosed by two
 .B .pinyin
 requests with different arguments.
 .
 The starting request is
 .RS
 .EX
-\e.pinyin start
+\&.pinyin start
 .EE
 .RE
 or
 .RS
 .EX
-\e.pinyin begin
+\&.pinyin begin
 .EE
 .RE
 and the ending request is
 .RS
 .EX
-\e.pinyin stop
+\&.pinyin stop
 .EE
 .RE
 or
 .RS
 .EX
-\e.pinyin end
+\&.pinyin end
 .EE
 .RE
-.
-.
-.\" ====================================================================
-.SH "PINYIN DETAILS"
-.\" ====================================================================
-.
-.I Pinyin
-is used for writing the Chinese language in a European-like
-(romanization) way.
-.
-The Chinese language consists of more than 400 syllables, each with
-one of 5 different tones.
-.
-In
-.IR Pinyin ,
-such toned syllables can be appended to word-like connections.
+\&.
 .
 .
 .\" ====================================================================
 .SS "Syllables"
 .\" ====================================================================
 .
-The Chinese language is based on about 411 defined
-.IR syllables ,
+The spoken Chinese language is based on about 411
+.IR syllables ;
 see
 .UR http://\:en.wikipedia.org/\:wiki/\:Pinyin_table
 .UE .
 .
 .
 .P
-In
-.IR Pinyin ,
-each syllable consists of 1 to 6 European-like letters, the normal
-ASCII characters in upper and lower case, the only unusual characters
-are the
-.BR "U dieresis " ( umlaut )
-in both cases, i.e.\&
-.BR [a\(enzA\(enZ��] .
+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 \[lq]U\[rq] with dieresis (umlaut) in both cases\[em]in
+other words,
+the members of the set \[lq][a\[en]zA\[en]Z\[:u]\[:U]]\[rq].
 .
 .
 .P
-In the
-.B groff gpinyin
+In
+.I groff
 input,
-all ASCII letters are written as usual.
+all ASCII letters are written as themselves.
 .
-But the
-.BR u / U
-.B dieresis
-can be written as either as
-.B \e[\[aq]u] or
-.B ue
-in lower case or
-.BR \e[\[aq]U] ,
-.BR Ue ,
-.B UE
-in upper case.
+The \[lq]u with dieresis\[rq] can be written as
+\[lq]\e[:u]\[rq]
+in lowercase or
+\[lq]\e[:U]\[rq]
+in uppercase.
+.
+Within
+.B .pinyin
+sections,
+.I gpinyin
+supports the form
+\[lq]ue\[rq]
+for lowercase and the forms
+\[lq]Ue\[rq]
+and
+\[lq]UE\[rq]
+for uppercase.
 .
 .
 .\" ====================================================================
 .SS "Tones"
 .\" ====================================================================
 .
-Each syllable has exactly one of 5 defined
+Each syllable has exactly one of five
 .IR tones .
 .
-The 5th tone is not written at all, but each tone 1 to 4 is written
-as an accent above a defined vowel within the syllable.
+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.
 .
 .
 .P
-In the source file, these tones are written by adding a number 0 to 5
-after the syllable name.
+In a
+.I 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.
 .
-.P
-In each writing, the tone numbers 1 to 4 are transformed into accents
-above vowels.
-.
-.
-.P
-The 1st tone is the horizontal macron
-.BR \e[a\-]
-.B \[a-] ,
-similar to a minus or sub character, but on top of the vowel.
-.
-In each source file, write the 1st tone as
-.IB "syllable" 1\fR.
+The tone numbers 0 and 5 are synonymous.
 .
 .
 .P
-The 2nd tone is the accute accent
-.B \e[aa]
-.BR \[aa] .
+The following table summarizes the tones.
 .
-In each source file, write the 2nd tone as
-.IB "syllable" 2\fR.
+Some output devices will not be able to render every output example.
 .
 .
 .P
-The 3rd tone is the caron sign,
-.BR \e[ah]
-.B \[ah] ,
-which looks a bit like a small
-.B v
-above the vowel.
-.
-In each source file, write the 3rd tone as
-.IB "syllable" 3\fR.
+.if t .ne 8 \" Try to keep the table on one page for printed output.
+.TS
+l l l l l.
+Tone   Description     Diacritic       Example Input   Example Output
+_
+first  flat    \[a-]   ma1     m\[u0061_0304]
+second rising  \[aa]   ma2     m\[u0061_0301]
+third  falling-rising  \[ah]   ma3     m\[u0061_030C]
+fourth falling \[ga]   ma4     m\[u0061_0300]
+fifth  neutral (none)  ma0     ma
+\^     \^      \^      ma5     \^
+.TE
 .
 .
 .P
-The 4th tone is the grave accent
-.B \e[ga]
-.BR \[ga] .
-.
-In each source file, write the 4th tone as
-.IB "syllable" 4\fR.
+The neutral tone number can be omitted from a word-final syllable,
+but not otherwise.
 .
 .
-.P
-The 5th tone is the no-tone.
+.\" ====================================================================
+.SH OPTIONS
+.\" ====================================================================
 .
-The numbers 0 and 5 can be used for the
-.BR ( no-tone ).
+.TP
+.B \-h
+.TQ
+.B \-\-help
+Print usage information and exit.
 .
-The
-.B no-tone
-number can be omitted, when the syllable is the end of some word.
 .
-But within a word of syllables, one of the
-.B no-tone
-numbers 0 or 5 must be written.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Print version information and exit.
 .
 .
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
+.
 .B gpinyin
 was written by
 .MT <address@hidden:web.de>
@@ -301,86 +260,89 @@ Bernd Warken
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-.BR \%groff (@MAN1EXT@),
-.BR \%grog (@MAN1EXT@),
-and
-.BR \%groffer (@MAN1EXT@)
-explain how to view
-.I roff
-documents.
-.
-.
-.P
-.BR \%groff (@MAN7EXT@)
-and
-.BR \%groff_char (@MAN7EXT@)
-are comprehensive references covering the language elements of GNU
-.I roff
-and the available glyph repetoire, respectively.
-.
-.
-.P
-Internet documents related to
-.I pinyin
-are
-.RS
+Useful documents on the World Wide Web related to Pinyin include
+.RS 4n
 .br
 .UR http://\:en.wikipedia.org/\:wiki/\:Pinyin
-.I Wikipedia pinyin
+\[lq]Pinyin\[rq] (Wikipedia)
 .UE ,
 .
 .br
 .UR http://\:en.wikipedia.org/\:wiki/\:Pinyin_table
-.I Pinyin Table
-.UE ,
-.
-.br
-.UR http://\:www.sino.uni\-heidelberg.de/\:course_resources/\:s02/\:\
-py\-vowels.htm
-.I Unicode vowels for Pinyin
+\[lq]Pinyin table\[rq] (Wikipedia)
 .UE ,
 .
+.\" XXX: dead link
+.\".br
+.\".UR http://\:www.sino.uni\-heidelberg.de/\:course_resources/\:s02/\:\
+.\"py\-vowels.htm
+.\".I Unicode vowels for Pinyin
+.\".UE ,
+.\".
 .br
 .UR http://\:www.foolsworkshop.com/\:ptou/\:index.html
-.I pinyin to Unicode
+.I Pinyin to Unicode
 .UE ,
 .
 .br
 .UR http://\:www.mandarintools.com/
-.I Online Chinese Tools
+.I On-line Chinese Tools
 .UE ,
 .
 .br
 .UR http://\:www.pinyin.info/\:index.html
-.I Main pinyin website
+.I Pinyin.info: a guide to the writing of Mandarin Chinese in \
+romanization
 .UE ,
 .
 .br
 .UR http://\:www.pinyin.info/\:rules/\:where.html
-.I Where do the tone marks go?
+\[lq]Where do the tone marks go?\[rq] (Pinyin.info)
 .UE ,
 .
 .br
 .UR http://\:git.savannah.gnu.org/\:gitweb/\:\
 ?p=cjk.git;a=blob_plain;f=doc/\:pinyin.txt;hb=HEAD
-.I Pinyin for TeX 1
+pinyin.txt from the CJK macro package for \*[TeX]
 .UE ,
+.br
+.RS -4n
+and
+.RE
 .
 .br
 .UR http://\:git.savannah.gnu.org/\:gitweb/\:\
 ?p=cjk.git;a=blob_plain;f=texinput/p\:inyin.sty;hb=HEAD
-.I Pinyin for TeX 2
+pinyin.sty from the CJK macro package for \*[TeX]
 .UE .
 .
 .RE
 .
+.P
+.BR \%groff (@MAN1EXT@),
+.BR \%grog (@MAN1EXT@),
+and
+.BR \%groffer (@MAN1EXT@)
+explain how to view
+.I roff
+documents.
+.
+.
+.P
+.BR \%groff (@MAN7EXT@)
+and
+.BR \%groff_char (@MAN7EXT@)
+are comprehensive references covering the language elements of GNU
+.I roff
+and the available glyph repertoire,
+respectively.
+.
 .
 .\" ====================================================================
-.\" Emacs settings
+.\" Editor settings
 .\" ====================================================================
 .
 .\" Local Variables:
 .\" mode: nroff
-.\" coding: latin-1
 .\" End:
 .\" vim: set filetype=groff: