* Added HACKING file to CMML codec plugin directory, which includes

  description of what it does and how it's implemented.

* Overview of the CMML codec:

  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>.

* CMML codec 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.

diff --git a/modules/codec/cmml/HACKING b/modules/codec/cmml/HACKING
new file mode 100644 (file)
index 0000000..9fcebf3
--- /dev/null
+++ b/modules/codec/cmml/HACKING
@@ -0,0 +1,103 @@
+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).
+