The documentation for Catalyst 2 has some mistakes on its web page. http://www.gentoo.org/proj/en/releng/catalyst/2.x/reference.xml In Section 7, entitled "Livecd-stage2 Target Reference", there is a cut-and-paste error. It appears that Catalyst1 documentation was cut and pasted into the Catalyst2 documentation, without accounting for the fact that some of the variables from Cat 1 are not existent in Cat 2. Specifically, the variable "livecd/archscript" is listed as being "required", though it is only required in Catalyst 1 and is non-existent in Catalyst 2.
"Currently the 2.x version is under construction, so it is only partitally correct. Please do not use it until this note is no longer here." http://www.gentoo.org/proj/en/releng/catalyst The document is not only wrong, it is completely unmaintained at this time. It isn't a copy and paste it is a direct copy, so I had a decent framework to begin from when I *started* to document catalyst 2.0 in the upcoming weeks.
I'm not exactly sure that I understand why this submission was "revolved invalid." In the gentoo-catalyst mailing list (just prior to my posting of this bug), you specifically asked for feedback on how the documentation could be improved because users were complaining that the documentation was not adequate. Well, you asked for suggestions, so I've provided one. And you've disqualified my response to your call for feedback by saying this: > "Currently the 2.x version is under construction, > so it is only partitally correct. Please do not > use it until this note is no longer here. > >The document is not only wrong, it is completely > unmaintained at this time." Your request for information on the mailing list was more recent than the post on the above captioned hyperlink, so I mistakenly interpreted your most recent request for reports on the documentation to actually represent sincere interest in receiving reports on the documentation. So I'm a bit confused. If I find more errors in the documentation, should I file reports on them in an effort to help you to improve the documentation, or should I just not report them because you're really disinterested? The "resolved invalid" disposition and the comment not to use the documentation are in direct contradiction to what you've posted on the mailing list. Now I'm left with the impression that you really don't want feedback, which suggests that you were just making the call for documentation suggestions on the mailing list in an effort to squelch someone who was complaining about the documentation. I can't see how its possible to have it both ways, so if you can clarify this information for me I'll know whether or not you really want more feedback on the documentation or not. If you want it, I'm happy to help, but if you don't want it then its pointless for me to waste both of our time.
*sigh* Every piece of documentation available, including the output from the ebuild and the main catalyst page tell you that the *only* good documentation is that provided in the tarball itself, namely the example spec files. Any other documentation is crap, currently, and I am well aware of it. The only updated documentation is the example spec files that are installed with catalyst. Catalyst tells you as much when you emerge it, and so does http://www.gentoo.org/proj/en/releng/catalyst immediately after the quote I pasted here. I'm just going to edit the page to make it more prominent that the web-based documentation is useless. Do I want help with the documentation where it fails? Sure. However, I only want it for the documentation within the tarball, as I will be using that to update and revise the online documentation once 2.0 goes final and is no longer a release candidate.
Allow me to apologize if that last response sounded a bit frustrated. It's just I don't know of any other way to make it clear that the online documentation isn't worth reading. I've gone as far now as to ensure that the warnings are much more prominent, and marked the 2.x reference guide as obsolete, so hopefully it will cause less confusion. I really do appreciate your assistance and can understand how there is confusion.
