diff --git a/documentation/Makefile b/documentation/Makefile
index 457f6add0b..410ff444df 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -1,272 +1,282 @@
 # Generate the FreeBSD documentation
 #
 # Copyright (c) 2020-2022, The FreeBSD Documentation Project
 # Copyright (c) 2020-2022, Sergio Carlavilla <carlavilla@FreeBSD.org>
 #
 # Targets intended for use on the command line
 #
 # all (default)	-	generate the books TOC and compile all the documentation
 # 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
 # to attempting to use the `run` target.  By default, hugo will start its
 # webserver on port 1313.
 
 MAINTAINER=carlavilla@FreeBSD.org
 
 # List of languages without book translations
 ARTICLEONLY_LANGS=	bn-bd da id 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 id it ja ko mn nl pl pt-br ru tr zh-cn zh-tw
 
 LOCALBASE?=	/usr/local
+USE_RUBYGEMS?=	NO
+GEM_PATH?=
 
-RUBY_CMD =	${LOCALBASE}/bin/ruby
+.if ${USE_RUBYGEMS} == "YES"
+GEMBASE?= 	${GEM_PATH}
+.else
+GEMBASE?= 	${LOCALBASE}
+.endif
+
+RUBY_CMD =	${GEMBASE}/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
+ROUGIFY_CMD=	${GEMBASE}/bin/rougify
+ASCIIDOCTOR_CMD=	${GEMBASE}/bin/asciidoctor
+ASCIIDOCTORPDF_CMD=	${GEMBASE}/bin/asciidoctor-pdf
+ASCIIDOCTOREPUB3_CMD= ${GEMBASE}/bin/asciidoctor-epub3
 
 .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
+				${ASCIIDOCTOR_CMD} \
+				${ROUGIFY_CMD}
 
 .ifndef HOSTNAME
 .  ifdef BIND
 .HOST=$(BIND)
 .  else
 .HOST=localhost
 .  endif
 .else
 .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: requirements
 .ORDER: starting-message
 .ORDER: starting-message 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
 
 requirements-pdf:
-.if !exists(${LOCALBASE}/bin/asciidoctor-pdf)
-	@(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1)
+.if !exists(${ASCIIDOCTORPDF_CMD})
+	@(echo ${ASCIIDOCTOR_CMD} not found, please 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)
+.if !exists(${ASCIIDOCTOREPUB3_CMD})
+	@(echo ${ASCIIDOCTOREPUB3_CMD} not found, please 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-pgpkeys-txt: static/pgpkeys/pgpkeys.txt
 
 static/pgpkeys/pgpkeys.txt: static/pgpkeys/*key
 	${RUBY_CMD} ./tools/global-pgpkeys-creator.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_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
 
diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc
index 157e6ea499..b728d23a9c 100644
--- a/documentation/content/en/books/fdp-primer/overview/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc
@@ -1,347 +1,349 @@
 ---
 title: Chapter 1. Overview
 prev: books/fdp-primer/preface
 next: books/fdp-primer/tools
 description: Overview about the FreeBSD Documentation Process
 tags: ["overview", "FreeBSD Documentation Project", "quick start"]
 showBookMenu: true
 weight: 2
 path: "/books/fdp-primer/"
 ---
 
 [[overview]]
 = Overview
 :doctype: book
 :toc: macro
 :toclevels: 1
 :icons: font
 :sectnums:
 :sectnumlevels: 6
 :sectnumoffset: 1
 :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::[]
 
 Welcome to the FreeBSD Documentation Project (FDP).
 Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly.
 
 This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools.
 
 Everyone is welcome to contribute to the FDP.
 Willingness to contribute is the only membership requirement.
 
 This primer shows how to:
 
 * Understand the role of documentation and its place in the ecosystem.
 * Identify which parts of FreeBSD are maintained by the FDP.
 * Install the required documentation tools and files.
 * Make changes to the documentation.
 * Submit changes back for review and inclusion in the FreeBSD documentation.
 
 [[overview-documentation-ecosystem]]
 == Documentation in the FreeBSD Ecosystem
 
 All documents are for the benefit of their readers, not their writers or caretakers.
 They should adapt to the reader and not expect the reader to adapt to them.
 
 Never blame the reader for:
 
 * being unable to make use of a document easily or at all
 * finding a document confusing
 * not understanding a document or how to apply it
 * not finding an explicit answer or successfully bridging gaps (or connecting dots) to reason their way to one
 
 Instead, acknowledge that the document is:
 
 * inaccessible
 * confusing
 * hard to understand or apply
 * incomplete
 
 Then, make the document:
 
 * more accessible
 * less confusing
 * clearer
 * more complete
 
 Use the following methods:
 
 * apply link:https://webaim.org/intro/#principles[accessibility best practices] to correct the problem reported and any similar ones you find
 * rework or clarify the confusing structure or language
 * add relevant examples to the part that is hard to understand or apply
 * fill in the gaps or add the missing stepping stones
 
 [[overview-quick-start]]
 == Quick Start
 
 Some preparatory steps must be taken before editing the FreeBSD documentation.
 First, subscribe to the {freebsd-doc}.
 Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet].
 These people can help with questions or problems involving the documentation.
 
 [[freebsd-installation-process]]
 === FreeBSD installation process
 
 [.procedure]
 ====
 . Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation.
 +
 [source,shell]
 ....
 # 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]).
 +
 [source,shell]
 ....
 % git clone https://git.FreeBSD.org/doc.git ~/doc
 ....
 +
 . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
 +
 Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems.
 Repeat until all of the errors are resolved.
 +
 . *_Always_* build and test the changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format.
 +
 [source,shell]
 ....
 % make
 ....
 +
 . Add all the files with `git add .`, then review the diff with `git diff`. For example:
 +
 [source,shell]
 ....
 % git add .
 % git diff --staged
 ....
 +
 Make sure that all required files are included, then commit the change to your local branch and generate a patch with `git format-patch`
 +
 [source,shell]
 ....
 % git commit
 % git format-patch origin/main
 ....
 +
 Patch generated with `git format-patch` will include author identity and email addresses,
 making it easier for developers to apply (with `git am`) and give proper credit.
 +
 [IMPORTANT]
 ======
 To make it easier for committers to apply the patch on their working copy of the documentation tree,
 please generate the [.filename]#.diff# from the base of your documentation tree.
 ======
 +
 In the example above, changes have been made to the *bsdinstall* portion of the Handbook.
 +
 . Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the patch or diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
 ====
 
 [[gnu-linux-installation-process]]
 === GNU/Linux installation process
 
 [.procedure]
 ====
 [TIP]
 ======
 Hugo version 0.90 or higher must be used
 ======
 
 . Install these packages in apt-based systems like Debian or Ubuntu.
 On other GNU/Linux distributions the package names may change.
 Consult your distribution's package manager if in doubt.
 +
 [source,shell]
 ....
 # apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake
 ....
 +
 . Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
 +
 [source,shell]
 ....
 % git clone https://git.FreeBSD.org/doc.git ~/doc
 ....
 +
 . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
 +
 Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems.
 Repeat until all of the errors are resolved.
 +
 . Always build and test the changes before submitting them. Running `bmake` in the top-level directory of the documentation will generate that documentation in HTML format.
 +
 [source,shell]
 ....
 % bmake run LOCALBASE=/usr
 ....
 +
 . Add all the files with `git add .`, then review the diff with `git diff`. For example:
 +
 [source,shell]
 ....
 % git add .
 % git diff --staged
 ....
 +
 Make sure that all required files are included, then commit the change to your local branch and generate a patch with `git format-patch`
 +
 [source,shell]
 ....
 % git commit
 % git format-patch origin/main
 ....
 +
 Patch generated with `git format-patch` will include author identity and email addresses,
 making it easier for developers to apply (with `git am`) and give proper credit.
 +
 [IMPORTANT]
 ======
 To make it easier for committers to apply the patch on their working copy of the documentation tree,
 please generate the [.filename]#.diff# from the base of your documentation tree.
 ======
 +
 . Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system.
 If using the web form, enter a Summary of _short description of problem_.
 Select the Component `Documentation`.
 In the Description field, enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field.
 Use the btn:[Add an attachment] button to attach the patch or diff file.
 Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
 ====
 
 [[mac-os-installation-process]]
 === macOS(R) installation process
 
 [.procedure]
 ====
 [TIP]
 ======
 Hugo version 0.90 or higher must be used
 ======
 
 . Install these packages using link:https://brew.sh/[Homebrew] and link:https://rubygems.org/[RubyGem].
 +
 [source,shell]
 ....
-$ brew install hugo ruby git bmake asciidoctor
+$ brew install hugo ruby git bmake
 ....
 +
 . Add Ruby to the Path.
 +
 [source,shell]
 ....
-$ echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
+$ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0"' >> ~/.zshrc
+$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
+$ source ~/.zshrc
 ....
 +
 . Install the rouge package using RubyGem.
 +
 [source,shell]
 ....
-$ sudo gem install rouge
+$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3
 ....
 +
 . Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]).
 +
 [source,shell]
 ....
 $ git clone https://git.FreeBSD.org/doc.git ~/doc
 ....
 +
 . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.
 +
 Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems.
 Repeat until all of the errors are resolved.
 +
 . Always build and test the changes before submitting them. Running `bmake` in the top-level directory of the documentation will generate that documentation in HTML format.
 +
 [source,shell]
 ....
-$ bmake run LOCALBASE=/usr
+$ bmake run LOCALBASE=/usr USE_RUBYGEMS=YES
 ....
 . Add all the files with `git add .`, then review the diff with `git diff`. For example:
 +
 [source,shell]
 ....
 % git add .
 % git diff --staged
 ....
 +
 Make sure that all required files are included, then commit the change to your local branch and generate a patch with `git format-patch`
 +
 [source,shell]
 ....
 % git commit
 % git format-patch origin/main
 ....
 +
 Patch generated with `git format-patch` will include author identity and email addresses,
 making it easier for developers to apply (with `git am`) and give proper credit.
 +
 [IMPORTANT]
 ======
 To make it easier for committers to apply the patch on their working copy of the documentation tree,
 please generate the [.filename]#.diff# from the base of your documentation tree.
 ======
 +
 . Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system.
 If using the web form, enter a Summary of _short description of problem_.
 Select the Component `Documentation`.
 In the Description field, enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field.
 Use the btn:[Add an attachment] button to attach the patch or diff file.
 Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.
 ====
 
 [[overview-doc]]
 == The FreeBSD Documentation Set
 
 The FDP is responsible for four categories of FreeBSD documentation.
 
 * _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users.
 * _FAQ_: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers.
 * _Manual pages_: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies.
 * _Web site_: This is the main FreeBSD presence on the web, visible at https://www.freebsd.org/[https://www.FreeBSD.org/] and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD.
 
 Translation teams are responsible for translating the Handbook and web site into different languages.
 Manual pages are not translated at present.
 
 Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at `https://cgit.freebsd.org/doc/`.
 
 Source for manual pages is available in a separate source repository located at `https://cgit.freebsd.org/src/`.
 
 Documentation commit messages are visible with `git log`.
 Commit messages are also archived at link:{dev-commits-doc-all}.
 
 Web frontends to both of these repositories are available at https://cgit.freebsd.org/doc/[] and https://cgit.freebsd.org/src/[].
 
 Many people have written tutorials or how-to articles about FreeBSD.
 Some are stored as part of the FDP files.
 In other cases, the author has decided to keep the documentation separate.
 The FDP endeavors to provide links to as much of this external documentation as possible.
diff --git a/documentation/tools/asciidoctor.sh b/documentation/tools/asciidoctor.sh
index a834b2e532..27ce3f790c 100755
--- a/documentation/tools/asciidoctor.sh
+++ b/documentation/tools/asciidoctor.sh
@@ -1,221 +1,228 @@
 #!/bin/sh
 #
 # Copyright (c) 2021 Danilo G. Baio <dbaio@FreeBSD.org>
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
 #
 # 1. Redistributions of source code must retain the above copyright notice, this
 # list of conditions and the following disclaimer.
 #
 # 2. Redistributions in binary form must reproduce the above copyright notice,
 # this list of conditions and the following disclaimer in the documentation
 # and/or other materials provided with the distribution.
 #
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 # shellcheck disable=SC3043
 
 
 LOCALBASE="/usr/local"
-ASCIIDOCTORPDF_CMD="${LOCALBASE}/bin/asciidoctor-pdf"
-ASCIIDOCTOREPUB_CMD="${LOCALBASE}/bin/asciidoctor-epub3"
+
+if [ "$USE_RUBYGEMS" = "YES" ]; then
+	GEMBASE="${GEM_PATH}"
+else
+	GEMBASE="${LOCALBASE}"
+fi
+
+ASCIIDOCTORPDF_CMD="${GEMBASE}/bin/asciidoctor-pdf"
+ASCIIDOCTOREPUB3_CMD="${GEMBASE}/bin/asciidoctor-epub3"
 
 build_pdf() {
 	if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then
 		exit 1
 	fi
 
 	local doc_type="$1"
 	local doc_lang="$2"
 	local doc_name="$3"
 
 	local cur_dir_source="content/$doc_lang/$doc_type/$doc_name/"
 	local cur_dir_output="public/$doc_lang/$doc_type/$doc_name/"
 
 	if [ ! -d "$cur_dir_output" ]; then
 		mkdir -p "$cur_dir_output"
 	fi
 
 	if [ "$doc_type" = "books" ]; then
 		local asciidoctor_type="book"
 
 		if [ -f "${cur_dir_source}book.adoc" ]; then
 			local asciidoctor_file_name="book.adoc"
 		else
 			local asciidoctor_file_name="_index.adoc"
 		fi
 	fi
 
 	if [ "$doc_type" = "articles" ]; then
 		local asciidoctor_type="article"
 		local asciidoctor_file_name="_index.adoc"
 	fi
 
 	$ASCIIDOCTORPDF_CMD \
 		-r ./shared/lib/man-macro.rb \
 		-r ./shared/lib/git-macro.rb \
 		-r ./shared/lib/packages-macro.rb \
 		-r ./shared/lib/inter-document-references-macro.rb \
 		-r ./shared/lib/sectnumoffset-treeprocessor.rb \
 		-r ./shared/lib/cross-document-references-macro.rb \
 		--doctype="$asciidoctor_type" \
 		-a skip-front-matter \
 		-a lang="$doc_lang" \
 		-a isonline=1 \
 		-a env-beastie=1 \
 		-a pdf-theme=default-with-fallback-font \
 		-o "${cur_dir_output}${doc_name}_${doc_lang}.pdf" \
 		"${cur_dir_source}${asciidoctor_file_name}"
 }
 
 
 build_epub() {
 	if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then
 		exit 1
 	fi
 
 	local doc_type="$1"
 	local doc_lang="$2"
 	local doc_name="$3"
 
 	local cur_dir_source="content/$doc_lang/$doc_type/$doc_name/"
 	local cur_dir_output="public/$doc_lang/$doc_type/$doc_name/"
 
 	if [ ! -d "$cur_dir_output" ]; then
 		mkdir -p "$cur_dir_output"
 	fi
 
 	if [ "$doc_type" = "books" ]; then
 		local asciidoctor_type="book"
 
 		if [ -f "${cur_dir_source}book.adoc" ]; then
 			local asciidoctor_file_name="book.adoc"
 		else
 			local asciidoctor_file_name="_index.adoc"
 		fi
 	fi
 
 	if [ "$doc_type" = "articles" ]; then
 		local asciidoctor_type="article"
 		local asciidoctor_file_name="_index.adoc"
 	fi
 
-	$ASCIIDOCTOREPUB_CMD \
+	$ASCIIDOCTOREPUB3_CMD \
 		-r ./shared/lib/man-macro.rb \
 		-r ./shared/lib/git-macro.rb \
 		-r ./shared/lib/packages-macro.rb \
 		-r ./shared/lib/inter-document-references-macro.rb \
 		-r ./shared/lib/sectnumoffset-treeprocessor.rb \
 		-r ./shared/lib/cross-document-references-macro.rb \
 		--doctype="$asciidoctor_type" \
 		-a skip-front-matter \
 		-a lang="$doc_lang" \
 		-a isonline=1 \
 		-a env-beastie=1 \
 		-o "${cur_dir_output}${doc_name}_${doc_lang}_POC_.epub" \
 		"${cur_dir_source}${asciidoctor_file_name}"
 }
 
 
 archive() {
 	if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then
 		exit 1
 	fi
 
 	local doc_type="$1"
 	local doc_lang="$2"
 	local doc_name="$3"
 
 	if [ -d "public/$doc_lang" ]; then
 		local pub_dir="public/$doc_lang/$doc_type/$doc_name/"
 	elif [ -d "public/$doc_type" ]; then
 		# single language build
 		local pub_dir="public/$doc_type/$doc_name/"
 	fi
 
 	if [ -f "${pub_dir}${doc_name}_${doc_lang}.tar.gz" ]; then
 		rm -f "${pub_dir}${doc_name}_${doc_lang}.tar.gz"
 	fi
 
 	local source_doc_dir=""
 	if [ -d "public/source/$doc_type/$doc_name/" ]; then
 		source_doc_dir="public/source/$doc_type/$doc_name/"
 	fi
 
 	local image_doc_dir=""
 	if [ -d "public/images/$doc_type/$doc_name/" ]; then
 		image_doc_dir="public/images/$doc_type/$doc_name/"
 	fi
 
 	tar -czf "public/${doc_name}_${doc_lang}.tar.gz" \
 		"$pub_dir" \
 		public/css/ \
 		public/fonts/ \
 		public/js/ \
 		$source_doc_dir \
 		$image_doc_dir
 
 	mv -f "public/${doc_name}_${doc_lang}.tar.gz" "$pub_dir"
 
 }
 
 
 main() {
 	if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then
 		echo "Needs parameters (type, language and format)."
 		echo "$0 articles en pdf"
 		exit 1
 	fi
 
 	local doc_type="$1"
 	local doc_lang="$2"
 	local doc_format="$3"
 
 	if [ ! "$doc_type" = "articles" ] && [ ! "$doc_type" = "books" ]; then
 		echo "First parameter needs to be 'articles' or 'books'"
 		exit 1
 	fi
 
 	case "$doc_format" in
 		pdf)
 			for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do
 				if [ "$document" = "pgpkeys" ]; then
 					continue
 				fi
 				echo "asciidoctor build_pdf: $doc_type $doc_lang $document"
 				build_pdf "$doc_type" "$doc_lang" "$document"
 			done
 			;;
 		archive)
 			for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do
 				echo "generate archive: $doc_type $doc_lang $document"
 				archive "$doc_type" "$doc_lang" "$document"
 			done
 			;;
 		epub)
 			for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do
 				if [ "$document" = "pgpkeys" ]; then
 					continue
 				fi
 				echo "asciidoctor epub: $doc_type $doc_lang $document"
 				build_epub "$doc_type" "$doc_lang" "$document"
 			done
 			;;
 		*)
 			echo "Formats available: archive, pdf, epub"
 			exit 1
 			;;
 	esac
 }
 
 main "$@"