获取 Gentoo！

GLEP 13: 为用户提供 Gentoo 手册

作者 Sven Vermeulen <swift@gentoo.org>
类型 标准跟踪
状态 垂死
版本 1
创建 2003-08-15
最后修改 2022-08-14
发布历史 2003-08-19, 2004-10-25
GLEP 源代码 glep-0013.rst

状态

手册不再使用 GuideXML，而是于 2014 年迁移到 wiki，Gentoo 文档项目不久后也停止使用。根据 Gentoo 委员会于 2022 年 8 月 14 日的决定，标记为垂死状态。

摘要

此 GLEP 提供了关于 Gentoo 文档演变的愿景，即一个类似手册的文档，为读者提供有关 Gentoo 发行版的各个方面的文档：安装、管理、应用程序使用、开发等。

动机

Gentoo 当前的安装指南 [1] 正在快速增长，不断扩展，包含了越来越多的功能，Gentoo 用户可以利用这些功能帮助他们追求完美的安装。这种增长是必要的，也是一件好事，但它使指南更难阅读或用作参考。

没有任何理由表明这种演变会停滞不前，相反：人们开始问为什么替代安装指南 [2] 没有合并到 Gentoo 安装指南中，或者为什么平台特定的安装指南不能合并，因为它们都使用相同的步骤（有一些差异）。我本人甚至希望将我们的 LVM 指南 [3] 合并到安装指南中，因为我相信许多用户会喜欢在他们的机器上使用 LVM，但目前他们没有这样做，因为他们不知道它有多么方便和容易 - 你们都知道这种感觉 :)

理由

为了解决上述问题，有两种想法

  • 将安装指南拆分为多个独立的指南。例如，我们可以将有关内核配置的信息移到内核指南中，创建一个分区指南，描述用户需要经历的 fdisk（以及可能的其他）步骤等。
  • 将所有信息合并到一个大型手册中。当然，这是一个从我们的 FreeBSD 朋友 [4] 那里借鉴的想法，他们已经拥有一个与他们的 BSD 发行版相关的广泛手册。

本 GLEP 描述的是第二个想法。

这个手册想法并没有减少安装说明，相反，它扩展了它们。但是，通过选择一个多页面的手册式文档，我们的用户会收到一个完全集成的文档，其中包含他们想要了解的关于 Gentoo 的所有内容。它还将使提供可打印的文档（PDF 或其他格式）变得更容易，而不会失去在线和 LiveCD 上获取安装文档的便利。

实施

为了实现这样的手册，Gentoo 文档项目 [5] 需要为其 GuideXML [6] 格式重写样式表。由于 GuideXML 本身没有问题，并且它在使用上非常灵活，因此建议坚持使用 GuideXML 是明确的。我们需要在 GuideXML 中添加一些额外的功能，而不会破坏当前的 GuideXML 实现。

最后一点很重要，因为实现这种手册式文档应该与我们当前文档的开发同步进行：开发 Gentoo 手册需要很长时间，我们不想强迫用户使用不可用的文档。

在改进 GuideXML 格式之后，需要解决的第一个问题是安装说明。它们应该与其他现有的指南合并，这些指南为用户提供了与安装相关的项目信息（例如替代安装指南、LVM 指南、平台特定安装指南等）。

其他需要实施的章节是

  • 关于 Gentoo 开发的章节，它涵盖了所有当前的开发特定指南，例如 Gentoo 开发者 HOWTO、Gentoo 策略、Ebuild HOWTO、Eclass HOWTO 等。Gentoo ebuild 维护者和其他许多 Gentoo 开发者已经多次要求这样做。
  • 一个专门用于系统管理的章节，例如邮件服务器管理、用户管理、打印管理等。我们已经有一些指南描述了这些项目的部分内容。
  • 一个专门用于 Gentoo 使用的章节，包括我们流行的桌面配置指南 [7] 和几个应用程序特定指南。

以下部分更详细地描述了这些步骤...

扩展 GuideXML

GuideXML 格式应该扩展以下项目

  • 关于信息划分的更多深度。
  • "包含" 外部源代码
  • 更轻松的文档内引用

我们当前的 GuideXML 格式为我们提供了以下关于信息划分的深度

<guide>
    <chapter>
        <section>

The<guide>标签当前是一个一次性标签：它定义了指南的开始，当然，指南以</guide>结束。The<chapter>标签将文档划分为单独的章节。但是，我们大多数文档的章节都很小，而普通书籍和文档的章节包含多个页面。The<section>标签进一步划分它所在的章节。

这意味着我们当前的安装指南的划分深度为 2：您可以定义一个章节，并在该章节中使用<section>进行细分。但是，这对类似手册的文档来说是不够的。为了改进 GuideXML，我们可以添加<subsection>以及，如果需要，<subsubsection>，基于 LaTeX 的划分。

另一个必要条件是能够包含外部文档。如果没有这种可能性，维护手册将至少说起来很麻烦。XSLT（用于处理 GuideXML 文件）可以轻松地提供这一点，因此没有必要专门包含此功能。

一个可能的标签是<include file="foobar.xml" />.

使用这种划分，我们可以将每个章节放在它自己的文档中，使维护变得容易得多。

最后实现的是文档内引用。目前，Gentoo 文档开发者必须猜测某个部分位于哪个章节，以及我们实际上讨论的是哪个部分#doc_chap4_sect3为我们提供了指向第 4 章第 3 部分的链接。对于小型文档来说，这是一个可行的实现，但对于手册来说是不可能的。

在划分标签中实现更类似 HTML 的引用将是更好的选择<chapter name="installation">, <section name="partitioning">等等，然后引用将是#installation和#partitioning分别。

安装说明

第一个真正的章节（在一些介绍之后）将是关于 Gentoo 安装的章节。然后，此章节可以包含有关替代安装说明、特定于体系结构的说明、分区方案、RAID 安装等的所有信息，而无需在整个手册中不断引用其他部分。

换句话说，一个想要在 SPARC 上使用 ATA RAID 安装 Gentoo Linux 的用户应该能够按照章节中的说明进行操作，无需在多个页面之间来回跳转。创建这样的章节并不容易，仅仅因为我们不想让用户从左到右来回跳转。

应该与当前指南的开发同步进行此章节的开发（这些指南仍然具有更高的优先级，因为只要手册中的章节没有完成并经过准确性审查，它们仍然是官方的安装说明）。

系统管理

此章节基于前面章节中描述的 Gentoo 的现有基本安装，包含了几个重要管理项目的章节。这是一个目前没有太多受影响指南的章节，但对于使 Gentoo 在服务器环境中正常工作（并得到记录）非常重要。

这些部分包含有关以下内容的信息，但并不限于

- Software Administration

- User Administration

- Mail Administration

- Print Services

- Network Administration

- Storage Management

- Security

- Clustering

Gentoo 开发

如前所述，此章节将包含帮助 Gentoo 开发所需的所有信息。它将涵盖所有现有的关于 Ebuild 和 Eclass 开发、阶段创建、Gentoo 策略等的指南。

用户应用程序

系统管理章节包含有关如何安装软件和服务（例如 XFree）的信息，而此章节将包含有关用户（而不是管理员）如何使用系统管理员安装的软件的信息。

Gentoo 目前有一些指南描述了此类用户应用程序 [8]，并且这些指南似乎是我们用户非常喜欢的，因此忽视它们无异于自杀 :)

由于这些文档的性质，用户应用程序章节将由独立的部分组成。

向后兼容性

通过只对 GuideXML 格式进行少量更改（实际上是扩展），可以（甚至建议）独立开发每个章节，并与涉及的指南同步进行开发。

通过在当前文档目录的子目录中开发手册（例如https://gentoolinux.cn/doc/en/handbook) 我们将维护现有的文档。当手册中的一章完成时，相关的文档可以在顶部包含一个大的注释，声明它们现在已被手册的这一章取代。

但是，请注意，本手册**不**并且**不会**涵盖 Gentoo 文档项目生成的所有文档。很可能有一些指南在本手册中没有明确的位置。与其强迫指南出现在某处，不如将指南保留为独立文档。

参考实现

这是 Gentoo 手册的可能路线图

- Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
(and leave the guide.xsl as it is now).

- Implement the Installation Instructions

- Develop a consistent layout, keeping the guides that are to be implemented
  in mind.

- Include all referenced guides. Do *not* extend it yet.

- Review the installation instructions and make them official

- Extend at will :)

- Implement the Gentoo Development Instructions

- Implement the User Application Instructions

- Implement the System Administration Instructions