git: e8b7b860df - main - Upgrade FDP to reflect changes introduced with the new documentation
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sun, 19 Dec 2021 10:45:42 UTC
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=e8b7b860df7a2620c105e54fc05c02e54f08022c
commit e8b7b860df7a2620c105e54fc05c02e54f08022c
Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2021-12-19 10:44:30 +0000
Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2021-12-19 10:44:30 +0000
Upgrade FDP to reflect changes introduced with the new documentation
---
.../fdp-primer/asciidoctor-primer/_index.adoc | 30 +-
.../en/books/fdp-primer/doc-build/_index.adoc | 363 ++++++++++++++++++---
.../en/books/fdp-primer/examples/_index.adoc | 19 +-
.../en/books/fdp-primer/overview/_index.adoc | 2 +-
.../books/fdp-primer/po-translations/_index.adoc | 2 +-
.../en/books/fdp-primer/see-also/_index.adoc | 8 +
.../en/books/fdp-primer/structure/_index.adoc | 93 +++---
7 files changed, 389 insertions(+), 128 deletions(-)
diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
index cbe13cba6e..3ad0e15b60 100644
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -86,7 +86,7 @@ For this we need markup.
The previous example is actually represented in this document like this:
....
-To remove [.filename]#/tmp/foo#, use man:rm[1].
+To remove */tmp/foo*, use man:rm[1].
[source,shell]
----
@@ -104,19 +104,19 @@ If the document type is `book` then there can be multiple level 0 (`=`) headings
This is an example of headings in an `article`.
....
- = Document Title (Level 0)
+= Document Title (Level 0)
- == Level 1 Section Title
+== Level 1 Section Title
- === Level 2 Section Title
+=== Level 2 Section Title
- ==== Level 3 Section Title
+==== Level 3 Section Title
- ===== Level 4 Section Title
+===== Level 4 Section Title
- ====== Level 5 Section Title
+====== Level 5 Section Title
- == Another Level 1 Section Title
+== Another Level 1 Section Title
....
[WARNING]
@@ -126,11 +126,11 @@ Section levels cannot be skipped when nesting sections.
The following syntax is not correct.
....
- = Document Title
+= Document Title
- == Level 2
+== Level 2
- ==== Level 4
+==== Level 4
....
====
@@ -144,12 +144,12 @@ To create a new paragraph leave one blank line.
For example, this is a heading with two paragraphs.
....
- = This is the heading
+= This is the heading
- This is the first paragraph.
- This is also the first paragraph.
+This is the first paragraph.
+This is also the first paragraph.
- And this is the second paragraph.
+And this is the second paragraph.
....
[[asciidoctor-lists]]
diff --git a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
index 4b06ab4f8b..19c2b20063 100644
--- a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
@@ -185,7 +185,6 @@ In order to export the document correctly all the extensions should be passed us
These are the tools used to build and install the FDP documentation.
* The primary build tool is man:make[1], specifically Berkeley Make.
-* Python is used to generate the Table of Contents and other related Tables.
* Hugo
* AsciiDoctor
* Git
@@ -217,7 +216,15 @@ This [.filename]#Makefile# takes the following form:
# Targets intended for use on the command line
#
# all (default) - generate the books TOC and compile all the documentation
-# run - serves the built documentation site for local browsing
+# clean - removes generated files
+# run - serves the built documentation site for local browsing
+# pdf - build PDF versions of the articles and books.
+# html - build HTML versions of the articles and books for
+# offline use.
+# If variable DOC_HTML_ARCHIVE is set, all documents will be
+# archived/compressed, and only these files will be kept in the public
+# directory.
+# epub - build EPUB versions of the articles and books (Experimental).
#
# The run target uses hugo's built-in webserver to make the documentation site
# available for local browsing. The documentation should have been built prior
@@ -226,55 +233,263 @@ This [.filename]#Makefile# takes the following form:
MAINTAINER=carlavilla@FreeBSD.org <.>
-PYTHON_CMD = /usr/local/bin/python3 <.>
-HUGO_CMD = /usr/local/bin/hugo <.>
-LANGUAGES = en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr <.>
+# List of languages without book translations
+ARTICLEONLY_LANGS= bn-bd da ko tr
+# List of languages without article translations
+BOOKONLY_LANGS= mn
+
+# List of all languages we have content for
+ALL_LANGUAGES= bn-bd da de el en es fr hu it ja ko mn nl pl pt-br ru tr zh-cn zh-tw <.>
+
+LOCALBASE?= /usr/local
+
+RUBY_CMD = ${LOCALBASE}/bin/ruby <.>
+HUGO_CMD = ${LOCALBASE}/bin/hugo <.>
+HUGO_ARGS?= --verbose --minify
+HUGO_OFFLINE_ARGS?= --environment offline --verbose --minify
+ASCIIDOCTOR_CMD= ${LOCALBASE}/bin/asciidoctor
+ASCIIDOCTORPDF_CMD= ${LOCALBASE}/bin/asciidoctor-pdf
+
+.if defined(DOC_LANG) && !empty(DOC_LANG)
+LANGUAGES= ${DOC_LANG:S/,/ /g}
+.if ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == "" && ${.TARGETS:Mhtml*} == ""
+.warning "Warning: cannot skip 'en'; adding it back"
+LANGUAGES+= en
+.endif
+.else
+LANGUAGES= ${ALL_LANGUAGES}
+.endif
+
RUBYLIB = ../shared/lib
.export RUBYLIB
+RUN_DEPENDS= ${HUGO_CMD} \
+ ${LOCALBASE}/bin/asciidoctor \
+ ${LOCALBASE}/bin/rougify
+
.ifndef HOSTNAME
-.HOST+=localhost
+. ifdef BIND
+.HOST=$(BIND)
+. else
+.HOST=localhost
+. endif
.else
-.HOST+=$(HOSTNAME)
+.HOST=$(HOSTNAME)
+.endif
+
+# Strip the languages with only articles from the list of languages we
+# will use to build books.
+BOOK_LANGS= ${LANGUAGES}
+.for a in ${ARTICLEONLY_LANGS}
+BOOK_LANGS:= ${BOOK_LANGS:N${a}}
+.endfor
+
+# Strip the languages with only books from the list of languages we
+# will use to build articles.
+ARTICLE_LANGS= ${LANGUAGES}
+.for a in ${BOOKONLY_LANGS}
+ARTICLE_LANGS:= ${ARTICLE_LANGS:N${a}}
+.endfor
+
+# Take the list of all languages, and take out the ones we have been
+# asked for. We'll feed this to hugo.
+SKIP_LANGS=
+.for a in ${ALL_LANGUAGES}
+.if ${LANGUAGES:M${a}} == ""
+SKIP_LANGS+= ${a}
.endif
+.endfor
-.ORDER: all run<.>
+.ORDER: all run <.>
-.ORDER: starting-message generate-books-toc
+.ORDER: requirements <.>
+.ORDER: starting-message
.ORDER: starting-message build
-.ORDER: generate-books-toc build
+.ORDER: build
+
+all: requirements starting-message generate-pgpkeys-txt build
+run: requirements starting-message generate-pgpkeys-txt run-local
+
+# clean does not call pdf-clean as that is a subset of hugo-clean
+clean: hugo-clean pgp-clean
+
+requirements:
+.for dep in ${RUN_DEPENDS}
+.if !exists(${dep})
+ @(echo ${dep} not found, please run 'pkg install docproj'; exit 1)
+.endif
+.endfor
-all: starting-message generate-books-toc build <.>
+requirements-pdf:
+.if !exists(${LOCALBASE}/bin/asciidoctor-pdf)
+ @(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1)
+.endif
+
+requirements-epub:
+.if !exists(${LOCALBASE}/bin/asciidoctor-epub3)
+ @(echo ${LOCALBASE}/bin/asciidoctor-epub3 not found, please run 'pkg install rubygem-asciidoctor-epub3'; exit 1)
+.endif
starting-message: .PHONY <.>
@echo ---------------------------------------------------------------
@echo Building the documentation
+ @echo included languages: ${LANGUAGES}
+ @echo excluded languages: ${SKIP_LANGS}
@echo ---------------------------------------------------------------
-generate-books-toc: .PHONY <.>
- ${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${LANGUAGES}
- ${PYTHON_CMD} ./tools/books-toc-creator.py -l ${LANGUAGES}
- ${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${LANGUAGES}
- ${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${LANGUAGES}
- ${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${LANGUAGES}
+generate-pgpkeys-txt: static/pgpkeys/pgpkeys.txt
+
+static/pgpkeys/pgpkeys.txt: static/pgpkeys/*key
+ ${RUBY_CMD} ./tools/global-pgpkeys-creator.rb
-run: .PHONY <.>
- ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"
+run-local: .PHONY <.>
+ HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
+ ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
- ${HUGO_CMD} --minify
+ HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS}
+
+build-offline: .PHONY
+ HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_OFFLINE_ARGS}
+
+pgp-clean: .PHONY
+ rm -f static/pgpkeys/pgpkeys.txt
+
+hugo-clean: .PHONY
+ rm -rf resources public
+
+#
+# PDF targets
+# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" pdf-books
+#
+pdf: pdf-articles pdf-books
+
+pdf-books: requirements-pdf
+.for _lang in ${BOOK_LANGS}
+ ./tools/asciidoctor.sh books ${_lang} pdf
+.endfor
+
+pdf-articles: requirements-pdf
+.for _lang in ${ARTICLE_LANGS}
+ ./tools/asciidoctor.sh articles ${_lang} pdf
+.endfor
+
+pdf-clean: pdf-articles-clean pdf-books-clean
+
+pdf-books-clean:
+.for _lang in ${BOOK_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/books
+ -rmdir ${.CURDIR}/public/${_lang}
+.endfor
+ -rmdir ${.CURDIR}/public/
+
+pdf-articles-clean:
+.for _lang in ${ARTICLE_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/articles
+.if !exists(${.CURDIR}/public/${_lang}/books)
+ rm -fr ${.CURDIR}/public/${_lang}
+.endif
+.endfor
+ -rmdir ${.CURDIR}/public
+
+#
+# HTML targets
+#
+html: build-offline html-clean-global html-clean-articles html-clean-books html-archive html-archive-clean-files
+
+html-clean: hugo-clean
+
+html-clean-global:
+ rm -fr ${.CURDIR}/public/index.html
+ rm -rf pgpkeys js
+
+html-clean-articles:
+.for _lang in ${ARTICLE_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/index.html
+ rm -fr ${.CURDIR}/public/${_lang}/articles/index.html
+.endfor
+
+html-clean-books:
+.for _lang in ${BOOK_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/books/index.html
+.endfor
+
+html-archive:
+.if defined(DOC_HTML_ARCHIVE)
+.for _lang in ${ARTICLE_LANGS}
+ ./tools/asciidoctor.sh articles ${_lang} archive
+.endfor
+.for _lang in ${BOOK_LANGS}
+ ./tools/asciidoctor.sh books ${_lang} archive
+.endfor
+.endif
+
+html-archive-clean-files:
+.if defined(DOC_HTML_ARCHIVE)
+ find ${.CURDIR}/public/ ! -name '*.pdf' ! -name '*.tar.gz' -type f -delete
+ find ${.CURDIR}/public/ -type d -empty -delete
+.endif
+
+#
+# EPUB targets
+# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" epub-books
+#
+epub: epub-articles epub-books
+
+epub-books: requirements-epub
+ @echo ---------------------------------------------------------------
+ @echo !!! EPUB output is experimental !!!
+ @echo
+ @echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the
+ @echo bulk of AsciiDoc content is converted, there’s still work needed to fill in
+ @echo gaps where conversion is incomplete or unstyled.
+ @echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status
+ @echo ---------------------------------------------------------------
+.for _lang in ${BOOK_LANGS}
+ ./tools/asciidoctor.sh books ${_lang} epub
+.endfor
+
+epub-articles: requirements-epub
+ @echo ---------------------------------------------------------------
+ @echo !!! EPUB output is experimental !!!
+ @echo
+ @echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the
+ @echo bulk of AsciiDoc content is converted, there’s still work needed to fill in
+ @echo gaps where conversion is incomplete or unstyled.
+ @echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status
+ @echo ---------------------------------------------------------------
+.for _lang in ${ARTICLE_LANGS}
+ ./tools/asciidoctor.sh articles ${_lang} epub
+.endfor
+
+epub-clean: epub-articles-clean epub-books-clean
+
+epub-books-clean:
+.for _lang in ${BOOK_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/books
+ -rmdir ${.CURDIR}/public/${_lang}
+.endfor
+ -rmdir ${.CURDIR}/public/
+
+epub-articles-clean:
+.for _lang in ${ARTICLE_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/articles
+.if !exists(${.CURDIR}/public/${_lang}/books)
+ rm -fr ${.CURDIR}/public/${_lang}
+.endif
+.endfor
+ -rmdir ${.CURDIR}/public
....
<.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile.
-<.> `PYTHON_CMD` flag specifies the location of the Python binary.
+<.> `ALL_LANGUAGES` flag specifies in which languages the table of contents has to be generated.
+<.> `RUBY_CMD` flag specifies the location of the Python binary.
<.> `HUGO_CMD` flag specifies the location of the Hugo binary.
-<.> `LANGUAGES` flag specifies in which languages the table of contents has to be generated.
<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
-<.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.
+<.> `all` target builds the documentation and puts the result in *~/doc/documentation/public*.
<.> `starting-message` shows a message in the CLI to show the user that the process is running.
-<.> `generate-books-toc` calls the scripts to generate the books TOCs.
-<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
-<.> `build` builds the documentation and puts the result in the [.filename]#~/doc/documentation/public#.
+<.> `run-local` runs hugo webserver on port 1313, or a random free port if that is already in use.
+<.> `build` builds the documentation and puts the result in the *~/doc/documentation/public*.
[[website-makefile]]
=== Website Makefile
@@ -291,56 +506,110 @@ This [.filename]#Makefile# takes the form of:
# Targets intended for use on the command line
#
# all (default) - generate the releases.toml and compile all the website
-# run - serves the built documentation site for local browsing
+# run - serves the built website for local browsing
#
-# The run target uses hugo's built-in webserver to make the documentation site
-# available for local browsing. The documentation should have been built prior
+# The run target uses hugo's built-in webserver to make the built website
+# available for local browsing. The website should have been built prior
# to attempting to use the `run` target. By default, hugo will start its
# webserver on port 1313.
MAINTAINER=carlavilla@FreeBSD.org <.>
-PYTHON_CMD = /usr/local/bin/python3 <.>
-HUGO_CMD = /usr/local/bin/hugo <.>
+# List of all languages we have content for
+ALL_LANGUAGES= de el en es fr hu it ja nl ru tr zh-cn zh-tw
+
+LOCALBASE?= /usr/local
+
+RUBY_CMD = ${LOCALBASE}/bin/ruby <.>
+HUGO_CMD = ${LOCALBASE}/bin/hugo <.>
+HUGO_ARGS?= --verbose
RUBYLIB = ../shared/lib
.export RUBYLIB
.ifndef HOSTNAME
-.HOST+=localhost
+. ifdef BIND
+.HOST=$(BIND)
+. else
+.HOST=localhost
+. endif
+.else
+.HOST=$(HOSTNAME)
+.endif
+
+.if defined(DOC_LANG) && !empty(DOC_LANG)
+LANGUAGES= ${DOC_LANG:S/,/ /g}
+.if ${LANGUAGES:Men} == ""
+.warning "Warning: cannot skip 'en'; adding it back"
+LANGUAGES+= en
+.endif
.else
-.HOST+=$(HOSTNAME)
+LANGUAGES= ${ALL_LANGUAGES}
+.endif
+
+# Take the list of all languages, and take out the ones we have been
+# asked for via DOC_LANG. We'll feed this to hugo.
+SKIP_LANGS=
+.for a in ${ALL_LANGUAGES}
+.if ${LANGUAGES:M${a}} == ""
+SKIP_LANGS+= ${a}
.endif
+.endfor
-.ORDER: all run<.>
+.ORDER: all run <.>
.ORDER: starting-message generate-releases
.ORDER: starting-message build
.ORDER: generate-releases build
+.ORDER: build post-build
+.ORDER: post-build end-message
-all: starting-message generate-releases run <.>
+all: starting-message generate-releases build post-build end-message <.>
+run: starting-message generate-releases run-local
+clean: hugo-clean releases-clean
starting-message: .PHONY <.>
- @echo ---------------------------------------------------------------
- @echo Building the website
- @echo ---------------------------------------------------------------
+ @echo "---------------------------------------------------------------"
+ @echo "Building the website started on $$(date)"
+ @echo " included languages: ${LANGUAGES}"
+ @echo " excluded languages: ${SKIP_LANGS}"
+ @echo "---------------------------------------------------------------"
+
+end-message: .PHONY
+ @echo "---------------------------------------------------------------"
+ @echo "Building the website completed on $$(date)"
+ @echo "---------------------------------------------------------------"
-generate-releases: .PHONY <.>
- ${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc
+generate-releases: data/releases.toml <.>
-run: .PHONY <.>
- ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"
+data/releases.toml:
+ ${RUBY_CMD} ./tools/releases-toml.rb
+
+run-local: .PHONY <.>
+ HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
+ ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
- ${HUGO_CMD}
+ HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS}
+
+post-build: cgi-permissions
+
+cgi-permissions:
+ @chmod 555 ./public/cgi/*.cgi
+
+hugo-clean:
+ rm -fr public resources
+
+releases-clean:
+ rm -f data/releases.toml
....
<.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile.
-<.> `PYTHON_CMD` flag specifies the location of the Python binary.
+<.> `RUBY_CMD` flag specifies the location of the Ruby binary.
<.> `HUGO_CMD` flag specifies the location of the Hugo binary.
<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
-<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#.
+<.> `all` target builds the website and puts the result in *~/doc/website/public*.
<.> `starting-message` shows a message in the CLI to show the user that the process is running.
<.> `generate-releases` calls the script used to convert from AsciiDoc variables to TOML variables.
With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates.
-<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
-<.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#.
+<.> `run-local` runs hugo webserver on port 1313, or a random free port if that is already in use.
+<.> `build` builds the website and puts the result in the *~/doc/website/public*.
diff --git a/documentation/content/en/books/fdp-primer/examples/_index.adoc b/documentation/content/en/books/fdp-primer/examples/_index.adoc
index d1e1acb004..55322389cf 100644
--- a/documentation/content/en/books/fdp-primer/examples/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/examples/_index.adoc
@@ -3,6 +3,9 @@ title: Appendix A. Examples
prev: books/fdp-primer/see-also/
description: Example of an article and a book used in the FreeBSD Documentation Project
tags: ["examples", "tutorial", "AsciiDoctor", "Book", "Article"]
+showBookMenu: true
+weight: 15
+path: "/books/fdp-primer/"
---
[appendix]
@@ -45,12 +48,12 @@ include::../../../../../shared/asciidoctor.adoc[]
endif::[]
These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter.
-For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
+For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git *doc* repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
[[examples-asciidoctor-book]]
-== AsciiDoctor `book`
+== AsciiDoctor *book*
-.AsciiDoctor `book`
+.AsciiDoctor *book*
[example]
====
[.programlisting]
@@ -118,9 +121,9 @@ toc::[]
====
[[examples-asciidoctor-article]]
-== AsciiDoctor `article`
+== AsciiDoctor *article*
-.AsciiDoctor `article`
+.AsciiDoctor *article*
[example]
====
[.programlisting]
@@ -133,7 +136,7 @@ authors:
trademarks: ["general"]
---
-\= An Example Article
+= An Example Article
:doctype: article
:toc: macro
:toclevels: 1
@@ -147,11 +150,11 @@ trademarks: ["general"]
toc::[]
-\== My First Section
+== My First Section
This is the first section in my article.
-\== My First Sub-Section
+== My First Sub-Section
This is the first sub-section in my article.
diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc
index e14f0f5453..1daec39462 100644
--- a/documentation/content/en/books/fdp-primer/overview/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc
@@ -76,7 +76,7 @@ These people can help with questions or problems involving the documentation.
+
[source,shell]
....
-# pkg install docproj python3
+# pkg install docproj
....
+
. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc
index 8a9cceed89..5c688ab1c2 100644
--- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc
@@ -259,7 +259,7 @@ _lang_ is a two-character lowercase code.
|===
The translations are in subdirectories of the main documentation directory,
-here assumed to be [.filename]#~/doc/documentation/# as shown in <<overview-quick-start>>.
+here assumed to be [.filename]#~/doc/documentation/# as shown in crossref:overview[overview-quick-start, Quick Start].
For example, German translations are located in [.filename]#~/doc/documentation/content/de/#,
and French translations are in [.filename]#~/doc/documentation/content/fr/#.
diff --git a/documentation/content/en/books/fdp-primer/see-also/_index.adoc b/documentation/content/en/books/fdp-primer/see-also/_index.adoc
index 84dc15aa28..f41b9b6270 100644
--- a/documentation/content/en/books/fdp-primer/see-also/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/see-also/_index.adoc
@@ -56,10 +56,17 @@ For more information about these, you are encouraged to see the following web si
* link:https://www.FreeBSD.org/docproj/[The FreeBSD Documentation Project web pages]
* extref:{handbook}[The FreeBSD Handbook]
+[[see-also-hugo]]
+== Hugo
+
+* link:https://gohugo.io/[Hugo]
+* link:https://gohugo.io/documentation/[Hugo documentation]
+
[[see-also-asciidoc]]
== AsciiDoctor
* link:https://asciidoctor.org/[AsciiDoctor]
+* link:https://docs.asciidoctor.org/[AsciiDoctor Documentation Portal]
[[see-also-html]]
== HTML
@@ -67,3 +74,4 @@ For more information about these, you are encouraged to see the following web si
* link:http://www.w3.org/[The World Wide Web Consortium]
* link:https://dev.w3.org/html5/spec-LC/[The HTML 5 specification]
* link:https://www.w3.org/Style/CSS/specs.en.html[CSS specification]
+* link:https://sass-lang.com/[Sass]
diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc
index b825e1cd28..8daaeda713 100644
--- a/documentation/content/en/books/fdp-primer/structure/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc
@@ -47,7 +47,7 @@ toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
-Files and directories in the [.filename]#doc/# tree follow a structure meant to:
+Files and directories in the *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.
@@ -59,24 +59,28 @@ It is important that the documentation tree structure does not enforce any parti
[[structure-top]]
== The Top Level, doc/
-There are three sections under [.filename]#doc/#, documentation and website share the same structure.
+There are three sections under *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.
+| *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.
+| *tools*
+| Contains a set of tools used to translate the documentation and the website using link:https://weblate.org/en/[weblate].
+The weblate instance can be found link:https://translate-dev.freebsd.org[here]
+
+| *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.
+| *website*
+| Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format.
Contains subdirectories to further categorize the information by languages.
|===
@@ -92,45 +96,45 @@ The documentation is organized into subdirectories below this level, following t
| Usage
-|[.filename]#archetypes#
-|Contain templates to create new articles, books and webpages.
+| *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.
+| *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.
+| *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#
+| *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#
+| *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#
+| *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#
+| *tools*
| Contain tools used to enhance the documentation build.
For example to generate the Table of Contents of the books, etc.
-| [.filename]#beastie.png#
+| *beastie.png*
| This image doesn't need an introduction ;)
-| [.filename]#LICENSE#
+| *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.
+| *Makefile*
+| The *Makefile* defines the build process of the documentation and the website.
|===
[[structure-document]]
@@ -155,39 +159,22 @@ There are a number of files and directories within the books directory, all with
[[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.
+The *_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.
+The *_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.
-====
+The *part*.adoc* files stores a brief introduction of one part of the book.
[[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.
+Each chapter in the Handbook is stored in a file called *_index.adoc* in a separate directory from the other chapters.
For example, this is an example of the header of one chapter:
@@ -201,16 +188,13 @@ next: books/handbook/printing
---
[[kernelconfig]]
-\= Configuring the FreeBSD Kernel <.>
+= 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 *kernelconfig/index.html*.
-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#.
+A brief look will show that there are many directories with individual *_index.adoc* files, including *basics/_index.adoc*, *introduction/_index.adoc*, and *printing/_index.adoc*.
[IMPORTANT]
====
@@ -230,12 +214,12 @@ The articles are divided into sections (`=`) and subsections (`==`, `===`) and s
[[structure-document-articles-physical]]
=== Physical Organization
-There is one [.filename]#_index.adoc# file per article.
+There is one *_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.
+The *_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:
@@ -249,7 +233,7 @@ authors:
trademarks: ["freebsd", "intel", "general"]
---
-\= Why you should use a BSD style license for your Open Source Project <1>
+= Why you should use a BSD style license for your Open Source Project
:doctype: article
:toc: macro
:toclevels: 1
@@ -264,8 +248,5 @@ trademarks: ["freebsd", "intel", "general"]
toc::[]
[[intro]]
-\== Introduction <1>
+== Introduction
....
-
-<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.