1 files changed, 66 insertions, 25 deletions

diff --git a/documentation/content/en/articles/nanobsd/_index.adoc b/documentation/content/en/articles/nanobsd/_index.adoc
index dc9d406b36..a006140591 100644
--- a/documentation/content/en/articles/nanobsd/_index.adoc
+++ b/documentation/content/en/articles/nanobsd/_index.adoc
@@ -20,6 +20,8 @@ trademarks: ["freebsd", "general"]
 include::shared/authors.adoc[]
 
 [.abstract-title]
+Abstract
+
 This document provides information about the NanoBSD tools, which can be used to create FreeBSD system images for embedded applications, suitable for use on a USB key, memory card or other mass storage media.
 
 '''
@@ -29,9 +31,12 @@ toc::[]
 [[intro]]
 == Introduction to NanoBSD
 
-NanoBSD is a tool developed by {phk} and now maintained by {imp}. It creates a FreeBSD system image for embedded applications, suitable for use on a USB key, memory card or other mass storage media.
+NanoBSD is a tool developed by {phk} and now maintained by {imp}.
+It creates a FreeBSD system image for embedded applications, suitable for use on a USB key, memory card or other mass storage media.
 
-It can be used to build specialized install images, designed for easy installation and maintenance of systems commonly called "computer appliances". Computer appliances have their hardware and software bundled in the product, which means all applications are pre-installed. The appliance is plugged into an existing network and can begin working (almost) immediately.
+It can be used to build specialized install images, designed for easy installation and maintenance of systems commonly called "computer appliances". 
+Computer appliances have their hardware and software bundled in the product, which means all applications are pre-installed.
+The appliance is plugged into an existing network and can begin working (almost) immediately.
 
 The features of NanoBSD include:
 
@@ -46,7 +51,8 @@ The features of NanoBSD include:
 [[design]]
 === The Design of NanoBSD
 
-Once the image is present on the medium, it is possible to boot NanoBSD. The mass storage medium is divided into three parts by default:
+Once the image is present on the medium, it is possible to boot NanoBSD.
+The mass storage medium is divided into three parts by default:
 
 * Two image partitions: `code#1` and `code#2`.
 * The configuration file partition, which can be mounted under the [.filename]#/cfg# directory at run time.
@@ -55,7 +61,8 @@ These partitions are normally mounted read-only.
 
 The [.filename]#/etc# and [.filename]#/var# directories are man:md[4] (malloc) disks.
 
-The configuration file partition persists under the [.filename]#/cfg# directory. It contains files for [.filename]#/etc# directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from [.filename]#/etc# back to the [.filename]#/cfg# directory if changes are expected to persist after the system restarts.
+The configuration file partition persists under the [.filename]#/cfg# directory.
+It contains files for [.filename]#/etc# directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from [.filename]#/etc# back to the [.filename]#/cfg# directory if changes are expected to persist after the system restarts.
 
 .Making Persistent Changes to [.filename]#/etc/resolv.conf#
 [example]
@@ -81,7 +88,8 @@ Keeping [.filename]#/cfg# mounted at all times is not a good idea, especially if
 
 === Building a NanoBSD Image
 
-A NanoBSD image is built using a simple [.filename]#nanobsd.sh# shell script, which can be found in the [.filename]#/usr/src/tools/tools/nanobsd# directory. This script creates an image, which can be copied on the storage medium using the man:dd[1] utility.
+A NanoBSD image is built using a simple [.filename]#nanobsd.sh# shell script, which can be found in the [.filename]#/usr/src/tools/tools/nanobsd# directory.
+This script creates an image, which can be copied on the storage medium using the man:dd[1] utility.
 
 The necessary commands to build a NanoBSD image are:
 
@@ -103,7 +111,8 @@ The necessary commands to build a NanoBSD image are:
 
 ==== Options When Building a NanoBSD Image
 
-When building a NanoBSD image, several build options can be passed to [.filename]#nanobsd.sh# on the command line. These options can have a significant impact on the build process.
+When building a NanoBSD image, several build options can be passed to [.filename]#nanobsd.sh# on the command line.
+These options can have a significant impact on the build process.
 
 Some options are for verbosity purposes:
 
@@ -111,7 +120,8 @@ Some options are for verbosity purposes:
 * `-q`: makes output quieter.
 * `-v`: makes output more verbose
 
-Some other options can be used to restrict the building process. Sometimes it is not necessary to rebuild everything from sources, especially if an image has already been built, and only little change is made.
+Some other options can be used to restrict the building process.
+Sometimes it is not necessary to rebuild everything from sources, especially if an image has already been built, and only little change is made.
 
 * `-k`: do not build the kernel
 * `-w`: do not build world
@@ -120,7 +130,8 @@ Some other options can be used to restrict the building process. Sometimes it is
 * `-f`: do not build a disk image of the first partition (which is useful for upgrade purposes)
 * `-n`: add `-DNO_CLEAN` to `buildworld`, `buildkernel`. Also, all the files that have already been built in a previous run are kept.
 
-A configuration file can be used to tweak as many elements as desired. Load it with `-c`
+A configuration file can be used to tweak as many elements as desired.
+Load it with `-c`
 
 The last options are:
 
@@ -128,7 +139,9 @@ The last options are:
 
 ==== The Complete Image Building Process
 
-The complete image building process is going through a lot of steps. The exact steps taken will depend on the chosen options when starting the script. Assuming the script is run with no particular options, this is what will happen.
+The complete image building process is going through a lot of steps.
+The exact steps taken will depend on the chosen options when starting the script.
+Assuming the script is run with no particular options, this is what will happen.
 
 . `run_early_customize`: commands that are defined in a supplied configuration file.
 . `clean_build`: Just cleans the build environment by deleting the previously built files.
@@ -151,7 +164,8 @@ The complete image building process is going through a lot of steps. The exact s
 
 === Customizing a NanoBSD Image
 
-This is probably the most important and most interesting feature of NanoBSD. This is also where you will be spending most of the time when developing with NanoBSD.
+This is probably the most important and most interesting feature of NanoBSD.
+This is also where you will be spending most of the time when developing with NanoBSD.
 
 Invocation of the following command will force the [.filename]#nanobsd.sh# to read its configuration from [.filename]#myconf.nano# located in the current directory:
 
@@ -167,9 +181,12 @@ Customization is done in two ways:
 
 ==== Configuration Options
 
-With configuration settings, it is possible to configure options passed to both the `buildworld` and `installworld` stages of the NanoBSD build process, as well as internal options passed to the main build process of NanoBSD. Through these options it is possible to cut the system down, so it will fit on as little as 64MB. You can use the configuration options to trim down FreeBSD even more, until it will consists of just the kernel and two or three files in the userland.
+With configuration settings, it is possible to configure options passed to both the `buildworld` and `installworld` stages of the NanoBSD build process, as well as internal options passed to the main build process of NanoBSD.
+Through these options it is possible to cut the system down, so it will fit on as little as 64MB.
+You can use the configuration options to trim down FreeBSD even more, until it will consists of just the kernel and two or three files in the userland.
 
-The configuration file consists of configuration options, which override the default values. The most important directives are:
+The configuration file consists of configuration options, which override the default values.
+The most important directives are:
 
 * `NANO_NAME` - Name of build (used to construct the workdir names).
 * `NANO_SRC` - Path to the source tree used to build the image.
@@ -191,28 +208,43 @@ There are three stages, by design, at which it is possible to make changes that
 
 To customize a NanoBSD image, at any of these steps, it is best to add a specific value to one of the corresponding variables.
 
-The `NANO_EARLY_CUSTOMIZE` variable is used at the first step of the building process. At this point, there is no example as to what can be done using that variable, but it may change in the future.
+The `NANO_EARLY_CUSTOMIZE` variable is used at the first step of the building process.
+At this point, there is no example as to what can be done using that variable, but it may change in the future.
 
-The `NANO_CUSTOMIZE` variable is used after the kernel, world and etc configuration files have been installed, and the etc files have been setup as to be a NanoBSD installation. So it is the correct step in the building process to tweak configuration options and add packages, like in the cust_nobeastie example.
+The `NANO_CUSTOMIZE` variable is used after the kernel, world and etc configuration files have been installed, and the etc files have been setup as to be a NanoBSD installation.
+So it is the correct step in the building process to tweak configuration options and add packages, like in the cust_nobeastie example.
 
-The `NANO_LATE_CUSTOMIZE` variable is used just before the disk image is created, so it is the very last moment to change anything. Remember that the `setup_nanobsd` routine already executed and that the [.filename]#etc#, [.filename]#conf# and [.filename]#cfg#directories and subdirectories are already modified, so it is not time to change them at this point. Rather, it is possible to add or remove specific files.
+The `NANO_LATE_CUSTOMIZE` variable is used just before the disk image is created, so it is the very last moment to change anything.
+Remember that the `setup_nanobsd` routine already executed and that the [.filename]#etc#, [.filename]#conf# and [.filename]#cfg# directories and subdirectories are already modified, so it is not time to change them at this point.
+Rather, it is possible to add or remove specific files.
 
 ===== Booting Options
 
-There are also variables that can change the way the NanoBSD image boots. Two options are passed to man:boot0cfg[8] to initialize the boot sector of the disk image:
+There are also variables that can change the way the NanoBSD image boots.
+Two options are passed to man:boot0cfg[8] to initialize the boot sector of the disk image:
 
 * `NANO_BOOT0CFG`
 * `NANO_BOOTLOADER`
 
-With `NANO_BOOTLOADER` a bootloader file can be chosen. The most common possible options are between [.filename]#boot0sio# and [.filename]#boot0# depending on whether the appliance has a serial port or not. It is best to avoid supplying a different bootloader, but it is possible. To do so, it is best to have checked the link:{handbook}#boot/[FreeBSD Handbook] chapter on the boot process.
+With `NANO_BOOTLOADER` a bootloader file can be chosen.
+The most common possible options are between [.filename]#boot0sio# and [.filename]#boot0# depending on whether the appliance has a serial port or not.
+It is best to avoid supplying a different bootloader, but it is possible.
+To do so, it is best to have checked the link:{handbook}#boot/[FreeBSD Handbook] chapter on the boot process.
 
-With `NANO_BOOT0CFG`, the booting process can be tweaked, like selecting on which partition the NanoBSD image will actually boot. It is best to check the man:boot0cfg[8] page before changing the default value of this variable. One option that could be interesting to change is the timeout of the booting procedure. To do so, the `NANO_BOOT0CFG` variable can be changed to `"-o packet -s 1 -m 3 -t 36"`. That way the booting process would start after approximately 2 seconds; because it is rare that waiting 10 seconds before actually booting is desired.
+With `NANO_BOOT0CFG`, the booting process can be tweaked, like selecting on which partition the NanoBSD image will actually boot.
+It is best to check the man:boot0cfg[8] page before changing the default value of this variable.
+One option that could be interesting to change is the timeout of the booting procedure.
+To do so, the `NANO_BOOT0CFG` variable can be changed to `"-o packet -s 1 -m 3 -t 36"`.
+That way the booting process would start after approximately 2 seconds;
+because it is rare that waiting 10 seconds before actually booting is desired.
 
-Good to know: the `NANO_BOOT2CFG` variable is only used in the `cust_comconsole` routine that can be called at the `NANO_CUSTOMIZE` step if the appliance has a serial port and all console input and output has to take place through it. Be sure to check the relevant parameters of the serial port, as setting a bad parameter value can make it useless.
+Good to know: the `NANO_BOOT2CFG` variable is only used in the `cust_comconsole` routine that can be called at the `NANO_CUSTOMIZE` step if the appliance has a serial port and all console input and output has to take place through it.
+Be sure to check the relevant parameters of the serial port, as setting a bad parameter value can make it useless.
 
 ===== Disk Image Creation
 
-In the end of the boot process is the disk image creation. With this step, the NanoBSD script provides a file that can simply be copied onto a disk for the appliance, and that will make it boot and start.
+In the end of the boot process is the disk image creation.
+With this step, the NanoBSD script provides a file that can simply be copied onto a disk for the appliance, and that will make it boot and start.
 
 There are many variable that need to be set just right for the script to produce a usable disk image.
 
@@ -225,7 +257,8 @@ There are many variable that need to be set just right for the script to produce
 
 ==== Custom Functions
 
-It is possible to fine-tune NanoBSD using shell functions in the configuration file. The following example illustrates the basic model of custom functions:
+It is possible to fine-tune NanoBSD using shell functions in the configuration file.
+The following example illustrates the basic model of custom functions:
 
 [.programlisting]
 ....
@@ -260,9 +293,14 @@ Packages can be added to a NanoBSD image, to provide specific functionalities on
 * Add the `cust_pkgng` to the `NANO_CUSTOMIZE` variable, or
 * Add a `'customize_cmd cust_pkgng'` command in a customized configuration file.
 
-Both methods achieve the same result: launching the `cust_pkgng` routine. This routine will go through `NANO_PACKAGE_DIR` directory to find either all packages or just the list of packages in the `NANO_PACKAGE_LIST` variable.
+Both methods achieve the same result: launching the `cust_pkgng` routine.
+This routine will go through `NANO_PACKAGE_DIR` directory to find either all packages or just the list of packages in the `NANO_PACKAGE_LIST` variable.
 
-It is common, when installing applications through pkg on a standard FreeBSD environment, that the install process puts configuration files, in the [.filename]#usr/local/etc# directory, and startup scripts in the [.filename]#/usr/local/etc/rc.d# directory. So, after the required packages have been installed, they need to be configured in order for them to start right out of the box. To do so, the necessary configuration files have to be installed in the correct directories. This can be achieved by writing dedicated routines or the generic `cust_install_files` routine can be used to lay out files properly from the [.filename]#/usr/src/tools/tools/nanobsd/Files# directory. Usually a statement, sometimes multiple statements, in the [.filename]#/etc/rc.conf# also needs to be added for each package.
+It is common, when installing applications through pkg on a standard FreeBSD environment, that the install process puts configuration files, in the [.filename]#usr/local/etc# directory, and startup scripts in the [.filename]#/usr/local/etc/rc.d# directory.
+So, after the required packages have been installed, they need to be configured in order for them to start right out of the box.
+To do so, the necessary configuration files have to be installed in the correct directories.
+This can be achieved by writing dedicated routines or the generic `cust_install_files` routine can be used to lay out files properly from the [.filename]#/usr/src/tools/tools/nanobsd/Files# directory.
+Usually a statement, sometimes multiple statements, in the [.filename]#/etc/rc.conf# also needs to be added for each package.
 
 ==== Configuration File Example
 
@@ -321,9 +359,12 @@ customize_cmd cust_allow_ssh_root
 customize_cmd cust_nobeastie
 ....
 
-All the build and install compilation options can be found in the man:src.conf[5] man page, but not all options can or should be used when building a NanoBSD image. The build and install options should be defined according to the needs of the image being built.
+All the build and install compilation options can be found in the man:src.conf[5] man page, but not all options can or should be used when building a NanoBSD image.
+The build and install options should be defined according to the needs of the image being built.
 
-For example, the ftp client and server might not be needed. Adding `WITHOUT_FTP=TRUE` to a configuration file in the `CONF_BUILD` section will avoid having them built. Also, if the NanoBSD appliance will not be used to build programs then it is possible to add the `WITHOUT_BINUTILS=TRUE` in the `CONF_INSTALL` section; but not in the `CONF_BUILD` section as they will be used to build the NanoBSD image.
+For example, the ftp client and server might not be needed.
+Adding `WITHOUT_FTP=TRUE` to a configuration file in the `CONF_BUILD` section will avoid having them built.
+Also, if the NanoBSD appliance will not be used to build programs then it is possible to add the `WITHOUT_BINUTILS=TRUE` in the `CONF_INSTALL` section; but not in the `CONF_BUILD` section as they will be used to build the NanoBSD image.
 
 Not building a particular set of programs - through a compilation option - shortens the overall building time and lowers the required size for the disk image, whereas not installing the same specific set of programs does not lower the overall building time.