Capítulo 4. Estrutura de Diretórios da Documentação

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Arquivos e diretórios no repositório doc/ seguem uma estrutura destinada a:

  1. Facilitar a conversão do documento para outros formatos.

  2. Promover a consistência entre as diferentes organizações de documentação, e assim facilitar a alternância entre diferentes documentos.

  3. 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.

4.1. O Nível Superior, doc/

Existem dois tipos de diretório em doc/, documentation e website, ambos compartilham a mesma estrutura.

DiretórioUso

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 Weblate. A instância do Weblate pode ser acessada 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 site do FreeBSD no formato AsciiDoc Contém subdiretórios para categorizar ainda mais as informações por idiomas.

4.2. 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 estrutura de diretórios Hugo.

DiretórioUso

archetypes

Contém templates para criar novos artigos, livros e páginas web. Para mais informações, veja aqui.

config

Contém os arquivos de configuração do Hugo. Um arquivo principal e um arquivo por idioma. Para mais informações, veja 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 TOML. Este diretório é usado para armazenar os eventos, notícias, imprensa, etc. Para mais informações, veja aqui.

static

Contem ativos estáticos. Imagens, avisos de segurança, pgpkeys, etc. Para mais informações, veja aqui.

themes

Contém os modelos na forma de arquivos .html que especificam a aparência do site. Para mais informações, veja 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.

4.3. Informação Específica de Documentação

Esta seção contém informações específicas sobre documentos gerenciados pelo FDP.

4.4. 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 partes, 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: Títulos e Níveis de Seção | Asciidoctor Docs.

4.4.1. Organização Física

Existem vários arquivos e diretórios no diretório books, todos com a mesma estrutura.

4.4.1.1. _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.

4.4.1.2. 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.

4.4.1.3. part*.adoc

Os arquivos part*.adoc armazenam uma breve introdução de uma parte do livro.

4.4.1.4. 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:

---
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.

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.

4.5. 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.

4.5.1. Organização Física

Existe um arquivo _index.adoc por artigo.

4.5.1.1. _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:

---
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"]
---

= 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

Última alteração em: 9 de março de 2024 por Danilo G. Baio