The OMC compiler and the simulation executables it builds feature hundreds of option flags, most of them quite useful for intermediate-level users which are not members of the inner circle of developers. How to obtain up-to-date information about them is quite obscure for people who do not belong to that circle and just read the documentation, and generates a lot of frustration and bad feelings about the whole environment in new users. This need not be the case!
Some documentation of the omc flags is actually present in the System Documentation, though there is no guarantee that it is always up-to-date (BTW, it would be nice to have means of automatically generate these sections from the source code). If one reads carefully, it is also possible to understand that by running omc +help one can get up-to-date information, as long as the developers take care of documenting their flags in the code, which most people do. However, this not stated explicitly and this information is not highlighted as it should.
As to the simulation flags, there is absolutely no mention of it anywhere, just try to do a text search for LOG_NLS or -emit_protected in both the System Documentation and User's Guide (see also #2051). The simflag argument of the simulate API function is mentioned three times in the User's Guide with an empty string as default, which is a bit infuriating.
My modest, but rather pressing, proposal:
- Add a new Section 2.1.1 to the System Documentation, entitled: "Getting help on all the compiler options" which clearly states in the text that running omc +help gives information about that, and that more in-depth information can be obtained by running, say, omc +help=optmodules. Say explicitly that omc +help=simulation gives help about the parameters that influence the run-time simulation, and that are passed to the simulation executable. Refer to Section 5 for a detailed description of the values of the simulation flags.
- Add information in Section 5 of the System Documentation (currently empty) about simulation flags, how to set them when running omc from the command line, when invoking the simulation executable directly, when using OMEdit, when using OMShell and when using OMNotebook. Explain how to obtain an up-to-date list of all flags and of all their values.
- In section 2.5.1 of the User's Guide, mention explicitly that an exhaustive list of the optional compiler flags is available in the System Documentation, section 2.1
- In section 2.5.3 of the User's Guide, refer to System Documentation, section 5, for an exhaustive list of the optional simulation flags is available in the System Documentation, section 5
- In section 14.1.5 of the User's Guide, simulate command, add pointers to the documentation that explain what can be used in cflags (that would be System Documentation, Section 2.1, I guess), simflags (ditto, Section 5), and also information about method (see also #2480)
- In section 14.11.5 of the User's Guide, for all other API calls that have input arguments corresponding to some omc or runtime flags (e.g. setIndexReductionMethod, setPastOptModules), add pointers to the appropriate sections in the System Documentation
- In OMEdit, Simulation setup window, add buttons to open the relevant documentation files next to the input fields with optional flags
See also #2913