The HTML rendering of SAL APIs is very handy, but I have a few requests for further enhancement.

• By far the biggest issue is that the generic topics are not listed. Unfortunately adding them will be some work. More on this below.
• I beg you to include a prominent link from the metadata for a given CSC (generated from SALSubsystems.xml) to the API for that CSC. Preferably also include that link in the table. That is arguably the most useful piece of information and it allows CSC docs to link to one obvious place, where a user sees the metadata and can quickly get to the API.
• Please include a link from the API back to the metadata (that may exist, but I didn't see it).
• Please consider omitting data for:
  • The Subsystem field. We know what subsystem this is. It's just clutter. (It's also clutter in the XML itself, but that's another issue).
  • Preferably omit the subsystem prefix as well.
  • Deprecated fields, including Version, Author and Explanation
• Also please consider omitting the following fields, though this is more of a stretch:
  • IDL_Size if it's 1. That means "no limit" (which is confusing) and is the most common case.
  • Count if it's 1. That's by far the common case.

Regarding how to handle generic topics. The obvious solution is to parse the Generics tag of SALSubsystems, though it's a bit of a nuisance. Another option is to parse the IDL files instead (salobj already has a parser for this, so just call that). This has the one really big disadvantage that it requires the IDL be built before you can generate the HTML. If you can live with that (and it's a big if) you gain some significant advantages:

• It gives you all the topics. The list is guaranteed to be correct because IDL files are the fundamental information used by OpenSplice (for all languages).
• It omits the garbage fields; you get the fundamentals: name, type (including if it's an array, and how many elements the array has), description and units.
• It gives you the actual data type. Several types in the XML are aliases which become the same standard DDS type in the IDL files.
• The parser already exists and it is the same one used by the sal/kafka producers.