New readme

[tom-adsfund]

I changed most of the top part of the readme to convey all the things I'd learned from talking with you, and also doing what I thought was right (as I described in previous emails).

Tell me if you want any changes.

[fgrandel]

Thanks Tom! It would be great if you could make two small formatting changes so that I can better review your changes:

1. Please wrap lines so that I don't have to scroll back and forth in github's diff to read long lines. ;-)
2. Please use the --- and === headline formatting I use elsewhere. I find this easier to read and it's nicer to have consistent formatting anyway. I didn't really understand why you shortened the headline formatting, it makes for nicer layout in ASCII if you have the underlines all the way under the headline.

[tom-adsfund]

You can click View File to the right of the file name to see the rendered version -- without non-wrapping issues.

And I use the hashes and shorter lines because it means much quicker changes to titles etc.

[fgrandel]

"View File" gives me the whole file, not the diff. This makes it difficult to review changes (as opposed to the whole file). Not sure what editor you're using but usually there should be a setting to wrap lines automatically so that you don't have to deal with it.

Wrt formatting: I recommend you always stick to the coding style of the project by default unless you confirmed a change in coding style beforehand with the project owner. In this case I don't really mind the style. Seems to be largely a matter of taste. If you want to change it: Please make the change consistently everywhere (including HACKING.md).

[tom-adsfund]

Which editor do you use? Emacs doesn't have that, or Gedit. I can only imagine that wrapping feature would be available if the software really understood the language of the file, like I've seen in IntelliJ for Java.

(I guess you can see that the edit is clearly just a big blob at the top of the file.)

I'll change the style of the formatting to be consistent.

[fgrandel]

I'll change the style of the formatting to be consistent.

Great. I'll take care of wrapping then. Most of the time I use vim where this is easy. In vim textwidth takes care of word wrapping. It can be applied to part of the text with the 'gq' shortcut.

In Emacs I think that FillParagraph is what you'd use. I'm not an Emacs expert, though.

I'm not using gedit very frequently, either. But seems there is a solution.

[tom-adsfund]

(I tried to use the formatting/hard-wrap tool in jEdit and it completely messed up the file -- as expected because it failed to understand the language.)

[fgrandel]

I manually took over most of your changes. In principle I liked your idea to give a good example right in the beginning. Your specific example was a bit contrived, though, and didn't really demonstrate the most useful feature, ie undo/redo. That's the reason why I didn't take it. I also left the old main title as I found it more to the point. For the rest I integrated your (good!) ideas.

You really improved the documentation considerably. Thanks for that!

[tom-adsfund]

I'm pleased that it's had a positive effect on the documentation.

[fgrandel]

Definitely. I hope you could follow the reasoning why I couldn't take over all changes. As soon as I come across a good representative example, I'll insert it in the beginning.

[tom-adsfund]

If you can create a representative example (preferably two), I think that would really help everyone including me understand what you see in the project. (I already see great value, but I think you can see more.)

I think the title should be worked on too. Not too much time, but I don't really think 'undo/redo' really explains what's happening with this system. Yes, from the client perspective it is like an undo and redo, but actually if it's only de-/re-activating a version, the effect is very unlike a common single-user-sequential undo/redo. Example: if I do something to a field, someone else writes to that field, and then I 'redo' my action I would expect my version to be visible, but it's not.