如何维护 Debian 网站

一般信息

资源需求

如果您想参与我们的网站工作，请准备在您的磁盘上至少存储 740 MB 的数据。这反映了源代码存档的当前大小。如果您（意外地）重新构建所有页面，您将需要至少三倍的空间。

这些以 `#' 开头的行是什么？

在 WML 中，以 `#' 开头的行是注释。这些比普通的 HTML 注释更受欢迎，因为它们不会出现在最终页面中。

请阅读关于使用 WML 的页面以获取有关 WML 的更多信息。

编辑者礼仪

我可以修改这个页面吗？

这取决于情况。如果您看到一个小错误，比如拼写错误，就直接修复它。

如果您注意到某些信息缺失，也可以随时修复它。

如果您觉得某些内容很糟糕需要重写，请在 debian-www 上提出来进行讨论。我们可能会同意您的观点。

如果您注意到模板中有问题（即 webwml/english/template/debian 目录中的文件），请在提交之前仔细考虑更改，因为对模板的更改往往会导致网站的大部分内容重新构建。

添加新目录时，也要添加 Makefile！

向 git 添加新目录时应该小心。如果当前目录在 ../Makefile 中列出，那么您必须在其中创建一个 Makefile — 否则 make 会给出错误消息。

使用清晰简单的英语

由于 Debian 网页由非英语母语者阅读并被翻译成其他语言，最好用清晰简单的英语写作，避免使用俚语、表情符号和晦涩的习语。

如果您确实使用了其中任何一个，请在文件中添加注释解释其含义。

如有任何疑问，或为了校对您的建议，请联系英语本地化团队。

查看 README 文件

某些目录包含 README 文件来帮助您理解该目录是如何组织的。这些文件应该提供在该区域工作时所需的任何特殊信息。

将内容更改与格式更改分开

总是为内容更改和格式更改制作单独的补丁或提交。当它们结合在一起时，翻译者很难找到差异。如果您对这种混合更改运行 git diff -u，您可以看到这种混乱。

通常，避免随机的格式更改。使页面的旧部分符合 XHTML/XML 标准不应该与其他更改在同一次提交中完成。（当然，新内容可以并且应该从一开始就正确完成。）

如果可能，也要更新翻译

某些更改独立于 WML 文件中使用的语言，比如对 URL 或嵌入式 Perl 代码的更改。修复拼写错误也属于同一类别，因为翻译者在翻译时通常会忽略它们。 对于这种与语言无关的更改，您可以在所有翻译文件中进行相同的更改，而无需实际了解其他语言，并且可以安全地增加翻译检查头部中的版本。

翻译者自己完成同样的工作并不困难，而且对于说英语的编辑者来说，拥有一个完整的检出来操作可能会很不方便。但是，我们仍然鼓励人们这样做，以避免为了一个人可以快速完成的事情而打扰二十几个人。

此外，为了使这种更改更容易应用，您可以使用来自 webwml git 模块顶级目录的 smart_change.pl 脚本。

链接

这个链接看起来不对。我应该更改它吗？

由于网络服务器的设置方式（使用内容协商），您不应该需要更改任何内部链接。实际上我们建议您不要这样做。如果您觉得链接不正确，请在更改之前写信给 debian-www。

修复链接

如果您注意到指向外部网站的链接导致重定向（301、302、<meta> 重定向或显示此页面已移动。的页面），请告知 debian-www。

如果您发现损坏的链接（404、403 或页面不是链接所说的内容），请修复它并告知 debian-www，以便翻译者知道。更好的是，修复所有其他翻译中的链接，如果可能的话更新翻译检查头部。

文本与数据的分离

这些 foo.def 和 foo.data 文件是什么？

为了使翻译保持最新更容易，我们将某些页面的通用部分（数据）与文本部分（文本）分开。翻译者只需要复制和翻译其中的文本部分，通用部分将自动添加。

一个例子可能有助于理解这一点。生成 CD/vendors 中的供应商列表页面需要几个文件：

index.wml：
供应商页面顶部的文本在此文件中。 应将此文件的翻译副本放置在每个语言目录中。
vendors.CD.def：
这包含每个供应商条目所需的所有文本片段。翻译通过 <language>/po/vendors.xy.po 添加。
vendors.CD：
此文件包含独立于语言的实际供应商条目，因此翻译者不需要修改此文件。

当 cdvendors@debian.org 背后的人员添加新供应商时，他们将其添加到 debiancd.db，将其转换为 WML 格式作为 vendors.CD（使用 getvendors.pl）， 然后让 WML 和 makefile 发挥作用。所有翻译都使用现有的翻译文本但带有新的供应商数据重新构建。（免费的更新翻译！）

添加新页面

向 Debian 添加新页面相当容易。获得正确页眉和页脚的所有工作都是使用 WML 完成的。您需要做的就是在新文件的顶部包含如下行：

#use wml::debian::template title="页面标题"

后跟正文。除非页面使用为该部分专门创建的特殊模板（例如新闻或安全条目），否则所有页面都应使用 wml::debian::template 模板文件。

我们拥有的模板允许您定义某些变量，这些变量将影响创建的页面。这应该避免必须为每种情况创建不同的模板，并允许更容易实现改进。当前可用的变量及其用途是：

BARETITLE="true"
删除通常添加到所有 <title> 标签前面的"Debian --"部分。
NOHEADER="true"
从页面中删除初始标题。当然，可以在正文中包含自定义标题。
NOMIRRORS="true"
从页面中删除镜像下拉列表。通常不建议使用，除了少数几个页面。
NOHOMELINK="true"
删除返回到主 Debian 页面的链接，该链接通常添加到页面底部。
NOLANGUAGES="true"
删除指向其他语言版本的链接，这些链接通常添加到页面底部。
GEN_TIME="true"
将结果文件上的日期设置为生成文件的时间戳，而不是源文件的时间戳。
NOCOPYRIGHT="true"
删除页面底部的版权声明。

请注意，您可以使用任何字符串作为这些变量的值，true、yes、foo，都没关系。

此用法的一个例子是在有自己标题的页面中。ports/arm/index.wml 使用：

#use wml::debian::template title="ARM 移植" NOHEADER="yes"

如果您想要做某些使用现有模板无法完成的事情，首先考虑扩展其中一个。如果无法以向后兼容的方式扩展，请尝试使新模板成为现有模板的超集， 以便页面可以在下一次主要升级时转换到它（希望永远不超过每 6 个月一次）。

如果您正在创建由脚本生成或散文很少的页面，请考虑使用 <gettext> 标签来简化保持翻译最新的任务。

包含其他文件

如果您想将页面的某些部分分离到一个独立的文件中（然后由您的主文件包含），如果您的文件包含应该翻译的内容，请使用扩展名 .src， 因为这样您包含的文件会像任何普通的 .wml 文件一样被跟踪更改。如果您使用任何其他扩展名，如 .inc，翻译者将不会注意到您的更新， 不同的语言可能会提供不同的内容。

添加新目录

注意：不要创建名为 install 的目录。这会混淆 make，该目录中的页面将不会自动更新。

下面是向网站添加新目录的注释示例。

   mkdir foo
   git add foo
   cd foo
   cp ../intro/Makefile .
   git add Makefile

编辑父目录中的 Makefile，并将您刚创建的目录添加到 SUBS 变量中。这将在运行 make 时将目录添加到构建中。

最后，使用以下命令将刚才所做的所有更改提交到存储库

  git commit Makefile foo