--- /dev/null
+What's CMML?
+------------
+
+This is an implementation of the Continuous Media Markup Language
+(CMML) for VideoLAN. In short, CMML is a (XML) markup language for
+time-continuous data, which of course includes multimedia such as
+video and audio. It allows one to annotate a media file with both
+structured and unstructured textual data, but one of its distinguishing
+features--and what this code implements--is its support for embedding
+hyperlinks in media files.
+
+So, while viewing some media (e.g. a radio interview with a band),
+you could provide a hyperlink to any URL, including a standard web
+page or other media (e.g. the band's home page). The hyperlinks
+are active only for specific intervals of time while the media is
+playing, so for example during a radio interview, the hyperlinks
+can change depending on what questions the interviewer is asking
+and topic is being discussed.
+
+For more general information on CMML and its role in the bigger
+picture of extending the World Wide Web to properly support multimedia,
+see <http://www.annodex.net/overview.html>. For specifications of
+CMML, see <http://www.annodex.net/specifications.html>.
+
+
+Usage
+-----
+
+Once you have hyperlinking capability, you take on some of the
+capabilities of a web browser, in particular following hyperlinks,
+and also maintaining a browsing history where you can go backwards
+and forwards between pieces of media you've linked to. So, if you
+are viewing a file with CMML markup:
+
+* Hyperlinks are displayed as a subtitle track
+
+* Hyperlinks are followed with the VLC "activate" hotkey (by default,
+ this is just the Enter key)
+
+* Going back and forward are done with the "history-back" and
+ "history-forward" keys, by default Cmd-[ and Cmd-] on Mac OS X,
+ and Ctrl-[ and Ctrl-] on all other platforms.
+
+Until the media browsing history features are made available outside
+of the CMML plugin, you can only use the history features while
+viewing a file that contains CMML markup: e.g. you cannot navigate
+backwards or forward in the history while viewing a standard MPEG
+video. This is a limitation which may be removed if the media
+browsing code is merged into the VLC core.
+
+
+Overview of the code
+--------------------
+
+First: a lot of this code could be implemented, or should be
+implemented, in VLC's core (libvlc) rather than be part of a codec
+plugin, either because it's something which really should belong
+in the core (e.g. media browsing history, system-indepedent interface
+to web browser) or a generally useful thing outside of the codec
+plugin (e.g. XML parser, URL handling library). That's well and
+good, but changes to libvlc are far-reaching and affect all of VLC,
+rather than only affecting a single plugin. It's sensible to
+gradually merge this stuff into libvlc on an as-needs basis, rather
+than trying to refactor out huge amounts of code at once.
+
+Here's a quick overview of what the files do:
+
+* browser_open.[ch]: A very simple attempt to provide a way to
+ open the system's web browser.
+
+* history.[ch]: Media browsing history (as described above in
+ "Usage").
+
+* xstrcat.h: Simple wrapper around strcat(1) which performs a
+ realloc(1) if needed.
+
+* xarray.[ch]: extensible (growable) array, similar to a Vector in
+ Java/C++. Could be replaced with a vlc_list_t from libvlc's
+ src/misc/objects.c if the vlc_list_t API were made public.
+
+* xlist.[ch]: Yet Another Linked List implementation (sorry guys
+ :), only here because XTag (see below) uses it internally.
+
+* xtag.[ch]: A very simple (but working!), lightweight XML
+ parser.
+
+* xurl.[ch]: A small URL handling library.
+
+* cmml.c: The actual 'codec' parser, which parses the CMML data
+ (demuxed from the incoming media stream, of course), and provides
+ two VLC vars ("psz-current-anchor-description" and
+ "psz-current-anchor-url") which enable intf plugins to display
+ the CMML data to the user and let them interact with it.
+
+* intf.c: Enables media browsing functionality by displaying
+ hyperlinks as a subtitle track, and responding to user
+ keypresses for following hyperlinks and navigating the media
+ browsing history.
+
+So, all the files except for cmml.c and intf.c could be made available
+and re-used outside of this plugin, but currently are not (for the
+reasons given above).
+