Bug 491028 - Minor wording errors in the Cluster LVM guide.
Minor wording errors in the Cluster LVM guide.
Status: CLOSED NOTABUG
Product: Red Hat Enterprise Linux 5
Classification: Red Hat
Component: Documentation-cluster (Show other bugs)
5.3
All Linux
low Severity low
: ---
: ---
Assigned To: Steven J. Levine
Content Services Development
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2009-03-18 20:00 EDT by Leam
Modified: 2009-09-03 12:33 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2009-09-03 12:33:03 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Leam 2009-03-18 20:00:51 EDT
Book Identifier: Cluster_Logical_Volume_Manager(EN)-5 (2009-01-05T15:20)

Page numbers refer to what the book identifies as a page, not the PDF.

Page 20:

   commandname --help

Might want to put commandname in italics to show that is is a variable, like the:

   man commandname

is below it. Unfortunately, Bugzilla doesn't show the italics.

Page 21:

How is the second pvcreate different than the first? It is supposed to show the difference between initializing an entire disk or just a partition. 

"The following command initializes /dev/sdd1, /dev/sde1, and /dev/sdf1 for use as LVM physical volumes.

  pvcreate /dev/sdd1 /dev/sde1 /dev/sdf1

To initialize partitions rather than whole disks: run the pvcreate command on the partition. The following example initializes /dev/hdb1 as an LVM physical volume for later use as part of an LVM logical volume.

  pvcreate /dev/hdb1"

Page 24:

Might want to change the sentence, as it seems confusing. Is the '-s' option not suitable with the default?  Old sentence:

"You can specify the extent size with the vgcreate command if the default is not suitable with the -s argument. "

Suggestion:

"You can specify the extent size with the -s option to vgcreate, if the default extent size is not suitable."

Page 25:

"crates" or "creates"?

"The command crates a local volume named vg1 that contains physical volumes /dev/sdd1 and /dev/sde1."


Page 26:

Do not condition a SysAdmin with what you feel the primary purpose of a command is. If the command can do something, that is it's purpose. Intent is one thing, purpose is another.

"The vgscan command will also display the volume groups, although its primary purpose is to scan all the disks for volume groups and rebuild the LVM cache file."

Page 28, same as page 26:

Also note that the sentence ends with a comma.

"Primarily, however, this command is used to deactivate and activate volume
groups, as described in Section 4.3.8, “Activating and Deactivating Volume Groups”,  "

Page 30:

Here and in some places an option or a disk identifier is broken between lines on the page. Also, should mknodes be bold?

"You can incorporate the vgmknodes command into the vgscan command by specifying the --
mknodes argument to the command."

Page 33:

While "stride" is occasionally used in place of "stripe", this is the only time in 4 chapters I recall seeing it. 

"The following command creates a striped logical volume across 2 physical volumes with a stride of 64kB."


Page 34:

Tough sentence:

"The mirrored volume this command creates is 500 megabytes in size, it is named
mirrorlv, and it is carved out of volume group vg0."

Perhaps:

"This command creates a 500 MB volume named mirrorlv in the vg0 volume group."


Page 35:

Suggest change "change" to "reduce", as change can be larger and there is a lvchange command. 

"To change the size of a logical volume, use the lvreduce command."


Page 36:

Does the single line duplicate stuff in the preceding paragraph?

"To remove an inactive logical volume, use the lvremove command. You must close a logical volume with the umount command before it can be removed. In addition, in a clustered environment you must deactivate a logical volume before it can be removed.

If the logical volume is currently mounted, unmount the volume before removing it."

Page 39:

What is "5A"?

"In this example, having added two physical volumes to the volume group we can extend the logical volume 5A to the full size of the volume group."



Page 42:

You broke up "/" and "dev".

"                                                                                                      The
filters consist of a series of simple regular expressions that get applied to the device names in the /
dev directory to decide whether to accept or reject each block device found."


Page 45:

Suggest dropping the sentence. Actually, a seperator would be useful with awk, but not with grep.

"This can be useful in a script if you are running a grep command on the 
output."

Pages 46, 48, and 50:

Some of the arguments in the first columns of the tables over-write information in the second column. 

That's all for tonight.  :)

Leam
Comment 2 Steven J. Levine 2009-06-26 12:37:42 EDT
Thanks for the thorough review. I have been updating the LVM manual for the RHEL 5.4 release and I have modified the book in accordance with all of these suggestions.

For the comment on page 21: Yes, the point of the second example is to show that you can run pvcreate on a partition. I wasn't sure how to make this clearer. I made a very slight change to this sentence:

The following example initializes /dev/hdb1 as an LVM physical volume for later use as part of an LVM logical volume.

It now reads:

The following example initializes the partition
/dev/hdb1 as an LVM physical volume for later use as part of an LVM logical volume.
 
So all I did was call out that this is a partition that is being used.

I have reformatted the tables so the text does not overlap.

As for the issue of filenames and commands being split across lines where they should not be: This is a bug in the production of our PDF documents. We are working on fixing this. If this isn't fixed in time for the RHEL 5.4 release I will try to go through the document and reword a few sentences to avoid the bad breaks.
Comment 3 Steven J. Levine 2009-09-03 12:33:03 EDT
With the release of RHEL 5.4 I am closing this bug.

Note You need to log in before you can comment on or make changes to this bug.