Indirect inclusion of images and other objects

[mbakeranalecta]

The SAM language spec predefines the meaning of certain insert types in order to allow editors to interpret them and pull in the image or object if available. These are:

• image
• video
• audio
• feed
• app

These are only supposed to be used for direct inclusion of each object type. However, in the structured writing book, I have violated this rule by using image for the indirect inclusion of several images. Indirect in this case means that the href used is not that of the image file but of an XML file that lists various versions of the image for use in different media.

    >>>(image ../graphics/Object-vs-dots.xml)

This is a very useful practice, but it violates the rule that an image include should be processable by an editor. It also affects what we can do in HTML output mode in the way on including images. So since the usage in the structured writing book is non-standard, it ought to use a custom include type.

The question is, should the concept of indirect inclusion be built into the SAM language spec. And what, generally, is a reasonable way of doing this. For instance, would it be reasonable to reserve or at least recommend indirect forms of the predefined set:

• i-image
• i-video
• i-audio
• i-feed
• i-app

Or should we say that part of indirection is allowing for a different kind of object altogether for different media, for instance, a video for online and a graphic for print? In this case, does it make sense to add another media neutral reserved type:

• indirect

The problem with any of these suggestions is they are at least slightly less functionally lucid than having the writer simply enter >>>(image ../graphics/Object-vs-dots.xml), as evidenced by the fact that it was months before I realized there was an issue with this.

The other way to handle this is to change the rule about what the predefined include types mean to include the possibility of indirection. In this case, the editor or HTML output mode trying to process them would have to look at the href and figure out, by whatever method seemed best (looking at the file extension being the most obvious) if this was a file it new how to display, and showing the appropriate warning, either as a parser warning or as text on the output page, if it did not know how to process that type. This is pretty much what a browser does, so this is not a left field solution.

[mbakeranalecta]

Given the notion that an indirect insertion may be type neutral, perhaps we need to add a neutral type to the reserved list:

• object

There may be no predefined semantics for this, meaning that editors and HTML output mode can't do anything with it, but it would provide a convention for saying, put something here of a type you decide appropriate.

[mbakeranalecta]

Actually, since HTML5 has a generic object tag for generic object inclusion, a generic object image type for SAM does make sense, and could have recognizable semantics for editors and HTML output mode. Adding it as a reserved type therefore makes a lot of sense independent of the issue of how to handle indirect inclusion.

[mbakeranalecta]

Fundamentally, this is a question of whether the insert type specified the type of object being inserted or the type of mechanism being used to insert the object.

If it names the type of mechanism being used to insert the object, that makes it easier for the processing code, but harder for the writer. It also limits the known semantics to know insert mechanisms, meaning that any mechanism we don't anticipate needs custom markup and custom code.

The overriding design goal of SAM is to direct complexity away from writers, which always means directing it to developers. The simplest thing for the writer is to name the type of object they are inserting, so that is what the semantics should be. This does mean that an editor, for example, would have to look at the object identifier provided and decide if it knew how to fetch the named object or not, but that is an appropriate redirecting of complexity.

That said, object should be added to the reserved list.

[mbakeranalecta]

object has been added to the reserved insert type list