[PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Qu Wenruo]

Although btrfs-convert can rollback converted btrfs, it still has some
limitation to ensure rollback.

Add a warning on the limitations.

Also add a note for users who decides to go on with btrfs and don't need
the rollback ability.

Reported-by: Vytautas D <vytdau@gmail.com>
Reported-by: Tsutomu Itoh <t-itoh@jp.fujitsu.com>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
v2:
  Add reporter tags
v3:
  Remove 'btrfs fi defrag' from commands that may disable rollback
  ability.
  Add a little explain to make the warning more reasonable.
---
 Documentation/btrfs-convert.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/btrfs-convert.txt b/Documentation/btrfs-convert.txt
index 8b3f05b..b57af73 100644
--- a/Documentation/btrfs-convert.txt
+++ b/Documentation/btrfs-convert.txt
@@ -15,6 +15,16 @@ DESCRIPTION
 and the original filesystem image is accessible as from separate subvolume
 named 'ext2_saved' as file image.
 
+WARNING: If one hopes to rollback to ext2/3/4, he or she should not execute
+*btrfs balance* command on converted btrfs.
+Since it will change the extent layout and make *btrfs-convert* unable to
+rollback.
+
+NOTE: If one is satisfied with converted btrfs, and not longer wants to
+rollback to ext2/3/4, it is highly recommended to remove 'ext2_saved' subvolume
+and execute *btrfs filesystem defragment* and *btrfs balance* command on the
+converted btrfs.
+
 OPTIONS
 -------
 -d|--no-datasum::
-- 
2.3.5

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Duncan]

Qu Wenruo posted on Fri, 03 Apr 2015 09:21:15 +0800 as excerpted:

> +WARNING: If one hopes to rollback to ext2/3/4, he or she should not execute
> +*btrfs balance* command on converted btrfs.
> +Since it will change the extent layout and make *btrfs-convert* unable to
> +rollback.

Because "since" is subordinating and the sentence doesn't contain what
it is subordinated to as that's explained in the previous sentence,
"Since it will..." introduces a sentence fragment.

Possible correction 1, combine the sentences:  Either simply eliminate
the period following the previous sentence, or convert it to a comma,
either way combining the sentences into one.

Possible correction 2, eliminate the subordinator:  Eliminate "Since"
and begin the second sentence with "A balance..." (replacing "it").

Possible correction 3, reorder and edit, something like this:

+WARNING: Do not execute a *btrfs balance" on a converted btrfs until you
+are sure you will not rollback, as a balance changes the extent layout
+and prevents btrfs-convert from successfully rolling back to ext2/3/4.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Qu Wenruo]

> Qu Wenruo posted on Fri, 03 Apr 2015 09:21:15 +0800 as excerpted:
>
>> +WARNING: If one hopes to rollback to ext2/3/4, he or she should not execute
>> +*btrfs balance* command on converted btrfs.
>> +Since it will change the extent layout and make *btrfs-convert* unable to
>> +rollback.
>
> Because "since" is subordinating and the sentence doesn't contain what
> it is subordinated to as that's explained in the previous sentence,
> "Since it will..." introduces a sentence fragment.
Thanks.

It seems my English is really poor... :(
>
> Possible correction 1, combine the sentences:  Either simply eliminate
> the period following the previous sentence, or convert it to a comma,
> either way combining the sentences into one.
I'll take this one.

Thanks,
Qu
>
> Possible correction 2, eliminate the subordinator:  Eliminate "Since"
> and begin the second sentence with "A balance..." (replacing "it").
>
> Possible correction 3, reorder and edit, something like this:
>
> +WARNING: Do not execute a *btrfs balance" on a converted btrfs until you
> +are sure you will not rollback, as a balance changes the extent layout
> +and prevents btrfs-convert from successfully rolling back to ext2/3/4.
>

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Roman Mamedov]

[-- Attachment #1: Type: text/plain, Size: 416 bytes --]

On Fri, 3 Apr 2015 15:06:46 +0800
Qu Wenruo <quwenruo@cn.fujitsu.com> wrote:

> >> +WARNING: If one hopes to rollback to ext2/3/4, he or she should not execute

It also seems a bit awkward to spell out "he or she", if you want to refer to
a user without specifying the gender, in software documentation it's more
common to use "they": https://en.wikipedia.org/wiki/Singular_they

-- 
With respect,
Roman

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Duncan]

Roman Mamedov posted on Fri, 03 Apr 2015 12:16:56 +0500 as excerpted:

> On Fri, 3 Apr 2015 15:06:46 +0800 Qu Wenruo <quwenruo@cn.fujitsu.com>
> wrote:
> 
>> >> +WARNING: If one hopes to rollback to ext2/3/4, he or she should not
>> >> execute
> 
> It also seems a bit awkward to spell out "he or she", if you want to
> refer to a user without specifying the gender, in software documentation
> it's more common to use "they":
> https://en.wikipedia.org/wiki/Singular_they

Tho as the link notes, "singular they" has been and remains somewhat 
controversial.

While "singular they" is accepted as correct (and as the link points out, 
has been used by certain professional writers in some instances for 
centuries, so it's not new!), so is "he or she", with both being 
generally agreed to be slightly awkward attempts at political 
correctness, for those uncomfortable with the arguably more traditional 
masculine second-person-generic when referring to a human, feminine when 
personifying an animal or inanimate object.

An individual's choice of usage will depend on how politically correct 
and inclusive their (usage in point) intent is, vs how traditional they 
intend to be.

So either usage would have been fine here in a modern context, as would  
the more traditional "he" in a traditional context, since the individual 
is assumed to be a person not an object.

The ones that really bother me, however, are the ones that arguably 
inappropriately use a feminine second-person singular when obviously 
referring to a (gender-unknown) person, not an object.  That's in-your-
face political correctness to the point of extremism, partly because it 
triggers a reparse, since the reader is then left to figure out whether 
the intent was really specifically human female or an inanimate object, 
where they had thought human generic or male, previously, and when the 
traditional usage doesn't match, the extreme in-your-face politically 
correct assertiveness of the deliberate female choice over singular-they, 
appropriate he/she form, or traditional gender-unknown but assumed human 
masculine, is jarring, to say the least.  I understand why some people 
make that choice and respect that they have the right to choose it, but 
still resent that they don't have at least minimal respect for my need as 
a reader to read without jarringly forced reparse.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[Duncan]

Qu Wenruo posted on Fri, 03 Apr 2015 15:06:46 +0800 as excerpted:

> It seems my English is really poor... :(

I think the usual response is "Better than my Chinese!" =:^)

Seriously, tho, it's better than many native English speakers/writers as 
well, good enough I'd not guess different were it not for the name and 
the cn hint in your email address.  Meanwhile, while it was a sentence 
fragment, in less formal settings (such as this list) it would have 
passed more or less unnoticed, particularly since the meaning was so 
obvious that not even a word needed changed, only a bit of punctuation.

In more formal setting such as btrfs documentation, however, a sentence 
fragment of that sort will trigger the reader's misparse detector, thus 
causing them to pause and go back and reread, slower, to see where their 
natural parsing went wrong.  As such, it brings attention to something 
that would otherwise be fairly minor.  So better to fix it now and not 
have all those people stumbling over it later. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [PATCH v3] btrfs-progs: Doc: Add warning and note on btrfs-convert.

[David Sterba]

On Fri, Apr 03, 2015 at 03:06:46PM +0800, Qu Wenruo wrote:
> > Qu Wenruo posted on Fri, 03 Apr 2015 09:21:15 +0800 as excerpted:
> >
> >> +WARNING: If one hopes to rollback to ext2/3/4, he or she should not execute
> >> +*btrfs balance* command on converted btrfs.
> >> +Since it will change the extent layout and make *btrfs-convert* unable to
> >> +rollback.
> >
> > Because "since" is subordinating and the sentence doesn't contain what
> > it is subordinated to as that's explained in the previous sentence,
> > "Since it will..." introduces a sentence fragment.
> Thanks.
> 
> It seems my English is really poor... :(

Do not worry too much, we need both the technical content and the
writing style. As you can see there are people to help, the comments
should not discourage you.  This is similar to the "code" patches, we
do cleanups. Technical writing is specialization on its own, we do not
have to be proficient in everything.