Wiki .md-files should use semantic newlines (less prone to merge-conflicts)

[ofossum]

Hi there,

i'd like to recommend semantic newlines when writing the *.md-files for documenting Freeplane.
I worked only a very brief time on documentation using git and really quick got into merge-conflicts.
These occur really fast, if text is spanning multiple lines and / or is automatically adjusted to fit lines.
These would provoke merge-conflicts in git.
This is especially true for not-code -- documentation, Readmes etc., as they use sentences, that often are a lot longer than code, where this issue of using a lot new lines is important for readability and structure of the code.

This proposal would mean:
re-arranging the existing and not-so-big documentation.
Also this would be one item on something like a style-guide for the wiki in the future.

Two quick references for a better understanding:

" Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, and long sentences should be 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."
-- https://man7.org/linux/man-pages/man7/man-pages.7.html

and also

• https://github.com/cllns/semantic_linefeeds#readme

[quickfold]

I understand the usefulness of this practice. Would this mean inserting newline breaks manually while writing the documentation? I don't see that happening for most contributors since it is such an unusual activity for non-technical writers. Perhaps it can be done automatically fairly easily on existing documentation by regularly doing a search and replace for commas, semicolons, and other punctuation and inserting newline codes after each?

[ofossum]

Well, there are numerous ways for this to do.
In fact, the second link i referenced is a ruby script to do this automatically on a given file.
You could use search + replace as well as regexes for this.

My goal was to bring this topic up in the early stage of this documentation, so that it does not mean to turn thousands of sentences around.
Right now, this is a task one could do in a not so great amount of time an then submit it to this repo.

[ofossum]

Here is another source describing why semantic line breaks are a thing: https://sembr.org/

Also, there is a good tip about merging with git:

How do I use semantic line breaks with Git?

The default Git diff options emphasize line changes in a way that may obscure certain revisions to text with semantic line breaks. You can pass the --word-diff option to the git diff command for better results:

$ git diff --word-diff

[ofossum]

I changed the existing files and rearranged them: one sentence per line (at least in text, not in tables, code or lists etc.)
See #11 (comment)

Edit:
Ah okay -- GitHub automatically shows the corresponding PR when i mention discussion-threads in PRs and vice versa. Nice!