|
Larry,
Sorry I didn't see the comments earlier. I didn't scroll far enough before looking at the change draft and the github issue and didn't see that there was comments on the items not updated in the document.
My comments on some of the items are below in red.
Jim
On 4/15/19 4:31 PM, Larry Golding (Myriad Consulting Inc) wrote:
Hi Jim,
With the exception of "location relationships" which we're still considering, the items you list below are the ones we decided not to take. I sent you an email with responses on all your items, including rationales for the ones we did not take. I've attached it here to share it with everybody. I suppose I should fill out #366 with the rest of the responses.
Thanks,
Larry
The following suggestion was rendered moot by the changes we accepted:
-
Appendix D no longer uses the lack of a converter version number to justify the now-removed advice against synthesizing properties, so the text that incorrectly stated that a converter doesnât have a version number has been removed.
We could discuss whether the general guidance for version numbers on tool components should be changed. As the spec stands, all the versioning properties
MAY be present. Iâd be open to tightening that, for instance, âAt least one of version or semanticVersion
SHOULD be present.â
This would be reasonable statement to add about the versions.
Here are explanations on some of your other feedback items:
-
With regard to your question about the distinction between
toolComponent.productSuite, product, and
name, think âMicrosoft Office/Excel/Excel Charting Toolâ.
It would be useful to state that name is intended to be displayed to users as the tool's name, and that viewers may display this as part of a table the name should be short; ideally it should not include line breaking characters,
the company name, version information, product or productSuite that are available in other properties.
Move the product and productSuite section to immediately follow the name section as they are similar concepts. In the product and productSuite properties state that
these can be used to form a hierarchy of related software: name can be part of a product which can be part of a productSuite.
-
With regard to your suggestion to provide a short (20-30 character) human readable name for a
reportingDescriptor that is localizable and not necessarily stable, we do have such a property:
reportingDescriptor.name. See Â3.46.7 in the provisional draft (Â3.44.7 in the e-ballot-3 draft). We donât provide explicit guidance on its length, but the example given ("SpecifyMarshalingForPInvokeStringArguments")
conveys the idea.
There should be advice similar to the above section. Viewer should use the name of the descriptor (or the id in its absence) to label this type of issue to users. The name should be short as it may be displayed in tabular
views that have limited horizontal space. It should not include line breaking characters.
-
With regard to your suggestion in Â3.15.2 (externalPropertyFileReference.location) that we not restrict
uriBaseId, this section does not actually introduce a new restriction. Â3.4.4 (artifactLocation.uriBaseId property) already says:
If the uri property contains an absolute URI, the
uriBaseId property SHALL be absent.
Although strictly speaking thereâs no need to repeat that in Â3.15.2, I think itâs helpful, so I added
these words:
If location is present, its
uri property SHALL be an absolute URI using the
sarif scheme (Â3.10.3), and
so (by Â3.4.4) its uriBaseId property
SHALL be absent.
My point here was that this text says that if you are using a sarif scheme URI, then the location SHALL NOT include a uriBaseId. I think that the uriBaseId should be allowed. It seems perfectly reasonable to create a baseUriId
named INLINED that has a uri="sarif:/inlineExternalProperties", and to then have a location of {uriBaseId="INLINED", uri="0"}. To support this, the text should just say that the resolved location SHALL be an absolute URI with a sarif scheme.
For the following suggestion, we have two proposals:
-
âAdd more languagesâ. We donât want to be in the business of proposing an exhaustive list, or even of presenting a list that spans many pages. Here are two options:
a) In the Appendix, add a statement to the effect that this list is just a start, and we expect the community to develop it over time.
b) Remove the Appendix.
I would add just a couple of more languages to cover more of the languages in the top-n lists (if you add these and format as 2-columns it will fit on one page).
visualbasic
visualbasicdotnet
objectpascal
r
d
groovy
lisp
lua
prolog
scheme
ada
rust
julia
haskell
erlang
actionscript
clojure
ocaml
We decided not to take the following suggestions:
-
With regard to the suggestion to introduce toolComponent.abbreviatedName, we prefer to add guidance to the effect that the tool name should be narrow because you never know where itâs going to be displayed, and if the
name is long, at least make sure that its leading portion is sufficiently informative to survive the name being truncated.
Adding guidance would be useful for the tool name and descriptor names would be useful. There is commentary in 11 and 12 above.
-
With regard to the guidance around toolComponent.shortDescription and
fullDescription: We understand that converters canât always follow the guidance; converters are always at the mercy of the native output format. And a tool author who writes in a language with no sentences, or who writes
a message whose first sentence canât be readily identified, should follow the guidance and supply both short and full descriptions.
Unless a first sentence algorithm can be defined, then viewers can not follow this document. It would be better to just say that if the shortDescription is not present, viewers MAY displays a truncated version of the fullDescription
such as the first 100 characters, the first paragraph, or the first sentence. This description is something that a viewer can easily do and gives the viewer latitude in how to truncate the text.
-
Likewise for toolComponent.shortDescription and
fullDescription.
-
Likewise for the guidance in Â3.11.3 about plain text messages (we did take the suggestion to remove the restriction to a single paragraph).
|