1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
---
title: Chapter 4. Documentation Directory Structure
prev: books/fdp-primer/working-copy
next: books/fdp-primer/doc-build
description: Documentation Directory Structure explanation used in the FreeBSD Documentation Project
tags: ["directory structure", "organization"]
---
[[structure]]
= Documentation Directory 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::[]
Files and directories in the [.filename]#doc/# tree follow a structure meant to:
. Make it easy to automate converting the document to other formats.
. Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents.
. Make it easy to decide where in the tree new documentation should be placed.
In addition, the documentation tree must accommodate documents in many different languages.
It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences.
[[structure-top]]
== The Top Level, doc/
There are three sections under [.filename]#doc/#, documentation and website share the same structure.
[cols="20%,80%", frame="none", options="header"]
|===
| Directory
| Usage
|[.filename]#documentation#
|Contains all the articles and books in AsciiDoc format.
Contains subdirectories to further categorize the information by languages.
|[.filename]#shared#
|Contains files that are not specific to the various translations of the documentation.
Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information.
This directory is shared between `documentation` and the `website`.
|[.filename]#website#
|Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format.
Contains subdirectories to further categorize the information by languages.
|===
[[structure-locale]]
== The Directories
These directories contain the documentation and the website.
The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure].
[cols="20%,80%", frame="none", options="header"]
|===
| Directory
| Usage
|[.filename]#archetypes#
|Contain templates to create new articles, books and webpages.
For more information take a look link:https://gohugo.io/content-management/archetypes/[here].
|[.filename]#config#
|Contain the Hugo configuration files.
One main file and one file per language.
For more information take a look link:https://gohugo.io/getting-started/configuration/[here].
|[.filename]#content#
|Contain the books, articles and webpages.
One directory exists for each available translation of the documentation, for example `en` and `zh-tw`.
| [.filename]#data#
| Contain custom data for build the website in link:https://en.wikipedia.org/wiki/TOML[TOML] format.
This directory is used to store the events, news, press, etc.
For more information take a look link:https://gohugo.io/templates/data-templates/[here].
| [.filename]#static#
| Contain static assets.
Images, security advisories, the pgpkeys, etc.
For more information take a look link:https://gohugo.io/content-management/static-files/[here].
| [.filename]#themes#
| Contain the templates in the form of `.html` files that specify how the website looks.
For more information take a look link:https://gohugo.io/templates/[here].
| [.filename]#tools#
| Contain tools used to enhance the documentation build.
For example to generate the Table of Contents of the books, etc.
| [.filename]#beastie.png#
| This image doesn't need an introduction ;)
| [.filename]#LICENSE#
| License of the documentation, shared and website. BSD 2-Clause License.
| [.filename]#Makefile#
| The [.filename]#Makefile# defines the build process of the documentation and the website.
|===
[[structure-document]]
== Document-Specific Information
This section contains specific notes about particular documents managed by the FDP.
[[structure-document-books]]
== The Books: books/
The books are written in AsciiDoc.
The books are organized as an AsciiDoc `book`.
The books are divided into ``part``s, each of which contains several ``chapter``s.
``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on.
[[structure-document-books-physical]]
=== Physical Organization
There are a number of files and directories within the books directory, all with the same structure.
[[structure-document-books-physical-index]]
==== _index.adoc
The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section.
[[structure-document-books-physical-book]]
==== book.adoc
The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters.
This file is used to generate the PDF with `asciidoctor-pdf` and to generate the book in one `html` page.
[[structure-document-books-physical-part]]
==== part*.adoc
The [.filename]#part*.adoc# files stores a brief introduction of one part of the book.
[[structure-document-books-physical-toc]]
==== toc*.adoc
The [.filename]#toc*.adoc# files stores the Table of Contents, Table of Figures, Table of Examples, Table of Tables and different Table of Contents for each part.
All of these files are generated by the Python `tools`.
*Please don't edit them.*
[[structure-document-books-physical-chapters-order]]
==== chapters-order.adoc
The [.filename]#chapters-order.adoc# file stores the order of the book chapters.
[IMPORTANT]
====
Please be careful with this file.
It is used by the Python `tools` to generate the Table of Contents of the books.
In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team.
====
[[structure-document-handbook-physical-chapters]]
==== directory/_index.adoc
Each chapter in the Handbook is stored in a file called [.filename]#_index.adoc# in a separate directory from the other chapters.
For example, this is an example of the header of one chapter:
[.programlisting]
....
---
title: Chapter 8. Configuring the FreeBSD Kernel
part: Part II. Common Tasks
prev: books/handbook/multimedia
next: books/handbook/printing
---
[[kernelconfig]]
\= Configuring the FreeBSD Kernel <.>
...
....
<.> The character at the end of the line should not be used in a production document.
This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files.
When the HTML5 version of the Handbook is produced, this will yield [.filename]#kernelconfig/index.html#.
A brief look will show that there are many directories with individual [.filename]#_index.adoc# files, including [.filename]#basics/_index.adoc#, [.filename]#introduction/_index.adoc#, and [.filename]#printing/_index.xml#.
[IMPORTANT]
====
Do not name chapters or directories after their ordering within the Handbook.
This ordering can change as the content within the Handbook is reorganized.
Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy.
====
[[structure-document-articles]]
== The Articles: articles/
The articles are written in AsciiDoc.
The articles are organized as an AsciiDoc `article`.
The articles are divided into sections (`=`) and subsections (`==`, `===`) and so on.
[[structure-document-articles-physical]]
=== Physical Organization
There is one [.filename]#_index.adoc# file per article.
[[structure-document-articles-physical-index]]
==== _index.adoc
The [.filename]#_index.adoc# file contains all the AsciiDoc variables and the content.
For example, this is an example of one article, the structure is pretty similar to one book chapter:
[.programlisting]
....
---
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"]
---
\= Why you should use a BSD style license for your Open Source Project <1>
:doctype: article
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
'''
toc::[]
[[intro]]
\== Introduction <1>
....
<1> The character at the end of the line should not be used in a production document.
This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files.
|
