Re: [PATCH 15/24] xfs_metadump.8: Add description for the newly introduced -v option

["Darrick J. Wong" <djwong@kernel.org>]

On Thu, May 25, 2023 at 03:34:47PM +0530, Chandan Babu R wrote:
> On Tue, May 23, 2023 at 10:40:53 AM -0700, Darrick J. Wong wrote:
> > On Tue, May 23, 2023 at 02:30:41PM +0530, Chandan Babu R wrote:
> >> Signed-off-by: Chandan Babu R <chandan.babu@oracle.com>
> >
> > This should be in the previous patch.
> >
> 
> Ok.
> 
> >> ---
> >>  man/man8/xfs_metadump.8 | 10 ++++++++++
> >>  1 file changed, 10 insertions(+)
> >> 
> >> diff --git a/man/man8/xfs_metadump.8 b/man/man8/xfs_metadump.8
> >> index c0e79d779..23695c768 100644
> >> --- a/man/man8/xfs_metadump.8
> >> +++ b/man/man8/xfs_metadump.8
> >> @@ -11,6 +11,9 @@ xfs_metadump \- copy XFS filesystem metadata to a file
> >>  ] [
> >>  .B \-l
> >>  .I logdev
> >> +] [
> >> +.B \-v
> >> +.I version
> >>  ]
> >>  .I source
> >>  .I target
> >> @@ -74,6 +77,9 @@ metadata such as filenames is not considered sensitive.  If obfuscation
> >>  is required on a metadump with a dirty log, please inform the recipient
> >>  of the metadump image about this situation.
> >>  .PP
> >> +The contents of an external log device can be dumped only when using the v2
> >> +format. Metadump in v2 format can be generated by passing the "-v 2" option.
> >
> > Please start each sentence on a separate line.
> 
> Does it need to be formatted as shown below?
> 
> The contents of an external log device can be dumped only when using the v2
> format.
> Metadump in v2 format can be generated by passing the "-v 2" option.

Yes, this is correct enough for me.  From man-pages(7):

   Use semantic newlines
       In the source of a manual page, new sentences should be started
       on  new  lines,  long  sentences  should be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and long
       clauses should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier to  see
       the  effect of patches, which often operate at the level of in‐
       dividual sentences, clauses, or phrases.

Frankly I don't care to split at the *clause* level because I think
newlines should come after a complete thought.  Note that the source of
that paragraph looks like this:

	.SS Use semantic newlines
	In the source of a manual page,
	new sentences should be started on new lines,
	and long sentences should split into lines at clause breaks
	(commas, semicolons, colons, and so on).
	This convention, sometimes known as "semantic newlines",
	makes it easier to see the effect of patches,
	which often operate at the level of individual sentences or sentence clauses.

Which is (IMHO) harder to read when reviewing diffs.

Oddly it also misses the fact that “sometimes known as "semantic
newlines",” is a parenthetical clause and should be a separate line.

I'm also pretty sure that “...should be started on new lines, and long
sentences should...” is a compound sentence and doesn't need the comma.

This whole thing also assumes that writers have had as comprehensive an
education in English grammar as I have forgotten over the past 30 years.

So.

I'm only going to go as far as asking for newlines after each sentence
so that manpage diffs don't write-amplify into adjacent thoughts that
haven't actually changed.

> >
> > This also should mention that metadump will pick v2 if there's no
> > explicit -v option and the fs has an external log.
> 
> Ok. I will include that as part of the description.

Thank you!

--D

> -- 
> chandan