[indiana-discuss] [pkg-discuss] OpenSolaris 2009.06 IPS Documentation posted for review

[Josh Simons]

Comments on the first 28 pages.

Page 8

	2009.06 is described as offering complete support for developing
	web applications -- one type of application among many. Why exclude  
others?
	
Page 15

"package will be searched in the preferred publisher's repository  
catalog first"
	--> "package will be searched for in the preferred publisher's  
repository catalog first"

(This is also a forward reference to the term "repository catalog.")

Page 17

"...then it is searched for in the other configured publishers"
	--> "..then it is searched for in the other configured repositories"

Page 18

Dry-Run section

	Dry-run various spelled with a regular dash, an em-dash and no dash.

Page 19

	Remove italics on 'amp' in first pfexec command. (why is this line  
repeated?)

	This section would benefit from a brief explanation of the output  
from the -nv
	command or a pointer to where that information can be found.

Page 20

	How does "server" relate to the concepts of "publisher" or "repository?

	Example 3-4. Does the '-l' mean 'local'? Would be clearer to mention  
this as
	is done in Example 3-5 with '-r'.

	Example 3-5. pkg example shown does not use '-r' switch

	Example 3-6. What exactly is searched? In the returned results 'book'  
is part
	of a directory name, not a 'description'...

	Example 3-7. Another mention of 'server' here.

Page 23

	Section on displaying state and version incorrectly says "Use the  
following
	command to uninstall existing packages" when introducing 'pkg list'.

	Example 3-10. Does '-a' mean 'even if not installed'?  if so, not  
consistent with
	pkg info's use of -r. if not, a description of -a would be useful.

Page 24

	I find this concept of publisher to be very confusing. On page 15,  
the example
	FMRI describes 'opensolaris.org' as the publisher, but in the  
examples here
	publisher is not a host-like string. I see from the 2nd example that  
the
	publisher name can look host-like (opensolaris.org and sunfreeware.com)
	and in both cases the associated URL includes the publisher name. Is
	that required?

	In addition, the concept of 'origin' is introduced here (origin_url  
and origin as
	a TYPE) but not defined.

	It would be very helpful if this could all be described more clearly.

	The How to Remove a Publisher Config increases the confusion by
	stating that the argument to -O is a 'repository' rather than an  
'origin_url.'

Page 25

	It also does not help that the output of the 'pkg publisher' command  
labels
	(for example) http://pkg.opensolaris.org/release as a URL. It is a  
repository,
	yes? Or is it an origin-url? Or are they the same?

	How to Display Publishers: Says that publishers have associated URLs.
	Should this be associated repositories? (which may be represented as
	URLs?)