Update build instructions for macOS

Approved by:                    carlavilla@
Reviewed by:                    Jose Luis Duran <jlduran_gmail.com>
Differential Revision:          https://reviews.freebsd.org/D37143

3 files changed, 35 insertions, 16 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index 457f6add0b..410ff444df 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -32,13 +32,23 @@ BOOKONLY_LANGS=		mn
 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}
@@ -54,8 +64,8 @@ RUBYLIB =	../shared/lib
 .export	RUBYLIB
 
 RUN_DEPENDS=	${HUGO_CMD} \
-		${LOCALBASE}/bin/asciidoctor \
-		${LOCALBASE}/bin/rougify
+				${ASCIIDOCTOR_CMD} \
+				${ROUGIFY_CMD}
 
 .ifndef HOSTNAME
 .  ifdef BIND
@@ -111,13 +121,13 @@ requirements:
 .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
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
@@ -251,21 +251,23 @@ Hugo version 0.90 or higher must be used
 +
 [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]).
@@ -284,7 +286,7 @@ Repeat until all of the errors are resolved.
 +
 [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:
 +
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
@@ -27,8 +27,15 @@
 
 
 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
@@ -110,7 +117,7 @@ build_epub() {
 		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 \