这本《用户手册》是为本转换工具的普通用户编写的使用操作手册。请从事开发工作的高级用户进一步阅读《技术手册》(DOC_TECHNICAL.html)。有关软件版本更新的情况，请看《最近更新》(DOC_WHATSNEW.html)。
“汉语拼音-国际音标转换工具”是一套能将汉语拼音转换成国际音标的Python脚本程序软件。本品的实际用途包括但不限于：
官方发布的两个程序文件名是“py2ipa.py”和“gPY2IPA.py”，分别是转换工具的核心模块兼命令行界面程序和图形用户界面程序。
程序的作者是徐清白，可通过如下网络手段取得联系：
作者将程序按照《GNU通用公共许可证》发布，或者说，这是一个“自由软件”。由于作者不拿该软件卖钱，所以一般用户也可以将其简单地理解为“免费软件”。如果您对许可证的具体条款感兴趣，请看GNU的官方网站：
还有一个非官方的简体中文翻译版本： 本软件的压缩包内附带了这两个文件的本地副本：特别声明：一切转换结果仅供学习参考。作者不会为错误的结果承担任何法律责任。
要运行本程序，用户必须找到一台安装有Python语言解释器的计算机。计算机用的是什么主流操作系统都可以，但Python解释器的版本不得低于2.5版。很多UNIX/Linux系统的安装设置默认包含Python解释器，但很可能低于2.5版。建议用户到Python的官方网站下载最新版本Python的二进制程序包或源代码包：
作者于2007年8月6日首次发布的时候，Python最新发布的是2.5.1版。此外，如果想要运行“gPY2IPA.py”脚本，即图形用户界面(GUI)程序，还必须安装wxPython接口库。建议用户到wxPython的官方网站下载最新版本wxPython的二进制程序包或源代码包：
作者于2007年8月23日首次制作本程序的GUI版本时使用的wxPython为2.8.4版。如果下载二进制程序(Prebuilt Binaries)，务必选择对应Python 2.5且支持Unicode编码的版本。作为程序输出结果的国际音标文稿，以Unicode统一字符集八位变换式（UTF-8）表示。为了能够正常地观看和打印输出结果，用户还应当在计算机上安装一种Unicode字体。作者推荐符合Unicode 4.0标准的Charis SIL字体——可以在SIL的官方网站下载到：
该字体也是GUI程序对字体的默认要求，相关用户最好选择这种字体。作者发布的程序安装包（RAR文件），用户下载后需要解开压缩才能使用。Windows用户可以用较新版本的WinRAR或Total Commander解压缩。UNIX/Linux用户可以使用unrar等程序解压缩。这样就得到了两个脚本程序文件以及若干附属文档文件。
Windows XP的用户，可以打开“开始->程序->附件->命令提示符”，或打开“开始->运行”，输入cmd命令后按“确定”，都会出现命令行窗口。如果Python解释器安装在C:\Python25的路径下，而py2ipa.py位于C:\MyPy目录中，那么这时就可以输入下面的命令来运行程序：
C:\Python25\python C:\MyPy\py2ipa.py
UNIX/Linux用户的控制台就是命令行界面，图形界面用户则需要打开一个终端窗口。正常情况下，用户不需要知道Python解释器的位置。再假定py2ipa.py位于~/路径。这时，也可以像Windows用户那样，将py2ipa.py作为参数传递给Python解释器来运行。但建议用户使用如下命令为py2ipa.py文件设置“可执行”属性，运行起来更方便：
chmod +x ~/py2ipa.py这样,以后只需要直接执行~/py2ipa.py命令就可以了。
如果用户了解所用操作系统的技术细节，还有其他方法避免提供文件的路径。简明起见，下面在展示命令行操作时，均省略路径，只保留文件名。
前面给出的命令行操作，将触发py2ipa.py程序最基本的工作方式：
如果没有使用重定向操作符，stdin即键盘输入，stdout即控制台窗口。这样运行后，光标位于控制台中一个新空行的开头，等待用户用键盘输入汉语拼音文稿。可以输入一行或多行文稿（具体格式在后面的“文稿格式”一节有详细说明），全部完成后按回车键，然后按Ctrl+Z(Win)或Ctrl+D(UNIX)组合键输入一个文件结束符并回车。正常情况下，会看到转换的结果就在下面显示出来了。
然而，键盘通常很难完成大量文稿的输入，控制台窗口也很能无法正常显示国际音标。因此，多数情况下用户需要以磁盘文件作为输入/输出的起止存储载体。有很多文本编辑器可供编写及查看这两种文稿文件，从而保证各种实际任务的完成。
要保存输出的国际音标文稿结果，就是要将stdout重定向到磁盘文件。无论哪种操作系统，用户都可以在py2ipa.py后面加上一个>号和一个文件名：
python py2ipa.py >result.txt这样，显示器的窗口中将看不到转换出来的国际音标文稿。如果指定路径下的输出文件已经存在，这时就会被新的内容覆盖。
还有一种“追加”方式，用两个>>号代替一个>号，新的内容会添补到原有文件之后。
要读取希望输入的汉语拼音文稿，可以将stdin重定向到一个既存的磁盘文件。无论哪种操作系统，用户都可以在py2ipa.py后面加上一个<号和一个文件名：
python py2ipa.py <pinyin.txt这个pinyin.txt应当已经存储有编写好的汉语拼音文稿。
两个方向的重定向可以同时使用：
python py2ipa.py <pinyin.txt >result.txt用户可以使用压缩包中附带的“SAMPLE_wind_sun.txt”文件测试效果。这个文件包含了伊索寓言《北风与太阳》的一部分，有汉字和拼音对照。
还有一种输入文件的格式，省略<号，等于将文件名当作一个普通命令行参数传递给程序：
python py2ipa.py pinyin.txt >result.txt与stdin重定向不同，使用这种普通参数（文件名匹配式）可以一次指定输入多个文件。该参数会启动UNIX shell风格的glob匹配规则，利用通配符扩展文件输入的范围。Windows用户要注意，glob通配符比DOS通配符增加了诸如[0-9]的字符类表达式。另外，这样的参数可以同时使用多个，之间用空格隔开即可。输出的结果先后对应每一个输入的文件，依次呈现。
运行过程中，有可能某个匹配式匹配不到任何文件，或由于种种原因文件数据读取失败。然则每次出错时程序会向“标准错误流”(stderr)输出一行错误提示。如果使用了stdout重定向，错误提示是不会与结果的输出混到一起的。
py2ipa.py程序内置了简单的使用说明，执行以下命令就可以随时看到：
python py2ipa.py --help注意：help前面有连续两道半角减号(-)。
准备就绪后，Windows用户通常可以直接运行该脚本文件；UNIX/Linux用户如果为该文件设置了“可执行”属性，也可以直接运行，或者只是将其文件名作为参数传递给Python解释器。Windows用户在开始运行该脚本程序后，可能会发现，在一个平常的程序窗口之外还有一个命令行界面的窗口在背后运行。这是正常现象，无需介意——但如果不喜欢这个背后的“黑窟窿”，可以将gPY2IPA.py文件改名为gPY2IPA.pyw文件（如果也想如此运行字节码程序gPY2IPA.pyc文件，则需手动变更其关联程序，由python.exe改为pythonw.exe，或创建一个向后者传递脚本文件参数的快捷方式）。
开始运行后，尺寸不大的程序主窗口出现。由于是采用wxWidgets技术制作的GUI程序，窗口的外观风格在不同的GUI平台（Windows / MacOS / GTK）中可能稍有不同，基本总是与用户所在平台的本土风貌相一致，做到“入乡随俗”。但除此之外，程序主要的外观结构和使用功能并无差别。主窗口上半部分是汉语拼音文稿输入区，下半部分显示作为转换结果的国际音标文稿，两者中间主要是一排命令按钮。一开始，输入区会有一小段示范的汉语拼音文稿，而且程序已将其转换为国际音标显示在了下面。
现在，用户可以在主窗口上方的文字输入区使用键盘输入或从剪贴板粘贴汉语拼音文稿（具体格式详见稍后的“文稿格式”一节），具体操作与各GUI平台的通常操作大体相同。根据默认的设置，程序会将其自动转换为国际音标文稿，显示在主窗口下方。
如果在性能较低的计算机上进行键盘输入，或者需要反复追加粘贴大段输入文稿，可以关闭“自动转换”选项（复选框），然后在全部输入完毕之后，单击“立刻转换”按钮，最后获得转换结果。可以使用“复制结果”按钮将全部转换结果直接复制到系统剪贴板，而无需用户分步手动操作。
上下两个文稿显示区域的文字样式，默认的设定是：Charis SIL字体 / 12磅（小四号）大小 / 藏青色前景颜色（关于如何取得Charis SIL字体，在前面的“安装要求”一节有所介绍）。如果想更换文字样式设定，可以使用“选择字体...”按钮，从弹出的“字体”对话框中选择适合的样式。作者还推荐使用Doulos SIL / Gentium / DejaVu Sans / Lucida Sans Unicode / Arial Unicode MS等字体备选（尤其是前三种）。注意：删除线修饰在本程序中无效。
转换工具程序最重要的选项，是各种不同的转换规则设置。在本GUI程序中，改变这些设置是非常方便的。用户只要使用“设置转换规则...”按钮，在弹出的“设置转换规则”窗口的右侧列表中切换各条规则（复选框），就可以个别地改变每一条转换规则。默认的设置表没有启用任何特殊规则——用户可以使用“清空转换规则”按钮恢复到这一初始状态。除此之外，程序还提供了“一揽子设置方案”的功能，即从设置表上方的下拉框中选择一套经典的转换规则体系，如“林焘、王理嘉《语音学教程》”等。背后主窗口的转换结果可以立刻反映规则的改变（只要开启了“自动转换”选项）。规则设置完毕后，请使用“关闭设置窗口”按钮返回主窗口。
另外，使用主窗口的“关于...”按钮可以查看程序的基本信息和简单的帮助说明。使用“退出”按钮则可以立即结束本程序的运行。
下面分别介绍由本程序输入/输出的两种文稿的写作格式与字符集编码要求：
拼音文稿格式兼容GF 3006-2001《汉语拼音方案的通用键盘表示规范》。简单地说就是由<拼音字母串>+<声调标号>构成每个字的拼音文稿。声调标号可有可无，有则取值1-5（半角），即普通话四声和轻声。
拼音字母包括26个不加声调的半角拉丁字母和ɑ/ɡ/ê/ü/ẑ/ĉ/ŝ等字母。其中：
需要理解的是，本程序并不会对输入文稿的合法性进行检查，也就是说，如果输入的汉语拼音文稿不合规范，那么转换得到的国际音标很可能毫无意义。进一步可以说，如果输入的拉丁字母文稿根本不是汉语拼音，程序也一样会怀着最大的善意去执行转换，结果却十有八九一团糟。特别提醒：由于[12345]这几个阿拉伯数字会一律当作声调标号处理，所以如果一定要混排非声调标号的阿拉伯数字，可以考虑用全角字符[１２３４５]等代替（协调起见，其他数字当然最好就也用全角了）。
另外，如果一行文稿以一个“#”符号开头，那么这一整行都不会得到转换（只是开头的“#”号会删除掉）。可以将这样的一行理解为文稿的注释。不过，如果一行以两个“#”符号开头，即以“##”开头，则照常转换（两个“#”符号会删掉一个）。
图形用户界面(GUI)程序的用户，只要保证操作系统确实支持UTF-8编码，便不用太多考虑编码问题；只包含普通拉丁字母和阿拉伯数字的汉语拼音文稿，对于编码也没有什么要求。然而，其他情况下可能需要处理一些汉字与拼音混合编排的文稿。这类文稿文件的字符编码页应当属于UTF-8或GB-18030两类之一。本程序对后者支持得并不完美，汉字与拼音在一行内混排时，有可能出“乱码”。因此作者推荐UTF-8编码。这样正好也与输出文稿的编码相一致。
转换出的国际音标基本属于严式音素音标，但也不想严格到吹毛求疵。而且采用了一部分汉语言学界专用的非标准符号，如舌尖元音等。标音风格与林焘、王理嘉《语音学教程》大体相同，差异仅在于没有采用弱送气符号，以及ai/uai韵母没有采用[æ]韵腹。
特别考虑了对儿化韵的转换，包括韵尾和韵腹的各种替换处理。重读音节的声调标号转换为普通话五度调值，用圆括号包围以示清晰。连读变调以及轻声对音质的影响，因标注难度较大，暂不处理，原样保留。
输出的国际音标文稿统一使用UTF-8编码，而不用GB-18030编码。再次建议用户安装Charis SIL等字体，以便正常查看和打印文稿。
本程序支持的特殊转换规则，可以在GUI程序中很方便地使用；其他用户请参看《技术手册》中的使用说明。
最后再次声明：一切转换结果仅供学习参考。作者不会为错误的结果承担任何法律责任。