Add Spec for Metadata Extension #451

Merged
prologic merged 3 commits from lyse/yarn:master into master 1 week ago
lyse commented 2 weeks ago
Collaborator

Finally! Please have a look at this draft.

For your convenience the rendered version is available here: https://lyse.isobeef.org/tmp/twtxt/doc/metadataextension.html

Finally! Please have a look at this draft. For your convenience the rendered version is available here: https://lyse.isobeef.org/tmp/twtxt/doc/metadataextension.html
lyse added 1 commit 2 weeks ago
461f2c5683 Document Metadata Extension
lyse reviewed 2 weeks ago
Whenever a physical line in a twtxt file starts with a hash sign (`#`) it is
considered a comment. The comment ends at the end of the line. Comments are
usually ignored by twtxt clients and can appear anywhere in a feed. Comments
must not be preceded with whitespace.
lyse commented 2 weeks ago
Poster
Collaborator

Or should we also allow whitespace in front of the # character introducing the comment?

Or should we also allow whitespace in front of the `#` character introducing the comment?
Poster
Owner

Nope. Let's be strict here.

Nope. Let's be strict here.
lyse marked this conversation as resolved
line. Multiline values must use the Unicode line separator `U+2028` just like
multiline twts do.
All whitespace around field names and values must be stripped. There might be
lyse commented 2 weeks ago
Poster
Collaborator

Do we really want to allow multiple hash signs in front of a field?

Do we really want to allow multiple hash signs in front of a field?
movq commented 2 weeks ago
Poster
Collaborator

To keep parsing easier, I’m almost inclined to restrict this to just # foo = bar, so one # and no whitespace in front of it.

To keep parsing easier, I’m almost inclined to restrict this to just `# foo = bar`, so one `#` and no whitespace in front of it.
lyse commented 2 weeks ago
Poster
Collaborator

We're now not allowing multiple hashes anymore.

We're now not allowing multiple hashes anymore.
lyse marked this conversation as resolved
#description =This feed tells about my everyday adventures.
```
## Standardized Fields
lyse commented 2 weeks ago
Poster
Collaborator

Any other standard fields to include here?

Any other standard fields to include here?
lyse commented 2 weeks ago
Poster
Collaborator

Addded following, followers and link.

Addded `following`, `followers` and `link`.
lyse marked this conversation as resolved
movq reviewed 2 weeks ago
# field-name = field value
```
Fields with the same name can be merged together to a multi value field. The
movq commented 2 weeks ago
Poster
Collaborator

What’s a multi value field? 🤔 Or is this just another name for a multiline field?

What’s a multi value field? 🤔 Or is this just another name for a multiline field?
lyse commented 2 weeks ago
Poster
Collaborator

Not sure how to really call that. With multi value field I mean a field which has several values, like url or follow. Both fields might occur more than once and thus the field names might have an array of values after merging. But that's perhaps too close to my own implementation and we need to try to be more general in the spec. Maybe don't introduce a concept of merging at all and keep the fields as individuals.

Open for any suggestions. :-)

Not sure how to really call that. With multi value field I mean a field which has several values, like `url` or `follow`. Both fields might occur more than once and thus the field names might have an array of values after merging. But that's perhaps too close to my own implementation and we need to try to be more general in the spec. Maybe don't introduce a concept of merging at all and keep the fields as individuals. Open for any suggestions. :-)
movq commented 2 weeks ago
Poster
Collaborator

Ahh, I see.

When I first read it, I thought it’d be legal to merge # follow = foo foourl and # follow = bar barurl into a single # follow = foo foourl, bar barurl or something like that.

Maybe something like this?

It is legal for the same field name to appear more than once. The format
allows this, but it doesn't make sense for all fields. For example, it
is reasonable to have many `# follow =` fields (one for each feed that a
user is following), but you probably won't find multiple `# avatar =`
fields.

(Then again, maybe it even makes sense for # avatar =, for example when you’re announcing various image formats. 🤔)

Ahh, I see. When I first read it, I thought it’d be legal to merge `# follow = foo foourl` and `# follow = bar barurl` into a single `# follow = foo foourl, bar barurl` or something like that. Maybe something like this? ``` It is legal for the same field name to appear more than once. The format allows this, but it doesn't make sense for all fields. For example, it is reasonable to have many `# follow =` fields (one for each feed that a user is following), but you probably won't find multiple `# avatar =` fields. ``` (Then again, maybe it even makes sense for `# avatar =`, for example when you’re announcing various image formats. 🤔)
lyse commented 2 weeks ago
Poster
Collaborator

I like that phrasing a lot, thanks! 👍 Let's go with that. I just replace the avatar with the description example, since in fact there might be several avatars. Probably not so common with descriptions. Thought about nick at first, but if somebody goes by several nicks in general or is in the transition of renaming themselves, that would be a more likely counterexample.

I like that phrasing a lot, thanks! 👍 Let's go with that. I just replace the `avatar` with the `description` example, since in fact there might be several avatars. Probably not so common with descriptions. Thought about `nick` at first, but if somebody goes by several nicks in general or is in the transition of renaming themselves, that would be a more likely counterexample.
lyse added 3 commits 2 weeks ago
929de3b452 Rephrase section on fields with same name
0b81be4ce6 Don't allow multiple hashes in fields
6d66c58935 Support more fields
lyse reviewed 2 weeks ago
It is legal for the same field name to appear more than once. The format allows
this, but it doesn't make sense for all fields. For example, it is reasonable
to have many `# follow =` fields (one for each feed that a user is following),
lyse commented 2 weeks ago
Poster
Collaborator

Do we want to call it "# follow = fields" or "follow fields"? Any preferences?

Do we want to call it "`# follow =` fields" or "`follow` fields"? Any preferences?
Poster
Owner

I think the later is beetter?

I _think_ the later is beetter?
lyse commented 2 weeks ago
Poster
Collaborator

Went with the name only.

Went with the name only.
lyse marked this conversation as resolved
prologic changed title from WIP: Document Metadata Extension to Add Spec for Metadata Extension 2 weeks ago
prologic added 1 commit 2 weeks ago
a45944d915 Merge branch 'master' into master
prologic approved these changes 2 weeks ago
prologic left a comment

LGTM 👌

Owner

Merge when ready and happy with the content. I think it looks pretty decent. 👌

Merge when ready and happy with the content. I _think_ it looks pretty decent. 👌
movq reviewed 2 weeks ago
---
In the wild several twtxt users came up with metadata comments in their twtxt
files for different purposes. So the **Metadata** extension is not truely
movq commented 2 weeks ago
Poster
Collaborator

truly? Or should we use actually?

Dunno, I’m not a native speaker, either. 🥴

`truly`? Or should we use `actually`? Dunno, I’m not a native speaker, either. 🥴
lyse commented 2 weeks ago
Poster
Collaborator

Thanks! Yeah, I went with actually and swapped it with not. To my ears that order sounds a tiny bit better for actually. Although, not sure if this is correct.

Thanks! Yeah, I went with `actually` and swapped it with `not`. To my ears that order sounds a tiny bit better for `actually`. Although, not sure if this is correct.
lyse force-pushed master from a45944d915 to e14346ab5f 2 weeks ago
Poster
Collaborator

Before merging I'd like to squash everything into a single commit to keep the history clean. I believe it's just easier for you reviewers to see what changed in new commits.

Now that contentwise everything seems to be fine, let's focus on grammatical and stylistic things. I'm pretty sure there's a comma missing somewhere and on other places where I used one, the English rules actually don't want one (perhaps even in this sentence you're reading right now ;-)).

Before merging I'd like to squash everything into a single commit to keep the history clean. I believe it's just easier for you reviewers to see what changed in new commits. Now that contentwise everything seems to be fine, let's focus on grammatical and stylistic things. I'm pretty sure there's a comma missing somewhere and on other places where I used one, the English rules actually don't want one (perhaps even in this sentence you're reading right now ;-)).
lyse force-pushed master from e14346ab5f to fa1136c2f0 2 weeks ago
Poster
Collaborator

Squashed into a single commit.

Squashed into a single commit.
lyse force-pushed master from fa1136c2f0 to 638b4e0abb 2 weeks ago
Collaborator

Looks good to me! 👍

(I don’t have an informed opinion about commas and grammar, though, as I’m not a native speaker.)

Looks good to me! 👍 (I don’t have an informed opinion about commas and grammar, though, as I’m not a native speaker.)
prologic added 1 commit 1 week ago
bd5d42fe3f Merge branch 'master' into master
prologic approved these changes 1 week ago
prologic added 1 commit 1 week ago
094477bcda Merge branch 'master' into master
prologic merged commit b39f4a49ef into master 1 week ago
prologic referenced this issue from a commit 1 week ago

Reviewers

prologic approved these changes 1 week ago
continuous-integration/drone/pr Build is passing
The pull request has been merged as b39f4a49ef.
Sign in to join this conversation.
Loading…
There is no content yet.