diff options
Diffstat (limited to 'documentation/content/ru/books/fdp-primer/structure/_index.adoc')
| -rw-r--r-- | documentation/content/ru/books/fdp-primer/structure/_index.adoc | 386 |
1 files changed, 386 insertions, 0 deletions
diff --git a/documentation/content/ru/books/fdp-primer/structure/_index.adoc b/documentation/content/ru/books/fdp-primer/structure/_index.adoc new file mode 100644 index 0000000000..a89d627650 --- /dev/null +++ b/documentation/content/ru/books/fdp-primer/structure/_index.adoc @@ -0,0 +1,386 @@ +--- +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[списка отношений наставник / подопечный] с указанием соответствующей даты. Изменять отношения наставник / подопечный не требуется. |