Comments on pages 29 - 42.
Josh Simons
Page 29
"New images are created to mark a boundary between the packages
installed in
different images." Sounds like a circular definition.
This paragraph: "After you have completed the installation of the
OPenSolaris 2009.06..."
is unclear. What seems to be missing is a statement that software
management tasks may
only be performed on images. Perhaps this would be clearer:
Software management tasks are performed are performed on images.
Since a complete
OpenSolaris 2009.06 installation creates a full image, it not
necessary in the usual case
to explicitly create an image to perform software management tasks.
However, if one
wants to provide logical separation beween different software
applications as during
zone creation process, an image must be explicitly created.
Page 30
Figure 4-1 might be clearer if you labeled the images as full or
partial.
The switches to image-create aren't shown correctly. It should be
either:
image-create [-R] [-FfPUz] ... (dashes on the inside of the
brackets)
or
image-create [-FfPRUz] ... (not sure why -R was called out
separately?)
Page 31
Example 4-1
Suggest changing last sentence to: "The -p option is used to specify
the
location of the package repository." (You mention earlier that
http://pkg.example.com
is the repository in this example.)
Put a backslash continuation character after -p to should this is one
command line?
Displaying image properties. "pkg property" shows properties...but for
which image since
none is specified? Is it really the case that this command does not
take an image/directory
as an argument? [I see on page 34 that this is explained...it would be
clearer to introduce
the idea of a current image before describing these commands.]
Example 4-2
Output of command says "lush-content-cache-on-success" .... the
leading "f" has been omitted.
Page 32
set-property applies to which image? (none specified)
Example 4-3
"pkg property" command should be preceded by "$ " prompt as in
other
examples.
Same comment for the "pkg -R set-property" and "pkg property"
commands that
follow.
Page 33
This discussion includes the concept of "a current image". How is
that defined?
Example 4-5
typo: pfexeec --> pfexec
(also , that line is duplicated...remove one?)
This seems to equate the concept of a clone with an image which is
confusing. (An
image-update results in a clone being updated.) [This is partially
explained on page
35...would be better if explained earlier.]
Page 39
In the Note remove "section." after "page 41"
Define "key attribute".
Last paragraph says the table shows type of actions and their
"standard attributes"? What is a standard attribute?
Page 40
In the table, the link and hardlink descriptions are written more
clearly than the
directory and file entries. How about:
The directory action represents a file system directory.
path -- the file system path where the directory is installed.
The file action represents an ordinary file.
Typo in "Driver" section: TThe --> The
"Driver"...Capitalize "The driver files must be installed..."
"Driver" payload reference is obscure. How about just:
"The driver action represents a device driver. Note that the driver
files must be
installed separately using File actions."
[This seems error-prone, especially if the argument to this action is
"usually the file
name of the driver binary." In such cases, might we expect people
will forget to
specify the appropriate File action with the same argument? Is this
an error case
we catch and flag?]
"Depend" -- with no key attribute, how is the dependency to another
package expressed?
Same question for Set, Group, and User. There is no required
attribute (which is how I
interpret "key attribute"?) [If the table really is meant to show
"standard attributes" as
described on Page 39, I would expect some argument to be described
for these actions.]
Page 42
"ISA" --- we support SPARC as well, not just x86 platforms.
Define "ARC case" for non-Sun readers?
Human-readable written twice here with em dashes.
Same comment on ISA in its second mention on this page. (Why is it
mentioned a
2nd time and included in an opensolaris attribute table when it isn't
an opensolaris
attribute (i.e. not prefixed by opensolaris)?)
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
