格式上的小建议

[Subilan]

好巧不巧看到了这样一个 Bukkit 教程，粗略地看来一下，虽然不是内容不是非常深入和非常丰富的那种，但是对于我这样的 Bukkit 新手玩家已经可以说是很难得的好教程了！不过作为格式强迫症的我还是想在 Markdown 格式上面提一些小建议，可以酌情考虑参考~

首先，恰当使用 accent block。对于 Docsify 中出现的一些 accent block（也就是 !> 和 ?>），很多时候前者是用来警告「这样做会导致 ... 严重后果」「因为 ... 所以千万不要这样做！」之类的重要消息，而后者可以用来写一些「你知道吗？」「知识拓展」「小练笔」亦或者是简单的几句论述性的文字。混用也许不仔细看并不能看出什么奇怪的地方，但是总感觉有一些不妥之处。例如 1.2-了解BukkitAPI.md 中的

!> 虽然你会觉得 **Minecraft** 的每个更新都是个 **`大更新`**，实际上并不是，在 **Bukkit API** 里面实际上大同小异，就是说，老版本有的一个很简单的发送消息的 API，在高版本仍然可以实现，但是如果你想在 `1.13` 版本中放置**哭泣的黑曜石(`1.16`)**，那是不可能的！**Valkyrie** 虽然使用 `1.13` 作为教学，**但是一切，都要看你对自己插件版本的定位**

这样的段落，实际上无需采用 accent block，或者使用绿色的 ?> 即可。那么究竟不恰当使用 accent block 会有哪些危害呢？其实很简单，有两点：

• 造成视觉上的疲劳。如果一篇文章或者一个整体系列中屡次出现 accent block，尤其是出现与该 accent block 并不适配的文字时，极有可能出现视觉疲劳；
• 造成理解上的困难。如果 accent block 的内容与其视觉上想要表达的相违背，那么无论这些内容是否真的「合适」，在经过一次又一次的混淆之后，也许就可能难以理解。在这里的「理解」并不是说理解这段文字在表达什么，而是理解这段文字在形式上的含义，究竟是「极为重要」还是「提醒劝告」还是「我就说说」还是「你知道吗」？

其次，合理安排自己的 Markdown 格式使用。还是拿这句话来举例子。比如

**`大更新`**
**哭泣的黑曜石(`1.16`)**

这些用法极为罕见。同时，我也发现从 README 开始，这个电子书就充斥了许许多多的粗体，让人看起来就像是在演讲，粗体则代表上扬的语气。我认为并不需要这样，因为也许反而在你想要真正强调有些东西的时候，就找不到合适的格式来用了，因为一些「并不那么重要」的语句都已经被冠上了粗体。那么在这个时候可能就会出现奇奇怪怪的格式，比如 这样子的格式。

我认为对于这种 粗体代码块，更恰当的用法是「对代码进行强调」。例如，这个地方就用得非常好：

...

你就可以看到 **`Hello Valkyrie`** 显示在控制台内，恭喜你，你掌握了如何使用 API，但别忘了，这只是开始，后续还有更多 API 等着你使用

然而代码块的滥用也是不太好的，例如这里

服务端分为 **`Vanilla`** (即官方原版服务器)、**`Bukkit / Spigot`** (即插件服务器，在原版的基础上可以额外加装插件，类似的还有 **`PaperSpigot`** 和 **`TorchSpigot`** 等)、**`Forge`** (如果你学过模组，这个应该很明显了，就是模组服务端，可以在服务器中加装模组，前提是，客户端也拥有同版本的同样模组)、**`Sponge`** (这个就比较神奇了，它支持插件+模组的混合使用，但唯一遗憾的一点是，**Bukkit** 的插件并不支持 **`Sponge`**，它有它自己的插件开发方式和规范)、**`社区服务端`** (不管其它的如何，光是社区端就五花八门了，而且社区端一个个能力都不差，比如 **`CatServer`** 或 **`Arclight`**，不仅仅支持使用模组，还能安装 **Bukkit** 插件)

我归纳出了三点问题

• 大量的 粗体代码块 使用在非代码名词上；
• 括号的内容过于冗长
• 非代码名词的格式不统一

诸如 Vanilla、Bukkit / Spigot 这类文字，其实是不需要使用代码块括起来的，它们只是几个普通的名字。而对于那些我们在实际过程中可能获取到的值，比如上文中的 Hello World，使用代码块则是再合适不过了。

如果想要解释某个名字，不如用注解符号¹。这种符号虽然并不包含在 Markdown 的标准范畴内，但是如果能够用 HTML 实现出来，想必效果是不错的。对于括号，则应用在一些并不复杂的句子上，如果括号的内容过多，甚至成段成段地写，就会打断用户对原本句子的整体理解，固然是不好的。

然后就是要注意格式之间的统一。假设我们真的用 这种方式 来标记 Bukkit、Spigot 等名词，也要尽量确保这些名词都被应用同一种格式。这段文字中出现的纰漏正是

**Bukkit** 的插件并不支持 **`Sponge`** ...
比如 **`CatServer`** 或 **`Arclight`**，不仅仅支持使用模组，还能安装 **Bukkit** 插件

Bukkit 在这段话中与其它提到的名词之间并不存在类义上的区别，因此应当尽量保证格式统一。

以上就是我对格式的想法。很支持你的这个电子书，已经 Star 了~ 期待 Ela 能够带来更多优质的内容！如果你有什么想法的话，欢迎与我讨论，在这个 issue 下或者给我发邮件都可以。

[Subilan]

补充一点：对于一个新的名词的出现，往往只需要在它首次出现的那个章节里用粗体加粗一次即可，并不需要全部加粗。

[ElaBosak233]

首先真的很惊喜，因为我以为即使我将来在 mcbbs 上面发布出去也没有人看，但万万没想到，在开发中，能有人提建议，所以一定要谢谢 Su，我将按照你的建议来适当地改进 Valkyrie，关于加粗文本这一点，本来我也是认为加粗能起到一个强调的作用，但现在回头看，发现很多不必要的地方我也强调了，这个问题我将在之后的版本陆续改进，根除为止，另外，accent block 的使用我也会进行重新审查，还有一件小事，这是我在 Github 玩的时候第一次收到除了 Gitalk 外的 issue，虽然有点 childlish，但我很开心，谢谢 Su

[Subilan]

加油~