6 ms·
Suggestions: A simple human-readable format for suggesting changes to text files
- mock-possum 3y agoDoesn’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.
- dash2 3y agoI'll think about that. Some syntax like %%[ % ... would work % for an aside... %%] but I wonder if it is too much effort for most people to arrange. The html formatter prints comments in <aside> blocks, which is possibly incorrect but the closest semantic match.
- jayd16 3y agoI 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.
- jimbobthrowawy 3y agoUntil 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.
- bsmith89 3y agoI've been looking for something like this! I'm wondering how it compares to https://github.com/CriticMarkup/CriticMarkup-toolkit https://github.com/CriticMarkup/CriticMarkup-toolkit I haven't tried using either yet; does anyone here have any opinions about features/ergonomics/tooling?
- dash2 3y agoCriticMarkup 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".
- drwu 3y agoI guess the way to suggest merging two paragraphs: --[ ]--++[ ]++
- dotancohen 3y agoOr perhaps just leave a comment %%[The following paragraph should be merged into the preceding paragraph. @dotancohen]%%
- deleted 3y ago[deleted]
- Iwan-Zotow 3y agoUnified diff?
- qiller 3y agoNot quite as easily readable by most humans...
- abdusco 3y ago`<pre>` blocks show up too short for me. The culprit is the `overflow: auto` property. Here's a screenshot of the bug: https://ibb.co/bdF6gMn https://ibb.co/bdF6gMn
- crazygringo 3y agoAs a format, it seems great and intuitive. 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?
- ashton314 3y agoI 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.
- dash2 3y agoA lot of academics use TeX. I hate TeX, but use rmarkdown a lot. Then there are alternatives like typst.app.
- shermantanktop 3y agoTex, 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.
- StableAlkyne 3y agoTo 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
- deleted 3y ago[deleted]
- dash2 3y agoThanks for all the comments. The software is at https://github.com/hughjonesd/suggestions https://github.com/hughjonesd/suggestions; it’s my first rust project and very early stage. Thoughts on the spec are very welcome. I’m considering --[ deleted // added]-- as a shorthand for a common case.
- lyjackal 3y agoOne 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?
- dash2 3y agoThat's a really interesting point, I'll think about it. There's a tension between "making it clear what the change is" and "making it clear what the old and new versions are". One approach would be something like --[MOVED X: blah blah blah]-- ... +[FROM X: blah blah blah]++. A more radical one is --[>>>]-- ... ++[<<< blah blah blah]++ where you actually delete the content from its old position, leaving only a marker.
- SOLAR_FIELDS 3y agoIsn’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
- thunderbong 3y agoIf I recall correctly, WordPerfect had special characters like this for formatting documents.
- encody 3y agoIs there a way to annotate suggestions with a timestamp?
- fsckboy 3y agodifferent 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.
- petepete 3y agoThis seems sensible but I'm not sure it's going to be much simpler than git/GitHub. The syntax is quite close to git's --word-diff syntax The [-old-]{+new+} word is better
- dash2 3y agoI'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.
- ellisv 3y agoI’m going to be a little facetious but how did you get your coworkers to adopt suggestions? I’m not sure using git is any more or less difficult than suggestions.
- dash2 3y agoIf it isn't, I've failed. I think you can learn suggestions in 5 minutes. I've been using git for 10 years and still feel like an amateur.
- deleted 3y ago[deleted]
- petepete 3y agoI'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).
- anonyme-honteux 3y agoGit 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
- azophy_2 3y agoThis 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.
- _a_a_a_ 3y ago@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.
- da39a3ee 3y agoIf you care so much then style it yourself. Please don't bore the rest of us with your personal style opinions. No-one's forcing you to read it.
- _a_a_a_ 3y agoIt was @author, and I thought they'd like to know. A 50% whitespace margin is surprising. > style it yourself Not my area (am back end guy). Can you give some links, I don't know how to, TIA
- nektro 3y ago> Use a version control system like git, which is complex and technical. we don't need to create a new tool just to stop people from learning the right one
- aaron695 3y ago[dead]
- BeFlatXIII 3y agoGit’s defaults are no good for prose. Can’t make line-by-line comments easily and the default diff is worthless for paragraphs.
- frumiousirc 3y agoEven simpler: Step 1: give me your edited `.tex` file. Step 2: I selectively merge it into mine. Step 3: There is no step 3. To selectively merge, I use `meld` https://meldmerge.org/ https://meldmerge.org/ but there are others. Benefits of this even simpler approach: - We continue to use the tools we are used to. - We and our software don't have to learn a new inline diff format. - Both files retain valid syntax before and during the selective merge. - I can choose chunks to accept with a simple mouse click instead of editing a diff chunk.
- from-nibly 3y agoBut what about comments?
- jawns 3y agoAs 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.
- dash2 3y agoI’m considering this for the suggs command line tool. You can already autoaccept or reject all changes.
- ellisv 3y agoI’ve never had much of a problem with how git handles markdown or Tex files. For those using markdown, I highly suggest newline after every sentence.
- rubyfan 3y agoI’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.
- cxr 3y agoThe 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.)
- dash2 3y agoWhat's your email address?
- cxr 3y agolettersregardingdavidnotknowingwhatprecedemeans@cold.moon
- dash2 3y agoStop talking to your email server! 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?
- cxr 3y agoIf 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.
- howdyhowdy 3y agoThere'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.
- owenpalmer 3y agoIt'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.
- dash2 3y agoHow about twine? https://twinery.org https://twinery.org
- deleted 3y ago[deleted]