david -AT- lupercalia.net
2002-01-28
| 修订历史 | ||
|---|---|---|
| 版本 1.1 | 2002-01-28 | 修订者：dcm |
| 添加了 QandASet 部分，不得不调整文件名标记的语法。 | ||
| 版本 1.0 | 2002-01-23 | 修订者：dcm |
| 初始版本。 | ||
LDP 为我们的新文档使用 DocBook 格式，并且我们正在尝试将旧文档也转换为 DocBook 格式。不幸的是，DocBook 是一个非常庞大且复杂的 DTD，因此人们可能难以使用。我们一直在寻找使其更易于使用的方法，以便更多人可以帮助 LDP。
我们想到的解决方案灵感来自 WikiWikiWeb，这要归功于 LDP 作者 Martin Wheeler 的出色建议。我称之为 WikiText，因为它不是真正的 Wiki，但它具有真正 Wiki 的一些最佳功能。
Wiki 是一种网站，任何阅读该网站的人也可以编辑它。虽然 LDP 不会实施这种宽松的编辑方式，但我们非常喜欢 Wiki 编辑的工作方式。您无需学习 html 标签，只需以纯文本格式输入您的信息。Wiki 软件会获取该纯文本，并将其转换为 html 以显示。
在我们的例子中，我们不是转换为 html，而是转换为 DocBook。然后，该 DocBook 会被输入到我们的常规发布系统中，就像您最初用 DocBook 编写的一样。
如果您从未使用过 WikiWikiWeb，请访问 http://www.wikipedia.com，这是一个蓬勃发展的 Wiki 的好例子。
创建链接、项目符号列表、编号列表和节标题等常用功能变得快速而简单。我们希望为 LDP 作者提供相同的易用性，因此我编写了一个实用程序，它将采用类似于 Wikis 中使用的文本格式（我们称之为 WikiText），并将其与 LDP Database 中的元数据结合起来以生成 DocBook。
这里有一些原因：
它快速而简单。无需学习花哨的标签，只有一些简单的文本“提示”。
它功能强大。虽然您可以在不使用任何 DocBook 的情况下编辑 WikiText，但您也可以在其中使用任何 DocBook 标签。
它具有版本控制功能。您编辑的完整版本历史记录保存在数据库中。如果您不喜欢所做的某些操作，可以恢复到以前的版本。您也可以使用 cvs 执行此操作，但在在线系统中要容易得多。
它共享文档。与其他作者一起处理文档的作者可以通过 WikiText 进行协作。是的，cvs 也可以做到这一点，但再次强调，WikiText 更简单。
它易于访问。您只需要任何 Web 浏览器和一个 LDP 数据库帐户。
它是 WYSIWYG 的。“预览”功能，因此您可以单击“预览”按钮，查看您的文档在 LDP 站点上的外观。无需运行实用程序，无需学习任何东西，无需安装 DTD 或处理目录文件。如果您曾经尝试在您的机器上获得一个可工作的 DocBook 系统，您会体会到这一点！ :-)
我们尝试使用与 Wikipedia 上使用的相同的文本提示，这些提示来自 UseModWiki。不同的 Wiki 系统之间存在一些差异，但大多数系统都与此系统非常相似，并且已通过使用证明了自身。
空行分隔段落，还有其他提示用于创建章节、项目符号列表、链接、文件名等。
=Introduction|intro= |
创建一个新的顶级章节。看到管道字符后跟“intro”了吗？许多提示都提供了“id”，这就是您提供它的方式。对于章节，id 将成为输出文件名（在第一个示例中为 intro.html），或用于文档内链接的 html “标签”。
==How Does It Work?|how-does-it-work== |
创建一个二级章节，以及
===Why Would I Use It?|why?=== |
创建一个三级章节。
使用方括号来标识链接，如下所示
[[http://www.linuxdoc.org|Linux Documentation Project]] |
在这种情况下，管道字符后的文本不是 id，而是链接的“标题”。
除了您可能熟悉的标准“http:”和“mailto:”命名空间之外，您还可以使用两个特殊的命名空间。第一个是“ldp:”命名空间。请看以下链接
[[ldp:Distributions-HOWTO]] |
当您使用“ldp:”命名空间时，WikiText 将在 LDP 数据库中查找您命名的文档，并生成指向它的链接。
注意：我们仍在努力在所有数据库记录中输入正确的“name”，因此只有少数几个在工作。但请不要担心。如果您需要使用尚未正确的链接，请告诉我们，我们会立即修复它。
第二个特殊的命名空间是“wiki:”命名空间。它将生成指向 Wikipedia 上文章的链接，Wikipedia 是一个开源百科全书项目。我们希望将 Wikipedia 上最合适的文章镜像到 LDP 上。Wikipedia 上有很多关于计算机相关主题的优秀文章，这些文章不是我们在 LDP 上所做的那种信息，但它们可以很好地补充我们的文档。例如，有关于虚拟内存、操作系统等等的文章。目前，您的链接将转到 live Wikipedia 站点。最终，它将转到我们站点上的镜像，但会链接到“真实”站点。
以下链接转到 Wikipedia 上名为“Operating system”和“Linux kernel”的文章
[[wiki:Operating system]] [[wiki:Linux kernel]] |
Wikipedia 是所有网民的绝佳资源。他们使用的软件和内容都是开源的。
您可以使用双括号将文件名括起来以指示文件名，就像 http 和其他链接一样。或者，您可以指定“file”命名空间
[[/etc/apache/httpd.conf]] [[file:/etc/apache/httpd.conf]] |
无论哪种方式，它都将呈现为/etc/apache/httpd.conf.
欢迎任何 LDP 作者使用 WikiText。它位于 LDP 数据库 http://db.linuxdoc.org 上。您需要拥有数据库帐户。如果您还没有帐户，可以通过电子邮件向我申请。将您的全名（如您的文档上所示）、用户名和密码发送给我，我将在当天为您设置。
登录数据库后，单击“我的文档”。如果您没有看到您自己的文档列表（仅限），那是我搞砸了。 :-)
单击您要编辑的文档。您将看到一个页面，其中显示了我们为该文档准备的元数据。该页面上还有一个指向 WikiEdit 的链接。单击它，您就可以开始了。
单击“预览”以查看您的文档在 LDP 上的外观（只是它将呈现为单页）。
单击“DocBook”以查看 WikiText 从您的文本生成的原始 DocBook。
单击“保存”以将您的更改保存到数据库。您还可以为其添加“注释”，以供将来参考。
单击“版本历史”以查看您对文档所做的所有更改的记录。