5 ms·

I'm currently using GitHub to collaborate on writing a book with a non-technical coauthor. Generally it works great, but there are two key issues: * Changes ar

by scottfr 13y ago

I'm currently using GitHub to collaborate on writing a book with a non-technical coauthor. Generally it works great, but there are two key issues: * Changes are tracked by line which is equivalent to a paragraph in a book. If I go in and add a comma to a paragraph and my coauthor simultaneously changes a word in that paragraph that can create issues. * Errors are very difficult to solve for my coauthor. When Github Window's app encounters an error, it basically says "Just open up the command line and you should be able to figure out how to solve this". Of course this isn't feasible for a non-technical audience. If your product can fix these two issues (which it looks like it is trying to) it could be very valuable.

nadaviv 13y ago
> Changes are tracked by line which is equivalent to a paragraph in a book. When using Markdown, I usually split paragraphs over multiple lines (usually between sentences) which makes diffs much easier to read, while still rendering as a single paragraph.
- vidarh 13y ago
  Same here. "Single line paragraphs" are a pet hate of mine - they have no place in plain text files even if those files are intended to be post-processed.
  - tasuki 13y ago
    I'm still undecided on this. Say you have a long paragraph and have to add one word at the beginning. You have two options - either rewrap and introduce a silly diff, or don't rewrap and exceed your chosen text width. Single line paragraphs don't put such a difficult choice in front of you. If your diff software is any useful, it'll highlight your change within the line.
    - gknoy 13y ago
      Perhaps you could have a special kind of commit, a "text-rewrap" commit (similar to merge commits), which might let your diff presentation tool alternate between diffing lines, pararaphs, or the like. I agree, the presentation layer really needs to be as granular as your editing team needs to be. I __really__ like how Github shows the differences within a line that is different.
    - nadaviv 13y ago
      That's why I don't use fixed-width. I break lines up logically, usually at the end of a phrase/sentence, regardless of their length.
  - breadbox 13y ago
    Absolutely, but you still have the issue that a minor wording change can cause an entire paragraph to be marked as changed if your editor re-wraps the paragraph. Or, if the editor doesn't rewrap the paragraph, then they slowly get more and more ragged over time, making it annoying to read through. A diff tool that understands paragraphs is an essential tool for this project.
  - gabemart 13y ago
    I disagree with this. In a plain text file that consists of prose, line breaks are presentation, not content. Hardcoding them into the file doesn't appeal to me. It makes editing a pain in the neck. It also means the line breaks have to be removed again if you want to move between formats.
    - gknoy 13y ago
      That sounds like an editor issue, though. You should be able to reflow a paragraph, indent it or whatever it as you like. A compromise might be to break lines on sentence boundaries: edits are often constrained within sentence or paragraph boundaries, and then diff would give more meaningful output for most sentences. ^-- This one sentence is two lines long, though, so perhaps my idea is not that good. Diffs would still be easier to read than if each paragraph were one line.
- jamie_ca 13y ago
  I know people who break lines per phrase/clause, rather than per sentence. You wind up with lots of very short lines, but that doesn't matter after Markdown is done processing. The benefit is some _very_ granular diffs that are easy to read, as you work out rewording things in the editing process.
cinger 13y ago
i write quite a bit with git, and recently brought an old collab project with a friend onto it. i do all of the git work, and i just have my friend add my edits to his document, then he sends it back and i diff the two for potential errors... he requested it be this way because he is stuck in his ways, but we've agreed to go full git on book two in the series... that said, when i first started sending him diff files we both saw this as a problem... my solution? i just wrote a script that i run on the diff to just highlight the changes made, then send him the new edited diff. -PARAGRAPH +PARAGRAPH becomes : -SENTENCE -word...word +word...word +SENTENCE ... i place git's diff at the bottom of the file in case he wants to look that over as well, but this cleans up the edits real nice
sdesol 13y ago
Disclaimer. I'm the creator of GitSense which is working on building advanced power tools for Git and GitHub. The diffing problem is solved quite easily with the Google Diff, Match, Patch algorithm and our Smart View technology. When GitSense was created, it was obvious that we all work differently and we all have different needs which was why we made it insanely customizable. If you are not familiar with the Google Diff, Match, Patch algorithm, you can learn more about it here: https://code.google.com/p/google-diff-match-patch/ https://code.google.com/p/google-diff-match-patch/ I've also put some screen shots of what the diff results for two markdown files would look like at: http://screenshots.gitsense.com/google-diff-patch-match.html http://screenshots.gitsense.com/google-diff-patch-match.html The context aware source code that is used in GitSense to display the diff can be found here: http://screenshots.gitsense.com/google-diff-match-patch-integration.js http://screenshots.gitsense.com/google-diff-match-patch-inte...

by scottfr 13y ago

nadaviv 13y ago

> Changes are tracked by line which is equivalent to a paragraph in a book. When using Markdown, I usually split paragraphs over multiple lines (usually between sentences) which makes diffs much easier to read, while still rendering as a single paragraph.

vidarh 13y ago
Same here. "Single line paragraphs" are a pet hate of mine - they have no place in plain text files even if those files are intended to be post-processed.
- tasuki 13y ago
  I'm still undecided on this. Say you have a long paragraph and have to add one word at the beginning. You have two options - either rewrap and introduce a silly diff, or don't rewrap and exceed your chosen text width. Single line paragraphs don't put such a difficult choice in front of you. If your diff software is any useful, it'll highlight your change within the line.
  - gknoy 13y ago
    Perhaps you could have a special kind of commit, a "text-rewrap" commit (similar to merge commits), which might let your diff presentation tool alternate between diffing lines, pararaphs, or the like. I agree, the presentation layer really needs to be as granular as your editing team needs to be. I __really__ like how Github shows the differences within a line that is different.
  - nadaviv 13y ago
    That's why I don't use fixed-width. I break lines up logically, usually at the end of a phrase/sentence, regardless of their length.
- breadbox 13y ago
  Absolutely, but you still have the issue that a minor wording change can cause an entire paragraph to be marked as changed if your editor re-wraps the paragraph. Or, if the editor doesn't rewrap the paragraph, then they slowly get more and more ragged over time, making it annoying to read through. A diff tool that understands paragraphs is an essential tool for this project.
- gabemart 13y ago
  I disagree with this. In a plain text file that consists of prose, line breaks are presentation, not content. Hardcoding them into the file doesn't appeal to me. It makes editing a pain in the neck. It also means the line breaks have to be removed again if you want to move between formats.
  - gknoy 13y ago
    That sounds like an editor issue, though. You should be able to reflow a paragraph, indent it or whatever it as you like. A compromise might be to break lines on sentence boundaries: edits are often constrained within sentence or paragraph boundaries, and then diff would give more meaningful output for most sentences. ^-- This one sentence is two lines long, though, so perhaps my idea is not that good. Diffs would still be easier to read than if each paragraph were one line.
jamie_ca 13y ago
I know people who break lines per phrase/clause, rather than per sentence. You wind up with lots of very short lines, but that doesn't matter after Markdown is done processing. The benefit is some _very_ granular diffs that are easy to read, as you work out rewording things in the editing process.

cinger 13y ago

i write quite a bit with git, and recently brought an old collab project with a friend onto it. i do all of the git work, and i just have my friend add my edits to his document, then he sends it back and i diff the two for potential errors... he requested it be this way because he is stuck in his ways, but we've agreed to go full git on book two in the series... that said, when i first started sending him diff files we both saw this as a problem... my solution? i just wrote a script that i run on the diff to just highlight the changes made, then send him the new edited diff. -PARAGRAPH +PARAGRAPH becomes : -SENTENCE -word...word +word...word +SENTENCE ... i place git's diff at the bottom of the file in case he wants to look that over as well, but this cleans up the edits real nice

sdesol 13y ago

Disclaimer. I'm the creator of GitSense which is working on building advanced power tools for Git and GitHub. The diffing problem is solved quite easily with the Google Diff, Match, Patch algorithm and our Smart View technology. When GitSense was created, it was obvious that we all work differently and we all have different needs which was why we made it insanely customizable. If you are not familiar with the Google Diff, Match, Patch algorithm, you can learn more about it here: https://code.google.com/p/google-diff-match-patch/ https://code.google.com/p/google-diff-match-patch/ I've also put some screen shots of what the diff results for two markdown files would look like at: http://screenshots.gitsense.com/google-diff-patch-match.html http://screenshots.gitsense.com/google-diff-patch-match.html The context aware source code that is used in GitSense to display the diff can be found here: http://screenshots.gitsense.com/google-diff-match-patch-integration.js http://screenshots.gitsense.com/google-diff-match-patch-inte...