An alternate perspective, if looking for feedback

[jasonjmcghee]

i wrote this as a comment on HN, thought I’d copy it here.

An important aspect of markdown is hand authorship.

Markdown Annotations are certainly interesting and I understand where the hash idea came from, but this requirement adds friction to hand authorship, and requires new custom parsing logic for markdown renderers.

I would argue it should instead be:

• file.md
• .file.md.owners

Where the owners file is generated / readable by a program supporting this behavior, along with a reference to the original file and its hash.

This provides the same information and capabilities, while decoupling it from the source. It also means you can retroactively generate ownership without modifying original work.

[hamatosan]

If I understand the provided examples correctly, the ownership is marked using the format

$author: $starting_position,$length $starting_position,$length $starting_position,$length ...

The main problem with hand authorship is not that the block is inside the file, it's that any edits to the text result in the starting positions and length being wrong after each edit with a non-annotations-aware editor. Moving the annotations into a dotfile makes the main file more tidy, but doesn't solve annotations being wrong after every manual edit. (And it would require manual editing the dotfile after each edit instead of just updating one file.

An alternative would be to embed the ownership into the text, but the good folks at iA correctly didn't walk that path as it would distract from the content and riddle the text with custom markup. Their blog entries make me think they put a lot of thought into this.

I guess if you're e.g. using git to version your writing, you can probably do some clever plumbing using diff to check text against the previous version and update the annotations if required as part of the commit, but frankly that sounds like the horrible stuff we did with svn hooks 20 years ago.

It's also not simply possible to regenerate the annotation block or dotfile, for iA Writer cannot possibly know the changes without access to the version history, and chances are that normal (read: non-programmer) writers don't use version control. I don't own iA Writer so I cannot tell if it uses Apple's builtin file system versioning - scratch this paragraph if it does, because then it can access the older versions and update the annotations. In that case, dotfiles would be fine as the user would never need to see or update them. Otherwise just leave the annotations in the file, that way a person hand-editing a file at least would be immediately aware of the annotations without having to check the folder for dotfiles or sidecars.

[andreagrandi]

i wrote this as a comment on HN, thought I’d copy it here.

An important aspect of markdown is hand authorship.

Markdown Annotations are certainly interesting and I understand where the hash idea came from, but this requirement adds friction to hand authorship, and requires new custom parsing logic for markdown renderers.

I would argue it should instead be:

• file.md
• .file.md.owners

Where the owners file is generated / readable by a program supporting this behavior, along with a reference to the original file and its hash.

This provides the same information and capabilities, while decoupling it from the source. It also means you can retroactively generate ownership without modifying original work.

I also vote for this approach. The main reason people use MarkDown files is because they are portable across platforms and different apps. If one app starts injecting proprietary content in the file, a different app won't be able to handle it.

If one day these annotations become standard, then you are very welcome to include them in original .md files, but until then you are injecting proprietary tags inside a file which is expected to be "standard".

Please reconsider your approach and at least give an option to the users to have these additional data saved in a separate .owners file (which can be easily ignored by processors).

I intend to use iA Writer to edit my .md content I publish on my Hugo bases website (but it could be Pelican, Jekill base etc....) if you leave these proprietary tags inside the .md file, it will be rendered in the final HTML file.