Filemark URLs part 2

2024-05-19 @equalsraf

I need a format to store file annotations. That is a list of locations that and associated data such as comment text. Initially I though I needed a higly structured file format for this, but decided against it for a way to embed references in other formats.

A URL schema for file marks

A file mark points to a location in a file. These are commonly used by text editors however the definition of "location" may vary. Some times it points at a line, other times it includes specific position inside the line.

Here is a proposal for a URL format for file marks

This particular example:

• points to a path some/path/file.txt
• the mark refers to line 33

The line argument can be either a line number or a range of two numbers which specifies a range of lines (the range is inclusive).

Other details to note:

• the first line is line 1
• file path is encoded as an absolute path

File hashes

The url can include a hash of the file (md5) so we can identify if the file being marked is correct.

The hash is for the entire file.

Description

A description for the marked region

This needs to be url encoded.

Links

A URL with the link attribute is converted into an actual file link instead of code.

Implementation

I have two pieces of software to implement this. The first one is a vim plugin to generate the URLs, the second is a renderer that converts gemtext files with these URLs into files with the original source code.

The vim plugin allows you to:

• generate URL for a given file
• generate URL for a range of lines inside a buffer

The renderer only work with gemtext files, but it can generate both gemtext and markdown as output. It should not be hard adopt the same approach to markdown input. In essence the renderer is a tool that replaces URLs with URLs, or URLs with code blocks (from other files).

References