cFE 6.6 Documentation Updates

[skliper]

This ticket will be used for all cFE 6.5 documentation updates including the VDD. A listing of the needed documentation updates will be added to this ticket as tickets, requiring code updates, are reviewed and determined there is an associated documentation change.

[skliper]

Imported from trac issue 220. Created by sstrege on 2017-11-06T20:06:45, last modified: 2019-03-05T14:58:28

[skliper]

Trac comment by jphickey on 2017-11-06 22:24:52:

I just pushed some revised markdown files on this ticket. (This will supercede the ones on ticket #238) as this seems like the more appropriate place for this.

This includes markdown versions of the VDD and requirements. The VDD here has more updates and includes a real list of tickets / changes included for CFE 6.6.

NOTE: the content of the tables in the markdown vdd is generated directly from git itself, by gathering the commit log between "master" and "development" and searching for the string "Trac" along with a number in the commit log. This seems to work however if any ticket didn't follow this convention it may be missing from the list....

It does reinforce the need to follow good/consistent practices when writing git commit logs, it helps at times like this. We should enforce it better for future commits.

commit [changeset:5f7ef89e] branch trac-220-cfe-660-vdd

[skliper]

Trac comment by jphickey on 2017-11-07 13:47:47:

Added testing matrix to VDD in commit [changeset:f2f9863]

[skliper]

Trac comment by sstrege on 2017-11-13 18:43:00:

Removed old MKS IDs from requirements in commit [changeset:4a52065]

[skliper]

Trac comment by sstrege on 2017-11-13 19:27:12:

I realized I did not hit save to push the second half of the changes to remove all IDs. Commit [changeset:900a3c1] contains the next set.

[skliper]

Trac comment by sstrege on 2017-11-13 20:01:54:

Updated requirements to remove memory pool 32-bit alignment specifications. Also updated to be in sync with changes made under Trac #230. Commit [changeset:bfa1e46] is ready for CCB review. This commit addresses Trac #250.

[skliper]

Trac comment by jphickey on 2017-11-14 13:55:29:

Signature page added in commit [changeset:24e3709]

[skliper]

Trac comment by glimes on 2017-11-16 13:30:47:

Commits mentioned above integrated via the ic-2017-11-14 integration branch,
leaving ticket open pending reesolution of these commits:

• Commit [changeset:934ffcb] Fix cmake doxygen documentation build
• Commit [changeset:e94f654] Update doxygen for MsgId wrappers

[skliper]

Trac comment by sstrege on 2017-11-17 12:41:41:

Recommend/approve commit [changeset:934ffcb] and commit [changeset:e94f654]

Note: commit [changeset:934ffcb] is associated with Trac #201 and is a duplicate of commit [changeset:0075b72]

[skliper]

Trac comment by sstrege on 2017-11-20 22:29:34:

Updated requirements to add rationale. Commit [changeset:3e5e0ff] includes rationale for ES, EVS, and TIME. This commit also removes the old requirements .doc file, replacing it with an updated .docx file which removes the functional requirements.

I forgot to update the TOC in the .docx file. This commit [changeset:7c81a82] contains the updated .docx file.

[skliper]

Trac comment by glimes on 2017-11-22 11:47:25:

Work so far will be included in RC3,
integration now in progress;
will leave this ticket open
pending additional possible changes.

[skliper]

Trac comment by sstrege on 2017-11-22 19:29:57:

Commit [changeset:506da6b] contains updates to the VDD:

1. Purpose and Summary section updated with 6.6.0 specific info
2. Updated tables listing new and changed functionality

[skliper]

Trac comment by glimes on 2017-11-28 13:46:52:

Updated MD and PDF are in [changeset:58b5c79]

[skliper]

Trac comment by sstrege on 2017-11-30 20:25:05:

Commit [changeset:1fccb30] contains the remaining updates to the functional requirements .md file adding rationale (from pre-existing Word doc in 6.5) for SB and TBL.

[skliper]

Trac comment by sstrege on 2017-11-30 21:16:47:

Commit [changeset:85903bd] contains the release notes .md file agreed upon at 11/28/17 CCB meeting.

[skliper]

Trac comment by sstrege on 2017-11-30 21:28:34:

A few editorial issues with the VDD, found by cthames, to note:

Two of the tables (1.4-1 and 1.5-1) are actually identified as “Table 3: 1.4-1” and “Table 4: 1.5-1”. It looks like Word stuck in additional identifiers on those two tables. I’m not really sure why it chose 3 and 4, considering there is no Table 1 or 2. Also, Table 1.2-1 does not have a label identifying it with that number. Identifying it is intuitive though since the table is in Section 1.2.1. Lastly, the intro information makes a reference to the table of new functionality in 1.2.1, but no mention of the table describing changes in Section 1.2.2. Again, all of these are very minor and should not cause any real confusion in the document. They are just items for clean-up.

[skliper]

Trac comment by sstrege on 2017-12-01 09:44:13:

Commit [changeset:3cbea33] contains the signed VDD

[skliper]

Trac comment by jphickey on 2017-12-01 12:10:04:

I have pushed commit [changeset:048bd4f] which makes some very minor formatting/style corrections to make it more markdown-friendly. In particular:

• Use backticks around any references to C symbols or shell output
  This avoids any special interpretation by markdown viewers.
• Use angle brackets around http links
• Use superscript for the exponent
• Use table captions/labels that are in //not// pandoc-recognized format

In particular the last item should help address [comment:17 this table issue]:

A few editorial issues with the VDD, found by cthames, to note:

Two of the tables (1.4-1 and 1.5-1) are actually identified as “Table 3: 1.4-1” and “Table 4: 1.5-1”. It looks like Word stuck in additional identifiers on those two tables. I’m not really sure why it chose 3 and 4, considering there is no Table 1 or 2. Also, Table 1.2-1 does not have a label identifying it with that number. Identifying it is intuitive though since the table is in Section 1.2.1. Lastly, the intro information makes a reference to the table of new functionality in 1.2.1, but no mention of the table describing changes in Section 1.2.2. Again, all of these are very minor and should not cause any real confusion in the document. They are just items for clean-up.

Some background here -- after googling a bit it seems there is currently not an ideal way to cite tables in pandoc/markdown -- at least not without an extra "crossref" plugin.

Pandoc automatically generates a sequential table number i.e. "Table 1", "Table 2" etc but these only appear in the output if there is an actual table caption. The e.g. "1.4-1" and "1.5-1" numbers are actually static labels from the word conversion. The confusion with respect to the caption in these two places is that it had both the automatically assigned number and the statically assigned number. By changing it to //not// be a pandoc-formatted table caption, the auto-assigned sequential number does not appear in the PDF, thereby mitigating the confusion.

For the next time around, we should consider using a more proper approach, but hopefully this suffices for now without making a substantive change here.

[skliper]

Trac comment by jphickey on 2017-12-01 12:31:11:

One more thing to note about the commit ---

This also makes the //older// pandoc command line options the default in the Makefile, rather than the bleeding edge options. Almost all distributions (Debian, Ubuntu, Fedora, openSUSE) are shipping a 1.x version in their repositories so I think most users will need the older-style options if they want to generate the PDF.

In particular, on Ubuntu 16.04 LTS using the version of pandoc available in the Ubuntu repository, it needs the older style options or else it fails to make the PDF.

[skliper]

Trac comment by jphickey on 2019-02-21 16:55:31:

Old ticket cleanup: CFE 6.6 is done, this ticket should have been closed.

[skliper]

Trac comment by jhageman on 2019-03-05 14:58:28:

Milestone renamed