RFC 1: Event properties

[kochrt]

• Start Date: 2023-09-19
• Target Parser Version: 0.11.0

Summary

Add properties to individual events, separate from the header/frontmatter.

Basic example

---
title: My calendar
timezone: America/New_York
---

2023-09-19: Made an RFC
link: https://github.com/mark-when/rfcs/discussions

2023-12-24: Family call
attendees: <list of email addresses>

Motivation

Currently, tags in markwhen allow one to attribute properties to events:

---
title: My calendar
timezone: America/New_York
#family:
  attendees: <list of email addresses>
  timezone: America/Chicago
#github:
  color: red
---

2023-09-19: Made an RFC
#github

2023-12-24: Family call #family

However, events may have bespoke or one-off properties that tags may not be especially useful for. Consider singular events that belong to a certain tag, but we want to color differently:

2024-01-01: New Years #holidy
color: yellow

Maybe one event is in an atypical timezone that belongs on the event directly:

2024-08-04: Flight from Singapore
timezone: +8

Maybe an event has certain people associated with it:

2023-05-08: Gathering of intellectuals
going: <list of people>
notGoing: <list of people>

Supported use cases

• Syncing with calendars
  • If/when markwhen can ever be used as a calendar replacement, the need to refer to events by id may be necessary or at least very helpful. It seems

What about tags

I'm not sure. Event properties nearly obsolete the usefulness of tags - one could have a header entry that is then referred to via event properties, similar to how yaml does it:

---

---

This is an RFC in a very literal sense, it would be helpful to have input

Detailed design

Option 1 - Additive

The addition of properties could be completely additive, in that properties would be optional to use, all current markwhen documents would be successfully parsed, but one could add properties to events where needed. Tags would still exist.

Option 2 - Replace tags

Replace tags with event properties. Similar functionality to tags would be achieved by having event properties that reference entries in the header when necessary, or by having a property tag or tags on an event:

Option 3 - Different

This is the bulk of the RFC. Explain the design in enough detail for somebody
familiar with Vue to understand, and for somebody familiar with the
implementation to implement. This should get into specifics and corner-cases,
and include examples of how the feature is used. Any new terminology should be
defined here.

Drawbacks

Formality

The introduction of something like properties for events makes markwhen look more and more like a yaml document. I don't know if this is necessarily bad, it's just not how markwhen has operated up til now.

One of the key benefits of markwhen (in my opinion) is the very low barrier to entry. One can get very complex with their document, but it is certainly not necessary to start that way. Progressive disclosure is key. As soon as something starts to look like a very formal language

Why should we not do this? Please consider:

• implementation cost, both in term of code size and complexity
• whether the proposed feature can be implemented in user space
• the impact on teaching people Vue
• integration of this feature with other existing and planned features
• cost of migrating existing Vue applications (is it a breaking change?)

There are tradeoffs to choosing any path. Attempt to identify them here.

Alternatives

What other designs have been considered? What is the impact of not doing this?

Adoption strategy

If we implement this proposal, how will existing Vue developers adopt it? Is
this a breaking change? Can we write a codemod? Can we provide a runtime adapter library for the original API it replaces? How will this affect other projects in the Vue ecosystem?

Unresolved questions

Optional, but suggested for first drafts. What parts of the design are still
TBD?