Suggestions: A simple human-readable format for suggesting changes to text files

[abdusco]

`<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

[dash2]

Should be fixed now.

[crazygringo]

As 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]

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.

[dash2]

A lot of academics use TeX. I hate TeX, but use rmarkdown a lot. Then there are alternatives like typst.app.

[dash2]

Thanks for all the comments. The software is at 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]

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?

[bsmith89]

I've been looking for something like this!

I'm wondering how it compares to https://github.com/CriticMarkup/CriticMarkup-toolkit

I haven't tried using either yet; does anyone here have any opinions about features/ergonomics/tooling?

[dash2]

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".

[frumiousirc]

Even 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/ 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]

But what about comments?

[jawns]

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.

[dash2]

I’m considering this for the suggs command line tool. You can already autoaccept or reject all changes.

[azophy_2]

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.

[rubyfan]

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.

[nektro]

> 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

[BeFlatXIII]

Git’s defaults are no good for prose. Can’t make line-by-line comments easily and the default diff is worthless for paragraphs.

[ellisv]

I’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.

[Iwan-Zotow]

Unified diff?

[qiller]

Not quite as easily readable by most humans...

[fsckboy]

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.

[dash2]

But this isn't markdown, right?

[petepete]

This 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

[anonyme-honteux]

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

[dash2]

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.

[mock-possum]

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.

[jimbobthrowawy]

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.

[jayd16]

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.

[dash2]

I'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.

[owenpalmer]

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.

[dash2]

How about twine? https://twinery.org

[howdyhowdy]

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.

[thunderbong]

If I recall correctly, WordPerfect had special characters like this for formatting documents.

[encody]

Is there a way to annotate suggestions with a timestamp?