Documentation Suggestions

I truly don't want to be bothersome, please feel free to tell me to hush 
at any time.  I'd like to retain my welcome for when I do have questions 
or problems I can't solve on my own.

I was totally unaware that jhalfs is intended primarily as a tool for 
the developers.  Such information isn't stated on the ALFS Home at 
https://www.linuxfromscratch.org/alfs/ nor is it in the README. I feel 
like it would be a helpful thing to have a clear expectation from the 
very first sentence for the user. Reading the heading What is Automated 
Linux From Scratch? and then the first sentence explicitly state 
something to the effect of:

"Although the current ALFS is intended primarily as a developers tool, 
it's also available for all to help automate the process of building 
their LFS system.

Automated Linux From Scratch (ALFS) is a project that allows building 
the LFS system automatically. It also allows building packages from the 
BLFS book, but that needs some manual intervention."

Now, I have an immediate understanding that what I'm looking at isn't 
really intended for me, it's intended for people that actually know what 
they are doing.

Moving along to the jhalfs make menu. Without trying to reinvent the 
wheel, something like the below would be helpful with clarifying 
documentation.

----------
(Top)-> Book Settings -> Use BOOK
----------
Use BOOK ---> This would be clearer to the layperson if it read
"Use book init style or BLFS" or something similar.
Book Version ---> This can also be reworded to add clarity
"Source of Book" would probably suit well.

----------
(Top)-> Book Settings -> Use BOOK
----------
Prompt: Use BOOK
This one is clear enough
#
----------
(Top -> BOOK Settings -> Book version)
----------
Prompt: Book version
Choice symbols:
   - BRANCH (I feel like this woule be more clearly labeled as "GIT 
clone")
   - WORKING_COPY (I feel like this would be more clearly labeled as 
"LOCAL_COPY")
I'll decend into here now...
( ) Branch (default to trunk) or any commit
The help currently reads: "Use an LFS book downloaded from the git 
repository, and
checked out at any commit (branch/tag/sha)"

I think it would be more clear to add some additional verbiage here, 
something to the nature of:
"Use an LFS book that will be downloaded from the git repository at 
{$URL}"
Perhaps even entirely omit the "and checked out at any commit 
(branch/tag/sha)" from this section as it currently is.
#
----------
(Top -> BOOK Settings)
----------
Name: COMMIT
Prompt: Branch, tag, or any commit

I'm not familiar with GIT.  However, I've come to the conclusion now 
that TRUNK means "current", at least in this context.  If that's a 
correct conclusion, can a line in this help section be added stating so? 
  Let's assume that for whatever reason, I want to build lfs11 rather 
than lfs12. Is that possible to do here, or do I need a local working 
copy of the xml to do that?  Perhaps a statement of "Most people will 
want to use trunk for the current version."  Any rewording here to 
direct the lay user to leave it as trunk for current, while still the 
wording of using a tag or sha to direct people more advanced than 
myself.
#
----------
(Top -> BOOK Settings)
----------
Name: BOOK
Prompt: Loc of working copy (mandatory)

I have now learned from your replies that a person acquires the XML 
using git. Can something be added here to help direct others?

Something to the nature of:
"XML sources are pulled using git by issuing $ git clone .... at the 
command line
"Older versions are able to be pulled by ...
"NOTE: Downloading the book from LFS is not the same as acquiring the 
XML from..."

-- 
http://lists.linuxfromscratch.org/sympa/info/alfs-discuss
Unsubscribe: See the above information page