Add flag to show both configuration styles (Java and XML) in reference docs

[Buzzardo]

I edited the leader paragraphs above each code block that was flagged as being XML or Java content, such that the paragraphs make sense when both the XML and the Java blocks are present. I turned the Both button back on. I also caught a bunch of other editing things.

[fmbenhassine]

I tested this PR and noticed that the "Both" option will introduce some repetitive sentences making the documentation not coherent:

Moreover, we need to make sure every section having a role corresponds to its snippet and test it with the "Both" option to avoid inconsistencies like the following one:

To be honest, I don't see the added value of this "Both" option, at least with the current design. May be we can update the style to show snippets side by side, but still.

@Buzzardo @mminella What do you think?

[Buzzardo]

Those are errors we need to correct. I'll make a new PR for them.

[Buzzardo]

Do you want an issue for this or is it too simple for that?

[fmbenhassine]

No need for an issue or a new PR. You can fix those in this PR so we merge a coherent change set at once.

[Buzzardo]

Hi, Mahmoud,

That was tricky. I had to rephrase a bit to make it make sense and still keep the key information. I also fixed a couple grammatical errors that I caught while I was there.

Please check this commit closely, as I had to resolve a bunch of conflicts due to the age of the original commit. I THINK I got everything right, but please do check.

Thanks much.

[fmbenhassine]

@Buzzardo Thank you for all these updates! I did a quick check and it looks ok now. Let's iterate on this. Could you please rebase the PR on the latest master branch? Thank you upfront.

[Buzzardo]

@benas I have rebased and cleared up all the conflicts.

[fmbenhassine]

Rebased, squashed and merged as efdce56. I did another check and noticed a couple of typos and rendering issues like:

which I fixed in ffd3908.

@Buzzardo Thank you very much for your PR!