--- 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 ...
Capítulo 4. Estrutura de Diretórios da Documentação
Índice
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.
4.1. O Nível Superior, doc/
Existem dois tipos de diretório em doc/, documentation e website, ambos compartilham a mesma estrutura.
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 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 |
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ório | Uso |
---|---|
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 |
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 |
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.
Os livros são organizados como um livro
AsciiDoc. Os livros estão divididos em partes, cada uma das quais contém vários capítulos. Os capítulos são subdivididos em seções (=
) e subseções (==
, ===
) e assim por diante.
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 _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 _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, 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:
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: 6 de fevereiro de 2022 por Danilo G. Baio