Merge trunk r3928, update README's

README

@@ -20,12 +20,10 @@ $Id$
 
   *.  It is recommended that you temporarily unpack your linux kernel,
   run <make menuconfig>, configure the kernel as per the book and save
-  the resulting .config file. This suggestion also applies to the
+  the resulting .config file.
-  configuration of the uClibc package when building a HLFS system using
-  uClibc rather than glibc.
 
-  *.  Read carefully this file and the other README.* files before start
+  *.  Read carefully this file and the other README.* files before beginning
-  using the tool.
+  to use this tool.
 
 2. PREREQUISITES::
 
@@ -34,7 +32,7 @@ $Id$
      - have experience building {c,h,b}LFS packages
      - know how to edit and write shell scripts
      - know how a Makefile works
-     - be able to trace build failures and to find what is causing it
+     - be able to trace build failures and to find what is causing them
        (user error, package bug, {c,h,b}LFS command bug, or jhalfs code bug)
 
      If you do not have the above skills, please don't use this tool.
@@ -42,12 +40,12 @@ $Id$
 
 3. INSTALLATION::
 
-     No installation is required. System-wide installation is not allowed.
+     No installation is required. You should just run <make> in this directory.
 
 4. CONFIGURATION::
 
-     We have installed the familiar menu based configuration tool driven by
+     Configuration is done through a menu based interface. See the section
-     GNU make. see the section RUNNING, for details
+     RUNNING, for details.
 
 5. RUNNING::
 
@@ -57,15 +55,34 @@ $Id$
      our use.
 
      Help on parameter function is available from the on-line help. Please
-     make use of that feature for additional information not in this file.
+     make use of that feature: it may contain additional information not
+     duplicated in this file.
 
-     Once you have set the parameters you wish and have saved your work the
+     You should first choose which book and flavour you want to build. Note
-     jhalfs script is launch. The script verify first that the host can run
+     that when you choose the BLFS book, the tool will just install the BLFS
-     it and build the xLFS system, then validate the configuration and present
+     tool to your system. You'll have to run that installed tool to build
-     you with your selections which you may accept or reject.
+     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 (see below). 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.
     
-     If you accepted the displayed settings jhalfs will proceed to create the
+
-     Makefile, optionally download packages.
+     Once you have set the parameters and saved the configuration, the script
+     is launched. Its aim is to extract instructions from the selected book
+     to generate scripts, and to generate a Makefile, which allows running
+     the scripts in the right order. The script verifies first that the host
+     can run it and build the xLFS system, then validates the configuration
+     and lists the parameters. At this point, you may choose to quit or to
+     continue with the listed parameters. The script will then proceed to
+     generate the Makefile and the build scripts, optionally download
+     packages, and eventually verify the host prerequisite. If you have
+     selected "Run the makefile", the command make is launched in the
+     adequate directory, and the build begins. If not, you'll have to run
+     "make" manually, for example: "make -C /mnt/build_dir/jhalfs", if you
+     have used the default parameters (see the layout under $BUILDDIR in the
+     Q&A below).
 
      IMPORTANT::
          You must be logged as a normal user with sudo privileges to run
@@ -80,17 +97,17 @@ $Id$
 
 6. BLFS_TOOL SUPPORT::
 
-     For books that support it (As of March 8, 2012, works only with LFS),
+     For books that support it (only LFS for jhalfs version 2.4),
      there is an option to install an automated framework for building BLFS
-     packages. it is called blfs-tool. When you tick `BOOK Settings/Add
+     packages. It is called blfs-tool. When you tick `BOOK Settings/Add
      blfs-tool support' in jhalfs configuration menu, the tools are
      installed in $BLFS_ROOT (default /blfs_root) on the xLFS system,
      and a few dependencies (which you may select) are built at the
      end of the jhalfs run, before the custom tools. The instructions for
      building the dependencies are taken from the BLFS book.
 
-     (TODO: blfs-tools have not been tested with current (version 3.0) CLFS,
+     (TODO: blfs-tools have not been tested with current (version 3.0) of CLFS,
-     and certianly need some adaptation to run)
+     and certainly need some adaptation to run)
      WARNING:: If you add blfs-tool support on a CLFS Sysroot build
                you MUST edit the scripts to fix the installation paths.
 
@@ -257,7 +274,7 @@ $Id$
        The only changes to your account will be the creation of a NEW .bashrc
        after saving your original to .bashrc.XXX
 
-    Q. "When I try to build CLFS the Makefile fails at the mid-point"
+    Q. "When I try to build CLFS the Makefile fails at mid-point"
     A. There could be numerous reasons for the failure but the most likely
        reason is you are doing a cross-build using the 'chroot' method and the
        target is not compatible with the host. If you choose to build using

README.BLFS

@@ -100,12 +100,13 @@ $Id$
 
     3.2.2 Install to an already running LFS/BLFS system
        If you forgot to install the tools when building xLFS, or want to try
-    the tools, you can just run the install-blfs-tools.sh script. It will
+    the tools, you can select the BLFS book from the jhalfs menu. It will
-    create the above hierarchy in your home directory and initialize the
+    run a script, which creates the above hierarchy in your home directory and
-    tracking file. You have first to make sure that the tracking dir exists
+    initialize the tracking file. You have first to make sure that the tracking
-    and is writable by the user. You may also populate it with (empty) files
+    dir exists and is writable by the user. You may also populate it with
-    whose names are of the form package-version, for installed packages, so
+    (empty) files whose names are of the form package-version, for installed
-    that they are included into the tracking file.
+    packages, so that they are included into the tracking file.
+
     3.3.3 Working files
         Several files are generated during the process:
 
@@ -161,8 +162,8 @@ $Id$
        When you are done with the menu, a few checks occur, and the dependency
     chain is generated. Each dependency appears with its priority (required,
     recommended, optional, or external), and it's level. There is a root level
-    0. The selected packages have level 1. The dependencies of selected packages
+    1. The selected packages have level 2. The dependencies of selected packages
-    have level 2, the dependencies of the dependencies have level 3, and so on.
+    have level 3, the dependencies of the dependencies have level 4, and so on.
     When circular dependencies are found, they appear with a priority of
     "circular". This means that two (or more) dependency chains arrive at the
     same package. The algorithm chooses the chain with the highest priority and

README.CUSTOM

@@ -5,21 +5,20 @@
 
 
   Normally JHALFS creates a Makefile containing only those scripts found in
-the {B,C,H}LFS books. An automated construction tool cannot predict the
+the {,B,C,H}LFS books. An automated construction tool cannot predict the
 needs of every individual and requests are made "Can you add xxxx package".
 Rather than adding numerous package scripts and switches for each request it
 was easier to add a tool for the user(s) to code their own package needs.
 
-  There is two areas that can be customized: how the base system is build
+  There are two areas that can be customized: how the base system is built
-and what additional configurations and packages requires your hardware to can
+and what additional configurations and packages your hardware requires to be
-boot and work with. Each one of this areas is handled in a different way.
+able to boot and run. Each of those areas are handled in a different way.
-
 
 
 
         BASE SYSTEM CUSTOMIZATION
 
-  There is two ways to alter how the base system will be built:
+  There are two ways to alter how the base system will be built:
 
   - Using a working copy of the book sources and editing the XML files.
     This is the way used by book editors to test packages upgrades,
@@ -28,22 +27,22 @@ boot and work with. Each one of this areas is handled in a different way.
     This method requires you know very well the book sources and what
     files need be edited. It will not be discussed here.
 
-  - Editing the generated build scripts to make any change you would.
+  - Editing the generated build scripts to make any change you want.
     This is the method discussed below.
 
 
   EDITING THE BASE SCRIPTS
 
-  First step is to generate the build scripts with book defaults. To do that,
+  To begin with, the build scripts should be generated with book defaults. To
-configure jhalfs activating any option you want included, but do not select
+do that, configure jhalfs activating any option you want included, but do not
-"Run the Makefile" option.
+select "Run the Makefile" option.
 
   Under the ${BUILD_DIR}/${SCRIPT_ROOT}/${PROGNAME}-commands directory
 (using the defaults values to do an LFS build, that directory name is
 /mnt/build_dir/jhalfs/lfs-commands) you will find the default build scripts.
 
   If all you want is modify, add, or remove some command from a package
-installation, for example to change it ./configure line, just edit the related
+installation, for example to change its ./configure line, just edit the related
 script. If changing or adding a patch, be sure to copy the new patch to the
 ${BUILD_DIR}/sources directory. When done, run 'make' from inside the
 ${BUILD_DIR}/${SCRIPT_ROOT} directory.
@@ -53,39 +52,38 @@ ${BUILD_DIR}/${SCRIPT_ROOT} directory.
 
   To remove a package from the system, just remove its script(s).
 
-  To change the version of some package to build a newest or oldest one than the
+  To change the version of some package, or to build a newer or older version
-one found in the book, edit ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list to
+than that in the book, edit ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list to
-change it tarball name and place the new tarball in the ${BUILD_DIR}/sources
+change its tarball name and place the new tarball in the ${BUILD_DIR}/sources
-directory,
+directory.
 
   To replace a package by an equivalent one, rename the replaced package script
 to reflect the new package name (for example, 102-man-db -> 102-man), edit the
 script to made the required commands changes, place the new tarball in the
 ${BUILD_DIR}/sources directory, and edit ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list
-file to replace the removed package tarball name by the new package tarball name.
+file to replace the removed package tarball name by the new package tarball
+name.
 
   To change the build order, rename the scripts changing the first 3-digits
-string until have it ordered in the way you want.
+string until they are sorted in the way you want.
 
-  To insert a new package, for example to build Cracklib to can build Shadow
+  To insert a new package, for example to build Cracklib in order to build
-with Cracklib support, first you should decide before what default package it
+Shadow with Cracklib support, you should first decide before what package it
-need be installed, in this example before 107-shadow. Then create a new script
+needs to be installed, in this example 107-shadow. Then create a new script
-containing the needed commands, using an existing one as template, and name it with
+containing the needed commands, using an existing one as template, and name it
-the same 3-digits string used for that mentioned default package, but adding
+with the same 3-digits string used for that mentioned default package, but
-another 1-digit string. In our example, the new script to build Cracklib just
+adding another 1-digit string. In our example, the new script to build Cracklib
-before Shadow will be named 107-1-cracklib. This naming schema allow to insert
+before Shadow will be named 107-1-cracklib. This naming scheme allows inserting
-up to 10 scripts before each one of the default scripts. Place the tarball for
+up to 10 scripts before each of the existing scripts. Place the tarball for
-the new package and required patches, if any, if ${BUILD_DIR}/sources and edit
+the new package and required patches, if any, in ${BUILD_DIR}/sources and edit
 ${BUILD_DIR}/${SCRIPT_ROOT}/pkg_tarball_list to add the tarball name for that
 package.
 
-  When ready, launch again the jhalfs configuration interface. Be sure that
+  When ready, launch again the jhalfs configuration interface. Make sure that
-are selected exactly the same options than when generating the default build
+exactly the same options are selected as when generating the default build
-scripts. Be sure that "Rebuild files" is unselected and select "Run the Makefile"
+scripts. Be sure that "Rebuild files" is unselected and select "Run the
-if you want. Then select "Rebuild the Makefile". This will create a new Makefile
+Makefile" if you want. Then select "Rebuild the Makefile". This will create a
-based on the changes you made to the build scripts.
+new Makefile based on the changes you made to the build scripts.
-
-
 
 
        ADDING POST-SYSTEM BUILD CONFIGURATION FILES AND EXTRA PACKAGES
@@ -96,8 +94,8 @@ more info.
 
   The feature described below was added so users could install remaining
 configuration files, build the packages necessary to access the Internet
-or to support specific hardware, or to install basic utilities that need
+or to support specific hardware, or to install basic utilities that are
-have available from the beginning, and was not intended to replace the BLFS
+needed from the beginning, and was not intended to replace the BLFS
 install system.
 
   :::NOTICE:::
@@ -108,9 +106,9 @@ add should honour the DESTDIR=${CLFS} switch or equivalent.
 
 
   LAYOUT
-  A new directory has been added to JHALFS tree which will contain the
+  A new directory has been added to JHALFS tree which contains the
 configuration scripts and a few examples. A switch has been added to the
-configuration file which enables/disables the inclusion of personal scripts.
+configuration file which enables/disables the inclusion of custom scripts.
 
     custom
       /config          <-- where to put your scripts.
@@ -121,7 +119,7 @@ configuration file which enables/disables the inclusion of personal scripts.
 
 
   NOTE::: You are responsible for including all dependencies and ensuring they
-          are built in the proper order.
+          are built in the right order.
 
   1. To add a package to the final JHALFS Makefile you must first create a file
      in the custom/config directory.

README.HLFS

@@ -2,10 +2,5 @@ $Id$
 
 
 		::::NOTICE::::
-
+HLFS has not be updated for a very long time. Since then, jhalfs has evolved
- Hardened Linux From Scratch is a highly volatile project. Extreme design
+and is now incompatible with HLFS.
- changes can occur and the build could be broken for extended periods of
- time.
-
- As of July 26.2007, the Glibc-based systems builds should work.
- uClibc-based system still fail due book issues.

README.PACKAGE_MANAGEMENT

@@ -16,13 +16,21 @@ BY    : Pierre Labastie (work in progress)
 
 2. OVERVIEW OF THE SYSTEM:
 
-      For now, package management is only available for LFS. I plan to
+      Presently, package management is only available for LFS. I plan to
   upgrade BLFS tools, but nothing usable right now. I have not attempted
   to adapt this tool for the other flavours of LFS.
+
+      To use package management, you need to create the required files in
+  the pkgmngt directory (see below), and to select "package management" in
+  the build settings. Note that this is incompatible with creating an SBU
+  and usage report.
+
+3. DETAILS OF OPERATION:
+
       This system performs basically a "DESTDIR install" for all pages
   in chapter 6, 7 and 8 of the book. The name of the DESTDIR directory is the
   same as the one of the executed script. The path to this directory is
-  available to the scriplets through the PKG_DEST variable.
+  made available to the scriplets through the PKG_DEST variable.
       The XSL stylesheet used for generating the scriptlets, automatically
   adds DESTDIR install instructions when "package management" is selected.
   Also all the paths beginning with " /" or ">/" (absolute paths) are prepended