Add a new paragraph instead of "<br>" if the text to be merged contains "\n"

[ZhengMingpei]

Description

Just modified the function "__merge_field" for adding real paragraphs instead of "<br>" if the text to be merged contains "\n".

Motivation and Context

For example, for field named "text" in docx, there are text to be merged: "1.one\n2.two\n3.three"

By the old function, it will insert "<br>" to get line break ( In MSword, it shows "Shift+Enter"):

But considering text indentation, (for me, Chinese language), actually we need "Real Enter".

By the old function, it will be:

In other word, now we need two more paragraphs instead of two "<br>".

So I writed some codes to add paragraphs to solve these "bugs",perhaps features?

I hope it will show:

How Has This Been Tested?

Tested on window10, python 3.6.6.

I run the unittest by python -m unittest and the result is FAILED (failures=8)

All these failures seem are the result of test cases, these cases are based on "<br>",It's no surprise that failed. Maybe these test cases need to be changed.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[ZhengMingpei]

@Bouke Sorry for my poor English

[Bouke]

This looks like an interesting change. I think it’s good to differentiate between line breaks and paragraph. And so my question with this change is, how can we differentiate between the two? What does the user intent when there’s a \n in the input? We could maybe have a flag to switch between the two. Or we might use \n for a line break and \n\n for starting a new paragraph. What do you think?

[ZhengMingpei]

I don‘t know whether you often use line breaks, In my country(China), almost everyone are used to just type "Enter" and get a new paragraph.
They don't know the differentiate between line breaks and paragraph. like this：

When I used docx-mailmerge for my script, I hope it'll add new paragraph instead of line break , that every line show the same text indentation and other style, In my view, it'll be good.
Maybe someone just not use text indentation or type multi text lines when use docx-mailmerge, and they will never face this question.

Although in xml file, line break and paragraph shows different, in MSword application, all the same except just some blank, text in their MSword like below:

I think it's a little puzzling to use \n for a line break and \n\n for starting a new paragraph, maybe setting a flag to switch between the two can be better ?
(For example, line break is default ,and can be set by document.merge(multiline_newparagrph=True) to garagraph)
What do you think？

[Bouke]

So I think the confusion on my part is due to the styling changes of new paragraphs that have changed between Word versions. I believe Word 2013 would offset paragraphs with a blank line, were this change was reverted in later versions. You might be correct that Word inserts a new paragraph with [enter], however it doesn't render different from a line-break for me in the default styling.

So what would happen now with this change when the merge field is surrounded by text, and the replacement contains a line break?

Student address: <[ADDRESS]>
Student name: <[NAME]>

ADDRESS = "Street 1\n12345 CITY\nCountry"
NAME = "Some Student"

[ZhengMingpei]

So I think the confusion on my part is due to the styling changes of new paragraphs that have changed between Word versions. I believe Word 2013 would offset paragraphs with a blank line, were this change was reverted in later versions. You might be correct that Word inserts a new paragraph with [enter], however it doesn't render different from a line-break for me in the default styling.

So what would happen now with this change when the merge field is surrounded by text, and the replacement contains a line break?

Student address: <[ADDRESS]>
Student name: <[NAME]>

ADDRESS = "Street 1\n12345 CITY\nCountry"
NAME = "Some Student"

I don't have any version of Microsoft Word for testing, all of my docx file were edited with WPS Office that is compatible with the Microsoft Word in China,
I set the first line indent for this two paragraph, Run my codes, it shows:

Run your codes, it shows:

There are my files for testing, run python readXls1104.py will get new docx file with mailmerge fields.
example.zip

If you create a new docx file as the template file with Microsoft Word 2013, such as template/r2.docx, After running python readXls1104.py, maybe you get the same file as :

It shows that you‘re right and users edit template docx file with some new version of Microsoft Word will solve questions, But for me or people that don't have any version of Microsoft Word, maybe changing the codes is a solution.