Chris Gianelloni <wolf31o2@g.o> posted
1180737662.17690.94.camel@..., excerpted below, on Fri, 01
Jun 2007 15:41:02 -0700:
> Why not just rename the "2007.0 Handbook" into the "2007.0 Networkless
> Installation Guide" or something similar? After all, the versioned
> Handbooks are only good for the release they correspond to and it won't
> mean going back to having a single and confusing Handbook. All that is
> really needed is a link to the networkless guide for people to follow if
> they're planning on a networkless install, assuming it isn't there
> already.
Renaming, so there's just one "Handbook", would indeed help.
What I'm left wondering, however, is why this:
http://www.gentoo.org/doc/en/handbook/2007.0/index.xml
(which /does/ say it's networkless only) then includes the non-
installation parts of the handbook, Working with Gentoo, Working with
Portage, and Gentoo Network Configuration (on what's supposed to be for
networkless?)?
If it's not intended to be the whole handbook, only the networkless
installation guide, why does it /look/ like the whole handbook?
A second question is one raised in the DRobbins review, but now relating
to documentation. I still don't know which "handbook" he was following,
but the installer CD he was using didn't have stages or sources. The
"Networkless"/dated "handbook" talks about prebuilt packages on the CD,
while the general handbook says two different things in different
places. In chapter 2, it explains that the minimal CD simply boots the
system and prepares the network, where everything else comes from "live",
while the Installer LiveCD contains everything needed to install Gentoo,
networkless if needed/desired. However, it then states that stage
tarballs need to downloaded separately (how, if it's networkless), which
would seem to make a lie of the "everything needed" claim. If everything
needed is included, a separate stage-X download is by definition NOT
required, as it's "included" as part of "everything". Chapter Five
mentions a THIRD kind of CD, the "Universal" CD (Um... why wasn't this
third choice mentioned earlier, in the section where people were actually
supposed to be choosing install media?), which is said to include the
stage tarballs, and thus would truly include "everything needed". Again
it says the other CDs, Minimal and LiveCD, don't include the necessary
tarballs. Again, how can the claim of "everything needed" /possibly/ be
true, if the needed tarballs aren't included?
So which is it? Does the LiveCD include "everything needed" as claimed,
or does it require a NOT included stage tarball, as claimed elsewhere?
What it looks like to me is that the LiveCD installer is new and now
emphasized on the media choices page of the main handbook, and in the
networkless install (2007.0) "handbook", and the universal CD was
possibly dropped, but general handbook chapter 5 wasn't updated to
reflect the new situation. Even when updated, however, there's still the
issue of saying "everything needed" is included on the installer CD, when
it apparently isn't, since according to both the main handbook and the
DRobbins review, the stage tarball must be downloaded separately. (His
comment was that a fully functional GNOME including Evolution was on the
CD, but not the stage tarball, which he thought would be a more sensible
use of the space required for the GNOME install. Perhaps an X installer,
but something lighter than GNOME, so the stage tarball could be
included. The point I'm making, however, is that if an additional stage
tarball is required, don't say "everything needed" is included, quite
separate from whether the full GNOME environment including Evolution is a
wise use of the space.)
So anyway, yes, renaming the networkless install to something other than
"Handbook is certainly one good step, IMO, so there's only one
"Handbook", but it's only one step. Maybe kill the additional parts
(Working with portage and etc) from what is now the Networkless Install
guide, so that's /all/ it is, would seem wise to me also (tho there are
arguments that could be made to keep them). The above confusion over
media and "everything needed" must be addressed too.
That would (IMO) straighten out the immediate confusion. Beyond that,
doing the single landing point for all things install documentation
related I think is also a good thing, but not as vital, so even if
undertaken, could be a longer term project.
--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman
--
gentoo-doc@g.o mailing list
|
