Re: Documentation Suggestions

On Sat, 2023-08-26 at 13:41 +0000, super1337 wrote:
> 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."

It's not really "intended" as a tool for developers. But it's mainly
used by devs, who don't care much about rough spots...

> 
> 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.
> 

This is clearly stated in the README, I think. "Knowing what they are
doing" does not mean "only for devs". Maybe we could add that a
reasonable amount of "git" knowledge may help, or so.

> 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..."
> 

Thanks for the suggestions. I'll make a ticket because I don't have
much time to look at it now, and I am at risk to forget, but I'll try
to improve this a bit after the release (lfs 12.0 coming soon).

Pierre

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