This looks great! Here's my comments, such as they are. There ended up
being quite a lot of them, but it's a huge spec. Fortunately, I don't
think any of them are very substantial.
p. 5: I don't understand the 'red' parts. I read it as they're red
because they're underdefined in the UML but fully defined in the text, but
I think what it actually means is that they're fully defined in a *later*
figure, cf 'ListOfColorDefinitions' in figure 2 (red) vs. figure 6 (blue).
Is this correct? If this text could be more clear, that'd be great.
p. 8: FillRule: It would be nice if at least a brief overview of what
'nonzero' and 'evenodd' mean was included, instead of only having a
reference to SVG.
p. 9: Figure 1 would be slightly more clear with dotted lines showing
where the defined parts end and the extrapolated bits begin, ideally
p. 10 line 28 is a comma splice: "...that complements it, this way..."
Making it a period or maybe a semicolon would work.
p. 10 section 3.3.1 I didn't understand this section at all. What has to
be unique, and why? Are these SIds that have to sort of be unique, or
p. 12: DefaultValues: The default values are both optional, and all their
attributes are optional, so what happens if a rendering application
encounters a situation for which there is no default? Does it give up?
Should it pick whatever it wants? Also, I can make an educated guess that
global defaults can be overridden by local default, which can be overridden
by specific declarations on particular items. But I don't see this
actually written up anywhere.
p. 14: versionMajor and versionMinor: Are these holdovers from when
Render was an l2 package? Do they still serve some purpose? If they're
functionally equivalent to the level of the package itself, I don't think
we need them any more, unless you want them for some sort of backwards
compatibility issue? Either way, it's hard to tell from the spec what the
purpose of these attributes is, nor what their values should be.
p. 14: "can encode that version information there is no relation to the
SBML attributes level and version." <-- not grammatical, and I can't tell
what is being said.
p. 15: versionMajor and versionMinor again. Do these have to match the
ones on p. 14? What do they mean? What version is this specification?
What does it mean that "All minor versions within a major version have to
be compatible."? What does 'compatible' mean in this context? Also, it
sounds like minor versions have to be *forward* compatible with other minor
versions which sounds difficult.
p. 15: referenceRenderInformation. It says, "A program reading and
interpreting the render information can use this information to access
another render information object, should the current object contain
unsuitable information." I don't know what 'unsuitable' means. Missing
information? Incorrect information? Correct information that cannot be
used by the current interpreter?
p. 16: referenceRenderInformation: I don't know what 'already been defined'
means. Is this a holdover from when order was important? If so, it will
need to be changed, since order is supposed to be irrelevant in L3 packages
(which should be simple enough; just say 'no loops'.)
p. 16: backgroundColor: Are there a list of allowed strings for this, or
can I put in whatever I want? Is it legal to have a backgroundColor of
'dusty rose', 'off-white' 'puce', or 'grasshopper'? Is there any
relationship between 'backgroundColor' and ColorDefinitions? If so, what
is it? If not, why isn't there? EDIT: OK, now that I've read the rest of
the spec, my guess is that this is supposed to be one of the 'hex value or
ColorDefinition reference' elements. It would be nice if this was defined
as a Type, so you only had to describe it once, and you could answer my
other questions re: formatting.
p. a bunch: Many classes claim to derive from the 'ListOf' class, but
there is no such class defined in SBML core. There's a ListOf class
defined in libsbml, but that's not in the spec.
p. 16: 'classand' <- missing space.
p. 18: "Style is an abstract class..." As far as I can tell, Style is not
an abstract class, but a normal class. Nothing seems to derive from it,
p. 18: "Note this relationship is only valid if there is no render
information object that is more specific." It would be nice if there was a
single global list somewhere of what was specifically meant by this. There
are types, roles, IDs, local and global things that might have ids and
roles and styles too (maybe?)... A single place that defines what the order
is would be great.
p. 19: There's a weird symbol in the example XML that looks like a bracket
fell over in the middle of "SPECIESGLYPH SPECIESREFERENCEGLYPH" (where the
space should be).
Figure 6: The ColorDefinition UML implies that the attributes are
required, but the text says otherwise ("In addition the ColorDefinition
object has the optional attributes id and value.")
p. 20: The 'value' attribute claims to be a '6 to 8' digit number, but if
I'm reading it correctly, 7 digits would actually be illegal. Probably
should be '6 or 8'.
p. 20: The 'value' attribute values are confusing as to how they should or
may be written. The text gives a value of "0xff" but then the example has
"#200000". Do you have to use the "#" form? Could you put in "0xff" (or
"0xFF") as the attribute and have it mean the same thing? Could you give
the base-10 version? What are the options; what is legal, and what is not
p. 20: 'offset': This claims that the attribute must be defined either as
x1, y1, z1, or as fx, fy, fz. What about cases where there are only two
displayed dimensions? Must a '0' be supplied for the 'z' position, or is
it OK to only provide x and y?
p. 20: 'spreadMethod': This claims to be an attribute of type
'GradientSpreadMethod' in the text, but the UML claims the type is
'spreadMethod'. 'GradientSpreadMethod' should also be used in Figure 1 and
Figure 7: The UML defines a 'Stop' class, but it is a 'GradientStop' class
in the text. And would its element name be 'stop' or 'gradientStop'?
p. 21: 'stop-color': It seems to me that it might be possible to have a
hexadecimal color value that was also the ID of a ColorDefinition, i.e.
'ff'. Is this wrong? It would be helpful to define explicitly what is
meant by 'a hexadecimal color value', here and elsewhere.
p. 21: "adjusted to be either 0% is the given value..." <- 'if', not 'is'.
p. 21 "The offset of any gradient stop has to be greater or equal to the
offset of the preceding gradient stop. If a gradient stop has an offset
that is smaller than the offset of the preceding stop, the offset is
considered to have the same value as the offset of the preceding stop." It
seems weird to me to simultaneously say that a particular condition is
illegal, and then proceed to say what to do when that illegal condition is
met. Maybe make this a validation warning instead of a validation error?
Or just don't say what to do if you get an illegal model?
p. 21 "If two gradient stops have the same offset value, the last gradient
stop with this offset value determines the color at this point in the
gradient." Is this order-dependent? If so, it should be replaced by a
statement that it's simply illegal to have two gradient stops with the same
p. 22: "The attributes x1, y1 and tokenz1 " and then later "The attributes
x2, y2 and tokenz2": latex error.
p. 22: In general, it's odd to me that all of the attributes of a
LinearGradient and a RadialGradient are optional. Aren't at least all the
x and y values required? Are there situations where
Figure 8: I can't tell by eye what bits from the XML correspond to what
bits of the figure. Where exactly do 000F60 and 000FF6 correspond? Can
you draw out the gradients, and say why they're going the way they're
going? Not knowing SVG, I can't tell what's going on here.
p. 23: 'should be positive' If only 'should', what happens when it's
negative? If it's an actual error to be negative, change to 'must'.
Figure 9: It would be nice to have labels for this one too, as there is for
Fig 8. Also, I thought that something that went from one color to another
and then back had to have spreadMethod of 'reflected'? Am I just wrong, or
is there a 'reflected' somewhere that's not displayed in the example?
p. 23: "The Transformation class is a common base class for all elements
that can be drawn. Since both the Layout package and the Render package are
currently limited to two dimensions, this class is only used as a base
class for Transformation2D and we leave the complete specification of this
class for a future version of this document." I don't think this statement
is true--there are a variety of things in the layout spec that have a third
dimension. Does this mean we need a Transformation3D element, too? If
not, just say, "Even though we can do 3D things, there hasn't been any call
for a Transformation3D class, so we haven't created one yet." or something.
p. 24: "A Transformation has a required attribute transform consisting of
an array of type double." However, the UML claims that the type is
p. 24: "This specifies an affine transformation matrix in three dimensions
in which case the array must consist of exactly 12 values." Didn't you
just say you couldn't do a 3D transformation? What's going on here?
p. 24-25 It would be nice to confirm that in the illustrated case, the
child object ends up getting transformed twice--once by the transform on
itself, and once for the transform on its group. Assuming that this is
p. 25: I'm going to guess that since Render is overlaid on top of Layout,
that if something is not specified, that means that the renderer can do
whatever it likes, just like it could with layout? So in general, Render
is an optional layer that can parts of information to a layout to add
*some* render information, but need not add *all* render information? It
would be nice to have this stated explicitly somewhere, perhaps in the
proposed 'what are the defaults' list--it's probably also worth mentioning
that if nothing in Render defines an aspect of the drawing, the tool is to
pick something that makes sense to it.
p. 25: stroke-width: What are the units of the stroke width? Pixels?
General: You have types listed in the same font as classes, which is not
the standard for the SBML core specification. (FillRule,
GradientSpreadMethod). This greatly confused me the first time I was
reading, as I assumed those were classes, not types. Also, all the links
go to the section in general, and not to the particular type listed.
p. 26: 'form the Layout package' -> 'from the Layout package'
p. 27: listOfElements: This is an ordered list, which in general we try
to avoid in SBML packages, though perhaps here it can't be avoided? In
other packages, we get around this by adding an 'index' attribute. Render
is old enough that perhaps it's OK and we can grandfather this in, but it's
probably worth checking with the editors.
p. 27: What is this 'xsi' namespace? It's never defined, and never stated
why we're using it. Also, it's called 'namespaces' and probably should be
'namespace'. And... why? Why do you need it, if it's always the same
value? It seems to compensate for the fact that the element name is
'element' instead of 'renderPoint'--was that an old decision that can't be
revisited at this point?
p. 28: It would be nice to see the actual curve produced by this XML,
illustrated by showing the control points, vectors, etc.
p. 30: "That is the last point" -> "That is, the last point"
Figure 13: This is great! This is exactly the sort of figure I would have
liked to see for the other elements.
p. 31: width, height, rx, ry: Am I correct that even though the type of
these values is the RelAbsVector, that the vector in question should only
be one element long? Is there a check for that somewhere? It might be
useful to have two different types, RelAbsValue and RelAbsVector, since
there are (I think) a lot of attributes that can only have one value in
p. 31: ratio (both): Must these be positive values? If not, what do
negative values mean?
p. 31: "we limit the display of text to normal text, outlined or
filled-outlined text are not supported." Using a comma here is basically
incorrect--either break off the second bit as a new sentence, or use a
p. 32: Can the Image class be given a 'name'? We usually give a name
attribute to anything with an ID.
p. 32: "within it’s bounding box" -> its
p. 33: "not to RenderCurve objects within the group/needis that not a
contradiction" What? Was that a note to yourself that accidentally was
uncommented? I don't know what is going on here.
p. 33: " andvtext-anchor" need space.
p. 33: various 'font' attributes: Are these again sort of local defaults
for their children, but which their children can override with more
specific entries? If so, this needs to go on the 'defaults' table (that
doesn't yet exist, but which I would like to see).
p. 33: "necessarty" -> necessary
p. 33: Another class with an 'id' that should probably also be given a
p. 34: enableRotationalMapping attribute: This is listed as an optional
attribute, but not only is it Boolean, you also (much later) claim that it
has a default value, which is a no-no in L3 packages. The attribute should
Figure 15: Another great figure.
p. 67: "If the enableRotationalMapping attribute is set to “true”, which
is the default" The attribute should have no default (see above)
p. 67: "The first example as depicted in Figure Figure 24" figure
references in LaTeX no longer need the additional word 'Figure'. (same for
p. 67: "arrow heads coordiante" -> coordinate
p. 69: "in the normlized vector" -> normalized
p. 67-69: Capitalize the first word of your three steps ('calculate' ->
p. 71: " if there are several styles with the same specificity, the first
one encountered in the file is to be used." More file-order dependence!
Can we get rid of this, and just say that it's wrong to define the same
p. 71: Ah, here's the section I wanted on defaults. It is basically OK,
but I think I would like some more clarity and some examples. Also, where
I was complaining earlier, maybe add a reference to section C.2.
p. 71: "One of these initiatives, the sboTerms, is about to be included
into SBML Level 2 Version 2." Wow, this spec has been around forever,
hasn't it? If you want to use sboTerms to define roles, you should
probably decide now if you want to do so. If not, just drop this section,
or say why this was never implemented.
p. 71: I'm still not 100% sure how style/roles/defaults work, as far as
what the full scope of precedence is. It seems like there are maybe 8
different ways to define something. It would be nice to have an example
that had all eight defined, and told you why the one that took precedence
took precedence, then said what happened if that was undefined, then if the
next was undefined, etc.
p. 71: "(see also Appendix 3.3.2 on page 12)." Section 3.3.2 is not an
I ran out of steam and didn't read the validation rules, but yay them being
On Wed, Apr 15, 2015 at 7:07 AM, Frank T. Bergmann <fbergman@...>
> Dear Members of the PWG,
> Over the past months we worked on getting the render specification into the
> official format for SBML Level 3 packages, and of course to ensure we have
> validation rules for all the bits and pieces. In time for HARMONY we
> to you now a first draft that you find under:
> and would ask for your feedback.
> All the best,
> Frank Bergmann,
> on behalf of the authors
> BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
> Develop your own process in accordance with the BPMN 2 standard
> Learn Process modeling best practices with Bonita BPM through live
> sbml-render mailing list