Various docs

James Robertson jwrober at linuxfromscratch.org
Wed Sep 24 08:13:06 PDT 2003


Neven Has wrote:
> On Tue, Sep 23, 2003 at 10:30:23AM -0500, James Robertson wrote:
> 
>>>>Any chance of moving that syntax_doc/ directory to ALFS/docs/,
>>>>directly in CVS?
>>>>
>>>I agree, the syntax docs (and the DTD) shouldn't be considered 
>>>nALFS-specific.
>>>
>>That will make writing a user's guide harder.  I was trying/wanting to 
>>write a nALFS specific user's guide including the syntax portion of the 
>>syntax doc.  I was going to merge the two into one, but I can keep them 
>>seperate and just reference the dtd xml pages with entities and relative 
>>paths if I need to.  This would also replace README since a lot will be 
>>duplicated in the user's guide.
> 
> I fail to see what does the nALFS user's guide has to do with the
> profile syntax and its documentation?  I don't think they have to be
> related at all.  Unless I'm misunderstanding your definition of "user
> guide".  (To me, it's similar to "Running and usage" from README, only
> much better, of course.)

I was thinking of an "all-in-one" book that described in more detail the 
use of nALFS to a user like:

      * Detailed explanation of the .nALFSrc file.
      * Detailed explanation of all the keyboard commands, maybe a 
"quick-sheet" page that would be on one page by itself to be printed out.
      * Detailed explanation of the DTD (including all the syntax)
      * Detailed explanation of how to write a profile using known best 
practices like xincludes, entities and such.  How to use xmllint to test 
your profile before going into nALFS with it.

Essentially it would take a lot of the README file and expand on it with 
more detail and also include the syntax doc in it for reference.

If you wanted to keep them seperate, that is fine too.  We can include 
both "books" rendered in the source tarball and the user's guide would 
just refernece the syntax doc.

>>If this is not something we want/need then I'll just move the files
>>and be done with it.
> 
> IMO, we should have a document describing the ALFS syntax in
> ALFS/docs, independent of anything else.

Ok, that goes along with my last paragraph above.

> And a user guide for nALFS would belong to ALFS/nALFS/doc of course.

Right.  We are on the same page here.

>>I also mentioned writing a developers/hackers guide in the same
>>lines as the editors guides that the books have.  Is this something
>>we want/need and if so, where do we want that source kept?
> 
> Sure, why not, as long as I'm not writing it. ;)

LOL.

> Although I think it would be much more useful with information about
> nALFS structure, inner workings and such, but that's a lot more work.
> But if someone is prepared to write about that too, I'm willing to
> help.
> 
> Neven

That would be a good idea too in time.  I was just wanting to start with 
the basics - CVS access and use, Bugzilla access and use, source tarball 
creation steps, and coding style.  I can write a lot, but not all. Since 
I am not a hacker I am probably not the one to write the pieces you 
mentioned above.

All I know is that good tools and applications come with good 
documentation.  That is one of the signatures of a mature and stable 
product.  I want nALFS to be successfull (especially since I use it for 
all sorts of stuff) in the eyes of the Linux community including LFS and 
the LSB.

Let me know what you think and I'll see what I can start piecing together.

BTW - do we need to update the syntax doc for 1.1.8?  Did you guys 
change how the profiles work?  Just wanted to make sure we had 
everything square in the tarball.

James
-- 
James Robertson -- jwrober at linuxfromscratch dot org
Reg. Linux User -- #160424 -- http://counter.li.org
Reg. LFS User   -- #6981   -- http://www.linuxfromscratch.org
LFS Bugzilla Maintainer    -- http://{blfs-}bugs.linuxfromscratch.org




More information about the alfs-discuss mailing list