Long lines (aka paragraph as a single line) issue

[pfalcon]

Currently, manual's *.md files appear to be formatted with very long (plain-text) lines, where each paragraph is effectively represented by a single long line. That may pose some discomfort for user of plain-text editors, where one plain-text line is actually represented by one on-screen line, necessitating excessive scrolling. Though, line-wrapping editors definitely exist, so it's not a too-big issue.

However, other tooling is still built around a concept of separate easily manageable lines, e.g. version control. Diffs are based on the concept of lines (a one character changes in a line means the entire line is changed), and having too long lines definitely complicate change review in management.

My particular issue is that wide varying changes too paragraph can't be differentiated. For example, I now (finally) go thru reading the entire manual, and fix various typos/punctuation/formatting issues, but also actually change the content for grammar/clarity/whole new additions. Those are very different types of changes, and normally I would submit them separately, using git add -p to cherry-pick particular type of change. With "whole paragraph as one line" approach, I effectively can't cherry-pick a particular change if single paragraph contains more than one type of changes. With normal plain-text lines, there's much higher chance to cherry-pick changes independently.

The risk factor here is that the changes I make can't be contributed back (or if contributed en-masse, can't be merged, because different changes require separate reviews).

@hug-sch, questions:

1. Do you see the above as a problem at all?
2. If so, would you be ok to make changes to that, i.e. would your workflow allow working with broken-down paragraph lines without much issues?
3. If so, would you consider reformatting the entire manual en masse?
4. Any other suggestions?

Thanks.

[pfalcon]

Just to elaborate, splitting a paragraph into many lines has its drawbacks too. Namely, as words are being added/deleted, length of the underlying plain-text lines goes uneven, and eventually the entire paragraph may needed to reformatted, causing a big diff again. That's generally a reason why people would use "paragraph as a single line" approach (with it, such reformatting are never needed). So, it's all matter of preferences and compromises (I for one prefer classical manageable plain-text lines and am ok with uneven length during editing and occasional (!) reformattings).

[hug-sch]

Hi, I wasn't aware of this problem. I'm working in VSCode (previous on Windows, now on Mac). In this editor, there seems to be no problem with the word wrap. I'm open for suggestions or other approaches. However, I'm not much knowledgeable about GIT, so, please, guide me in the process.

[hug-sch]

Will this splitting have an effect on the rendering of the webpage? What will happen if one adds a few words to a line? Will these extra words wraps to the next line and cause white space after them? Something like:

This is a line.
This is the next line.

becomes

This is a very long, long, ...
line.
This is the next line.

[pfalcon]

@hug-sch :

What will happen if one adds a few words to a line? Will these extra words wraps to the next line and cause white space after them?

No, it shouldn't be like that, per standard Markdown rules, paragraphs are separated by empty lines, and consecutive lines should be rendered as a single paragraph. Some Markdown variants (e.g. Github-flavored Markdown) have some heuristics when to still break rendered lines, but again, it's not per the standard Markdown. Worth checking how MkDocs handles that, of course.

@hug-sch : Just to clarify, I wouldn't expect any immediate actions re: this ticket, just wanted to record this issue for discussion, based on my spending a few hours on weekend reading thru the docs and trying to make a bunch of changes here and there. For one, that would be a sweeping change across the entire repo, and worth good consideration and planning (especially after recent sweeping changes regarding line endings).

So, yeah, I'd say let it sit here and collect more thoughts from different people based on their experience contributing...

Thanks!

[Sn1kk3r5]

Hi all,

Regarding 3) we need to consider the german version as well...
Regarding 4) iirc the whole page format depends on this, so if we will rework the whole thing, we need to spend quite some hours... and at least for the German site I'm still having free time issues.