Jack, I've made these edits in my master copies. Please see my added comments below. There's a few responses worth noting.
Thank for the quick review!! Barbara On 11/10/08 12:18, Barbara.Lundquist at Sun.COM wrote: > > > -------- Original Message -------- > Subject: Re: [caiman-discuss] REVIEW AI/DC documentation final review > Date: Mon, 10 Nov 2008 11:57:54 -0800 > From: Jack Schwartz <Jack.A.Schwartz at Sun.COM> > To: Barbara.Lundquist at Sun.COM > CC: caiman-discuss <caiman-discuss at opensolaris.org> > References: <49179982.3050102 at Sun.COM> > > > > Hi Barbara. > > Thanks for your work. Here is my lot of comments on the DC guide. > Manpage to follow: > > Page 5: > > Instead of saying "And, you can revise..." it sounds more concise to me > to say "You can also revise..." > done > Rather than say "Set up the system requirements" I would say "Set up the > system to meet the prerequisite requirements" or something like that. > > done > Page 6: > > For the note in the middle of the page, I would say: > > "While custom scripts will be needed to create your own custom image, > support for scripts is limited to unmodified scripts supplied with the > application packages. If you choose to customize supplied scripts, > backup the original scripts first." > > done > Page 8: > > Second PP, under network access in table 1-1: "the" is missing before > "distribution constructor". > done > Bottom note: "The distribution constructor and finalizer scripts require > files provided by the SUNWinstall package, including > /usr/bin/ManifestRead and files in > /usr/lib/python2.4/vendor-packages/osol_install. SUNWinstall also > includes /usr/bin/ManifestServ, which can be used as a debugging tool > for XML manifests." > done > Page 10: > > Table 2.1 top, extra ">" in <pkg_repo_default_authority> > > That > is created by the line wrap in the .pdf. Shouldn't be an issue when I deliver HTML version. > <bootroot_contents>: "image" is misspelled. > > done > <build_area>/logs: "contain" should be "contains" in both places here. > > done > Page 11: > > Table 2.1 finalizer section, 2nd PP: "You do not need to edit this > section unless you add finalizer scripts, or change the name or argslist > of existing scripts." > > done > Table 2.1 key_value_pairs section: > > "Specifies additional parameters needed by the disribution constructor > and/or finalizer scripts." > > "You do not need to edit the key value pairs except to add new ones > recognized by finalizer scripts you add or customize. > > done > 1st PP below table 2.1: "when you use the distro_const command ..." > done > 2nd PP below table 2.1: I would start by saying: "If the default scripts > do not leave the build_area as you need it, you can create your own > scripts to make further modifications. If you do create new scripts..." > > done > In the note directly below: mention to backup the original manifest as > well as the default scripts. > > done > 1st PP, "Using the Finalizer Scripts" section: there is an extra period > after "scripts". > > done > Page 11-12: Where the scripts are listed, please include: > > pre_bootroot_pkg_image_mod - Image area modifications for all types of > images. (Place before slim_cd/slimcd_pre_bootroot_pkg_image_mod.) > > bootroot_configure - Boot root configuration for all types of images. > (Place AFTER slim_cd/slimcd_bootroot_configure.) > > grub_setup - Initialization of grub menu for all types of images. > (Place after slim_cd/slimcd_post_bootroot_pkg_image_mod and before > post_bootroot_pkg_image_mod.) > > done > The bullets for the scripts listed on page 12 don't line up with the > bullets for the scripts listed on page 11. > that's just the .pdf showing the difference between a lefthand page and a righthand page Will not affect the final HTML delivery > Page 12: Just before the bullets at the bottom: the bullets are true and > are to be noted whether or not scripts are modified, so I would change > the "intro line" by saying "Please note the following characteristics of > finalizer scripts:" > > done > I know I suggested for you to do this originally, but in the third to > bottom bullet, please remove "and other parameters". Seeing this, given > its context, will confuse readers. Just say "The argslist, which can > accept a list of items, uses double-quotes..." Also, I would combine > the subsequent bullet about using commas between args with this bullet, > as it pertains only to the argslist. > done > Bottom bullet: "The Distribution Constructor passes five initial > arguments to all scripts which are executed. These five arguments do > not show in the manifest. The manifest specifies additional arguments > passed in after these five arguments. These five initial arguments are > as follows:" > > done > Page 13: > > Table 2.2 is missing a name. Call it "Finalizer Script Arguments" > done > Middle: Instead of: > "Or, you can use a python script as in the following example.", > and the subsequent line "From osol_install.Manifest.... following script" > say > " The following example shows how to make use of ManifestRead from a > python script: > > from osol_install.ManifestRead import ManifestRead (just like > this, no add'l punctuation) > > # get the manifest reader object from the socket > manifest_reader_obj = ManifestRead(MFEST_SOCKET) > > (and continue with the text as is through the end of what you already > have written) > done > Note: it may be clearer to the reader to put how to use ManifestRead in > a different section, and refer to that section from here. Then you can > just state that the first arg is just the server socket file name and it > is used with the ManifestReader, and see section xxx on how to use the > ManifestReader. > > If you do this, you can put the key/value pair section (starts on page > 14) there with it. > I'm unclear on this piece, so will leave as is for now > Package image area path section: > > - "which" is missing before "specifies". > > - Change > "you can use this argument if you wanted to modify a file..." > to > "Use this argument to locate a file in the package image area. The > following example checks whether the user "jack" is in the password file:" > done > Page 14: > > Under "Additional arguments", please change: > > "In the following example from the slim_cd.xml manifest file, an > additional arg specifies the bootroot_configure script" > > to > > "In the following example from the slim_cd.xml manifest file, two > additional arguments are passed to the bootroot_configure script (as > arg6 and arg7):" > done > Also, please indent the two lines inside <argslist> and </argslist> > > done > Page 15: Please delete examples 2-1 and 2-2 from here. These don't use > keys. Please leave the examples which use keys: 2-3 and 2-4. > > done > Page 16: > > "Creating an Image" section: > > Due to a bug, for now at least, -p needs to be specified before -r in > the distro_const command. Can you please reverse the -p and -r here? > (This also needs to go to release notes BTW.) > Done Please contact Pallavi for any Release Notes needed, per recent email about RN procedures. I'm not in the loop for that, unless you guys need me to edit any writeups. > "distro_const Command Reference" section: > > Bottom PP: I would split off "The following table summarizes these > command options" to its own paragraph, and change "these" to "the", > since not all commands deal with checkpointing. > done > Page 17: "distro_const build -l" section: add to the end of the first > sentence "... if checkpointing is active" This whole section is for > naught if checkpointing isn't active (either because it isn't enabled or > because ZFS filesystems aren't being used). > done > Ditto for build -r, build -p and build -R sections. > done > Page 18: > > "How to Create..." section, item 1, make "identification" plural in the > paragraph. "Use the step identifications provided..." > > done > Page 19: > > Due to that bug mentioned earlier (comments regarding page 16), how do > you feel about switching -p and -r in example 2-5 item 3? > Done - I rewrote simplifying it and using only -p in one step and only -r in the next and final step. > Page 21: > > Please be sure you have the latest manifest file before submitting. I > see some items listed in the included manifest file which have been > removed. Please ping me if you need the latest file, very close to your > delivery time to get the most updated file. > > Thanks, > Will do > Jack > > > > > > > Barbara.Lundquist at Sun.COM wrote: > > Install gang, > > > > This is the final review for the Automated Installer documentation > > and the Distribution Constructor documentation before I deliver > > these documents this Friday, 11/14. Thank you for all the edits > > I received to date! > > > > Please send me your final edits ASAP. > > > > - I will continue to make edits this week, but > > I may need to postpone some revisions until a later delivery, if > > time runs out. > > > > - For the AI article, I will be adding more material this week from > > Sundar and other > > engineers about the criteria manifest and more, as time permits. > > > > - Does the DC team have a final manifest file with comments done? > > > > AI man page: > > http://www.opensolaris.org/os/project/caiman/files/installadm.1m.txt > > > > AI article: > > http://www.opensolaris.org/os/project/caiman/files/AIinstallNearFinal.pdf > > > > DC man page: > > http://www.opensolaris.org/os/project/caiman/files/distro_const.1m.txt > > > > DC article: > > http://www.opensolaris.org/os/project/caiman/files/DistroConstNearFinal.pdf > > > > Thanks in advance! > > Barbara > > > > > > _______________________________________________ > > caiman-discuss mailing list > > caiman-discuss at opensolaris.org > > http://mail.opensolaris.org/mailman/listinfo/caiman-discuss > > > > _______________________________________________ > caiman-discuss mailing list > caiman-discuss at opensolaris.org > http://mail.opensolaris.org/mailman/listinfo/caiman-discuss > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/caiman-discuss/attachments/20081110/b71cec49/attachment.html>
