第1章 概述

安装这些软件包。docproj 元端口安装执行 FreeBSD 文档相关工作所需的所有应用程序。

# pkg install docproj

从 FreeBSD 存储库中在 ~/doc 中安装文档的本地工作副本（请参阅 工作副本）。

% git clone https://git.FreeBSD.org/doc.git ~/doc

编辑需要更改的文档文件。如果文件需要进行重大更改，请咨询邮件列表以获取输入。

始终在提交更改之前构建和审查更改。在 documentation 或 website 子目录中运行 make 将生成 HTML 格式的文档。

% make

% make DOC_LANG=en

查看构建输出并确保编辑内容没有错别字、布局问题或错误。如果在构建过程中发现任何错误，请编辑有问题的文件以修复显示的任何问题，然后再次运行构建命令，直到所有错误都得到解决。

使用 git add . 添加所有文件，然后使用 git diff 查看差异。例如

% git add .
% git diff --staged

% git commit
% git format-patch origin/main

使用基于 Web 的 问题报告 系统提交补丁或差异文件。如果使用 Web 表单，请输入 [补丁] 问题的简短描述 的摘要。选择组件 Documentation。在“描述”字段中，输入更改的简短描述以及有关它们的任何重要详细信息。使用 添加附件 按钮附加补丁或差异文件。最后，使用 提交 Bug 按钮将您的差异提交到问题报告系统。

在基于 apt 的系统（如 Debian 或 Ubuntu）中安装这些软件包。在其他 GNU/Linux 发行版中，软件包名称可能会更改。如有疑问，请咨询您发行版的软件包管理器。

# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake

从 FreeBSD 存储库中在 ~/doc 中安装文档的本地工作副本（请参阅 工作副本）。

% git clone https://git.FreeBSD.org/doc.git ~/doc

编辑需要更改的文档文件。如果文件需要进行重大更改，请咨询邮件列表以获取输入。

始终在提交更改之前构建和测试更改。在 documentation 或 website 子目录中运行 bmake 将生成 HTML 格式的文档。

% bmake run LOCALBASE=/usr

使用 git add . 添加所有文件，然后使用 git diff 查看差异。例如

% git add .
% git diff --staged

% git commit
% git format-patch origin/main

使用基于 Web 的 问题报告 系统提交补丁或差异文件。如果使用 Web 表单，请输入 问题的简短描述 的摘要。选择组件 Documentation。在“描述”字段中，输入“摘要”字段中问题的简短描述，并在“关键字”字段中添加 patch。使用 添加附件 按钮附加补丁或差异文件。最后，使用 提交 Bug 按钮将您的差异提交到问题报告系统。

使用 Homebrew 和 RubyGem 安装这些软件包。

$ brew install hugo ruby git bmake

将 Ruby 添加到路径中。

$ echo 'export GEM_PATH="$(gem environment gemdir)"' >> ~/.zshrc
$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

将 git 别名添加到 Homebrew git，因为 Apple 提供的 git 中的 git format-patch 无法与 Phabricator 一起使用。

$ echo 'alias git=/usr/local/bin/git' >> ~/.zshrc
$ source ~/.zshrc

使用 RubyGem 安装 rouge 软件包。

$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3

从 FreeBSD 存储库中在 ~/doc 中安装文档的本地工作副本（请参阅 工作副本）。

$ git clone https://git.FreeBSD.org/doc.git ~/doc

编辑需要更改的文档文件。如果文件需要进行重大更改，请咨询邮件列表以获取输入。

始终在提交更改之前构建和测试更改。在 documentation 或 website 子目录中运行 bmake 将生成 HTML 格式的文档。

$ bmake run USE_RUBYGEMS=YES RUBY_CMD=$(brew --prefix ruby)/bin/ruby

使用 git add . 添加所有文件，然后使用 git diff 查看差异。例如

% git add .
% git diff --staged

% git commit
% git format-patch origin/main

使用基于 Web 的 问题报告 系统提交补丁或差异文件。如果使用 Web 表单，请输入 问题的简短描述 的摘要。选择组件 Documentation。在“描述”字段中，输入“摘要”字段中问题的简短描述，并在“关键字”字段中添加 patch。使用 添加附件 按钮附加补丁或差异文件。最后，使用 提交 Bug 按钮将您的差异提交到问题报告系统。