combine common api error codes

[bbrcknl]

The seL4 API has three common error codes

• seL4_IllegalOperation
• seL4_InvalidCapability
• seL4_TruncatedMessage
  as described in Separate documentation for common error codes in kernel object API #622

I've replaced the text in the descriptions in the xml files, E.g.

<error name="seL4_IllegalOperation">
    <description>
        The <texttt text='_service'/> is a CPtr to a capability of the wrong type
    </description>
</error>

is now

<error name="seL4_IllegalOperation">
    <description>
        &illegal_operation;
    </description>
</error>

There are a few problems with this approach.

1. Global variable declaration is done at the top of each api xml file. I'm too new to xml and python to place the global variable declaration into a single file (e.g. py code) such that it can be called or added to each api xml file.

2. The text strings that describe error messages are too long. I aimed to include a useful error message + a link to a table with common error codes, e.g.

illegal_operation = "The _service is a CPtr to a capability of the wrong type (see error:illegal_operation in common error codes)"
where error:illegal_operation links to a common error codes table

The long strings are particularly unreadable when there are multiple error codes
E.g.
10.3.3 seL4_IRQControl
10.3.3.1 Get
seL4_IllegalOperation On x86, an IOAPIC is being used. Or, the _service is a CPtr to a capability of the wrong type (see seL4_IllegalOperation in common error codes)

This could be made readable by listing the error codes
E.g.
10.3.3 seL4_IRQControl
10.3.3.1 Get
seL4_IllegalOperation

• On x86, an IOAPIC is being used.
• Or, the _service is a CPtr to a capability of the wrong type (see seL4_IllegalOperation in common error codes)

But I'm struggling with the xml and python, can can't figure out how to include lists in the descriptions of errors.

@Indanz @lsf37 Any suggestions/hints?

[bbrcknl]

@indan Zupancic Thanks for the xinclude code
I've tried to use it to include a test fail, but have unfortunately failed.
Can you please take a look at the files I changed in 85c6504 to see what might be going wrong?

[Indanz]

The final result looks okay, but some commits have garbage or other messiness in the that shouldn't be there, it would be nice if you could clean that up, e.g. rebase -i a58480. That would also get rid of the merge commits, which is necessary before we can merge it.

[Indanz]

This seems some stray test change.

[Indanz]

I think we're almost there. You forgot to update a few files (missing git add?), but otherwise looks a lot cleaner now.

[Indanz]

None of these recursive ones seem to work, at least not when including the whole common error file, it works for appending error reasons: All generated output is empty, and hence replaced with TODO in the generated PDF. And if this happens, error processing stops and further errors aren't shown at all. :-(

If I remove those elements from the included file I get the expected output.

When it works,the copyright comment also gets inserted into the PDF as readable text, messing things up.

I tried a few different things, but they didn't fix it.

[bbrcknl]

This is baffling. I get the pdf attached manual.pdf, which inserts errors as expected, with no TODOs (at least not in the error descriptions).

[Indanz]

I get manual.pdf. I'm using a Debian 11 Bullseye based distro, I guess there is some version difference in some tool that explains this difference. I have Python 3.9.2. @lsf37 does it work for you? Any ideas?