技术说明 0
6 分钟阅读
Technical Note 0 技术说明 0
Last update: Thu Mar 18 14:03:37 BRT 2004 by lhf.
How to write a Lua Technical Note 如何编写 Lua 技术说明
There are no official guidelines for writing a Lua Technical Note. You may read Author’s Guide and On the Elements of a Technote, from the Macintosh Technical Notes, but read these documents just for an idea of what technical notes look like; Lua Technical Notes are much more informal.
没有编写 Lua 技术说明的官方指南。您可以阅读 Macintosh 技术说明中的作者指南和技术说明的要素，但阅读这些文档只是为了了解技术说明的样子；Lua 技术说明更为随意。
Below is a personal (and self-referential!) view of how to write LTNs.
以下是有关如何编写 LTN 的个人（且自我参照的！）观点。
How to write an LTN 如何编写 LTN
by Reuben Thomas 作者：Reuben Thomas
Abstract 摘要
An LTN should have the following structure: LTN 应具有以下结构：
- Abstract 摘要
- The problem - Motivation and statement 问题 - 动机和陈述
- The solution - Description 解决方案 - 说明
- Explanation and justification 说明和理由
- Weaknesses and suggested improvements 弱点和建议改进
- Conclusion 结论
The problem 问题
Lua is a brilliantly economical tool for solving many programming problems. Unfortunately, its economy and flexibility of design can confuse the newcomer: they may find a clumsy solution to their problem, or worse, not see one at all, when there is a simple and elegant solution waiting to be found. Unlike users of most languages, who simply program in them, Lua programmers will often want to embed, interface to, or even change Lua. Lua 是一个非常经济的工具，可以解决许多编程问题。不幸的是，它的经济性和设计灵活性可能会让新手感到困惑：他们可能会发现一个笨拙的解决方案来解决他们的问题，或者更糟糕的是，根本看不到解决方案，而实际上有一个简单而优雅的解决方案等待着被发现。与大多数语言的用户不同，他们只是用这些语言进行编程，Lua 程序员通常希望嵌入、接口甚至更改 Lua。
Various libraries and tools have grown up to meet many of these needs, such as tolua, CGILua and LuaSocket. However, some needs are more abstract, and cannot easily be met by a tool or library; questions such as: How can I integrate Lua into my C++ program? How can I interface Lua to another language? How can I avoid pausing my game for garbage collection? Questions like these are best tackled by HOWTO-like documents, and this is what the LTN series aims to do. But how should LTNs best be written in order to meet this need?
各种库和工具已经发展起来以满足这些需求中的许多需求，例如 tolua、CGILua 和 LuaSocket。但是，有些需求更抽象，无法通过工具或库轻松满足；例如以下问题：如何将 Lua 集成到我的 C++ 程序中？如何将 Lua 与另一种语言连接？如何避免因垃圾回收而暂停我的游戏？诸如此类的问题最适合通过 HOWTO 类文档来解决，而这就是 LTN 系列的目标。但是，为了满足这一需求，LTN 最好如何编写？
An LTN should have the following properties:
LTN 应具有以下属性：
- It should address a real need. As a rule of thumb, if you can be motivated to write an LTN, it’s probably addressing a real need, though it’s even better if others have asked for solutions to the problem it addresses. 它应该解决一个实际需求。作为经验法则，如果您有动力编写 LTN，那么它可能正在解决一个实际需求，但如果其他人要求解决它所解决的问题的解决方案，那就更好了。
- It should be brief. This allows others to read, understand and use the knowledge it contains as quickly as possible; or, on the other hand, to discard it if it’s no good to them. As part of this, it should not be necessary to read the whole LTN to know if it’s what you need. 它应该简短。这允许其他人尽可能快地阅读、理解和使用其中包含的知识；或者，另一方面，如果对他们没有好处，则将其丢弃。作为其中的一部分，无需阅读整个 LTN 来了解它是否是您需要的。
- It should be authoritative. An inaccurate or badly thought out LTN may well be worse than nothing. Again, if you feel like writing an LTN, you’ll probably know what you’re talking about. The Lua designers act as editors for the series, which also helps. 它应该是权威的。不准确或考虑不周的 LTN 可能比没有 LTN 更糟糕。同样，如果您想编写 LTN，您可能知道自己在说什么。Lua 设计师充当该系列的编辑，这也提供了帮助。
The solution 解决方案
There are two parts to the solution: form and content. The content is up to the author; the suggested form for an LTN is as follows: 解决方案分为两部分：形式和内容。内容由作者决定；建议的 LTN 形式如下：
Abstract 摘要
Summarise the LTN. 总结 LTN。
The problem 问题
Motivate the problem: why is it important. End with a clear statement. This will help both you and the reader to focus. By the end of this section the reader should know if the LTN is useful for them. 激发问题：为什么它很重要。以明确的陈述结束。这将帮助您和读者集中注意力。在本节结束时，读者应该知道 LTN 是否对他们有用。
The solution 解决方案
Describe the solution, without elaborating on the whys and wherefores more than necessary. By the end of this section, a reader who’s in a hurry should be able to implement the solution. 简要描述解决方案，不必过多地阐述原因和缘由。在这一部分的结尾，匆忙的读者应该能够实施解决方案。
Explanation 解释
Explain and justify why you designed your solution the way you did. This will hopefully convince the skeptical and reassure the cautious that your solution is good and you know what you’re doing. Peripheral matters and non-critical subtleties can be explored here (but keep it relevant!). 解释并说明您为何以这种方式设计解决方案。希望这能够说服持怀疑态度的人，并向谨慎的人保证您的解决方案很好，并且您知道自己在做什么。可以在这里探讨外围问题和非关键的细微差别（但要保持相关性！）。
Weaknesses 弱点
Discuss weaknesses of your solution, say why they’re not critical to its success, and suggest future improvements. This is where you’ll really convince the skeptic you know your stuff. 讨论解决方案的弱点，说明为什么它们对解决方案的成功并不关键，并提出未来的改进建议。在这里，您将真正说服持怀疑态度的人，让他们知道您了解自己的东西。
Conclusion 结论
Summarise, and give a wider perspective on the problem and solution. 总结，并对问题和解决方案给出更广泛的视角。
Explanation 解释
This structure follows standard practice for good technical writing. The simple five-part structure encourages brevity, fits most conceivable LTNs, is simple for the author and reader to follow, and allows most readers to get everything they need from the LTN by starting at the top and reading until they’ve had enough. 此结构遵循良好的技术写作标准惯例。简单的五部分结构鼓励简洁，适合大多数可以想象的 LTN，作者和读者易于遵循，并且允许大多数读者通过从顶部开始阅读直到他们读够为止，从而从 LTN 中获取他们需要的所有内容。
Weaknesses 弱点
One size never fits all. The proposed structure will be too detailed for some, not enough for others, and simply irrelevant to others. I have said nothing about how actually to write (see “The Elements of Style” by Strunk and White for clear, brief guidance on this). Nonetheless, if most authors follow this structure, they will hopefully find LTNs easier to write, and readers will certainly find them easier to read because, if nothing else, of their common structure. 一种尺码永远不适合所有人。提议的结构对一些人来说过于详细，对另一些人来说不够，对另一些人来说根本不相关。我没有谈论如何实际写作（请参阅 Strunk 和 White 的“风格要素”，以获得有关此方面的清晰简短的指导）。尽管如此，如果大多数作者遵循此结构，他们有望发现 LTN 更容易编写，读者肯定会发现它们更容易阅读，因为如果没有别的，它们具有共同的结构。
Conclusion 结论
Lua’s brilliance lies largely in providing generally applicable mechanisms rather than solutions to specific problems. Nevertheless, many problems crop up frequently in the use of Lua. Some of the more concrete ones are addressed by the variety of libraries and tools available; LTNs attempt to address some of the more abstract kind. This LTN proposes a structure for LTNs to make them more likely to be useful. Lua 的出色之处在于它主要提供一般适用的机制，而不是针对具体问题的解决方案。然而，在使用 Lua 时，许多问题经常出现。各种可用的库和工具解决了其中一些更具体的问题；LTN 尝试解决一些更抽象的问题。此 LTN 为 LTN 提出了一个结构，以使其更有可能有用。
Finally, Lua programmers and LTN authors alike should always bear in mind the first rule of Lua: “Do it in Lua”. Lua almost always provides you with the tools you need to solve your problem; it’s just a case of seeing how to use them. You should rarely have to use Lua API seriously, and even more rarely have to change Lua itself. In terms of the three cardinal virtues, Lua ranks laziness above impatience, and impatience above hubris. But of course, hubris is just what it takes to write an LTN!
最后，Lua 程序员和 LTN 作者都应该始终牢记 Lua 的第一条规则：“用 Lua 来做”。Lua 几乎总是为您提供解决问题所需的工具；这只是如何使用它们的问题。您很少需要认真使用 Lua API，甚至更少需要更改 Lua 本身。就三个基本美德而言，Lua 将懒惰置于不耐烦之上，将不耐烦置于傲慢之上。但当然，傲慢正是编写 LTN 所需要的！