annotate DOCS/xml/zh_CN/bugreports.xml @ 32032:52b0385d2d7a

Move **sub_name extern declaration to mpcommon.h. It is used in both mplayer.c/mencoder.c.

<?xml version="1.0" encoding="utf-8"?>
<!-- synced with r21612 -->
<appendix id="bugreports">
<title>如何报告错误</title>

<para>
好的错误报告对于任何软件项目都是非常有价值的贡献。但如同写好软件一样，好的错误
报告也牵涉一些工作。请意识到大多数开发者非常忙碌，每天收到大量邮件。所以如果你
的反馈对提高<application>MPlayer</application>很重要并能得到很多认可，请理解你
必须提供我们所需的<emphasis role="bold">所有</emphasis>信息，并遵守下文所述守
则。
</para>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_security">
<title>报告安全相关错误</title>

<para>
如果你发现了一个可被利用的错误并且你愿意做正确的事而且在你揭露出错误之
前让我们修正此错误，我们很高兴在<ulink url="mailto:[e-mail]">
[e-mail]</ulink>收到你关于安全注意的电子邮件。
请在标题中加注[SECURITY]或者[ADVISORY]字样。
请确定你的报告包含了对于错误完整而细致的分析。
更欢迎提交相关修正。
如发现概念上可被利用的错误请不要停留，你可以在另一封邮件中提交此报告。
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_fix">
<title>如何修正错误</title>

<para>
如果你觉得你有足够能力，你也会被邀请自行修改此错误。或者你已经做了？请阅读
<ulink url="../../tech/patches.txt">此文档</ulink>以找出如何将您的代码加入
<application>MPlayer</application>。如果你有问题，在
<ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">MPlayer-dev-eng</ulink>
邮件列表里的人将会帮助你。
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_regression_test">
<title>如何用Subversion进行倒退测试</title>

<para>
一个经常发生的问题是‘它从前可以工作，但现在不行了’。
此处将提供一步步的过程以帮助定位问题何时产生。这
<emphasis role="bold">不</emphasis>是为普通用户而设。
</para>

<para>
首先，你需要从Subversion处获得MPlayer的代码树。
<ulink url="http://www.mplayerhq.hu/dload.html">此页面</ulink>
底部你将会发现相应指示。
</para>

<para>
在客户端，你现在将在mplayer/目录下得到一份Subversion的镜像。
现在把此镜像更新到你所想要的日期：
<screen>
cd mplayer/
svn update -r {"2004-08-23"}
</screen>
日期格式是YYYY-MM-DD HH:MM:SS。
用此日期格式你将根据补丁提交的日期将其提取出来，如
<ulink url="http://lists.mplayerhq.hu/pipermail/mplayer-cvslog/">MPlayer-cvslog archive</ulink>.
所示
</para>

<para>
现在继续对于普通更新所需步骤：
<screen>
./configure
make
</screen>
</para>

<para>
如果有非程序员阅读至此，找到问题发生处的最快方法是使用二分法查找&mdash;，
即循环不断地将搜索间隔日期除二。
例如，如果问题发生在2003年，从这一年的中间查起，然后自问"问题已经在这里了
么？"
如果回答肯定，回溯到四月一号；如不在，前进到十月一号，以此类推。
</para>

<para>
如果你有很多空余的硬盘空间（完全编译现在将占用100MB，如果调试标志被指定，
大概占用300-350MB），在更新前复制一份最近的正常版本；如果你要返回，这将
节约一些时间。
（在重新编译一份较早版本前经常需要执行'make distclean'，所以如果你没有
备份你原始的代码树，当你回到当前代码时，你将不得不重新编译其中的所有代
码。）
</para>

<para>
当你发现问题发生的那日期，使用mplayer-cvslog压缩文档（按日期排序）继续查找，
并且用更精确的包含小时，分钟，秒的查询。
<screen>
svn update -r {"2004-08-23 15:17:25"}
</screen>
这将使你很容易的发现是哪个补丁引起的问题。
</para>

<para>
如果你发现了引起问题的补丁，你几乎成功了；把它报告到：
<ulink url="http://bugzilla.mplayerhq.hu/">MPlayer Bugzilla</ulink>或者
注册到
<ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users">MPlayer-users</ulink>
并且把错误发送到那里。
有可能原始作者站出来提交一个修正。
你也可以仔细阅读补丁直到发现错误产生的地方:-)。
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_report">
<title>如何提交错误</title>

<para>
首先请尝试<application>MPlayer</application>的最新Subversion版本，因为你的
错误可能已经在那里修正了。开发进展的相当快。正式发行版中的错误经常在几天甚
至几小时内被公布上来，所以请<emphasis role="bold">只使用Subversion</emphasis>
报告错误。
这包括<application>MPlayer</application>的二进制包。
Subversion的指令可在
<ulink url="http://www.mplayerhq.hu/dload.html">此页</ulink>底部查找，或在
README文件中。如果这未能提供帮助，请查询 已知错误
列表以及其后文档。
如果你的问题是未知的或在我们的指示下未能解决，请报告此错误。
</para>

<para>
请不要单独向开发者私自提交错误报告。这是团队工作，所以可能有另外一些人对此
感兴趣。有时其他用户已经体验到你的问题并且知道如何避免一个问题即使他在
<application>MPlayer</application>代码中是个错误。
</para>

<para>
请尽可能详细的描述你的问题。稍微做些测试工作以便缩小产生情况的范围。此错误
只在某些特定情况下发生吗？它只针对特定文件或文件类型吗？它只伴随一个编解码
器出现还是和编解码器无关？你能利用所有的输出驱动重复此错误吗？您提供的信息
越多我们越有可能解决你的问题。请别忘记提供下列有价值的信息，否则我们将不能
很好的查出你的问题。
</para>

<para>
一篇写的很好的关于在公共论坛上提问的指导是
<ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">如何聪明的问问题</ulink>
由<ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>编写。
还有一篇
<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">如何有效报告错误</ulink>
由<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>编写。
如果你遵循这些指导你将会得到帮助。但请明白我们都是自愿在空余时间查询邮件列表。我们非常忙
并且不能保证你的问题会得到解决甚至一个回答。
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_where">
<title>到哪里报告错误</title>

<para>
加入MPlayer-users邮件列表:
<ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users"/>
然后把你的错误报告发送到
<ulink url="mailto:[e-mail]"/>在那里，你也可以讨论它。
</para>

<para>
如果你喜欢，你也可以用我们另外使用我们全新的
<ulink url="http://bugzilla.mplayerhq.hu/">Bugzilla</ulink>。
</para>

<para>
此列表的语言为<emphasis role="bold">英文</emphasis>。
请遵循
<ulink url="http://www.ietf.org/rfc/rfc1855.txt">礼仪指导</ulink>标准
并且<emphasis role="bold">不要发送HTML邮件</emphasis>到我们任何一个邮
件列表上。你将会被忽略或禁止。如果你不知道什么是HTML邮件或为什么他是邪
恶的，阅读这篇
<ulink url="http://efn.no/html-bad.html">文章</ulink>。
他解释了所有的细节并有关闭HTML的指示。此外请注意我们不单独CC(抄送)给个
人，所以注册上来以便得到你的答案是个好主意。
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_what">
<title>报告什么</title>

<para>
你可能要在你的错误报告中包含日志，配置或例子文件。如果他们中一些非常大，
最好把它压缩（请尽量使用gzip或bzip2）并提交到我们的
<ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/">FTP服务器</ulink>
上并且在你的错误报告中只包含路径及文件名称。我们的邮件列表有80k的信息限制，
如果你有更大的附件，你不得不压缩后提交。
</para>

<!-- ********** -->

<sect2 id="bugreports_system">
<title>系统信息</title>

<para>
<itemizedlist>
<listitem><para>
你的Linux发行版本或操作系统及版本，如：
  <itemizedlist>
    <listitem><para>Red Hat 7.1</para></listitem>
    <listitem><para>Slackware 7.0 + devel packs from 7.1 ...</para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
内核版本：
  <screen>uname -a</screen>
</para></listitem>
<listitem><para>
libc版本：
  <screen>ls -l /lib/libc[.-]*</screen>
</para></listitem>
<listitem><para>
gcc及ld版本：
  <screen>
gcc -v
ld -v<!--
  --></screen>
</para></listitem>
<listitem><para>
binutils版本：
  <screen>as --version</screen>
</para></listitem>
<listitem><para>
如果你在全屏模式下出现问题：
  <itemizedlist>
    <listitem><para>视窗管理器类型及版本</para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
如果你有关于XVIDIX的问题：
  <itemizedlist>
  <listitem><para>
  X颜色深度：
    <screen>xdpyinfo | grep "depth of root"</screen>
  </para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
如果只是GUI有错误：
  <itemizedlist>
    <listitem><para>GTK版本</para></listitem>
    <listitem><para>GLIB版本</para></listitem>
    <listitem><para>libpng版本</para></listitem>
    <listitem><para>错误产生时的GUI情况</para></listitem>
  </itemizedlist>
</para></listitem>
</itemizedlist>
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_hardware">
<title>硬件及驱动</title>

<para>
<itemizedlist>
<listitem><para>
CPU信息（这只在Linux上工作）：
  <screen>cat /proc/cpuinfo</screen>
</para></listitem>
<listitem><para>
显卡厂家及型号，例如：
  <itemizedlist>
    <listitem><para>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</para></listitem>
    <listitem><para>Matrox G400 DH 32MB SGRAM</para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
显卡驱动 &amp; 版本，例如:
  <itemizedlist>
    <listitem><para>X built-in driver</para></listitem>
    <listitem><para>nVidia 0.9.623</para></listitem>
    <listitem><para>Utah-GLX CVS 2001-02-17</para></listitem>
    <listitem><para>DRI from X 4.0.3</para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
声卡型号 &amp; 驱动，例如：
  <itemizedlist>
    <listitem><para>Creative SBLive! Gold with OSS driver from oss.creative.com</para></listitem>
    <listitem><para>Creative SB16 with kernel OSS drivers</para></listitem>
    <listitem><para>GUS PnP with ALSA OSS emulation</para></listitem>
  </itemizedlist>
</para></listitem>
<listitem><para>
如果还存在疑问，包含LInux系统上的<command>lspci -vv</command>输出信息。
</para></listitem>
</itemizedlist>
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_configure">
<title>Configure问题</title>

<para>
当你在执行<command>./configure</command>,或一些自动检测发生错误，阅读
<filename>config.log</filename>。你可能会在那里发现答案。例如同一链接库的不同
版本共存于你的系统上，或者你忘记安装开发包（包含有-dev后缀）。如果你认为有错误，
在你的错误报告中包含<filename>config.log</filename>。
</para>
</sect2>

<sect2 id="bugreports_compilation">
<title>编译问题</title>

<para>
请包含这些文件：
<itemizedlist>
  <listitem><para>config.h</para></listitem>
  <listitem><para>config.mak</para></listitem>
</itemizedlist>
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_playback">
<title>回放错误</title>

<para>
请包含<application>MPlayer</application>在一级verbose模式下的输出，另外谨记
当你把它粘贴入邮件时<emphasis role="bold">不要截断输出</emphasis>
开发者需要所有信息以便正确诊断一个问题。你可以如下把输出定向到一个文件：
<screen>
mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> &gt; mplayer.log 2&gt;&amp;1
</screen>
</para>

<para>
如果你的问题只针对一个或更多文件，请把他们上传到：
<ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/>
</para>

<para>
另外上传一个和你的原始文件有相同本名并用.txt为后缀的小文本文件。描述你在此文件
上遇到的问题，并且包含你的email以及<application>MPlayer</application>在verbose
一级模式下的输出。通常，文件的前1-5 MB足够用于重现问题，可是确定我们请你做：
<screen>
dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5
</screen>
它将提取'<emphasis role="bold">你的文件</emphasis>'的前5MB，并将它写入
'<emphasis role="bold">小文件</emphasis>'。然后在此小文件上重试，如果
错误重现，你的例子对我们已经足够了。
请<emphasis role="bold">千万不要</emphasis>通过邮件传送此文件！
上传并且只发送文件在FTP服务器上的路径/文件名。如果文件在网络上获得，那么发送
<emphasis role="bold">精确的</emphasis>URL就足够了。
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_crash">
<title>崩溃</title>

<para>
你需要在<command>gdb</command>里运行<application>MPlayer</application>并且把
完全输出发给我们，或者如果你有此崩溃的<filename>core</filename>输出，你能从
Core文件中提取有用的信息。如下：
</para>


<sect3 id="bugreports_debug">
<title>如何保存一个可重复崩溃的信息</title>

<para>
重新编译<application>MPlayer</application>并打开debug选项:
<screen>
./configure --enable-debug=3
make
</screen>
然后在gdb中运行<application>MPlayer</application>:
<screen>gdb ./mplayer</screen>
你先在在gdb里面。输入：
<screen>
run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable>
</screen>
重复你的崩溃。你一重现此现象，gdb将使你返回命令行，在此你输入
<screen>
bt
disass $pc-32 $pc+32
info all-registers
</screen>
</para>
</sect3>


<sect3 id="bugreports_core">
<title>如何从core输出文件中提取有用信息</title>

<para>
创建如下命令文件：
<screen>
bt
disass $pc-32 $pc+32
info all-registers
</screen>
然后只执行这个命令
<screen>
gdb mplayer --core=core -batch --command=command_file &gt; mplayer.bug
</screen>
</para>
</sect3>
</sect2>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_advusers">
<title>我知道我在做什么...</title>

<para>
如果你依照如上步骤创建了一个正确的错误报告，并且你确信它是个
<application>MPlayer</application>中的错误，不是编译器或损坏文件，你已经读过
文档并且找不到解决方案，你的声卡驱动正常，那么你可能想注册到MPlayer-advusers
列表中并发送你的错误报告到那里，以便得到更好更快的回答。
</para>

<para>
请注意如果你提交新手问题或手册中已经解答的问题，你可能会被忽略甚至批评而不是
得到相应答案。所以不要骚扰我们并且只有你知道你自己在做什么并且觉得自己是个高
级<application>MPlayer</application>用户或开发者的时候才注册到-advusers。如果
你符合这些标准，查出如何注册并不困难...
</para>
</sect1>

</appendix>