On Wed, Feb 03, 2010 at 03:54:25PM -0800, Stephen Hahn wrote:
>
> I've spent a bit of time cleaning up some of the manual page bugs
> we've accumulated in the past dev phase. Please have a look at
>
> http://cr.opensolaris.org/~sch/pkg-man/
>
pkg.1.txt:
- line 202: (nit) can we change the 'which' to 'that'
- lines 772-773: If we want a less conversational style, this could be
broken into two sentences:
A pkg(5) image can be located arbitrarily within a larger file
system. Use the token $IMAGE_ROOT to distinguish relative paths.
pkg.5.txt:
- line 149 - 153: This seems a bit confusing as written. A possible
correction:
If a package operation triggers a directory removal, the client can
take two possible actions. It will either preserve the directory,
or move its contents into $IMAGE_META/lost+found. See FILES for
more information about $IMAGE_META. Directory removal typically
occurs during an uninstall operation, but it may also occur during
an update from one version to another.
- line 225 - 227: The parenthetical 'in addition' throws me off when
reading this. Would it be correct to state this as the following?
If the value is 'incorporate', then the dependency is optional, but
the version of the dependent package will become constrained.
pkg.depotd.1m.txt:
- We may want to point users to --add-content in the --rebuild entry,
since that's the non-destructive way to update the repository.
pkgdepend.1.txt:
- The DESCRIPTION is confusing to read. A possible re-write:
The pkgdepend command is used to generate and resolve dependencies
for packages. A package may depend upon files from other packages.
The generate function examines a package's content and discovers
what external files the package needs. The resolve function takes
the list of files from the generate step, and figures out the name
of the packages that contain the dependent files. The reference set
of packages is defined as the packages currently installed on the
publisher's system.
- SUBCOMMANDS
The subcommands should have their options broken out like the
options in the other files. Currently, the options are contained in
sentences, which is different from our other style.
If you re-write the options to use the present tense and active
voice, they will be easier to understand. There is some pronoun
confusion in a few of these descriptions, too.
pkgdiff.1.txt:
- line 28: Can you put spaces around the "--" marks in this text? I
didn't realize I was reading punctuation and had to re-read this
sentence for it to make sense.
-j
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
