技术说明 0

如何撰写 Lua 技术说明

没有撰写 Lua 技术说明的官方指南。你可以阅读作者指南和技术说明的要素，它们来自 Macintosh 技术说明，但阅读这些文档只是为了了解技术说明的外观；Lua 技术说明更加非正式。

下面是撰写 LTN 的个人（且自指）观点。

如何撰写 LTN

作者：Reuben Thomas

摘要

LTN 应具有以下结构

摘要
问题 - 动机和陈述
解决方案 - 描述
说明和理由
弱点和改进建议
结论

问题

Lua 是一个非常经济的工具，可用于解决许多编程问题。不幸的是，它的经济性和设计灵活性可能会让新手感到困惑：他们可能会找到一个笨拙的解决方案来解决他们的问题，或者更糟的是，根本看不到解决方案，而实际上有一个简单而优雅的解决方案等待着被发现。与大多数语言的用户不同，他们只是用这些语言进行编程，Lua 程序员通常希望嵌入、接口甚至更改 Lua。

各种库和工具已经发展起来以满足这些需求中的许多需求，例如 tolua、CGILua 和 LuaSocket。然而，有些需求更加抽象，无法轻易地通过工具或库来满足；例如以下问题：如何将 Lua 集成到我的 C++ 程序中？如何将 Lua 与另一种语言进行接口？如何避免因垃圾回收而暂停我的游戏？像这样的问题最适合通过类似 HOWTO 的文档来解决，而这正是 LTN 系列的目标。但是，为了满足这一需求，LTN 应该如何以最佳方式撰写？

LTN 应具有以下属性

它应该解决一个实际需求。根据经验，如果你有动力撰写 LTN，那么它可能正在解决一个实际需求，但如果其他人已经要求解决它所解决的问题，那就更好了。
应该简明扼要。这样，其他人就可以尽可能快地阅读、理解和使用其中包含的知识；或者，另一方面，如果对他们没有好处，就可以丢弃它。作为其中的一部分，无需阅读整个 LTN 即可了解它是否是你需要的。
它应该是权威的。不准确或考虑不周的 LTN 可能比没有更糟。同样，如果你想写一个 LTN，你可能知道自己在说什么。Lua 设计师充当该系列的编辑，这也提供了帮助。

解决方案

解决方案有两个部分：形式和内容。内容由作者决定；LTN 的建议形式如下

摘要: 总结 LTN。
问题: 阐明问题：为什么它很重要。以明确的陈述结束。这将帮助你和读者集中注意力。在本节结束时，读者应该知道 LTN 是否对他们有用。
解决方案: 描述解决方案，无需过多地阐述原因和缘由。在本节结束时，一位匆忙的读者应该能够实施该解决方案。
说明: 解释并说明你设计解决方案的方式。希望这能说服持怀疑态度的人，并让谨慎的人确信你的解决方案很好，并且你了解自己在做什么。可以在这里探讨外围问题和非关键的细微差别（但要保持相关性！）。
弱点: 讨论你解决方案的弱点，说明为什么它们对其成功不是至关重要的，并提出未来的改进建议。在这里，你将真正让持怀疑态度的人相信你了解自己的东西。
结论: 总结，并对问题和解决方案提供更广泛的视角。

说明

此结构遵循良好的技术写作的标准做法。简单的五部分结构鼓励简洁，适合大多数可以想象的 LTN，作者和读者易于遵循，并且允许大多数读者从顶部开始阅读并阅读到他们有足够的内容为止，从而从 LTN 中获得他们需要的一切。

弱点

一种尺码永远无法满足所有人。建议的结构对于一些人来说过于详细，对于另一些人来说还不够，而对于另一些人来说则根本不相关。我没有说明如何实际编写（请参阅 Strunk 和 White 的“风格要素”以获取对此的清晰简要指导）。尽管如此，如果大多数作者遵循此结构，他们有望发现 LTN 更容易编写，而读者肯定会发现它们更容易阅读，因为如果没有别的，它们具有共同的结构。

结论

Lua 的出色之处主要在于提供普遍适用的机制，而不是针对具体问题提供解决方案。然而，在使用 Lua 时，许多问题经常出现。各种可用的库和工具解决了其中一些更具体的问题；LTN 尝试解决一些更抽象的问题。此 LTN 为 LTN 提出了一个结构，以使其更有可能有用。

最后，Lua 程序员和 LTN 作者都应始终牢记 Lua 的第一条规则：“用 Lua 来做”。Lua 几乎总是为你提供解决问题所需的工具；这只是一个如何使用它们的问题。你很少需要认真使用 Lua API，甚至更少需要更改 Lua 本身。就三个基本美德而言，Lua 将懒惰置于不耐烦之上，将不耐烦置于傲慢之上。但当然，傲慢正是编写 LTN 所需要的！

上次更新：2004 年 3 月 18 日星期四下午 2:03:37 BRT，作者为lhf。