feat: Add error output to suggest possible causes when scenario parsing fails

[b-s-code]

Problem

A misplaced/misnamed/unlocatable XSD file is not easily identified by new users, from existing OpenMalaria stderr output.

This is a mostly a quality of life issue, where very experienced OpenMalaria users can generally infer the nature of the issue from existing stderr output contents. But only because they've already spent the time to learn what the symptoms mean.

Solution

Much of the code that gets called when parsing the scenario is generated (by xsdcxx) C++ code.

To avoid getting too involved with such generated code, I looked at what could be done in relevant code within OpenMalaria's source tree.

The solution presented in this PR is to simply print additional output to stderr when parsing fails, suggesting 2 possible causes to the user.

A notable limitation of this PR is it does not check the 2 suggested possible causes in order to determine which if any of them are actually responsible.

Testing

I tested before/after for 3 cases:

1. Scenario conforms to schema, schema is appropriately named/located.
2. Scenario conforms to schema, schema is wrongly named/located.
3. Scenario does not conform to schema, schema is appropriately named/located.

Scenario conforms to schema, schema is appropriately named/located.

This is the happy path. No change in output occurs.

Scenario conforms to schema, schema is wrongly named/located.

Before:

XSD error: instance document parsing failed
:0:0 warning: unable to open primary document entity 'scenario_48.xsd'
:22:234 error: no declaration found for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2000/xmlns/}om' is not declared for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2000/xmlns/}xsi' is not declared for element 'om:scenario'
:22:234 error: attribute 'name' is not declared for element 'om:scenario'
:22:234 error: attribute 'schemaVersion' is not declared for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2001/XMLSchema-instance}schemaLocation' is not declared for element 'om:scenario'
:29:66 error: no declaration found for element 'demography'
:29:66 error: attribute 'maximumAgeYrs' is not declared for element 'demography'

[...]

:341:55 error: attribute 'value' is not declared for element 'group'
:345:43 error: no declaration found for element 'computationParameters'
:345:43 error: attribute 'iseed' is not declared for element 'computationParameters'
OpenMalaria: No such file or directory

After:

Error: parsing scenario file failed.
        Likely the XSD file is not present at an expected location/with expected filename,
        or the scenario file example_scenario.xml does not conform to the relevant schema.
instance document parsing failed
XSD error: instance document parsing failed
:0:0 warning: unable to open primary document entity 'scenario_48.xsd'
:22:234 error: no declaration found for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2000/xmlns/}om' is not declared for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2000/xmlns/}xsi' is not declared for element 'om:scenario'
:22:234 error: attribute 'name' is not declared for element 'om:scenario'
:22:234 error: attribute 'schemaVersion' is not declared for element 'om:scenario'
:22:234 error: attribute '{http://www.w3.org/2001/XMLSchema-instance}schemaLocation' is not declared for element 'om:scenario'
:29:66 error: no declaration found for element 'demography'
:29:66 error: attribute 'maximumAgeYrs' is not declared for element 'demography'

[...]

:341:55 error: attribute 'value' is not declared for element 'group'
:345:43 error: no declaration found for element 'computationParameters'
:345:43 error: attribute 'iseed' is not declared for element 'computationParameters'
OpenMalaria: No such file or directory

Scenario does not conform to schema, schema is appropriately named/located.

(For this test case, I used 48.0 schema, instead of scenario_current.xsd.)

Before:

XSD error: instance document parsing failed
:192:46 error: missing required attribute 'propInfected'
:192:46 error: missing required attribute 'propInfectious'
:222:23 error: missing required attribute 'minInfectedThreshold'
:243:44 error: missing required attribute 'propInfected'
:243:44 error: missing required attribute 'propInfectious'
:250:23 error: missing required attribute 'minInfectedThreshold'
:271:46 error: missing required attribute 'propInfected'
:271:46 error: missing required attribute 'propInfectious'
:278:23 error: missing required attribute 'minInfectedThreshold'

After:

Error: parsing scenario file failed.
        Likely the XSD file is not present at an expected location/with expected filename,
        or the scenario file example_scenario.xml does not conform to the relevant schema.
instance document parsing failed
XSD error: instance document parsing failed
:192:46 error: missing required attribute 'propInfected'
:192:46 error: missing required attribute 'propInfectious'
:222:23 error: missing required attribute 'minInfectedThreshold'
:243:44 error: missing required attribute 'propInfected'
:243:44 error: missing required attribute 'propInfectious'
:250:23 error: missing required attribute 'minInfectedThreshold'
:271:46 error: missing required attribute 'propInfected'
:271:46 error: missing required attribute 'propInfectious'
:278:23 error: missing required attribute 'minInfectedThreshold'

Documentation

No wiki updates or other documentation changes needed for this PR.

[b-s-code]

@acavelan may I please get a review?

@melissapenny @nakul7 FYI

[acavelan]

This is a really good idea.

It would be even better if we could detect that the file does not exist before trying to parse the document. I believe users get confused because they get 300 lines of errors when this happens. They will probably miss the new helper text at the top.

If not possible, perhaps the new error description should appear at the end?