Path: blob/main/documentation/content/pt-br/books/fdp-primer/structure/_index.adoc
18098 views
---
description: 'Explicação da Estrutura de Diretórios usada no Projeto de Documentação do 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: 'Capítulo 4. Estrutura de Diretórios da Documentação'
weight: 5
---
[[structure]]
= Estrutura de Diretórios da Documentação
: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::[]
Arquivos e diretórios no repositório *doc/* seguem uma estrutura destinada a:
. Facilitar a conversão do documento para outros formatos.
. Promover a consistência entre as diferentes organizações de documentação, e assim facilitar a alternância entre diferentes documentos.
. Facilitar a decisão de onde a nova documentação deve ser colocada.
Além disso, o repositório de documentação deve acomodar documentos em vários idiomas e codificações diferentes. É importante que a estrutura do repositório de documentação não imponha quaisquer padrões particulares ou preferências culturais.
[[structure-top]]
== O Nível Superior, doc/
Existem dois tipos de diretório em *doc/*, documentation e website, ambos compartilham a mesma estrutura.
[cols="20%,80%", frame="none", options="header"]
|===
| Diretório
| Uso
| *documentation*
| Contém todos os artigos e livros em formato AsciiDoc.
Contém subdiretórios para categorizar ainda mais as informações por idiomas.
| *tools*
| Contém um conjunto de ferramentas usadas para traduzir a documentação e o site usando link:https://weblate.org/en/[Weblate].
A instância do Weblate pode ser acessada link:https://translate-dev.freebsd.org[aqui].
| *shared*
| Contém arquivos que não são específicos para as várias traduções da documentação.
Contém subdiretórios para categorizar ainda mais as informações por idiomas e três arquivos para armazenar as informações dos autores, lançamentos e espelhos.
Este diretório é compartilhado entre `documentation` e o `website`.
| *website*
| Contém o link:https://www.FreeBSD.org[site do FreeBSD] no formato AsciiDoc
Contém subdiretórios para categorizar ainda mais as informações por idiomas.
|===
[[structure-locale]]
== Os Diretórios
Esses diretórios contêm a documentação e o website. A documentação está organizada em subdiretórios abaixo deste nível, seguindo o link:https://gohugo.io/getting-started/directory-structure/[estrutura de diretórios Hugo].
[cols="20%,80%", frame="none", options="header"]
|===
| Diretório
| Uso
| *archetypes*
| Contém templates para criar novos artigos, livros e páginas web.
Para mais informações, veja link:https://gohugo.io/content-management/archetypes/[aqui].
| *config*
| Contém os arquivos de configuração do Hugo.
Um arquivo principal e um arquivo por idioma.
Para mais informações, veja link:https://gohugo.io/getting-started/configuration[aqui].
| *content*
| Contém os livros, artigos e páginas web.
Existe um diretório para cada tradução disponível da documentação, por exemplo `en` e `zh-tw`.
| *data*
| Contem dados personalizados para compilar o site no formato link:https://en.wikipedia.org/wiki/TOML[TOML].
Este diretório é usado para armazenar os eventos, notícias, imprensa, etc.
Para mais informações, veja link:https://gohugo.io/templates/data-templates/[aqui].
| *static*
| Contem ativos estáticos.
Imagens, avisos de segurança, pgpkeys, etc.
Para mais informações, veja link:https://gohugo.io/content-management/static-files/[aqui].
| *themes*
| Contém os modelos na forma de arquivos `.html` que especificam a aparência do site.
Para mais informações, veja link:https://gohugo.io/templates/[aqui].
| *tools*
| Contém ferramentas usadas para aprimorar a construção da documentação.
Por exemplo, para gerar o índice dos livros, etc.
| *beastie.png*
| Esta imagem não precisa de introdução ;)
| *LICENSE*
| Licença da documentação e site. Licença BSD de 2 cláusulas.
| *Makefile*
| O *Makefile* que executa o processo de compilação da documentação e do website.
|===
[[structure-document]]
== Informação Específica de Documentação
Esta seção contém informações específicas sobre documentos gerenciados pelo FDP.
[[structure-document-books]]
== Os Livros: books/
Os livros são escritos em AsciiDoc.
Para cada livro do FreeBSD, o tipo de documento AsciiDoc (também conhecido como doctype) é `book`. Os livros possuem ``part``es, cada uma contendo vários ``capítulos`` (chapter).
Quando o documento é convertido para HTML 5 (usando o backend `html5` embutido):
* A seção AsciiDoc nível 0 (`=`) no início de um ``capítulo `` de um `livro` será `<h1>`
* A seção AsciiDoc nível 1 (`==`) deve ser usada para a primeira seção lógica de um capítulo e será `<h2>`
* A seção AsciiDoc nível 2 (`===`) deve ser usada para a primeira subseção lógica e será `<h3>`
– e assim por diante. Referência: link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/[Títulos e Níveis de Seção | Asciidoctor Docs].
[[structure-document-books-physical]]
=== Organização Física
Existem vários arquivos e diretórios no diretório books, todos com a mesma estrutura.
[[structure-document-books-physical-index]]
==== _index.adoc
O arquivo *_index.adoc* define algumas variáveis AsciiDoc que afetam como o código AsciiDoc é convertido para outros formatos e lista o Índice, a Tabela de Exemplos, a Tabela de Figuras, a Tabela de Tabelas e a seção de resumo.
[[structure-document-books-physical-book]]
==== book.adoc
O arquivo *book.adoc* define algumas variáveis AsciiDoc que afetam como o código AsciiDoc é convertido para outros formatos e lista o Índice, a Tabela de Exemplos, a Tabela de Figuras, a Tabela de Tabelas, a seção de resumo e todos os capítulos. Este arquivo é usado para gerar o PDF com `asciidoctor-pdf` e para gerar o livro em uma página `html`.
[[structure-document-books-physical-part]]
==== part*.adoc
Os arquivos **part*.adoc** armazenam uma breve introdução de uma parte do livro.
[[structure-document-handbook-physical-chapters]]
==== directory/_index.adoc
Cada capítulo do Handbook é armazenado em um arquivo chamado *_index.adoc* em um diretório separado dos outros capítulos.
Por exemplo, este é um exemplo do cabeçalho de um capítulo:
[source.programlisting, asciidoc]
....
---
title: Chapter 8. Configuring the FreeBSD Kernel
part: Part II. Common Tasks
prev: books/handbook/multimedia
next: books/handbook/printing
---
[[kernelconfig]]
= Configurando o kernel do FreeBSD
...
....
Quando a versão HTML5 do Handbook é produzida, será gerado o *kernelconfig/index.html*.
Uma breve olhada mostrará que existem muitos diretórios com arquivos *_index.adoc* individuais, incluindo *basics/_index.adoc*, *introduction/_index.adoc*, e *printing/_index.xml*.
[IMPORTANT]
====
Não nomeie capítulos ou diretórios com a ordenação do Handbook. Essa ordenação pode mudar conforme o conteúdo do Handbook é reorganizado. A reorganização deve ser realizada sem renomear arquivos, a menos que capítulos inteiros sejam promovidos ou rebaixados dentro da hierarquia.
====
[[structure-document-articles]]
== Os Artigos: articles/
Os artigos são escritos em AsciiDoc.
Os artigos são organizados como um `artigo` do AsciiDoc. Os artigos são divididos em seções (`=`) e subseções (`==`, `===`) e assim por diante.
[[structure-document-articles-physical]]
=== Organização Física
Existe um arquivo *_index.adoc* por artigo.
[[structure-document-articles-physical-index]]
==== _index.adoc
O arquivo *_index.adoc* contém todas as variáveis AsciiDoc e o conteúdo.
Por exemplo, este é um exemplo de um artigo, a estrutura é muito semelhante a um capítulo de livro:
[source.programlisting, 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"]
---
= Por que você deve usar uma licença de estilo BSD em seu Projeto Open Source
:doctype: article
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
'''
toc::[]
[[intro]]
== Introdução
....