Small typos and improvements

[clagms]

First of all, great work! It reads very well and already has a lot of useful content!

The following are notes from a quick read. Sorry that they are all gathered here, but it would be cumbersome to create separate issues for small things.

• In "Chapter 1. Introduction", we should probably make it clear that the guide is best read after having read the standard. The text clearly makes this assumption in many places.
• We should always use the same terms to refer to the importer and exporter, as per the fmi standard. Sometimes we use "importing implementation" and "master", and "co-simulation master", to refer to the same thing. Same with "exporting implementations" and "Implementations that produce FMUs".
• In "Robust participation, including testing with a relevant selection of available releases, is recommended.", I would make it clear that testing FMUs should be incorporated into the integration tests of the tool provider.
• In "FMU exporting implementations should also use the FMU Compliance Checker", I think we should include a link to a place where we collect links to all FMI utilities. It could be a wiki page, or part of https://fmi-standard.org/ . There we would classify tools according to whether they help exporters or importers, and it would include things such as the FMU Compliance Checker, Reference-FMUs, fmu-builder, VDMCheck and UniFMU.
• In "Exchange of FMUs can be eased tremendously if an option exists to generate FMUs that do not require license mechanisms at the receiving party.", maybe we need to detail what the alternatives are, to ensure IP protection without having to use license mechanisms.
• In "detailed information should be provided using the ports and icons information.", add a reference to where the ports and icons standard is defined.
• The following are potentially ambiguous references:
  • "allow the user to easily add those information items"
  • "Where that is not feasible, implementations should prefer"
  • "Ideally this support should include"
• In each subsection, we could use formatting to make it clear what are recommendations that apply to importers and what are recommendations that apply to exporters.
• In " the searched paths will be based on the importer executable", maybe clarify what "based on" means.
• In "preference should be given to native arrays over structured ", maybe clarify what native here means.
• In "Note especially that null pointers are not valid for any of the string arguments to these functions, unless explicitly allowed.", maybe clarify where it would be expicity allowed.
• In "or in combination with Section 6.2, as described below.", maybe clarify what is actually being combined.
• Avoid ambiguities by adding oxford commas to "However the exact semantics, capability flags and rules when to call this function vary between all
  major releases of FMI" so it becomes "However the exact semantics, capability flags, and rules when to call this function, vary between all
  major releases of FMI"
• Typos:
  • during creation of an FMU: Imports should, if more suitable
  • "false" should be "fmi2False" and "true" should be "fmi3True", or something like that.

[pmai]

Many thanks for the substantial feedback, many points of which are addressed in PR #43.

Feedback on some individual points:

In "Robust participation, including testing with a relevant selection of available releases, is recommended.", I would make it clear that testing FMUs should be incorporated into the integration tests of the tool provider.

I do not think we should speak to how tool providers implement our advice in terms of processes, that is their domain (in other words, if a tool provider needs this kind of advice they are beyond hope anyway).

"FMU exporting implementations should also use the FMU Compliance Checker", I think we should include a link to a place where we collect links to all FMI utilities.

I don't think we should do this in the guide, since one has to traverse the fmi-standard.org site to get to the guide (once it is published) anyway, and that site should include those links/pages. Otherwise we need to maintain this in multiple places.

I have however updated the wording on which tools to use to include the newer VDMCheck.

In "Exchange of FMUs can be eased tremendously if an option exists to generate FMUs that do not require license mechanisms at the receiving party.", maybe we need to detail what the alternatives are, to ensure IP protection without having to use license mechanisms.

This is most often not about IP protection, but rather DRM in the sense that exporters do not want to create FMUs that can be run by anyone without a license. The alternatives here are different business models which we cannot mandate in the document - this would be a compliance problem - hence the reticence here. We can just state that not requiring license mechanisms is beneficial in terms of usability.

I have however added a pointer to the IP Protection Appendix of the SmartSE Rec V2, which discusses the IP protection aspects in great detail.

In "detailed information should be provided using the ports and icons information.", add a reference to where the ports and icons standard is defined.

I don't think we currently have stable anchors in terms of the standard for external usage, hence linking directly is a tad problematic. But this is something we should discuss in fmi-design.

In each subsection, we could use formatting to make it clear what are recommendations that apply to importers and what are recommendations that apply to exporters.

That was the formatting of the original document, but that turned out to be fairly unreadable, lead to uneccesary duplication , and left the reader with little understanding: The expectation should not be to only read the parts that explicitly name exporters/importers to gain a sufficient understanding of the matter at hand.

In "Note especially that null pointers are not valid for any of the string arguments to these functions, unless explicitly allowed.", maybe clarify where it would be expicity allowed.

I have added that these places are defined in the respective standards. We do not want to duplicate this information here: The standards remain the normative references, we don't want to keep tool implementers from reading them to understand what they should understand.

In " the searched paths will be based on the importer executable", maybe clarify what "based on" means.

I have added location of the importer executable. Clarifying what based on really means would mean duplicating the whole Win32 API logic on this, which is complex and differs based on Windows version and flags. This is just to point out a not so obvious trap; implementers still need to read their OS API documentation.

[clagms]

Thanks for addressing the comments @pmai !