On Tue, Jul 26, 2011 at 11:02 PM, Alex Elder <aelder@xxxxxxx> wrote:
> On Fri, 2011-07-22 at 11:52 -0400, Christoph Hellwig wrote:
>> On Mon, May 23, 2011 at 02:34:54AM +0400, CoolCold wrote:
>> > Basing on irc discussions and questions about reading xfs_info output
>> > I've added example in xfs_growfs manpage.
>>
>> Alex, Dave, Eric, do you guys have any comments on this? Language
>> nitpicks from the native speakers? Otherwise I'd be inclined to put it
>> in.
>>
>> > Signed-off-by: Roman Ovchinnikov <coolthecold@xxxxxxxxx>
>
> I had to dust off my troff command knowledge to review this.
> It has been many years...
I was testing how manpage will look with "man man/man8/xfs_growfs.8", works for
me.
>
> Christoph prompted to review this from a native speaker's
> point of view though, so I do that here. I do end up
> with a question for others to try to resolve.
>
> I think what you are doing (adding the example) is a good idea
> to help clarify things in any case.
Thanks!
>
>> > ---
>> > man/man8/xfs_growfs.8 | 34 ++++++++++++++++++++++++++++++++++
>> > 1 files changed, 34 insertions(+), 0 deletions(-)
>> >
>> > diff --git a/man/man8/xfs_growfs.8 b/man/man8/xfs_growfs.8
>> > index 02793ae..c782fc1 100644
>> > --- a/man/man8/xfs_growfs.8
>> > +++ b/man/man8/xfs_growfs.8
>> > @@ -1,3 +1,14 @@
>> > +.\" Verbatim blocks taken from openssl req manpage content
>> > +.de Vb \" Begin verbatim text
>> > +.ft CW
>> > +.nf
>> > +.ne \\$1
>> > +..
>> > +.de Ve \" End verbatim text
>> > +.ft R
>> > +.fi
>> > +..
>> > +
>> > .TH xfs_growfs 8
>> > .SH NAME
>> > xfs_growfs, xfs_info \- expand an XFS filesystem
>> > @@ -105,6 +116,7 @@ this is specified with
>> > Specifies that no change to the filesystem is to be made.
>> > The filesystem geometry is printed, and argument checking is performed,
>> > but no growth occurs.
>> > +.B See output examples below.
>> > .TP
>> > .BI "\-r | \-R " size
>> > Specifies that the real-time section of the filesystem should be grown.
>> > If the
>> > @@ -152,6 +164,28 @@ reside. In order to grow a filesystem, it is
>> > necessary to provide added
>> > space for it to occupy. Therefore there must be at least one spare new
>> > disk partition available. Adding the space is often done through the use
>> > of a logical volume manager.
>> > +.SH "EXAMPLES"
>> > +
>> > +Examining xfs_info output.
>
> How about, "Understanding xfs_info output"
>
>> > +.PP
>> > +Let's assume one have the next xfs_info output:
>> > +.PP
>> > +.Vb 1
>
> Maybe you could add something indicating how the command was issued.
> I.e.:
>
> \&# xfs_info /dev/sda
Okay.
>
>> > +\& meta-data=/dev/sda isize=256 agcount=32, agsize=16777184 blks
>> > +\& = sectsz=512 attr=2
>> > +\& data = bsize=4096 blocks=536869888, imaxpct=5
>> > +\& = sunit=32 swidth=128 blks
>> > +\& naming =version 2 bsize=4096
>> > +\& log =internal bsize=4096 blocks=32768, version=2
>> > +\& = sectsz=512 sunit=32 blks, lazy-count=1
>> > +\& realtime =none extsz=524288 blocks=0, rtextents=0
>
> I think you should drop the space character after each '&' above.
> The way you have it puts a slight indent in the output.
Personally I like indentation here, to make the text look like "quote", and may
be I'd add one more space
>
>> > +.Ve
>> > +.PP
>> > +
>> > +Here, data section block size (bsize) is 4096 bytes. Therefore
>> > +"sunit=32 swidth=128 blks" means stripe unit is 32*4096 bytes = 128
>> > kibibytes
>> > +and stripe width is 128*4096 bytes = 512 kibibytes. Filesystem is striped
>> > +over 4 ( 128 / 32 ) stripes.
>
> I'll just write what I think it should be rather than trying
> to show lots of little changes:
>
> Here, the data section of the output indicates "bsize=4096",
> meaning the data block size for this filesystem is 4096 bytes.
> This section also shows "sunit=32 swidth=128 blks", which means
> the stripe unit is 32*4096 bytes = 128 kibibytes and the stripe
> width is 128*4096 bytes = 512 kibibytes.
>
> The last sentence I'm not sure I agree with. I think you're
> trying to explain the relationship between a stripe width
> and stripe unit, and the components that make up a stripe.
> Your use of the term "stripe" doesn't match what I take
> to be its meaning. I'm not saying my meaning is right, but
> I'd like to make sure we have agreement on these terms.
Generally I was trying to fact out units of measurement - as,say, mkfs.xfs
manpage describes option parameters as 512 bytes blocks/just bytes to be
specified when calling mkfs.xfs, and when someone gets xfs_info output for that
mount point it really differs from parameters he passed to mkfs.xfs (at least
at first sight).
>
> Given that, I would re-state your last sentence (using my
> terminology as):
>
> A single stripe of this filesystem therefore consists
> of four stripe units (128 blocks / 32 blocks per unit).
>
> I.e., my meaning says that a "stripe" is "stripe width"
> blocks wide, made up of four "stripe units", each of which
> is 32 blocks, where a block is 4096 bytes.
>
> I think you are using the term "stripe" to represent what
> I'm calling the "stripe unit".
>
> Perhaps someone else can help ensure we're using
> terms with meaning consistent with how XFS has used
> them historically.
I've checked manpage for mkfs.xfs and it operates with terms "stripe unit" &
"stripe width" in your understanding, so I think this is historically proper
way to think about stripes.
>
> -Alex
>
>
>> > .SH SEE ALSO
>> > .BR mkfs.xfs (8),
>> > .BR md (4),
>
>
So, I've updated patch (now it mostly contains your text), but left
indentation. Patch is attached and url for it is
http://web.coolcold.org/data/0001-adding-example-with-xfs_info-decryption-v2.patch
I'm new to all this public patch-through-email process, should I start
new mail thread with new patch text inside message?
--
Best regards,
[COOLCOLD-RIPN]
0001-adding-example-with-xfs_info-decryption-v2.patch
Description: Binary data
|