I'm just curious who this is for? I've done lots of collaboration with Word and Docs. And with code in git.
But I'm having a hard time imagining the scenario where you would be using a plaintext file to make suggestions.
Like is this for committing documentation changes in git but you want someone else to review them first?
Or is this meant for e.g. papers in LaTeX?
Or something else? I just feel like I'm missing the full context here. When do you need to provide suggestions but it's important to be plaintext rather than rich text like Word/Docs?
I am a PhD student. Collaborating with people writing LaTeX is a little tricky when you want to add comments and such. I like this little format: it might make it easier for me to work with people on the same paper.
My workflow is a .tex file checked into git repository that everybody has full access to. We do a lot of face-to-face conversation to make sure that we are synchronized with our changes, which I think is a really good thing, but it is nice adding commentary in line. Instead of some ad hoc system with comments, this scheme adds a little bit more discipline that might be welcome.
Tex, for when you want to fit in with all the other PhD candidates, who want fit in with the professors, who want to fit in with their mentors, who insist that their journals use Tex, because “everyone uses it.”
I understand it has some actual virtues as an editor/programming language, but to me (a non-academic) it seems to mostly function as a group membership signifier.
To be fair, one could outcrack even the most cracked of the crackpots, and as long as it was in the default style that every LaTeX article uses, it would immediately have a veneer of credibility
One thing that especially git fails at, is content that’s been moved around. Moving content is a simple and powerful editorial tool, but it starts to make any simple diff incomprehensible, showing large sections as added and removed.
Curious if you’ve thought about attacking this problem, or have seen any other tools that solve it elegantly?
Isn’t the latter one how git works? I think one difficulty with the former from git’s POV is that it’s difficult to divine the difference between moves and add/delete without the end user explicitly specifying that they’ve “moved” a file. One easy to grok example is moving a file to one location and creating a copy of that file in another location in that same diff. Perhaps in this approach that same limitation does not exist
CriticMarkup seems to emit more correct HTML, but is more demanding (e.g. it recommends against embedded newlines). It doesn't emit TeX. It does have more (i.e. any) editor syntax files.
I mildly prefer having the marks outside the brackets: ++[foo]++ seems easier to read than {++foo++} because the "wrapping" is outside the "box".
As a writer who has had to deal with suggested changes by editors extensively, I would say that it is weighted toward the user experience of the _reader_, not the user experience of the person who has to actually accept or reject the changes.
If I am the person who has to incorporate these suggested changes into my document, having to delete two segments, one on either side, for each change is not an ideal experience.
If this type of formatting does become adopted, I would recommend that the process of accepting or rejecting the change be done programmatically, rather than manually. I could envision a small utility program that is fed a file with this text format and allows the user to interactively accept or reject the changes without having to do the deletions within the file itself.
This is a hacky workaround for medium with limited capabilities, but I like it.
The proper way is of course to actually use format/tools/apps with builtin feature for such needs, as addressed in the beginning of the landing page. There is initial cost for adopting it, but if you actually doing it regularly (novelist/journalist/programmer) it would make more sense in the long run.
In the end its about tradeoff. If your medium is limited and you only need it for once in a while, this format is simple & clear. But for more frequent uses I think this format is costly to maintain compared to using specialized tools/apps.
I’ve been looking for a tools like this that will help me work with Typst files. I was an engineer but now work on specialized legal contracts with lawyers. Most of them know the basic track changes in Word. I grew up with code and source code management so the idea of templates, including partials and managing differences between them all is something I’m looking for but my colleagues don’t really know about (or want to deal with).
I’ve been toying with the notion of using Typst as the source of truth to assemble contracts so I’m going to give this a spin.
different people have different perceptions of what markdown is, what its goals are/should be.
html started simple, and went down a path of unreadable complexity.
markdown has already started down that path with the mathjax stuff, urls, images, etc, all of it ugly and paradigm shattering. The markdown document should be fully readable; the new changes are making it "nope, you're gonna need a viewer". I think people gonna need to learn to comfortably read markdown.
i'm not opposed to this suggestion (as if what i think matters to anybody but me), but seems to me it needs to be considered in light of other semantic needs other usages might want, and hopefully the discovery of common syntax elements that serve multiple/overlapping purposes, something that's not simply one weird scheme within another weird scheme. This syntax seems busy. What's the justification for each and every additional character?
I'd rather see (maybe/depending) a diff based "view both side by side" sort of tool working from two versions of the file, perhaps with an annotation file. I'd differentiate between changes that fix typos ("must haves") vs fixing language/meaning ("requests")
I think it's a big mistake to go the way that C (for example) went, where every possible ascii character has a meaning, and nothing can be changed without breaking it.
markdown needs a Benevolent Dictator for Life for the time being.
You accidentally used markdown as an example of a plain text format, and programmers have a trapped prior that everything uses markdown, so even putting it after TeX won't avoid this sort of comment.
Git is designed for code and is terrible/overcomplex for words.
A proper vcs for documentation is what Wikipedia does.
You always see the latest version of a document and you can see the changes to that document, revert and follow renames.
No global history, no commits of multiple files, no manual pull/push, no branches, no CI, no pr, no rewrite of history, no multiple remotes, etc etc etc
I wonder how difftastic would handle a paragraph that got reflowed via a gqip command. Would it show almost every word as changed or only the changed words and ignore the fact that many others now reside on different lines?
If you teach a beginner to use GitHub Desktop lots of the complexities you mention above are smoothed over.
The PR/MR is the biggest win, being able to comment on, discuss, suggest, resolve and 'sign off' changes works better in a PR/MR than any other versioned tool I've seen.
I've tried to get coauthors to move to github and it is a huge blocker. Even just installing git is painful, then they have to learn about add/commit/pull/push. They don't get it.
I'd recommend trying GitHub Desktop. I've had plenty of success helping content designers get to the level where they can directly contribute to projects (instead of pinning a Word doc to a JIRA ticket).
Doesn’t seem awful - ++[, —[, and %%[ are all pretty unlikely to collide with the content of your average document.
It is a bit messy once suggestions get nested, and given the option I’d still strongly prefer visually separating the change suggestions from the original content by pulling them out to aside blocks, but - if you held a gun to my head and forced me to do it all in plaintext, I wouldn’t hate this method.
Until they start using this system for suggesting changes to the documentation for this system itself.
I am unsure if the suggestion files are meant to just be snippets long enough to uniquely identify where changes are meant to go, or the whole file again but with change suggestions.
I don't know that nesting is a problem. It's somewhat nonsensical from a single edit perspective and if we're allowing multiple edits merged together then all bets are off on making sense of this or working with it.
If two deletions partially overlap then they can't be acted on easily either.
It's a shame that git is too complicated for most non-programmers. I've always wished my sisters (who are all avid writers) could use the branching functionality to explore different possibilities for their fictional stories. It's a beautiful tool but hopelessly unintuitive.
There's also the todo package for latex that has worked really well. Doesn't help much for markdown though I suppose. You can specify colors for different types of notes and can render said comments inline or in the margins.
@author, Thanks for this, will read, but your webpage is 50% white space; there's almost nothing on the left with all content pushed into the right half. I'm used to this kind of breakage with jscript disabled but (kudos!) you don't use any. FYI.
The markup/formatting of their paragraphs-and-newline example is messed up. Also:
> %%[Is this clearer? @stephen]%%
> You can sign the comment with a @handle as the last word.
Author seems to fundamentally misunderstand the significance of having "@" precede the names of folks in the conventions of online discourse. "@" means "at". You're addressing someone. In this example, they're signing off, instead—the exact opposite. Their prescribed format means that if you encounter a message like the one in the above example somewhere in the wild, then you have to be very careful to stop and consider the context to disambiguate between whether it was written by someone (who is not Stephen) expecting Stephen respond to the question, or whether it was written by Stephen himself expecting someone else to answer. This is bad design.
(The choice of "%" to denote comments is also pretty odd—particularly for a format that's supposed to be more human-centered than other more traditional formats. It strikes me as something that was arbitrary more than anything else.)
More seriously, it's called an "address" because people can "address" you with it. There's a natural overlap between at-ing somebody, and putting your name up so that people can at you. The @ sign helps clarify that is what this is, and it also differentiates it from the text. Have you got a simpler and more intuitive alternative?
If someone writes "Is this clearer? @stephen" today, that looks like a person who is not Stephen trying to direct their question to Stephen. It's not the most conventional way to do it, because the most common practice would be to address Stephen at the beginning of the message, but it's still unambiguously a message for Stephen, not from Stephen. That's literally what it means: This is directed at Stephen.
The linked proposal reverses this by turning "@foo" into a signoff/attribution instead of an address, increasing the amount of ambiguity in communication—"Wait, what conventions are we following? The natural way of reading things, or are we in the world of Suggestions files where up is down?"
> Have you got a simpler and more intuitive alternative?
Yeah, the way people have been doing it forever:
--stephen
You don't need to invent new syntax for it, let alone counterintuitive syntax.
Someone else already pointed out the existing "plain word diff" syntax[1] that (a) is actually more human-friendly and (b) neither you nor the other respondent actually addressed—you both just pirouetted around it while hoping that no one would notice, I guess (by changing the subject to how bad Git and GitHub are—true, but completely irrelevant to the merit of using --[foo]-- over [-foo-]).
> One would be ~~[ ]~~
That would be genuinely terrible—for basically the same reasons that --[foo]-- is worse than [-foo-], but more extreme.
> it works better for the extremely online
I thought this was supposed to be designed for actual human beings?
https://ibb.co/bdF6gMn