From owner-dev-commits-doc-all@freebsd.org Wed Jun 16 23:55:39 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 5C2D5647AA1 for ; Wed, 16 Jun 2021 23:55:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4G52BM29k6z4bNW; Wed, 16 Jun 2021 23:55:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 32CE6250E5; Wed, 16 Jun 2021 23:55:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 15GNtdtO009103; Wed, 16 Jun 2021 23:55:39 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 15GNtdx4009102; Wed, 16 Jun 2021 23:55:39 GMT (envelope-from git) Date: Wed, 16 Jun 2021 23:55:39 GMT Message-Id: <202106162355.15GNtdx4009102@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: "Danilo G. Baio" Subject: git: 44bb3f68fb - main - books/fdp-primer: Update tools and add advanced build examples MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: dbaio X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 44bb3f68fbe8aeef7ccbc3dc838ed11d4f53b067 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Jun 2021 23:55:39 -0000 The branch main has been updated by dbaio: URL: https://cgit.FreeBSD.org/doc/commit/?id=44bb3f68fbe8aeef7ccbc3dc838ed11d4f53b067 commit 44bb3f68fbe8aeef7ccbc3dc838ed11d4f53b067 Author: Danilo G. Baio AuthorDate: 2021-06-16 23:45:46 +0000 Commit: Danilo G. Baio CommitDate: 2021-06-16 23:54:21 +0000 books/fdp-primer: Update tools and add advanced build examples This updates the documentation to reflect the changes that were made recently. Reviewed by: ceri Differential Revision: https://reviews.freebsd.org/D30749 --- .../en/books/fdp-primer/doc-build/_index.adoc | 39 ++++++++++++++++++++++ .../en/books/fdp-primer/overview/_index.adoc | 11 ++---- .../content/en/books/fdp-primer/tools/_index.adoc | 2 +- 3 files changed, 42 insertions(+), 10 deletions(-) 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 146f32ad11..c39adf8a40 100644 --- a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc +++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc @@ -89,6 +89,45 @@ To render the documentation and the website to `html` use one of the following e .... ==== +Advanced build examples are given below: + +[[documentation-build-example-verbose]] +.Build the documentation with verbose and debug messages +[example] +==== +[source,shell] +.... +% cd ~/doc/documentation +% make HUGO_ARGS="--verbose --debug --path-warnings" +.... +==== + +[[documentation-build-example-server]] +.Build and serve the content with Hugo’s internal webserver +[example] +==== +[source,shell] +.... +% cd ~/doc/documentation +% make run +.... +This webserver runs on `localhost`, port `1313` by default. + +To serve the content with Hugo’s internal webserver binding a specific IP address: + +[source,shell] +.... +% make run BIND=192.168.15.10 +.... + +A `hostname` can also be set as base url to Hugo’s internal webserver: + +[source,shell] +.... +% make run BIND=192.168.15.10 HOSTNAME=example.com +.... +==== + [[doc-build-rendering-pdf]] === Rendering to pdf diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index 2fef4f9b53..fcea50e851 100644 --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -50,18 +50,11 @@ These people can help with questions or problems involving the documentation. [.procedure] ==== -. Install these packages. These packages are all of the software needed to edit and build FreeBSD documentation. The Git package is needed to obtain a working copy of the documentation and generate patches with. +. Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation. + [source,shell] .... -# pkg install gohugo python3 git-lite rubygem-asciidoctor rubygem-rouge -.... -+ -. Optional: to generate PDF documentation install `asciidoctor-pdf` -+ -[source,shell] -.... -# pkg install rubygem-asciidoctor-pdf +# pkg install docproj python3 .... + . 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/tools/_index.adoc b/documentation/content/en/books/fdp-primer/tools/_index.adoc index 459ce9aa5b..a5acaf0859 100644 --- a/documentation/content/en/books/fdp-primer/tools/_index.adoc +++ b/documentation/content/en/books/fdp-primer/tools/_index.adoc @@ -31,7 +31,7 @@ Some are optional, adding capabilities or making the job of creating documentati [[tools-required]] == Required Tools -Install `gohugo` and `rubygem-asciidoctor` as shown in crossref:overview[overview,the overview chapter] from the Ports Collection. +Install `docproj` and `python3` as shown in crossref:overview[overview,the overview chapter] from the Ports Collection. These applications are required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below.