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

[Jyothi Srinath]

On 04/12/09 10:40, Shawn Walker wrote:
> [I'm not the doc writer, just a developer.]
>
> Josh Simons wrote:
>> Comments on the first 28 pages.
> ...
>> Page 17
>>
>> "...then it is searched for in the other configured publishers"
>>     --> "..then it is searched for in the other configured repositories"
>
> Actually, that should be:
>
> ...then the catalogs of the remaining publishers will be searched.
>
> The repositories are not searched for packages; the publisher catalogs 
> are.
>
>> Page 20
>>
>>     How does "server" relate to the concepts of "publisher" or 
>> "repository?
>
> server represents an origin_uri of a repository.
>
>>     Example 3-6. What exactly is searched? In the returned results 
>> 'book' is part
>>     of a directory name, not a 'description'...
>
> What *exactly* is searched is beyond the scope of the documentation. 
> However, in general terms, the complete metadata of the package is 
> searched (this means attribute values, pathnames, filenames, 
> descriptions, etc.).  The specifics should not be explained here as 
> they are subject to change and very based on the package metadata.
>
> However, the package search output does indicate where matching 
> entries were found.  Note that in the search results for Example 3-6, 
> you see 'basename dir' and 'description set'.  So, matching entries 
> were found when searching the pathnames of directories for packages 
> and the description of a package.
>
>>     Example 3-7. Another mention of 'server' here.
>
> That should probably be 'from the image's publisher repositories.'
>
>>     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.
>
> It means "all known", but your wording is essentially correct.
>
>> 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?
>
> Technically, a publisher name is a forward or reverse domain name, but 
> they are not required to be so.  Instead, think of a publisher name as 
> just an identifier for "a person, group of persons, or a corporation 
> that publishes a package" as noted on page 15.
>
> The URL does not have to include the publisher name, the publisher 
> name could be extra.opensolaris.org while the url could be xkcd.net/325.
>
> Eventually, the user won't have any control over publisher names so 
> these examples will change drastically and the user will only be 
> specifying URIs.
>
>> 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?
>
> Actually, the sample output of pkg publisher on page 25 for examples 
> 3-14 and 3-15 is no longer correct, it should be this (without the 
> wrapping of course):
>
> pkg publisher
> PUBLISHER                             TYPE     STATUS   URI
> opensolaris.org          (preferred)  origin   online 
> http://pkg.opensolaris.org/release/
>
>>     How to Display Publishers: Says that publishers have associated 
>> URLs.
>>     Should this be associated repositories? (which may be represented as
>>     URLs?)
>
> Actually: associated repositories and their associated origins and 
> mirrors (which are represented by URIs).
>
> Cheers,
Thanks, Josh, for your feedback and edits.
And Shawn, for the  clarifications.
I will update the doc with these edits and others that I have received 
in the next few days.

Thanks,
Jyothi