Publish the vdir spec independantly

[WhyNotHugo]

I intend to publish the vdir storage format as a standalone page. Ideally, something like https://vdir.pimutils.org.

Currently, the vdir storage format is documented in vdirsyncer's documentation. This somewhat gives the impression of being an implementation detail of vdirsyncer. I'd like to push it a bit more as a standard which other desktop clients can rely on. I intend for different applications that support a vdir storage to point here for canonical documentation.

I will likely keep this single-page, with the spec itself and some FAQ at the bottom -- nothing too fancy really, it's all about the content itself. I do intent to reword some bits, without changing meaning.

I will take into considerations proposals to enhance the spec, within reason, but honestly have nothing in mind and don't want anything incompatible with existing tools. It does low-key bother me that filenames themselves are meaningless, but I also don't have obvious suggestions for improving this. Trying to represent internal data in filenames (e.g.: DTSTART or whether an item is recurring) would have the side-effect of requiring a filename change when content changes -- this is no acceptable.

I think that proper extensions should become mandatory tho (e.g.: ics to icalendar, vcf for vcard, etc). This prevents conflicts with metadata files and makes the content-type self-describing.

Comments, @geier, @untitaker ?

[untitaker]

I intend to publish the vdir storage format as a standalone page

the only consideration i made there was to reduce the amount of static sites that have to be maintained. maybe a middle ground here could be to publish under pimutils.org/vdir and rework that entire website. then it's documented outside of the tool as well.

It does low-key bother me that filenames themselves are meaningless, but I also don't have obvious suggestions for improving this.

i remember that early revisions of the spec did hard-require all files to be named <UID>.ics, but was changed for a few reasons:

• i wanted tools to be able to write their own proprietary indexing metadata into the .ics file. now obviously there is plenty of potential conflict there for tools to overwrite each other's metadata, so this never happened. but if somebody wanted to write a script to periodically rename all .vcf files to <firstname>-<lastname>.vcf, then vdirsyncer shouldn't stop the user from doing that.
• the current naming scheme did not provide any performance benefit for any tool at the time, and in fact every tool ended up writings its own index anyway.
• the actual deciding factor: by removing requirements, the spec becomes easier to implement. IIRC specifically ppl suddenly was compatible with vdirsyncer even though it did not intend to impl vdir.

I think that proper extensions should become mandatory tho (e.g.: ics to icalendar, vcf for vcard, etc). This prevents conflicts with metadata files and makes the content-type self-describing.

at least as per spec, ics and vcf are basically the only two allowed file-extensions for items. it's invalid to add foo.txt into the vdir. maybe vdirsyncer is too configurable in this regard though and allows the user to do wrong things.

[WhyNotHugo]

On Sun, 10 Mar 2024, at 16:03, Markus Unterwaditzer wrote: a middle ground here could be to publish under `pimutils.org/vdir` and rework that entire website. then it's documented outside of the tool as well.

+1. I can rework the main site into gohugo and publish the spec as a page with it.

• *the actual deciding factor:* by removing requirements, the spec becomes easier to implement. IIRC specifically ppl <https://github.com/henrycatalinismith/ppl> suddenly was compatible with vdirsyncer even though it did not intend to impl vdir.

+1

> I at least as per spec, ics and vcf are basically the only two allowed file-extensions for items. it's invalid to add `foo.txt` into the vdir. maybe vdirsyncer is too configurable in this regard though and allows the user to do wrong things. >

Yeah, I think that making extensions configurable was a mistake. I’d say a txt is allowed and applications can ignore it. If someone wants a README it’s fine. Same as any other formats. Only the metadata file names as reserved. I considered updating those to displayname.meta, color.meta, etc, but don’t like the idea of breaking compatibility.

…

-- Hugo