diff --git a/spec.asciidoc b/spec.asciidoc index 4c50b61..8f06ce8 100644 --- a/spec.asciidoc +++ b/spec.asciidoc @@ -86,36 +86,79 @@ The goal of the shows file is to: ** dedicated feed ** link to specialized page for the show +The syntax tries to be compatible with link:http://pyxml.sourceforge.net/topics/xbel/[XBEL], a bookmark +format. While this format has not seen extensive usage in the latest years, it's still valuable to reuse +someone else work instead of reinventing the wheel. + Here is an example: - - - - Learn to cook in C++ - http://radioexample.com/shows/learn-cook - http://radioexample.com/shows/learn-cook/feed - http://radioexample.com/shows/learn-cook.ics - - - Uncensored information - http://radioexample.com/shows/info - http://radioexample.com/shows/info/feed - - -(link:shows.xsd[Schema XSD]) + + + + Learn to cook in C++ + + + Learn to cook in C++ + learn-C++ + A podcast about C++, templates, and nouvelle cuisine + http://radioexample.com/shows/learn-cook + http://radioexample.com/shows/learn-cook/feed + http://radioexample.com/shows/learn-cook.ics + + + + + Information + + Uncensored information + + + Uncensored information + uncensored + News, news & more news + http://radioexample.com/shows/uncensored + http://radioexample.com/shows/uncensored/feed + http://radioexample.com/shows/uncensored.ics + http://radioexample.com/shows/uncensored.json + + + + + + +(XXX: Schema XSD is yet to be written) + +Only ``show:name`` is required, though parsers are invited to apply the Postel law and read the parent +``title`` element. + +The ``type`` attribute is available for ``show:feed`` and ``show:schedule``; it defines the mime type of the +resource, so that in the future different formats can be used. Right now, the default is +``application/rss+xml`` for ``show:feed`` and ``text/calendar`` for ``show:schedule``. + +``show:feed`` and ``show:schedule`` can be present multiple times; When this happens, the semantic is that +those files are equivalent, and can be considered different formats for the same data. The example shows +exactly this: here, the producer is providing the same calendar in both ICS and +link:https://tools.ietf.org/id/draft-kewisch-et-al-icalendar-in-json-00.html#RFC6321[jCal]. + +XBEL supports folders, and we want to be XBEL-compatible. However, the parser is free to flatten the folder +structure if they so prefer. In this case, they should use depth-first order when presenting the content to +the user. We encourage producers not to rely on the fact that the user will be able to use a tree-like +navigation. -Only ``name`` is required. A schedule can point to an iCal resource. All entries in the calendar are assumed to -be part of the show. === Relationship with schedule -It's pretty clear that in many cases shows.xml and schedule.ics will benefit from being linked. How to do -that? +It's pretty clear that in many cases ``shows.xml`` and ``schedule.ics`` will benefit from being linked. How to +do that? For every event in the schedule, apply this rules: - 1. If there is an ``X-SHOW-ID``, and it is the same as ```` - 2. If ``CATEGORIES`` include ```` - 3. If ``SUMMARY`` is the same as ```` + 1. If the VEVENT has a ``X-SHOW-ID`` field, see if a show with the same ```` exists + 2. If the VEVENT has a ``CATEGORIES`` field, see, for all categories, if a show has the same ```` + 3. If the VEVENT has a ``SUMMARY``, see if there is a show with the same ```` + +If any of this rule has a match, the event in the calendar belongs to that show. == Implementation details