On Tue, Jul 26, 2011 at 11:02 PM, Alex Elder 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 > > 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]