Глава 4. Структура каталогов документации

Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.

Содержание

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

  1. Сделать удобным автоматическое преобразование документа в другие форматы.

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

  3. Сделать удобным выбор места в дереве для размещения новой документации.

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

4.1. Верхний уровень, doc/

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

КаталогИспользование

documentation

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

tools

Содержит набор инструментов для перевода документации и веб-сайта с использованием Weblate. Экземпляр Weblate доступен здесь.

shared

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

* website*

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

4.2. Каталоги

Эти каталоги содержат документацию и веб-сайт. Документация организована в подкаталоги ниже этого уровня, следуя структуре каталогов Hugo.

КаталогИспользование

* archetypes*

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

config

Содержат файлы конфигурации Hugo. Один основной файл и по одному файлу для каждого языка. Для получения дополнительной информации смотрите здесь.

content

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

data

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

static

Содержат статические ресурсы. Изображения, бюллетени безопасности, pgpkeys и т.д. Подробнее смотрите здесь.

* themes*

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

tools

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

beastie.png

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

LICENSE

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

Makefile

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

4.3. Информация, относящаяся к документу

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

4.4. Книги: books/

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

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

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

  • Уровень раздела AsciiDoc 0 (=) в начале главы книги будет <h1>

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

  • Уровень раздела AsciiDoc 2 (===) должен использоваться для первого логического подраздела и будет преобразован в <h3>

– и так далее. Ссылка: Заголовки и уровни разделов | Документация Asciidoctor.

4.4.1. Физическая организация

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

4.4.1.1. _index.adoc

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

4.4.1.2. book.adoc

Файл book.adoc определяет некоторые переменные AsciiDoc, которые влияют на преобразование исходного кода AsciiDoc в другие форматы, а также включает оглавление, список примеров, список рисунков, список таблиц, раздел с аннотацией и все главы. Этот файл используется для генерации PDF с помощью asciidoctor-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]]
= Настройка ядра FreeBSD
...

При создании HTML5-версии Handbook это приведёт к формированию файла 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: 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]]
== Введение

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

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

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

Начиная с FreeBSD 7.0, FreeBSD поддерживает три списка отношений наставник/подопечный — один для исходного кода, один для портов и один для документации. Эти файлы имеют формат «.dot» и предназначены для использования с популярным пакетом для построения графиков graphics/graphviz[], доступным как пакет или порт FreeBSD.

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

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

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

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

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

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

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

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

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

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

include-contrib-committers:     ~/doc/shared/contrib-committers.adoc
include-contrib-corealumni:     ~/doc/shared/contrib-corealumni.adoc
include-contrib-develalumni:    ~/doc/shared/contrib-develalumni.adoc
include-contrib-portmgralumni:  ~/doc/shared/contrib-portmgralumni.adoc
include-contrib-additional:     ~/doc/shared/contrib-additional.adoc
include-contrib-386bsd:         ~/doc/shared/contrib-386bsd.adoc

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

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

НазначениеЯкорь разделаФайл в ~/doc/shared/Спецификация порядка

Разработчики FreeBSD

include-contrib-committers

contrib-committers.adoc

упорядочено по алфавиту по фамилии

Бывшие члены основной команды

include-contrib-corealumni

contrib-corealumni.adoc

приблизительно в обратном хронологическом порядке

Бывшие члены команды разработчиков

include-contrib-develalumni

contrib-develalumni.adoc

приблизительно в обратном хронологическом порядке

Бывшие члены команды управления портами

include::contrib-portmgralumni

contrib-portmgralumni.adoc

приблизительно в обратном хронологическом порядке

Дополнительные участники проекта FreeBSD

include-contrib-additional

contrib-additional.adoc

упорядочено по алфавиту по имени

Участники, предоставившие патчи для 386BSD Patch Kit

include-contrib-386bsd

contrib-386bsd.adoc

упорядочено по алфавиту по имени

Участники проекта центрального сервера

Файл include не используется

contributors/_index.adoc

неупорядоченное

Прямое финансирование

Файл include не используется

contributors/_index.adoc

неупорядоченное

Участники, предоставившие оборудование

Файл include не используется

contributors/_index.adoc

неупорядоченное

Особые участники

Файл include не используется

contributors/_index.adoc

неупорядоченное

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

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

  1. Используйте файл ~/doc/shared/authors.adoc для поиска имени человека и ссылки на атрибут, например {foobsd}.

  2. Если они являются текущим членом одной или нескольких команд проекта FreeBSD в ~/doc/website/content/en/administration.adoc, удалите все упоминания их атрибута. Также выполните следующие правки:

    • ~/doc/shared/contrib-committers.adoc - Удалите ссылку на атрибут.

    • ~/doc/shared/contrib-corealumni.adoc - Если они являются действующим членом основной команды, создайте запись с указанием дат начала и окончания.

    • ~/doc/shared/contrib-develalumni.adoc - Добавьте ссылку на атрибут и даты активности в качестве коммиттера.

    • ~/doc/shared/contrib-portmgralumni.adoc - Добавьте ссылку на атрибут при необходимости.

    • ~/doc/shared/contrib-additional.adoc — Удалите запись.

    • ~/doc/shared/contrib-386bsd.adoc - Это исключительно исторический документ. Изменения не требуются.

  3. В файле ~/doc/shared/authors.adoc закомментируйте (используя одну обратную косую черту '\') адрес электронной почты, чтобы избежать создания ссылки "mailto:". См. пример для itojun ниже:

    [shared/authors.adoc]

[..]

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

[..]

  4. Поскольку участник скончался (что следует перепроверить), добавьте его в файл contrib-develinmemoriam.adoc "Памяти ушедших".

    Постарайтесь найти информацию, подкрепленную фактами, о его вкладе в FreeBSD за прошедшие годы и добавьте её к записи в файле. Для этого может потребоваться запрос в списках рассылки разработчиков, обращение к коллегам, связь с FreeBSD Foundation или поиск в журналах коммитов.

    Чтобы узнать дату их первого коммита, используйте:

    % cd ~/src
% git log --reverse --author=foobsd     # search for first commit of foobsd

    Это выведет их коммиты в обратном порядке. Дата первого коммита будет вверху.

    Убедитесь, что формат дат соответствует другим записям:

    (год начала предоставления права коммита - год окончания предоставления права коммита; RIP год ухода)

Например:

* Foo BSD (2007 - 2010; RIP 2016)

    Проверьте порядок записей в файле.

    НазначениеЯкорь разделаФайл в ~/doc/documentation/content/{язык}/articles/contributors/Спецификация порядка

    Команда разработчиков: Памяти ушедших

    contrib-develinmemoriam.adoc

    contrib-develinmemoriam.adoc

    приблизительно в обратном хронологическом порядке

    Смотрите файл "In Memoriam" для похожих записей.

  5. Наконец, если применимо, переместите запись участника с правами коммиттера из раздела «current» в раздел «alumni» соответствующего списка отношений наставник / подопечный с указанием соответствующей даты. Изменять отношения наставник / подопечный не требуется.

Изменено: 20 сентября 2025 г. by Vladlen Popolitov

Главная