Re: ISSUE-2147 (external-refs confusing): Section on externally referenced documents confusing [Last Call: SVG 1.2 Tiny ]

Hi Cyril and Doug.

Doug Schepers:
> That section of the spec is indeed pretty poorly written, with lots of
> repetition.  I cleaned it up and reordered it, though I didn't make as
> many changes as Cyril.  The attached file has the original, Cyril's
> reworking, and my rough draft.
> 
> I don't have a feel strongly about any of the content, though I agree
> the section needs a revision.

I just read through both of the rewordings, and they are both somewhat
better than the current text.  I have a couple of specific comments
though:

  * I think we should keep the sentence Cyril marked in red, but reword
    it a bit.  I think it is trying to say that if you have a large
    resource document that multiple primary documents reference, then
    these need to be logically separate instance of the document, but
    that in some cases the UA may be able to optimise this (if no
    scripts run in it and it’s not modified, or something).  While it’s
    not strictly necessary to point out where implementors may optimise
    (since implicitly they may optimise anywhere as long as they adhere
    to the conformance criteria), it still may be useful as an
    indication to authors that they may not necessarily get a
    performance benefit here.

  * I don’t think it’s necessary to introduce new subsections to
    introduce the primary/resource document terms, since those
    subsections are pretty short.

  * While referenced media are not shared across primary documents, I
    don’t think it’s necessary to discuss them, since they aren’t SVG
    documents (which is really what the whole section is dealing with).
    (Although my proposed text below does include it.) Perhaps the
    section should be retitled “Processing of external references to SVG
    documents” to be clear on that.

  * As mentioned before, it seems we don’t need to say anything about
    scripts.

Having said that, here is some proposed text that takes a bit of wording
from Cyril’s and Doug’s proposals, and a fair bit of my own:

  Processing of external references to SVG documents

  When an SVG user agent resolves an external reference to an SVG
  document, how the document is loaded and processed depends on how the
  document was referenced.  As defined below, an externally referenced
  SVG document or document fragment is classified as either a primary
  document or a resource document, and this classification determines
  the document’s processing.

  A primary document is an SVG document that is referenced, or an SVG
  document fragment that is included in another document, that is to be
  presented in whole by the user agent.  Specifically, the following are
  classified as primary documents:

    * An entire SVG document that is loaded into an SVG user agent
      for presentation, such as when navigating a web browser to an IRI
      that references an SVG document, whether by typing the IRI into
      the browser’s address bar, clicking on a link to that IRI, or
      having the Location.assign() method invoked.  (In an HTML 5 user
      agent, this is when an SVG document is part of a top-level
      browsing context ([HTML5], section 4.1).)

    * An entire SVG document that is loaded due to it being referenced
      by an 'animation' element.

    * An entire SVG document that is loaded due to it being referenced
      for inclusion by a parent non-SVG document for presentation, such
      as using the HTML 'object' or 'iframe' elements.

    * An SVG document fragment that is embedded within a non-SVG
      document that is being presented by the user agent, such as an
      XHTML document that has an 'svg' element child of an HTML 'div'
      element.  While the SVG document fragment is not a whole document
      in itself, it does act as a primary document for the processing
      purposes described below, and is distinct from any other primary
      document that may be embedded within the non-SVG document.

  A resource document is an SVG document that has been loaded because it
  is referenced as a resource by an SVG document fragment.
  Specifically, the following kinds of external references, all of which
  are references to elements, will cause the loaded SVG document to be
  classified as a resource document:

    * The 'xlink:href' attribute on a 'use' element 
    * The 'xlink:href' attribute on a 'font-face-uri' element
    * A paint server reference in a 'fill' or 'stroke' property

  Each primary document maintains a dictionary that maps IRIs to
  resource documents.  This dictionary is used whenever a resource
  document is to be loaded because the primary document or one of its
  resource documents references it.  Before loading a resource document,
  its IRI is first looked up in the primary document’s dictionary to
  determine if it has already been loaded.  If so, then that
  already-loaded document is used instead of creating a separate
  document instance.  Thus, for each primary document, a given resource
  document is loaded only once.  Primary documents, however, are always
  separate, self-contained document instances, and resource documents
  are not shared between primary documents.

  The IRI used as the key in the dictionary of resource documents must
  be the absolute IRI after resolving it against any applicable base
  IRI, and comparisons of the dictionary keys must be performed using a
  Simple String Comparison, as defined in section 5.3.1 of
  Internationalized Resource Identifiers [RFC3987]. 

  Whether a document is a primary document or a resource document, its
  processing once loaded is the same: events are fired, scripts are
  executed, an animation timeline is created and animations are run,
  stylesheets are applied (if supported by the SVG user agent), and so
  on.  Since a resource document is not just a static DOM, any changes
  to it (be they modifications by script or changing presentation values
  with animation) will be visible through all references to that
  resource document.

  Note that since IRI references to resources from different primary
  documents will result in logically separate resource documents being
  instantiated, an SVG user agent will in general not be able to
  conserve memory by having only one instance of the resource document
  in memory.  In the case that many primary documents all have
  references to a single, large, common resource file, this will
  probably result in a large amount of memory consumed.  If the SVG user
  agent is able to prove that the primary documents will behave exactly
  the same if a single instance is shared in memory (by using
  copy-on-write semantics for the resource documents, for example), then
  such an optimization may of course be performed.

  References to non-SVG resources, such as media, are not classified as
  primary or resource documents, and multiple references to media at a
  particular IRI always result in separate timelines being created.

I’m not convinced by my second last paragraph there, and wouldn’t mind
if it was omitted.  I think also some concrete examples should be
included here.

And a question: should resource documents be restricted to being entire
SVG documents, or can they be SVG document fragments within say an XHTML
document?

[blah.svg]
  <svg …>
    <use xlink:href='blah.xml#r'/>
  </svg>

[blah.xml]
  <html …>
    …
    <body>
      <svg …>
        <rect id='r' width='100' height='100'/>
      </svg>
    </body>
  </html>

-- 
Cameron McCormack ≝ http://mcc.id.au/

Received on Thursday, 30 October 2008 06:35:37 UTC