小例子

什么是 “小例子”?

一个小例子 (tiny example) 是一个 任何 内容都不再能移除的例子。

为什么要创建小例子？

  • 例子越小，越能快速地让那些潜在的帮助者明白你的意图并帮助你。
  • 一个小例子演示了你如何自己尝试努力解决这个问题。如果人们 发送大量的输入，那看上去我们是否帮助他们并不那么重要。
  • 创建小例子可以帮助你理解当前发生了什么。在创建小例子时， 可以避免创建许多“假”的问题报告；如果你在小例子中不能复现 “bug” ，则问题可能是对 LilyPond 的不充分理解导致的， 而非一个真正的错误！

如何创建小例子？

  • 包含 \version 号。
  • 让它尽可能地小！关于空白（spacing）或页面布局的例子可能需要大量 小节的音乐，但更多的问题可以在一个小节内复现。
  • 当尝试创建小例子时，尝试将你文件中 (% 或者 %{ … %}) 的部分注释掉。如果注释掉这些内容后， 你仍然能够演示你的核心意图，则将这些内容从文件中移除。
  • 避免使用复杂的音符、调号或者拍号，除非错误是关于它们的外观的。
  • 不要使用 \override 或 \set 指令，除非错误时关于这些指令的
  • 可选地，附加一份图片来展示你期望的图形输出。

例子应当有多小？

下面代码展示的是一个小例子吗？ 

\version "2.14.1"
\include "english.ly"

\score {
  \new Staff {
    \key d \major
    \numericTimeSignature
    \time 2/4
    <cs' d'' b''>16 <cs' d'' b''>8.
    %% Here: the tie on the D's looks funny
    %% Too tall? Left-hand endpoint is not aligned with the B tie?
    ~
    <cs' d'' b''>8 [ <b d'' a''> ]
  }
}

显然，它并不是特别大，但真正的最小例子是这样的： 

\version "2.14.1"
{
  % middle tie looks funny here:
  <c' d'' b''>8. ~ <c' d'' b''>8
}

极少数的小例子会超过 10 行代码—— 大部分情形下， 4 行代码就足以演示问题！