Open edwardchapin opened 5 years ago
edwardchapin
commented
5 years ago edwardchapin
commented
5 years ago 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.).
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 .
[x] 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.,θ<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.[x] 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 ofparseModelFile.py, e.g., using themarkdown2module. Decision: restrict model file formatting to use HTML.[ ] 3. Indicating pre-/post- conditions: NFIRAOS has been adding to
DescriptionstringsPrecondition:andPostcondition:with a list of state event values. However, there is a proposal for the ICDDB schema to be updated to include these conditions (https://github.com/tmtsoftware/icd/issues/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 (https://github.com/tmtsoftware/icd/issues/63).
[ ] 5. Indicating command properties WRT common patterns: We also have a concept of command properties, including
preemptable,friendly, andscheduled. Currently NFIRAOS indicates this in the Description string using something like*Friendly Command.*.[ ] 6. Sequence diagrams: Doxygen
\mscsequence 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.pymust 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 theNIC/template/icddb/genIcd.pyscript to drop a subset of irrelevant command/telemetry from the ICD.