开始之前

developerWorks 的编辑期盼与您合作，发表您的文章。在使用这些说明之前，请确保您已经向一位编辑提出了您的投稿意向并获得了他/她的同意。如果您没有作好这些准备，您可以使用我们的 “提交文章”表单 提交您的想法。

developerWorks 上的文章和教程以 XML（扩展标记语言）格式写作，以 HTML 格式发布。在发表之前，每篇文章或教程的 XML 源文件都要经过验证，以符合 developerWorks 模式中的定义。然后，使用 XSLT（扩展样式表转换语言）样式表转换成 HTML 格式发表。本文将分步骤详细介绍这一流程，这将使您能够控制文章最终发表时显示在浏览器上的样式，同时也可以帮助我们利用自动化的流程管理您的投稿。

我们提供的创作步骤并不需要专业技能。如果您已经熟悉 XML 或者 HTML，那么你会发现我们的文章或教程模板非常容易使用。否则，您可以稍后通过阅读说明中的 写作注意事项 来熟悉 XML。另外，请浏览 developerWorks XML 专区 中的 XML 新手入门 页面。

回页首

是文章，还是教程?

如果您浏览过 developerWorks 站点，就会了解：文章和教程是 developerWorks 的主要内容，二者的格式和目的各不相同。您的 developerWorks 编辑能帮助您决定什么样的格式最适合您的内容主旨。

教程

• 教程具有教育性的目的，用来传授知识。教程解释了所采取的每一步骤以及它会对最终结果造成怎样的结果，而不只是简单的步骤罗列。教程清楚地说明了其教育性目的和完成时间（通常是 2 个小时左右）。阅读完一篇教程后，读者应当能够独立地重做所学的任务。
• 教程能够讲授概念或者传授怎样完成任务。许多教程不仅讲授概念和任务，还鼓励读者在阅读时尝试操作。为了便于读者理解，教程经常包括一些简单的代码和建议，用来建立读者的使用环境。而且，教程也经常把大的任务分成离散的、易于管理的小块任务。
• 教程需要注册 IBM ID。
• 如果打印出来，教程平均有 20 到 30 页。由于教程中的任务可能需要几个小时才能完成，许多读者在完成任务的过程中都会将其打印出来，作为参考手册。
• 一个教程可能是独立的，也可能是一个系列的一部分。

文章

• 像教程一样，文章也会说明其教育目的或完成时间，但讲述的不像教程那样详细。
• 除在指导读者完成特殊任务外，文章还会介绍新理念、架构或者产品特性。这种文章的目的是为了唤起读者的共鸣，刺激他们的求知欲（很可能使读者去进而学习另一份相关的教程）。其他一些文章则更具理论色彩，作者是为了分享他/她自己独特的方法、观点或经验。还有一些文章通过专家访谈或审读当前著作深入研究一个新产品或新技术。
• 文章不需要注册。
• 文章不超过 10 页。读者一般在线阅读文章内容。
• 跟教程一样，文章可能是独立的，也可能是一个系列的一部分

回页首

基本步骤

要创建一篇文章或者教程，请按以下步骤操作：

1. 下载作者工具包（author package）并解压。
2. 复制文章或者教程的 XML 模板。
3. 编辑XML 模板放入您的目录，然后根据模式验证 XML 并纠正错误。
4. 在浏览器中预览您的文章或者教程，查看它的显示效果。

回页首

第 1 步. 下载作者工具包（author package）

下载 author-package-cn-vnn-xxxxxxxx.zip 文件并放在适当的位置（例如，Windows 中的 C:\ 或者 Linux 中的 home 目录)。解压文件并把所有解压后的文件放置到正确的目录。

developerworks 目录不一定要放到根目录或者是 Windows 中的 C:\ 盘。工具认为所有的文件位于 developerworks 目录以及它的子目录内，所以请保持 developerworks 目录结构以及文件名的原样。

解压文件后，您会看到一个名为 developerworks 的目录（文件夹），包含以下子目录：

• i —— 包含预览您的文章或教程所需的图片。
• js —— 包含预览您的文章或教程所需的 JavaScript。
• readme -- 包含本文的副本（index.html），还包含关于使用可选则工具的指导文章（tools.html)。 两个文件的 XML 源文件也包括在里面。
• schema —— 包含模式 (schema) 文件。主要的模式 (schema) 文件是 dw-document-n.n.xsd。（n.n 是 developerWorks 模式的版本号，5.8 是写这篇文章所用的模式版本。）
• xsl —— 包含主要的样式表文件 dw-document-html-n.n.xsl 和一些次要的样式表文件。
• tools —— 包含两个模板 （template-dw-article-5.8xml 和 template-dw-tutorial-5.8.xml），还有一些简单的工具帮助您建立和验证一篇新的文章。万一您想更改或重建 Linux 验证和转换工具，Java 子目录中包含可以使用的 Java™ 程序。

作者工具包中包含的文件和工具只能在 Linux 或 Windows 下使用。 如果您需要在 Windows 或 Linux 以外的系统中使用辅助编辑模板，请联系您的 developerWorks 编辑。

回页首

版本信息

在继续第 2 步之前，让我们预览一下在这个版本中的改变。在写这篇文章时，developerWorks 模式和样式表的版本是 5.8。工具包中的文件和这篇文章符合 5.8 版本。所以，您将要准备在您的文章或教程中使用 5.8 模式和样式表。如果您还在使用早期的版本，请在 下载 部分中了解如何下载 5.8 工具包。

5.8 模式和样式表都是在 2007 年 5 月发布的。并且根据使用者的观点，它与以前版本相比只有一些很小的改动。 教程和文章都使用同一种主要的模式（xsd 文件）和主要的样式表 (xsl file):

• 主要的模式：dw-document-5.8.xsd
• 主要的样式表：dw-document-html-5.8.xsl

作者们关注的变化小结如下：

• 优化了文章和教程的可视宽度，代码清单（<code type="section">）中的行包括空格不能超过 90 字节。为了帮助您发现超过 90 字节的代码行，在您预览时，您会在代码清单中看到错误信息。如果不能够拆分过长的行，您的编辑可能给出其他可选建议，比如把代码清单放在一个可下载的文件中，而不是放在您的文章或教程主体中。
  
  
• 同样，若图像在文章中超过 572 像素或在教程中超过 500 像素，在您预览时，您会看到在图像所在的地方是一个错误信息。您可以改变图像的尺寸或把它们放在一个单独的文件中。
  
  
• 如果您的文章或教程包括下载标记，像这篇文章中的 下载 一样，那么您可以包含一些注释，以说明关于下载的更多细节。
  
  
• 增加了扩展名为 .sch 的文件下载支持。

回页首

第 2 步. 创建新的模板

在这个步骤中，您将可以使用作者工具包中的工具建立一个文章或者教程模板的副本。这将在一个单独的目录中创建新的 index.xml 文件。它会建立合适的路径并调整模板，以使它能正确地在不同的操作系统环境中工作。

使用 Microsoft Windows

在 developerworks 目录中，双击 new-article.vbs 建立一篇文章。您可以选择一个有效的名字作为您的文件夹名。 默认的名字是 my-article。

单击 OK 之后，您会在 developerworks 目录中看到一个新的文件夹。您可能需要刷新您的视图（View > Refresh）才能看到。在这个新文件夹中包含您的文章或教程的模板（index.xml）以及验证和转换脚本（dw-transform.vbs）。

使用 Linux

使用 developerworks 目录中的 new-article.sh shell 脚本。（如果您运行了 KDE 或 GNOME 桌面，可以在像 Nautilus 或者 Konqueror 的图形管理器中运行。否则，在终端窗口中运行脚本。）您将会看到一个可以输入新项目名称的对话框。您可任意选有效的名字。默认的名字是 my-article 和 my-tutorial。

在您选择了 OK（或按下 Enter）后，您会在 developerworks 文件夹中看到一个新的文件夹。这个新的文件夹包含您的文章或教程的模板（index.xml）以及验证和转换脚本（dw-transform.vbs）。

回页首

第 3 步. 编辑和验证您的 XML

有两种基本方法可用于编辑和验证 XML 源文件，您可任选其中的一种。

使用 XML 验证工具

使用一个 XML 验证编辑器来编辑和验证您的 XML 可以帮助您识别错误。现在市场上有许多用于 Windows 和 Linux 的商业 XML 编辑器。例如：Rational® Web Developer for WebSphere® Software、<oXygen/> 和 Altova XMLSpy（请参见 参考资料 中的下载和文档链接）。 三者都提供免费下载的试用版本，并且我们推荐您阅读其中的产品说明去学会怎么使用它们。在 developerWorks author-package.zip 文件 里有如何使用这些产品或其他商业 XML 编辑器开发文章或教程所需的文件和支持文件。

还有一些免费的 XML 编辑器可用。上面提到的 XMLSpy 除商业版本之外，Altova 已经发布了一个免费的 XMLSpy Home Edition 编辑器。除此之外，如果您使用 Eclipse 平台准备 XML 文档，那么有一些插件可以使用。请参见 参考资料 链接。

当使用 XML 验证编辑器或工作台时，谨记：

• 在模板里，设计模式和样式表文件的相对目录都是相对于 您的教程或文章目录。您可能需要更改相对目录（..\schema\5.8\dw-document-5.8.xsd 和 ..\xsl\5.8\dw-document-html-5.8.xsl）为绝对目录，例如 C:\developerworks\schema\5.8\dw-document-5.8.xsd。在一些编辑器里，您可能必须通过其他的构造方式指定这些文件的位置。
• 如果您在一个 XML 编辑器中转换您的教程或文章，但未显示出任何图像，那可能是编辑器在用于临时存储的文件夹中创建了 HTML 文件。因此，您需要将生成的 HTML 文件保存到您的文章目录中（在我们的例子中是 my-article），并用 XML 图形编辑器或其他浏览器打开它。

使用文本编辑器和验证工具

如果您没有找到喜欢的 XML 验证编辑器，或者不愿意花时间学习，那么可以使用您偏好的文本编辑器来编辑 XML 模板。然后使用作者工具包提供的工具（Windows 的 dw-transform.vbs 或 Linux 的 dw-transform.sh）验证您的 XML 并将其转换为 HTML。这样，您就可以在浏览器中预览 HTML了。请参见相关文章 “使用 developerWorks XML 验证工具” 中关于这一工具的使用细节。

回页首

第 4 步. 预览您的文章或教程

您可以通过预览大致了解文章或教程最后输出的效果。然而，预览版本和最后版本之间存在一些不同。预览教程或文章时，将精力集中在内容上，不要担心版式或样式方面。在最后的编辑中，我们将会作出必要修改。

如果您使用 XML 验证编辑器，按照怎样转化 XML 为 HTML 的说明检查文件，然后用浏览器观察文件。如果您使用的是有浏览器览选项的编辑器，则可以省略这个步骤。

如果您使用文本编辑器和 dw-transform 脚本，您的 HTML 输出文件将在文档或教程文件夹中创建。用浏览器打开 index.html。使用这些脚本的更多详细介绍请参见 “使用 developerWorks XML 验证工具” 中。

回页首

写作注意事项

在您写作文章或教程时，XML 模板中的注释是您最好的综合指南。模板（在 tools 目录中的 template-dw-article-5.8.xml）中的大量注释将指导您完成文章和教程中编码的每个细节。您还可以将本文的 XML 源代码作为指南（readme 目录中的 index.xml）。下面给出一些对您可能有用的提示：

• 您可以将内容从其他格式的文件中剪切和粘贴到 XML 模板中。如果您剪切和粘贴的文件有嵌入格式，例如 Microsoft Word 文件，利用编辑器的功能将其粘贴（或者选择性粘贴）为文本或者在您剪切和粘贴前将原文件保存为纯文本格式。不要直接剪切和粘贴格式化的文件，例如 Word 文件。
  
  
• 务必牢记使用结束标记。例如，每个段落标记（<p>）都需要结束标记（</p>）。同样，像换行标记（<br />）和图片标记（<img />）这样的空元素结尾处需要具有一条斜线。
  
  
• 避免使用跨距标记、代码字体标记和 font 类。
  
  
• 在包含示例代码清单时：
  
  
• 限制代码行长度为 90 字节（含空格）。
• 避免在代码行尾处使用全角空格或者制表符。
• 避免在代码行的开始使用制表符。如果必需缩进，则使用空格。
• 不要使用彩色。如果您想突出显示部分示例代码，请使用粗体（<b> 和 </b>）。
  
  
• 假若要提供代码供下载，压缩您的代码并把压缩文件单独发给编辑。
  
  
• 将所有图片文件（包括屏幕截图在内）创建为 JPG 或 GIF 文件，确保它们的宽度不超过 572 象素（教程中的图片宽度不超过 500 像素）。将图片文件发送给编辑。参阅 “Illustrating your article or tutorial for developerWorks”，了解如何创建和递交效果更好的图片。
  
  
• 编码的特殊字符如下：
  
  
  
  

  表 1. 特殊字符

  字符	XML 编码
  & 符号（&）	&（请把所有 & 符号编码成 & —— 即便是在 URL 中）
  单引号（'）	'
  大于号（>）	>
  小于号（<）	<
  双引号（“）	"
  注册商标（®）	<reg/>（作者可以插入商标符号，但不是必须的。）
  商标（™）	<trade/>（作者可以插入商标符号，但不是必须的。）

  
  
  
  

  例如，要在代码中包含尖括号：

  <TABLE border="0" width="100%">

  
  

  您将在 XML 模板中编入以下代码：
  
  <TABLE border="0" width="100%">

• 最后，为了更好地在开发时查看您自己的内容，在您熟悉标记后，请删除掉文章中的注释行。

回页首

突出显示

不能确定哪些需要 <code type="inline"> 标记，哪些不需要？您为文章中的书名使用斜体和引号吗？您应该在什么时候用粗体 —— 或者根本不使用突出显示？表 2 展示了推荐给 developerWorks 作者的突出显示的惯例。

代码示例

回页首

将您的文章或教程提交给 developerWorks

完成您的杰作后，就随时可以把它发送给您对应的 developerWorks 编辑。将文章或教程的 XML 文件（连同相关的图片或代码）用电子邮件发送给您的编辑。关于为文章创建和提交图片的详细指南和注意事项，请参见 “Illustrating your article or tutorial for developerWorks: Graphic design tips for authors”。

如果您还有其他疑问和问题，请 联系编辑 获取额外的帮助。

回页首

下载

关于下载方法的信息

参考资料

学习

• 您可以参阅本文在 developerWorks 全球站点上的 英文原文 。
  
  
• “使用 developerWorks XML 验证工具”（developerWorks，2006 年 8 月）：如果您倾向于使用文本编辑器编辑 XML 模板，您可以使用作者工具包提供的工具验证 XML 并且预览您的内容。
  
  
• “Illustrating your article or tutorial for developerWorks: Graphic design tips for authors”（developerWorks，2006 年 1 月）：获得创建并提交您文章或教程中的图形的详细指导方针和注意事项。
  
  
• developerWorks 投稿指南：了解更多的编辑方针并看看 developerWorks 征稿内容列表。
  
  

获得产品和技术

• Microsoft 的 XML 解析器（MSXML）：为了使用 dw-transform.vbs 脚本来转换您的文章或教程, 您需要最新版本的 MSXML 解析器。还需要 msxml.msi 文件。
  
  
• IBM Developer Kit for Java， Version 1.4.2：在 Linux 上使用 dw-transform.sh 脚本转换您的文章或教程，您需要 IBM Developer Kit for Java V1.4.2 或更新版本。
  
  
• Rational® Web Developer for WebSphere® Software V6.0：直接从 developerWorks 下载试用版本。
  
  
• 供下载的 IBM 试用产品：使用IBM 试用软件构建您的下一个开发项目，这些软件可以从 developerWorks 直接下载。
  
  
• XML 编辑器：详细查看免费的 XML 编辑器的清单，这是由 Lars Marius Garshol 维护的。
  
  
• <oXygen/> XML 编辑器 & XSLT 调试器（多平台）和 Altova XMLSPY（用于 Windows）：了解并下载其他的商业 XML 产品试用版本。
  
  
• “XML development with Eclipse”（developerWorks，2003 年 4 月）：使用带插件（例如 Bocaloco Software 的 XMLBuddy）的 Eclipse 创建 XML 文档。
  
  

讨论

• “提交文章”表单：将文章或教程的想法提交给 developerWorks，并开始与 developerWorks 编辑交流。查看 内容列表 中的哪些是最需要的。
  
  

关于作者

为本文评分

评论

回页首

内容

• 开始之前
• 是文章，还是教程?
• 基本步骤
• 第 1 步. 下载作者工具包（author package）
• 版本信息
• 第 2 步. 创建新的模板
• 第 3 步. 编辑和验证您的 XML
• 第 4 步. 预览您的文章或教程
• 写作注意事项
• 突出显示
• 将您的文章或教程提交给 developerWorks
• 下载
• 参考资料
• 关于作者
• 建议