search

AcademySoftwareFoundation / MaterialX

MaterialX is an open standard for the exchange of rich material and look-development content across applications and renderers.
http://www.materialx.org/
Apache License 2.0
1.88k stars 357 forks source link

"name" vs. "ref" #40

Closed meshula closed 7 years ago

meshula commented 7 years ago 
<constant name="c1" type="color3">
  <parameter name="value" type="color3" value="0.0,0.0,0.0" publicname="diffbase"/>
</constant>

In most cases name names an object.

nodename is confusing because it does not name a thing. I suggest "noderef".

publicname is confusing because it also does not name a thing, it indicates use, or semantic. I suggest "semantic"

Similarly, I suggest "fileref" as type for images, as opposed to "filename"

I suspect there are other uses of name I haven't spotted that don't name things but reference things.

dbsmythe commented 7 years ago

Sometimes the most difficult part of a project is figuring out what to name things. :-)

"nodename" was chosen because it refers to the "name" value of a node. Your suggestion of instead calling this "noderef" (and "fileref" in place of the "filename" type) are reasonable; we can take a look again at how xxname and xxref are used throughout the spec to see if better consistency can be achieved by renaming this and perhaps other attributes.

"publicname" has been in the spec for a very long time, like pre-1.14, and was intended to be an alternate, publicly-visible (e.g. from outside the nodegraph) name of something. Since this is defining an alternate name for an input or parameter, and the term "semantic" is already used in the context of types, I would personally be disinclined to change "publicname".

meshula commented 7 years ago

Went back to read the documentation of public name on page 18, it was easier to understand in light of your comment as to it being an alternate publicly-visible name.

Would you guys consider hosting the spec as a markdown file, perhaps in the markdeep dialect, in order to facilitate collaboration on the spec? I could then PR some wording changes that would have made it easier for me to understand :)

dbsmythe commented 7 years ago

I'm not sure I'd want to have an alternate copy of the Spec in live, editable form out there, if only because it would be too easy for it to become out of sync with the "real" spec document, and confusion could easily arise about what the real version of the Spec is. However, if you'd like to propose some alternate wording to make the Spec easier to understand, I'm very open to hearing them!

BTW- I would encourage discussions about the Spec itself to be done in the Google discussion group, at https://groups.google.com/forum/#!forum/materialx, and then reserve the GitHub issues for things about the code itself.

meshula commented 7 years ago

Ok, I'll take my questions over there.