第 4 章。文档目录结构

目录

doc/ 树中的文件和目录遵循一种结构，其目的是

  1. 简化文档转换为其他格式的自动化过程。

  2. 促进不同文档组织之间的统一性，以便更轻松地在不同文档之间切换工作。

  3. 简化确定新文档应放置在树中的哪个位置。

此外，文档树必须适应多种语言的文档。重要的是，文档树结构不应强制执行任何特定的默认值或文化偏好。

4.1. 顶层，doc/

doc/ 下有三个部分，文档和网站共享相同的结构。

目录用法

documentation

包含所有以 AsciiDoc 格式编写的文章和书籍。包含子目录以根据语言进一步对信息进行分类。

tools

包含一组工具，用于使用 Weblate 翻译文档和网站。Weblate 实例可以在 这里 找到。

shared

包含不特定于文档各种翻译的文件。包含子目录以根据语言进一步对信息进行分类，以及三个文件用于存储作者、版本和镜像信息。此目录在 documentation 和 website 之间共享。

website

包含 FreeBSD 网站 的 AsciiDoc 格式。包含子目录以根据语言进一步对信息进行分类。

4.2. 目录

这些目录包含文档和网站。文档在该级别以下的子目录中组织，遵循 Hugo 目录结构.

目录用法

archetypes

包含用于创建新文章、书籍和网页的模板。有关更多信息，请查看 这里.

config

包含 Hugo 配置文件。一个主文件和每个语言一个文件。有关更多信息，请查看 这里.

content

包含书籍、文章和网页。每个可用的文档翻译都存在一个目录，例如 en 和 zh-tw。

data

包含用于构建网站的自定义数据，以 TOML 格式。此目录用于存储事件、新闻、新闻稿等。有关更多信息，请查看 这里.

static

包含静态资产。图像、安全公告、pgp 密钥等。有关更多信息，请查看 这里.

themes

包含以 .html 文件形式的模板，这些文件指定网站的外观。有关更多信息，请查看 这里.

tools

包含用于增强文档构建的工具。例如，用于生成书籍的目录等。

beastie.png

这张图片不需要介绍 ;)

LICENSE

文档、共享和网站的许可证。BSD 2 条款许可证。

Makefile

Makefile 定义了文档和网站的构建过程。

4.3. 文档特定信息

本节包含有关 FDP 管理的特定文档的特定说明。

4.4. 书籍：books/

书籍是用 AsciiDoc 编写的。

对于每本 FreeBSD 书籍，AsciiDoc 文档类型（又名文档类型）为 book。书籍有 part，每个 part 包含几个 chapter。

当文档转换为 HTML 5 时（使用内置的 html5 后端）

  • book 的 chapter 开头处的 AsciiDoc 节点级别 0 (=) 将为 <h1>

  • AsciiDoc 节点级别 1 (==) 必须用于章节的第一个逻辑部分，并将为 <h2>

  • AsciiDoc 节点级别 2 (===) 必须用于第一个逻辑子部分，并将为 <h3>

– 依此类推。参考：节标题和级别 | Asciidoctor 文档.

4.4.1. 物理组织

书籍目录中包含许多文件和目录，它们都具有相同的结构。

4.4.1.1. _index.adoc

_index.adoc 文件定义了一些 AsciiDoc 变量，这些变量会影响 AsciiDoc 源代码转换为其他格式的方式，并列出目录、示例表、图表表、表格表和摘要部分。

4.4.1.2. book.adoc

book.adoc 文件定义了一些 AsciiDoc 变量，这些变量会影响 AsciiDoc 源代码转换为其他格式的方式，并列出目录、示例表、图表表、表格表、摘要部分和所有章节。此文件用于使用 asciidoctor-pdf 生成 PDF，并在一个 html 页面中生成书籍。

4.4.1.3. part*.adoc

part*.adoc 文件存储书籍某一部分的简要介绍。

4.4.1.4. directory/_index.adoc

手册中的每一章都存储在一个名为 **_index.adoc** 的文件中，该文件位于与其他章节不同的单独目录中。

例如，这是一个章节标题的示例

---
title: Chapter 8. Configuring the FreeBSD Kernel
part: Part II. Common Tasks
prev: books/handbook/multimedia
next: books/handbook/printing
---

[[kernelconfig]]
= Configuring the FreeBSD Kernel
...

当生成手册的 HTML5 版本时，这将产生 **kernelconfig/index.html**。

简单看一下就会发现，有许多目录包含单独的 **_index.adoc** 文件，包括 **basics/_index.adoc**、**introduction/_index.adoc** 和 **printing/_index.adoc**。

不要根据章节在手册中的顺序来命名章节或目录。这种顺序可能会随着手册内容的重新组织而改变。重新组织应该可以在不重命名文件的情况下进行，除非整个章节在层次结构中被提升或降级。

4.5. 文章：articles/

文章是用 AsciiDoc 编写的。

文章被组织成 AsciiDoc 的 article。文章被分为节 (=) 和子节 (==, ===) 等等。

4.5.1. 物理组织

每篇文章有一个 **_index.adoc** 文件。

4.5.1.1. _index.adoc

**_index.adoc** 文件包含所有 AsciiDoc 变量和内容。

例如，这是一个文章的示例，其结构与一个书章非常类似

---
title: Why you should use a BSD style license for your Open Source Project
authors:
  - author: Bruce Montague
    email: [email protected]
trademarks: ["freebsd", "intel", "general"]
---

= Why you should use a BSD style license for your Open Source Project
:doctype: article
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:

'''

toc::[]

[[intro]]
== Introduction

上次修改时间：2024 年 3 月 9 日，作者：Danilo G. Baio

首页