On Fri, May 31, 2002 at 10:35:32PM -0400, rpjday wrote:
>
> [possible submission to bugzilla. comments?]
>
Sure, thanks for asking.
> p. 18: bullet point: "Items must be specified *in order*."
> This is misleading since, according to the next few bullet
> points, it's just the *sections* that have to be in the
> right order -- nothing said about the order of items within
> those sections.
I would make a slightly more general point: the description of the
configuration file syntax should use more consistent terminology. The
document refers to "items", "arguments", "options", "commands",
"keywords", and "sections"; sometimes these refer to the same things,
sometimes not. What rpjday mentions above is only one case where this
can be confusing. I'm not asking for strict formalism, but terms should
be used to refer unambiguously to single syntactical elements.
[I would suggest *not* using "option" to refer to the lines in the command
section, because talking about "required options" is kind of grating.]
As has been pointed out, the meaning of "required" in the doc is extremely
unclear. For example, if you're doing an upgrade, most "required" items
apparently aren't required.
Some argument descriptions don't describe their syntax. For example
"--fstype": should it be "--fstype=ext3" or "--fstype ext3"?
[And why does the config file use these two different syntaxes anyway?
But that's not a documentation issue.]
Sometimes when a command has no arguments, it's explicitly stated:
"(no arguments)". Sometimes not.
The section called "Creating the Kickstart File" says
"LILO Configuration" is required in an upgrade kickstart file,
but this should probably refer to "bootloader" instead.
Missing altogether is the description of how to avoid the installation
of a package in the %package section, e.g.
@ GNOME
-gnome-games
[I found the above trick in the archives of this list, while I was
looking for something else. Is it documented *anywhere*?]
I ranted on the Kickstart doc in Bugzilla #40550
about a year ago and--thanks, Red Hat--the doc is much improved
since then. But it's still not as good as it could be.
--
-- Paul A. Sand | If Barbie is so popular, why
-- University of New Hampshire | do you have to buy her friends?
-- pas@xxxxxxx | (Jerry, via the Internet)
-- http://pubpages.unh.edu/~pas |
