Index: README
===================================================================
--- README	(revision cd87e527fe152ed8e50e44437853dd6a60c48cd0)
+++ README	(revision 35094eda67103de7a8380b8c2744ee3ebeee0036)
@@ -1,149 +1,267 @@
 1. INTRODUCTION::
 
-     The scripts in this directory implement an automation of the building
-  of a GNU/LInux system, as described in the Linux From Scratch book series.
-  The name of the project is jhalfs: in that name, "alfs" stands for
-  "automated linux from scratch", and the initials "jh" have been kept since
-  the original "jhalfs-0.2" code developed by Jeremy Huntwork.
-
-     The list of supported books can be found at
-  http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks.
-
-     The documentation is split among various README.* files. Here is a list
-  of what is in which:
-    - README (this file): instructions to use the LFS book. This should be
-      enough if you just want to build a base system as per the LFS book. It is
-      also a required reading for all the other projects.
-    - README.BLFS: instructions to install an automated build infrastructure
-      for the BLFS book. There are two ways to do so: (i) install the
-      tools at the end of an LFS build, or
-      (ii) install the tools on an already running system. Both methods are
-      described in that file.
-    - README.CUSTOM: instructions to run custom commands either during the xLFS
-      build, at the end of a xLFS build. Note that you will not find
-      instructions on how to write those commands, but some examples are
-      available.
-    - README.PACKAGE_MANAGEMENT: instructions to use package management during
-      the build
-
-     Other sources of information are the context help in the menu interface,
-  and the xLFS books themselves.
+      The scripts in this directory implement an automation of the building
+   of a GNU/LInux system, as described in the Linux From Scratch book series.
+   The name of the project is jhalfs: in that name, "alfs" stands for
+   "automated linux from scratch", and the initials "jh" have been kept since
+   the original "jhalfs-0.2" code developed by Jeremy Huntwork.
+
+      The list of supported books can be found at
+   http://wiki.linuxfromscratch.org/alfs/wiki/SupportedBooks (maybe outdated,
+   current develoment books and latest version are always supported).
+
+      The documentation is split among various README.* files. Here is a list
+   of what is in which:
+      - README (this file): instructions to use the LFS book. This should be
+        enough if you just want to build a base system as per the LFS book. It
+        is also a required reading for all the other projects.
+      - README.BLFS: instructions to install an automated build infrastructure
+        for the BLFS book. There are two ways to do so: (i) install the
+        tools at the end of an LFS build, or
+        (ii) install the tools on an already running system. Both methods are
+        described in that file.
+      - README.CUSTOM: instructions to run custom commands either during the LFS
+        build, or at the end of a LFS build. Note that you will not find
+        instructions on how to write those commands, but some examples are
+        available.
+      - README.PACKAGE_MANAGEMENT: instructions to use package management during
+        the build (Note: the only package manager that is regularly tested is
+        porg)
+
+      Other sources of information are the context help in the menu interface,
+   and the LFS books themselves (both required readings of course!).
 
 2. PREREQUISITES::
 
-     As said elsewhere, it is strongly advised that you first build manually
-  a complete system before attempting to automate the build.
-
-     Of course the "Host System Requirements" should be fulfilled. The needed
-  supplementary packages are detailed at the bottom of the page:
-  https://www.linuxfromscratch.org/alfs/download.html. In short, you need
-  wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons.
+      It is strongly advised that you first build manually a complete system
+   before attempting to automate the build.
+
+      Of course the "Host System Requirements" should be fulfilled. Some
+   supplementary packages are needed for using jhalfs. They are detailed
+   at the bottom of the page:
+   https://www.linuxfromscratch.org/alfs/download.html. In short, you need
+   wget, sudo, libxml2, libxslt, docbook-4.5-xml, and docbook-xsl-nons.
 
 3. INSTALLATION::
 
-     No installation is required. You may want to move the files in this
-  directory to a convenient location, and then follow the instructions below.
+      No installation is required. You may want to move the files in this
+   directory to a convenient location, and then follow the instructions below.
 
 4. CONFIGURATION::
 
-  4.1. CONFIGURATION OF THE TOOLS:
-       There is no configuration of the tools themselves. The various
-    parameters for the build are set through a menu driven interface. See
-    the section RUNNING below for details.
-
-  4.2. PRELIMINARY TASKS:
-       This tool has no support at all for creating a partition and a mount
-    point for the built system. You should follow the book up to the section
-    "Mounting the new partition". Note that the default name for the
-    partition mount point is "/mnt/build_dir", instead of /mnt/{c,}lfs.
-    You can change that default to anything you'd like in the menu, so you
-    may name it /mnt/lfs, or whatever you like. We'll use the name
-    /mnt/build_dir in the sequel.
-
-       The tool can download the needed packages for you, or you may download
-    them yourself. The tool may optionally use a package archive directory
-    where the downloaded packages are stored. That directory name may be made
-    available to the tool in two ways: (i) export the SRC_ARCHIVE variable,
-    for example SRC_ARCHIVE=/usr/src, (ii) enter the name at the "Package
-    Archive Directory" menu prompt. Note that the user should have write
-    permission to that directory. If a needed package is found in that
-    directory, it is copied to /mnt/build_dir/sources, if not, it is
-    downloaded to that directory and copied to /mnt/build_dir/sources,
-    except if found in /mnt/build_dir/sources, in which case, it is just
-    copied to $SRC_ARCHIVE. If you want the tool to download packages and you
-    do not want to archive them, just unset SRC_ARCHIVE, and keep the
-    default entry for "Package Archive Directory". If you choose to download
-    the packages by yourself, you should download (or copy) them to
-    /mnt/build_dir/sources directly.
-
-       If you want to build the kernel as part of the automated build, select
-    "Build the kernel" in the menu. Then, a configuration file must be
-    provided. In order to do so, it is recommended to download the kernel
-    tarball, unpack it, run <make menuconfig> (or any other *config),
-    configure the kernel as per
-    the book, and save the resulting .config file to a location where it can
-    be retrieved later on (a convenient location and name is
-    $SRC_ARCHIVE/config-<arch>-<kernel version>-<config details>).
-
-       Another file you may provide is the fstab file. To use it, select
-    "Use a custom fstab file" in the menu interface, and enter the name of
-    the file where asked. As for the kernel configuration, this file has to
-    be prepared before running the menu. A convenient location and name is
-    $SRC_ARCHIVE/fstablfs.
-
-       At a more advanced level, you may want to supply custom commands
-    to be run at the end of (C)LFS build. Scripts containing those commands
-    are located in the ./custom/config directory. Examples are given in
-    ./custom/examples. A template is provided as ./custom/template. See
-    README.CUSTOM for more details.
+   4.1. CONFIGURATION OF THE TOOLS:
+         There is no configuration of the tools themselves. The various
+      parameters for the build are set through a menu driven interface. See
+      the section RUNNING below for details.
+
+   4.2. PRELIMINARY TASKS:
+         This tool has no support at all for creating a partition and a mount
+      point for the built system. You should follow the book up to the section
+      "Mounting the new partition". Note that the default name for the
+      partition mount point is "/mnt/build_dir", instead of /mnt/lfs.
+      You can change that default to anything you'd like in the menu, so you
+      may name it /mnt/lfs if you prefer . We'll use the name /mnt/build_dir
+      in the sequel.
+
+         For downloading packages, you can use the tool or download them
+      yourself. Even if using the tool, it is recommended to set up a source
+      repository where you store already downloaded packages. The tool will
+      automatically search a package in this repository before downloading it
+      if it is not found there. This repository cannot be the same as
+      /mnt/build_dir/sources. As an example, we'll use /usr/src. You should
+      arrange for the user running the tool to have write access to this
+      directory.
+
+         If you want to build the kernel as part of the automated build,
+      a configuration file must be provided. In order to do so, it is
+      recommended to download the kernel tarball, unpack it, run
+      <make menuconfig> (or any other *config), configure the kernel as per
+      the book, and save the resulting .config file to a location where it can
+      be retrieved later on. It is suggested to put it into the source
+      repository, with a versioned name, e.g.
+      /usr/src/config-<arch>-<kernel version>-<config details>.
+
+         Another file you may provide is the fstab file. As for the kernel
+      configuration, this file has to be prepared before running the menu.
+      You can copy-paste the file from the "Creating the /etc/fstab File"
+      page, then edit to suit the future lfs system layout, then save the
+      file. A convenient location and name is /usr/src/fstablfs.
+
+         At a more advanced level, you may want to supply custom commands
+      to be run at the end of LFS build. Scripts containing those commands
+      are located in the ./custom/config directory. Examples are given in
+      ./custom/examples. A template is provided as ./custom/template. See
+      README.CUSTOM for more details.
 
 5. RUNNING::
 
-  IMPORTANT::
-      You must be logged as a normal user with sudo privileges to run
+   IMPORTANT::
+         You must be logged as a normal user with sudo privileges to run
       the Makefile. Furthermore, you are supposed to have enough privilege
       to become any user. If you are not bothered about security issues,
-      the entry for the user "jhalfs_user" in /etc/sudoers could be
-      jhalfs_user ALL=(ALL) NOPASSWD:ALL
-
-     The command <make> will launch a menu based configuration program. The
-  underlying menu code was borrowed from BusyBox and slightly modified for
-  our use.
-
-     Help on parameter function is available from the on-line help. Please
-  make use of that feature: it may contain additional information not
-  duplicated in this file.
-
-     You should first choose which book and flavour you want to build. Note
-  that when you choose the BLFS book, the tool will just install the BLFS
-  tool to your system. You'll have to run that installed tool to build
-  packages in BLFS. See README.BLFS to know how. If you choose any other
-  book, you'll have to configure the settings and the build parameters
-  from the menu. Note that you may choose to install the blfs tools onto
-  the newly built system. It is not the same thing as choosing
-  the BLFS book in the menu, which will install the blfs tools on the
-  currently running system.
-
-     The "General Settings" menu is where the "Build Directory" name is to be
-  entered. Other entries in that menu select what the tool should do. The
-  "Run the Makefile" entry selects whether the tool will start the build
-  automatically after generating the needed files. The "Rebuild files" selects
-  whether to clean the build directory before doing anything else. To protect
-  against removing important files, this can only be done in an empty directory,
-  or a directory previously populated by the tool.
-
-     The "Build Settings" menu is where various options for the build can be
-  selected. Two options, "Use a custom fstab file" and "Build the kernel",
-  have been described above. "Do not use/display progress_bar", if set, will
-  prevent a progress bar to be displayed during the build. That may be useful
-  on slow machine. The other options should be self explanatory, using either
-  the online help or book reading.
-
-     The "Advanced Features" menu is for various maintenance tasks, like
-  testing the build instructions or reporting build statistics. One useful
-  option is "Optimization and parallelisation". It is not recommended to use
-  it for setting compiler optimization flags, although it is possible, but
-  if you select it, you'll be able to select the number of parallel `make'
-  jobs, which allows much faster builds on modern multicore CPUs.
+      the entry for the user running the tool in /etc/sudoers could be
+      <user> ALL=(ALL) NOPASSWD:ALL
+
+      The command <make> will launch a menu based configuration program,
+   similar to the kernel "menuconfig" configuration tool.
+
+      Help on parameter function is available from the on-line help (type the
+   character `?' after highlighting the parameter). Please do use the help:
+   it may contain additional information not duplicated in this file.
+
+   MENU "BOOK Settings"
+
+      Use BOOK: You have three choices: LFS System V, LFS systemd, BLFS.
+         The BLFS part is described in README.BLFS
+
+      Book version: You have two choices: "Branch" or "Working Copy"
+         Branch will have the tool clone the book's git repository. The
+      choice of the branch (actually any git commit) or of the file
+      location for the working copy is done in the next menu entry.
+
+      Multilib: Four choices: Normal LFS, Multilib with i686 libraries,
+      multilib with x32 libraries, multilib with all libraries.
+         It is recommended to use "Normal LFS" unless you know what you
+      are doing
+
+      Build method: two choices: chroot (as in book), boot
+         Presently, the "boot" method is not implemented, so keep the default.
+
+      Add blfs-tools support (see README.BLFS)
+         This will install the blfs tools onto the newly built system. It
+      is not the same thing as choosing the BLFS book in the menu, which
+      will install the blfs tools on the currently running system.
+
+      Add custom tools support (see README.CUSTOM)
+
+   MENU "General Settings"
+
+      Build Directory: the name of the root of the LFS system
+         This is the equivalent of the LFS variable in the book. Set it
+      to "/mnt/lfs" if you have followed the book for creating the LFS
+      partition and mount point.
+
+      Retrieve source files: Say y to have jhalfs download the packages
+         If you say no, you must download the packages yourself and put
+      them into the /mnt/build_dir/sources directory. Follow book's
+      chapter 3 instructions.
+         If you say yes, you'll be asked several other questions:
+         - Package Archive Directory: Repository of downloaded packages
+            This directory, which is on the host and should be writable
+         by the user running the tool, is for storing downloaded packages.
+            If you keep the default "$SRC_ARCHIVE", you can set this variable
+         to the absolute path of the repository and export it. Or if the
+         variable is not set, jhalfs downloads the sources directly to
+         /mnt/build_dir/sources.
+            Instead of using the SRC_ARCHIVE envar, you can also enter the
+         path of the repository directory into this field.
+         - Retry on 'connection refused' failure: self explanatory
+         - Number of retry attempts on download failures: self explanatory
+         - Download timeout (in seconds): self explanatory
+
+      Run the makefile: start the build immediately after running the tool
+         This is not the preferred method: it is recommended to rather
+      run "make -C /mnt/build_dir/jhalfs" after the tool has finished
+      setting up the build. But this may be handy if you are sure everything
+      is well, and want to leave the tool and the build run without
+      supervision.
+
+      Rebuild files: clean up the /mnt/build_dir directory
+         Say n if you want to rerun the tool (to update generated scripts
+      for example) without removing what has already been done. Otherwise,
+      say y. Note that there are some guards against removing a directory
+      containing useful things, but double check that the /mnt/build_dir
+      directory is really what you want to erase.
+
+   MENU "Build Settings"
+
+      MENU Parallelism settings
+       - Use all cores:
+            If you say y, MAKEFLAGS will be set to "-j$(nproc)" at the
+         beginning of each script. Other envars are supposed to be passed
+         from the environment, as done in new books. Note that for old books,
+         this means the scripts using make or ninja will be run with all
+         cores, but not when this needs to set special envars like
+         TESTSUITEFLAGS. You can still define the number of cores used
+         in next field.
+            If you say n, you'll be asked for a static number of threads
+         to use.
+       - set of cpus to use, or 'all' for all cpus (only if using all cores):
+            You can define here the cores you want to use. See help for
+         details. This is the preferred way of reducing the number of cores
+         rather than using a static thread number.
+       - Number of parallel `make' jobs (only if not using all cores):
+            Every occurrence of $(nproc) in new books will be replaced with
+         the number entered here. Also MAKEFLAGS will be set to "-jN" (where
+         N is the number entered) at the beginning of each scripts. Furthermore
+         NINJAJOBS will be set to N in the environment. This allows to run all
+         books with N threads, except for paarts that need other envars to be
+         set
+       - Build Binutils pass1 without parallelism (Real SBU)
+            The standard SBU is defined as the time to run the binutils-pass1
+         build with only one thread. Saying y here allows to get a value for
+         it. If you say n, the value is not meaningful for SBU measurements.
+
+      Run testsuites: say y to run the test suites
+         You'll have the choice between running all the test suites, or only
+      those deemed critical (binutils, gmp, mpfr, mpc, and gcc).
+
+      Package management: see README.PACKAGE_MANAGEMENT
+
+      Create a log of installed files for each package: self explanatory
+
+      Strip Installed Binaries/Libraries: use the book instructions for
+      stripping
+
+      DO NOT use/display progress_bar (self explanatory)
+
+   MENU System configuration
+
+      Use a custom fstab file:
+         If you say y, you'll have to provide a file containing the fstab
+      for the LFS system. See above "preliminary tasks".
+
+      Build the kernel:
+         If you say y, you'll be asked for a file containing the kernel
+      configuration. See above "preliminary tasks".
+
+      Install non-wide-character ncurses (rarely used nowadays):
+         If you say y, the system will use instructions in the note on the
+      ncurses page to install those libraries.
+
+      TimeZone: set to the result of "tzselect"
+
+      Language: set to the result of the instructions on "The Bash Shell
+      Startup Files" page.
+
+      Install the full set of locales: installs all the locales known to
+      glibc.
+
+      Groff page size: choice between "A4" and "Letter".
+
+      Hostname: self explanatory
+
+      Network configuration: various fields for setting network. Look at
+      chapter 9 for background.
+
+      Console configuration: various fields for setting console, as described
+      in chapter 9.
+
+   MENU Advanced features:
+
+      Optimization: Optimization settings are done by editing files in the
+      "optimize" directory. The menu just allows you to choose between applying
+      optimizations only to the final chapter or to all the book. Say n for
+      a normal build
+
+      Create SBU and disk usage report: self explanatory
+
+      Save temporary system work: self explanatory (see help)
+
+      Run comparison analysis on final stage: build the system several times
+      using the preceding one, to test whether it is able to rebuild itself
+      identically. Don't use normally...
+
+      Internal Settings (WARNING: for jhalfs developers only): says it all
 
      Once you have set the parameters and saved the configuration, the script
@@ -276,19 +394,4 @@
        machine.
 
-    Q. "What is the function of "User account" and "Group account" menu
-        settings?"
-    A. If you are running jhalfs from a low or non-privileged account you may
-       not have the priv to create/delete the user needed to build temporary
-       tools.
-       These settings allow you to use your own user and group name to do those
-       build steps.
-
-       These variables are adjustable also when invoking make:
-
-         cd $BUILDDIR; make LUSER=myaccount LGROUP=mygroup
-
-       The only changes to your account will be the creation of a NEW .bashrc
-       after saving your original to .bashrc.XXX
-
     Q. "How could I stop the build at a predefined chosen point?"
     A. Launch the Makefile manually passing the last numbered target to be build
