Next: , Previous: , Up: Introduction   [Contents][Index]

1.4 Feedback

如果你在使用 Org 时发现问题，或有相关疑问、意见与建议， 请发送邮件至 Org 邮件列表 。 你可以通过该网页订阅该邮件列表。 若你并非邮件列表成员，你的邮件需经管理员审核后才会发布至列表2。 在该邮件列表发言时，请阅读并遵守GNU 友好交流准则。 反馈后请耐心等待最长一个月的回复时间，若错误报告未收到回应可再次跟进。

提交错误报告时，请先使用最新版本的 Org 尝试复现问题— 如果你使用的是过时版本，该问题很可能已被修复。 若问题仍然存在，请准备报告并尽可能提供详细信息， 包括 Emacs 版本信息（M-x emacs-version）、 Org 版本信息（M-x org-version）， 以及 Emacs 初始化文件中与 Org 相关的配置。 完成此事最简单的方式是执行命令： 

M-x org-submit-bug-report <RET>

该命令会将所有相关信息填入 Emacs 邮件缓冲区， 你只需补充问题描述即可。 若你并非在 Emacs 内发送邮件，请将相关内容复制粘贴到你的邮件客户端中。

有时你遇到的问题可能源于 Emacs 或 Org 模式的配置错误。 提交错误报告前，以最小化自定义配置启动 Emacs 并复现问题会很有帮助。 这样做通常能帮你判断问题出自你的自定义配置还是 Org 模式本身。 你可以通过类似下方示例的命令启动典型的最小化会话。 

$ emacs -Q -l /path/to/minimal-org.el

但如果你使用的是 Emacs 自带的 Org 模式版本，则无需最小化配置， 直接以 ‘emacs -Q’ 启动 Emacs 即可。 ‘minimal-org.el’ 配置文件可包含如下内容： 

;;; 用于加载最新 `org-mode' 的最小化配置

;; 启用调试
(setq debug-on-error t
      debug-on-signal nil
      debug-on-quit nil)

;; 将最新 Org 模式加入加载路径
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))

若你使用的是 Git 仓库中的 Org 模式版本， 可通过 ‘make’ 启动最小化会话。 

# 纯净 Emacs
make repro
# 或传入额外参数
make repro REPRO_ARGS="-l /path/to/minimal/config.el /tmp/bug.org"

若出现错误，“调用栈回溯(backtrace)” 信息会非常有用— 下文会说明如何生成该信息。 通常一份小型示例文件会很有帮助，同时请清晰说明以下内容：

  1. 你具体执行了什么操作？
  2. 你期望发生什么结果？
  3. 实际发生了什么？

若你感受到性能下降，可录制一份 “性能剖析文件(profile)” 并分享至 Org 邮件列表。 下文会说明如何生成有效的性能剖析数据。

感谢你帮助改进这款程序。

How to create a useful backtrace

若使用 Org 时出现无法理解的错误提示，你可能遇到了程序缺陷。 报告此类问题的最佳方式是，除上述信息外，额外提供一份调用栈回溯信息。 该信息来自内置调试器，记录了错误发生的位置与原因。 以下是生成有效调用栈回溯信息的方法：

  1. 重新加载所有未编译的 Org 模式 Lisp 文件。 使用未编译代码生成的回溯信息会丰富得多。 执行此操作的命令为： 
    C-u M-x org-reload <RET>

    或通过菜单操作：Org → 刷新/重新加载 → 以未编译形式重新加载 Org。

  2. 随后启用调试器： 
    M-x toggle-debug-on-error <RET>

    或通过菜单：选项 → 出错时进入调试器。

  3. 执行触发错误的操作，并记得记录操作步骤。
  4. 触发错误后，屏幕会出现 ‘*Backtrace*’ 缓冲区。 将该缓冲区保存为文件（例如使用 C-x C-w）， 并附加到错误报告中。

How to profile Org performance

有时 Org 会无故运行缓慢。 这类卡顿通常由第三方包与 Org 模式的交互导致， 但定位根本原因并非总是易事。

Emacs 可以记录性能统计数据， 借此找出执行耗时最长的函数。 记录统计数据需要使用性能剖析器。 使用 Emacs 剖析器建议按以下步骤操作：

  1. 确保当前无剖析器正在运行： 
    M-x profiler-stop <RET>
  2. 启动新的 CPU 性能剖析会话： 
    M-x profiler-start <RET> cpu <RET>
  3. 正常使用 Emacs，执行那些感觉卡顿的操作。
  4. 查看并分析记录的性能统计数据： 
    M-x profiler-report <RET>

    该命令会显示 profiler-start 与 profiler-report 执行期间所运行的命令与函数摘要，耗时最长的命令会显示在顶部。

    可在剖析器缓冲区中按 ‘<TAB>’ 键折叠或展开行。 展开后显示的子项即为被展开父项所调用的函数与命令。

    根本原因通常深藏在剖析器的子项中。 你可以按 ‘B’ (profiler-report-render-reversed-calltree) 快速定位实际耗时最长的函数/命令。

    按 ‘C’ profiler-report-render-calltree 可恢复原始视图。

  5. 若需要进一步帮助，可分享统计数据。

    保存数据的命令为： 

    M-x profiler-report-write-profile <RET>
/path/to/profile-file-to-be-saved <RET>

    随后将保存的文件附加到发送至 Org 邮件列表的邮件中， 并详细说明触发卡顿的操作。

    注意：保存的统计数据仅包含函数名与执行耗时， 不会记录任何隐私数据。

Footnotes

(2)

为减轻邮件列表管理员的工作负担，建议你订阅该邮件列表。

Next: Typesetting Conventions Used in this Manual, Previous: Activation, Up: Introduction   [Contents][Index]