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

by dash2 • 3 years ago

112 66 3 years ago

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.

dash218• 3 years ago

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.

mjevans• 3 years ago

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

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

jayd16• 3 years ago

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.

jimbobthrowawy• 3 years ago

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.

bsmith89• 3 years ago

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?

dash218• 3 years ago

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

drwu• 3 years ago

I guess the way to suggest merging two paragraphs:

--[

]--++[ ]++

dotancohen• 3 years ago

Or perhaps just leave a comment

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

Iwan-Zotow• 3 years ago

Unified diff?

qiller• 3 years ago

Not quite as easily readable by most humans...

abdusco• 3 years 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

dash218• 3 years ago

Should be fixed now.

Tyr42• 3 years ago

The newline addition is broken now. Everything is spaces

crazygringo• 3 years ago

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• 3 years ago

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.

dash218• 3 years ago

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

shermantanktop• 3 years ago

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.

dash218• 3 years ago

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• 3 years ago

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?

dash218• 3 years ago

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.

thunderbong• 3 years ago

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

encody• 3 years ago

Is there a way to annotate suggestions with a timestamp?

fsckboy• 3 years ago

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.

dash218• 3 years ago

But this isn't markdown, right?

juped• 3 years ago

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.

petepete3• 3 years ago

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

dash218• 3 years ago

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.

ellisv2• 3 years ago

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.

petepete3• 3 years ago

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

anonyme-honteux• 3 years ago

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

ivanjermakov• 3 years ago

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

petepete3• 3 years ago

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.

azophy_2• 3 years ago

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.

_a_a_a_2• 3 years 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• 3 years ago

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.

_a_a_a_2• 3 years ago

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

nektro• 3 years 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

BeFlatXIII2• 3 years ago

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

frumiousirc• 3 years ago

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• 3 years ago

But what about comments?

jawns• 3 years ago

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.

dash218• 3 years ago

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

ellisv2• 3 years ago

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.

rubyfan• 3 years ago

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.

cxr6• 3 years ago

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

dash218• 3 years ago

What's your email address?

cxr6• 3 years ago

lettersregardingdavidnotknowingwhatprecedemeans@cold.moon

howdyhowdy• 3 years ago

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.

owenpalmer• 3 years ago

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.

dash218• 3 years ago

How about twine? https://twinery.org

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

Related Stories