Standardize approach to NFIRAOS & IRIS ICDDB model files

[edwardchapin]

This issue is intended to track discussion and summarize decisions regarding how to format ICD model files, and incorporate them into our Doxygen documentation. The checklist at the top indicates proposals/decisions. Discussion occurs below, and as we reach consensus we update the wording (and possibly add/remove items) in this top list, and click the check-box when an approach is agreed upon. When the issue is closed, these decisions (along with canonically-formatted model file examples) will be added to https://docushare.tmt.org/docushare/dsweb/Get/Document-57492 .

• 1. Including math: Doxygen allows for LaTex-style formulae, but not when using \includedoc. Furthermore, icdwebserver can not render this style of math. One proposal is to restrict math to HTML tags within model files which render universally, e.g., &theta;<SUB>i</SUB> renders as θ_i. Another proposal (for stand-alone equations on a separate line; it will not work for in-line math) is to modify parseModelFile.py so that it converts math into an image. Remember that model files are for defining interfaces -- detailed formulae should normally be restricted to our tech notes (where LaTex-style math can be used).
  Decision: display all math/greek using HTML.

• 2. General text formatting: NFIRAOS currently uses HTML tags for formatting (e.g., <ul> and <li> to generate lists). This is cumbersome, and an alternative suggestion is to use simpler markdown formatting (which should produce good output in icdwebserver natively). Then, the Doxygen documentation would need to convert the md to HTML as part of parseModelFile.py, e.g., using the markdown2 module.
  Decision: restrict model file formatting to use HTML.

• 3. Indicating pre-/post- conditions: NFIRAOS has been adding to Description strings Precondition: and Postcondition: with a list of state event values. However, there is a proposal for the ICDDB schema to be updated to include these conditions (Add attributes for preconditions and postconditions for commands. icd#65).

• 4. Indicating CSW command completion type: A caller needs to know if a command is oneway, submit etc. (i.e., standard CSW types). This appears to be covered by a proposed ICDDB schema change (Add completion information for commands icd#63).

• 5. Indicating command properties WRT common patterns: We also have a concept of command properties, including preemptable, friendly, and scheduled. Currently NFIRAOS indicates this in the Description string using something like *Friendly Command.*.

• 6. Sequence diagrams: Doxygen \msc sequence diagrams can help to understand complex command sequences. The current suggestion for embedding these in such a way that they will be ignored by icdwebserver (which cannot render them) is to place them within a comment block formatted in the following way: <!--doxygen [...multi-line special input for Doxygen, including \msc...] doxygen-->. parseModelFiles.py must then simply remove the <!--doxygen... tags.

• 7. Engineering/Calibration commands: NFIRAOS facilitated the auto-generation of certain ICDs (e.g., having AOSQ "send all NFIRAOS commands" and "subscribe to all NFIRAOS telemetry") by adding strings at the end of the first line of command descriptions like (engineering) and (calibration). These were then used as filters when invoking the NIC/template/icddb/genIcd.py script to drop a subset of irrelevant command/telemetry from the ICD.

[edwardchapin]

1. Decided to restrict math to pure HTML for simplicity (converting math to images as proposed seems too messy). There shouldn't be a need for large amounts of math in the model files.

[edwardchapin]

2. After experimenting with the markdown2 Python module it was found that all literal multi-line syrings (using triple quotes) would need to be left-justified in the model files in order not to be interpreted as code blocks (i.e., monospaced font). It was decided that this was an undesirable constraint, so again, we will revert to using pure HTML tags for any required formatting (such as lists, boldface etc.).