Suggestions: A simple human-readable format for suggesting changes to text files | Hacker News Reader

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

suggestions.ink

112 pointsdash266 comments

Open articleView on HN

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

Should be fixed now.

The newline addition is broken now. Everything is spaces

Yep, makes absolutely no sense. I was going to comment about it, I think this is the issue I'm seeing.

Hopefully fixed now. CSS is not very newbie-friendly :-(

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?

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.

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

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

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.

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?

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

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

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?

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

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.

But what about comments?

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.

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

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.

> 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

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

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.

Unified diff?

Not quite as easily readable by most humans...

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.

But this isn't markdown, right?

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.

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

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

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

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

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

> Git is designed for code and is terrible/overcomplex for words

I think this is not git problem, rather diff tool it's using? Wonder if using another one, e.g. difftastic[1] would be a better experience.

[1]: https://github.com/Wilfred/difftastic

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.

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.

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.

Maybe a distinct syntax for multiline and another for single line changes?

Think 'heredoc' like syntax or  from XML/xhtml.

Too complex? It’s got to be super easy to use…

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.

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.

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.

How about twine? https://twinery.org

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.

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

Is there a way to annotate suggestions with a timestamp?

I guess the way to suggest merging two paragraphs:

--[

]--++[ ]++

Or perhaps just leave a comment

  %%[The following paragraph should be merged into the preceding paragraph. @dotancohen]%%

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

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

It 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

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

What's your email address?

lettersregardingdavidnotknowingwhatprecedemeans@cold.moon

Stop 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?

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.

But the -- clashes with the delete symbol…

Whose fault is that?

My fault, sure, but you didn’t suggest a better delete symbol. One would be ~~[ ]~~ but I think it’s less intuitive for the average person.

I see the strength of your argument, but I suspect it works better for the extremely online.

> you didn’t suggest a better delete symbol

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?

1. <https://news.ycombinator.com/item?id=38791539>

I think your argument works better for the extremely online.

What?

Reply on news.ycombinator.com