---
description: 'Структура каталогов документации, используемая в проекте документации FreeBSD'
next: books/fdp-primer/doc-build
params:
  path: /books/fdp-primer/structure/
prev: books/fdp-primer/working-copy
showBookMenu: true
tags: ["directory structure", "organization"]
title: 'Глава 4. Структура каталогов документации'
weight: 5
---

[[structure]]
= Структура каталогов документации
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 4
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

Файлы и каталоги в дереве *doc/* следуют структуре, преследующей цели:

. Сделать удобным автоматическое преобразование документа в другие форматы.
. Способствовать согласованности между различными организациями, занимающимися документацией, чтобы упростить переход между работой над разными документами.
. Сделать удобным выбор места в дереве для размещения новой документации.

В дополнение, дерево документации должно поддерживать документы на многих разных языках. Важно, чтобы структура дерева документации не навязывала каких-либо конкретных настроек по умолчанию или культурных предпочтений.

[[structure-top]]
== Верхний уровень, doc/

В разделе *doc/* есть три подраздела, документация и веб-сайт имеют одинаковую структуру.

[cols="20%,80%", frame="none", options="header"]
|===
| Каталог
| Использование

| *documentation*
| Содержит все статьи и книги в формате AsciiDoc.
Содержит подкаталоги для дальнейшей категоризации информации по языкам.

| *tools*
| Содержит набор инструментов для перевода документации и веб-сайта с использованием link:https://weblate.org/en/[Weblate].
Экземпляр Weblate доступен link:https://translate-dev.freebsd.org[здесь].

| *shared*
| Содержит файлы, не относящиеся к различным переводам документации.
Включает подкаталоги для дальнейшей категоризации информации по языкам, а также три файла для хранения данных об авторах, выпусках и зеркалах.
Этот каталог является общим для `documentation` и `website`.

| * website*
| Содержит ссылку link:https://www.FreeBSD.org[FreeBSD website] в формате AsciiDoc.
Содержит подкаталоги для дальнейшей категоризации информации по языкам.
|===

[[structure-locale]]
== Каталоги

Эти каталоги содержат документацию и веб-сайт. Документация организована в подкаталоги ниже этого уровня, следуя структуре каталогов link:https://gohugo.io/getting-started/directory-structure/[Hugo].

[cols="20%,80%", frame="none", options="header"]
|===
| Каталог
| Использование


| * archetypes*
| Содержит шаблоны для создания новых статей, книг и веб-страниц.
Дополнительную информацию смотрите link:https://gohugo.io/content-management/archetypes/[здесь].

| *config*
| Содержат файлы конфигурации Hugo.
Один основной файл и по одному файлу для каждого языка.
Для получения дополнительной информации смотрите link:https://gohugo.io/getting-started/configuration/[здесь].

| *content*
| Содержат книги, статьи и веб-страницы.
Для каждого доступного перевода документации существует отдельный каталог, например `en` и `zh-tw`.

| *data*
| Содержит пользовательские данные для сборки веб-сайта в формате link:https://en.wikipedia.org/wiki/TOML[TOML].
Этот каталог используется для хранения событий, новостей, пресс-релизов и т.д.
Для получения дополнительной информации ознакомьтесь link:https://gohugo.io/templates/data-templates/[здесь].

| *static*
| Содержат статические ресурсы.
Изображения, бюллетени безопасности, pgpkeys и т.д.
Подробнее смотрите link:https://gohugo.io/content-management/static-files/[здесь].

| * themes*
| Содержите шаблоны в виде файлов `.html`, которые определяют внешний вид веб-сайта.
Для получения дополнительной информации посмотрите link:https://gohugo.io/templates/[здесь].

| *tools*
| Содержит инструменты, используемые для улучшения сборки документации.
Например, для генерации оглавления книг и т.д.

| *beastie.png*
| Это изображение не нуждается в представлении ;)

| *LICENSE*
| Лицензия документации, общих материалов и веб-сайта. Лицензия BSD с 2 пунктами.

| *Makefile*
| Файл *Makefile* определяет процесс сборки документации и веб-сайта.
|===

[[structure-document]]
== Информация, относящаяся к документу

Этот раздел содержит особые примечания о конкретных документах, которыми управляет FDP.

[[structure-document-books]]
== Книги: books/

Книги написаны в AsciiDoc.

Для каждой книги FreeBSD тип документа AsciiDoc (также известный как doctype) — это `book` (книга). Книги содержат ``part`` (части), каждая из которых включает несколько ``chapter`` (глав).

Когда документ преобразуется в HTML 5 (с использованием встроенного бэкенда `html5`):

* Уровень раздела AsciiDoc 0 (`=`) в начале `главы` `книги` будет `<h1>`
* Уровень секции AsciiDoc 1 (`==`) должен использоваться для первого логического раздела главы и будет преобразован в `<h2>`
* Уровень раздела AsciiDoc 2 (`===`) должен использоваться для первого логического подраздела и будет преобразован в `<h3>`

– и так далее. Ссылка: link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/[Заголовки и уровни разделов | Документация Asciidoctor].

[[structure-document-books-physical]]
=== Физическая организация

В каталоге books находится множество файлов и директорий, все с одинаковой структурой.

[[structure-document-books-physical-index]]
==== _index.adoc

Файл *_index.adoc* определяет некоторые переменные AsciiDoc, которые влияют на преобразование исходного кода AsciiDoc в другие форматы, а также содержит оглавление, список примеров, список рисунков, список таблиц и раздел с аннотацией.

[[structure-document-books-physical-book]]
==== book.adoc

Файл *book.adoc* определяет некоторые переменные AsciiDoc, которые влияют на преобразование исходного кода AsciiDoc в другие форматы, а также включает оглавление, список примеров, список рисунков, список таблиц, раздел с аннотацией и все главы. Этот файл используется для генерации PDF с помощью `asciidoctor-pdf` и для создания книги в виде одной страницы `html`.

[[structure-document-books-physical-part]]
==== part*.adoc
Файлы **part*.adoc** содержат краткое введение к одной части книги.

[[structure-document-handbook-physical-chapters]]
==== directory/_index.adoc

Каждая глава Руководства хранится в файле с именем *_index.adoc* в отдельном каталоге от других глав.

Например, вот пример заголовка одной главы:

[source.programlisting, asciidoc]
....
---
title: Chapter 8. Configuring the FreeBSD Kernel
part: Part II. Common Tasks
prev: books/handbook/multimedia
next: books/handbook/printing
---

[[kernelconfig]]
= Настройка ядра FreeBSD
...
....

При создании HTML5-версии Handbook это приведёт к формированию файла *kernelconfig/index.html*.

Быстрый взгляд покажет, что существует множество каталогов с отдельными файлами *_index.adoc*, включая *basics/_index.adoc*, *introduction/_index.adoc* и *printing/_index.adoc*.

[IMPORTANT]
====
Не называйте главы или каталоги в соответствии с их порядком в Руководстве. Этот порядок может измениться при реорганизации содержания Руководства. Реорганизация должна быть возможной без переименования файлов, за исключением случаев, когда целые главы перемещаются вверх или вниз по иерархии.
====

[[structure-document-articles]]
== Статьи: articles/

Статьи написаны в AsciiDoc.

Статьи организованы как документ AsciiDoc `article`. Статьи разделены на разделы (`=`), подразделы (`==`, `===`) и так далее.

[[structure-document-articles-physical]]
=== Физическая организация

На каждый статью приходится один файл *_index.adoc*.

[[structure-document-articles-physical-index]]
==== _index.adoc

Файл *_index.adoc* содержит все переменные AsciiDoc и контент.

Например, это образец одной статьи, структура довольно похожа на главу книги:

[source.programlisting, asciidoc]
....
---
title: Why you should use a BSD style license for your Open Source Project
authors:
  - author: Bruce Montague
    email: brucem@alumni.cse.ucsc.edu
trademarks: ["freebsd", "intel", "general"]
---

= Почему вы должны использовать лицензию в стиле BSD для вашего Open Source проекта
:doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental:

'''

toc::[]

[[intro]]
== Введение
....

== Управление списками участников

Проект FreeBSD отмечает вклад участников в нескольких различных списках в документации и печатных материалах. В этом разделе описано, как команда документации управляет изменениями в этих списках.

=== Списки отношений наставника и нового коммиттера

Начиная с FreeBSD 7.0, FreeBSD поддерживает link:https://cgit.freebsd.org/src/tree/share/misc[три списка отношений наставник/подопечный] — один для исходного кода, один для портов и один для документации. Эти файлы имеют формат *«.dot»* и предназначены для использования с популярным пакетом для построения графиков graphics/graphviz[], доступным как пакет или порт FreeBSD.

[NOTE]
====
man:dot[1] устанавливается как часть пакета или порта: graphics/graphviz[]. Программа [.filename]#dot# читает файлы в формате *".dot"* и создает графическое изображение направленного графа.
====

Три файла часто служат учебным опытом для новых коммиттеров всех трёх команд, которым поручается добавить себя и своего наставника в соответствующий файл в качестве их первого коммита. Каждый файл содержит раздел «current» для новых коммиттеров, раздел «alumni» для случаев возврата прав на коммит и раздел «mentor / mentee», отображающий взаимоотношения. Формат каждой записи поясняется в начале файла.

=== Общий список участников

extref:{contributors}[Участники] проекта FreeBSD поддерживаются в формате статьи. Исходный файл для управления статьёй *Участники* находится по адресу:

[subs=+quotes]
----
doc
 /documentation
   /content
     /{language}
       /articles
         /contributors
           [.filename]#_index.adoc# – Contains a list of include files that apply to each section.
           [.filename]#_index.po# – Translation page
           [.filename]#contrib-develinmemoriam.adoc# - content of “In Memoriam” section
           [.filename]#contrib-develinmemoriam.po# – Translation page
----

Копии этого каталога contributors могут существовать в других каталогах с контентом на различных языках.

Обратите внимание, что файл [.filename]#contrib-develinmemoriam.adoc# также находится в этом каталоге. Дополнительную информацию смотрите ниже.

Файл [.filename]#contributors/_index.adoc# представляет собой набор включаемых файлов. Включаемые файлы перечислены в разделе, специфичном для Hugo, в исходном файле. Раздел разделён на несколько частей с помощью операторов "ifdef::". Существует подраздел для вывода на веб-сайт и подраздел для вывода вне веб-сайта (включая PDF).

Текст каждого раздела страницы *Участники* содержит оператор "include::". Например, запись для "Экс-участники менеджера портов" выглядит как `include::{include-contrib-portmgralumni}[]`. Это подключает текст об экс-участниках менеджера портов в итоговый вывод.

Чтобы внести изменения, отредактируйте соответствующий include-файл:

[subs=+quotes]
----
include-contrib-committers:     [.filename]#~/doc/shared/contrib-committers.adoc#
include-contrib-corealumni:     [.filename]#~/doc/shared/contrib-corealumni.adoc#
include-contrib-develalumni:    [.filename]#~/doc/shared/contrib-develalumni.adoc#
include-contrib-portmgralumni:  [.filename]#~/doc/shared/contrib-portmgralumni.adoc#
include-contrib-additional:     [.filename]#~/doc/shared/contrib-additional.adoc#
include-contrib-386bsd:         [.filename]#~/doc/shared/contrib-386bsd.adoc#

Также отредактируйте файл [.filename]#authors.adoc#:  [.filename]#~/doc/shared/authors.adoc#
и все связанные с ним переводы.

----

В общем случае, если добавляется новый человек, требуется лишь одно изменение — его можно добавить в соответствующий включаемый файл. Если человек переводится из статуса «текущий» в «бывший», необходимо два изменения: одно для удаления и одно для добавления в соответствующие файлы. Порядок записей для всех файлов указан в таблице ниже.

[cols="25%,25%,25%,25%", frame="none", options="header"]
|===
| Назначение | Якорь раздела | Файл в ~/doc/shared/ | Спецификация порядка
| *Разработчики FreeBSD* | include-contrib-committers | [.filename]#contrib-committers.adoc# | упорядочено по алфавиту по фамилии
| *Бывшие члены основной команды* | include-contrib-corealumni | [.filename]#contrib-corealumni.adoc# | приблизительно в обратном хронологическом порядке
| *Бывшие члены команды разработчиков* | include-contrib-develalumni | [.filename]#contrib-develalumni.adoc# | приблизительно в обратном хронологическом порядке
| *Бывшие члены команды управления портами* | include::contrib-portmgralumni | [.filename]#contrib-portmgralumni.adoc# | приблизительно в обратном хронологическом порядке
| *Дополнительные участники проекта FreeBSD* | include-contrib-additional | [.filename]#contrib-additional.adoc# | упорядочено по алфавиту по имени
| *Участники, предоставившие патчи для 386BSD Patch Kit* | include-contrib-386bsd | [.filename]#contrib-386bsd.adoc# | упорядочено по алфавиту по имени
| *Участники проекта центрального сервера* | Файл include не используется | [.filename]#contributors/_index.adoc# | неупорядоченное
| *Прямое финансирование* | Файл include не используется | [.filename]#contributors/_index.adoc# | неупорядоченное
| *Участники, предоставившие оборудование* | Файл include не используется | [.filename]#contributors/_index.adoc# | неупорядоченное
| *Особые участники* | Файл include не используется | [.filename]#contributors/_index.adoc# | неупорядоченное
|===

=== Раздел "Памяти"

Когда уведомляют сообщество BSD о смерти члена сообщества, следует использовать следующую процедуру:

. Используйте файл [.filename]#~/doc/shared/authors.adoc# для поиска имени человека и ссылки на атрибут, например `{foobsd}`.
. Если они являются текущим членом одной или нескольких команд проекта FreeBSD в [.filename]#~/doc/website/content/en/administration.adoc#, удалите все упоминания их атрибута. Также выполните следующие правки:
+
* [.filename]#~/doc/shared/contrib-committers.adoc# - Удалите ссылку на атрибут.
* [.filename]#~/doc/shared/contrib-corealumni.adoc# - Если они являются _действующим_ членом основной команды, создайте запись с указанием дат начала и окончания.
* [.filename]#~/doc/shared/contrib-develalumni.adoc# - Добавьте ссылку на атрибут и даты активности в качестве коммиттера.
* [.filename]#~/doc/shared/contrib-portmgralumni.adoc# - Добавьте ссылку на атрибут при необходимости.
* [.filename]#~/doc/shared/contrib-additional.adoc# — Удалите запись.
* [.filename]#~/doc/shared/contrib-386bsd.adoc# - Это исключительно исторический документ. Изменения не требуются.
+
. В файле [.filename]#~/doc/shared/authors.adoc# закомментируйте (используя одну обратную косую черту '\') адрес электронной почты, чтобы избежать создания ссылки "mailto:". См. пример для `itojun` ниже:
+
[source.programlisting, asciidoc]
....
[shared/authors.adoc]

[..]

:itojun-name: Jun-ichiro Itoh
:itojun-email: \itojun@FreeBSD.org
:itojun: {itojun-name} <{itojun-email}>

[..]
....
+
. Поскольку участник скончался (что следует перепроверить), добавьте его в файл [.filename]#contrib-develinmemoriam.adoc# "Памяти ушедших".
+
Постарайтесь найти информацию, подкрепленную фактами, о его вкладе в FreeBSD за прошедшие годы и добавьте её к записи в файле. Для этого может потребоваться запрос в списках рассылки разработчиков, обращение к коллегам, связь с FreeBSD Foundation или поиск в журналах коммитов.
+
Чтобы узнать дату их первого коммита, используйте:
+
[source.programlisting, asciidoc]
....
% cd ~/src
% git log --reverse --author=foobsd     # search for first commit of foobsd
....
+
Это выведет их коммиты в обратном порядке. Дата первого коммита будет вверху.
+
Убедитесь, что формат дат соответствует другим записям:
+
[source.programlisting, asciidoc]
....
(год начала предоставления права коммита - год окончания предоставления права коммита; RIP год ухода)

Например:

* Foo BSD (2007 - 2010; RIP 2016)
....
+
Проверьте порядок записей в файле.
+
[cols="25%,25%,25%,25%", frame="none", options="header"]
|===
| Назначение | Якорь раздела | Файл в ~/doc/documentation/content/{язык}/articles/contributors/ | Спецификация порядка
| *Команда разработчиков: Памяти ушедших* | [.filename]#contrib-develinmemoriam.adoc# | [.filename]#contrib-develinmemoriam.adoc# | приблизительно в обратном хронологическом порядке
|===
+
Смотрите файл "In Memoriam" для похожих записей.
+
. Наконец, если применимо, переместите запись участника с правами коммиттера из раздела «current» в раздел «alumni» соответствующего link:https://cgit.freebsd.org/src/tree/share/misc[списка отношений наставник / подопечный] с указанием соответствующей даты. Изменять отношения наставник / подопечный не требуется.