Merge pull request #171 from fprime-community/issue-168-users-guide

Update User's Guide
nasa · Oct 25, 2022 · f82af60 · f82af60
2 parents 6cdc0b9 + 0aea5d8
commit f82af60
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 45 deletions.
diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html
@@ -668,6 +668,7 @@ <h1>The F Prime Prime (FPP) User&#8217;s Guide, v1.1.0</h1>
 <ul class="sectlevel3">
 <li><a href="#Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Constant-Definitions">13.3.1. Constant Definitions</a></li>
 <li><a href="#Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Topology-Definitions">13.3.2. Topology Definitions</a></li>
+<li><a href="#Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Other-Definitions">13.3.3. Other Definitions</a></li>
 </ul>
 </li>
 <li><a href="#Analyzing-and-Translating-Models_Identifying-Generated-Files">13.4. Identifying Generated Files</a></li>
@@ -701,7 +702,9 @@ <h2 id="Introduction">1. Introduction</h2>
 <a href="https://nasa.github.io/fprime/">F Prime flight software framework</a>.
 A <a href="https://digitalcommons.usu.edu/smallsat/2018/all2018/328/">paper presented at
 SmallSat 2018</a>
-provides an overview of F Prime.</p>
+provides an overview of F Prime.
+For more detailed information about F Prime, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 <div class="paragraph">
 <p>The goals of FPP are as follows:</p>
@@ -3597,7 +3600,7 @@ <h3 id="Defining-Components_Port-Instances">9.2. Port Instances</h3>
 The port definition provides information common to all uses of the port, such as
 the kind of data carried on the port.
 The port instance provides use-specific information, such
-as the name of the instance and the the direction of invocation
+as the name of the instance and the direction of invocation
 (input or output).</p>
 </div>
 <div class="sect3">
@@ -3693,13 +3696,13 @@ <h4 id="Defining-Components_Port-Instances_Basic-Port-Instances">9.2.1. Basic Po
 base class with a virtual handler function, and then override that virtual
 function in a derived class that you write.
 For further details about implementing F Prime components, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 <div class="paragraph">
 <p><strong>Note on terminology:</strong> As explained above, there is a technical
-distinction between a <em>port</em> (defined outside any component, and providing
+distinction between a <em>port type</em> (defined outside any component, and providing
 the type of a port instance)
-and a <em>port instance</em> (defined inside a component and instantiating
+and a <em>port instance</em> (specified inside a component and instantiating
 a port type).
 However, it is sometimes useful to refer to a port instance with
 the shorter term "port" when there is no danger of confusion.
@@ -3979,7 +3982,7 @@ <h4 id="Defining-Components_Port-Instances_Serial-Port-Instances">9.2.6. Serial
 This flexibility comes at the cost that you lose the type
 compile-time type checking provided by port connections with named types.
 For more information about serial ports and their use, see
-the F Prime User&#8217;s Guide.</p>
+the <a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 </div>
@@ -4099,7 +4102,7 @@ <h4 id="Defining-Components_Special-Port-Instances_Command-Ports">9.3.1. Command
 <div class="paragraph">
 <p>For further information about command registration, receipt, and
 response, and implementing command handlers, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 <div class="sect3">
@@ -4180,7 +4183,7 @@ <h4 id="Defining-Components_Special-Port-Instances_Event-Ports">9.3.2. Event Por
 </div>
 <div class="paragraph">
 <p>For further information about events in F Prime, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 <div class="sect3">
@@ -4229,7 +4232,7 @@ <h4 id="Defining-Components_Special-Port-Instances_Telemetry-Ports">9.3.3. Telem
 </div>
 <div class="paragraph">
 <p>For further information about telemetry in F Prime, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 <div class="sect3">
@@ -4314,7 +4317,7 @@ <h4 id="Defining-Components_Special-Port-Instances_Parameter-Ports">9.3.4. Param
 </div>
 <div class="paragraph">
 <p>For further information about parameters in F Prime, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 <div class="sect3">
@@ -4364,7 +4367,7 @@ <h4 id="Defining-Components_Special-Port-Instances_Time-Get-Ports">9.3.5. Time G
 </div>
 <div class="paragraph">
 <p>For further information about time in F Prime, see the
-F Prime User&#8217;s Guide.</p>
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 </div>
@@ -4507,7 +4510,8 @@ <h3 id="Defining-Components_Commands">9.5. Commands</h3>
 </div>
 <div class="paragraph">
 <p>For complete information about F Prime command dispatch and
-handling, see the F Prime User&#8217;s Guide.
+handling, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.
 Here we concentrate on how to specify commands in FPP.</p>
 </div>
 <div class="sect3">
@@ -4848,7 +4852,8 @@ <h3 id="Defining-Components_Events">9.6. Events</h3>
 </div>
 <div class="paragraph">
 <p>For complete information about F Prime event
-handling, see the F Prime User&#8217;s Guide.
+handling, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.
 Here we concentrate on how to specify events in FPP.</p>
 </div>
 <div class="sect3">
@@ -5147,7 +5152,8 @@ <h4 id="Defining-Components_Events_Throttling">9.6.4. Throttling</h4>
 <p>Once an event is throttled, the component instance will no longer
 emit the event until the throttling is canceled.
 Typically, the canceling happens via a FSW command.
-For details, see the F Prime User&#8217;s Guide.</p>
+For details, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.</p>
 </div>
 </div>
 </div>
@@ -5167,7 +5173,8 @@ <h3 id="Defining-Components_Telemetry">9.7. Telemetry</h3>
 </div>
 <div class="paragraph">
 <p>For complete information about F Prime telemetry
-handling, see the F Prime User&#8217;s Guide.
+handling, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.
 Here we concentrate on how to specify telemetry channels in FPP.</p>
 </div>
 <div class="sect3">
@@ -5529,8 +5536,8 @@ <h3 id="Defining-Components_Parameters">9.8. Parameters</h3>
 <p>F Prime has special support for parameters, including a parameter
 database component for storing parameters in a non-volatile
 manner (e.g., on a file system).
-For complete information about F Prime parameters, see the F Prime User&#8217;s
-Guide.
+For complete information about F Prime parameters, see the
+<a href="https://github.com/nasa/fprime/blob/master/docs/UsersGuide/guide.md">F Prime User&#8217;s Guide</a>.
 Here we concentrate on how to specify parameters in FPP.</p>
 </div>
 <div class="sect3">
@@ -9726,10 +9733,10 @@ <h3 id="Analyzing-and-Translating-Models_Generating-XML">13.2. Generating XML</h
 <div class="sect2">
 <h3 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus">13.3. Generating C Plus Plus</h3>
 <div class="paragraph">
-<p>As discussed in the previous section, our current strategy is to generate XML
+<p>As discussed in the previous section, our general strategy is to generate XML
 and to use the F Prime autocoders to generate
 C&#43;&#43;.
-As of the current version of FPP, we make two exceptions to this rule:</p>
+As of the current version of FPP, we make the following exceptions to this rule:</p>
 </div>
 <div class="olist arabic">
 <ol class="arabic">
@@ -9753,6 +9760,10 @@ <h3 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus">13.3. Generatin
 However, we still use the F Prime XML to generate dictionaries
 for the F Prime ground data system.</p>
 </li>
+<li>
+<p>We are phasing in direct C&#43;&#43; code generation for types, ports,
+and components.</p>
+</li>
 </ol>
 </div>
 <div class="paragraph">
@@ -9998,6 +10009,15 @@ <h4 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Topology-Definit
 the include guard prefix comes from the name of the topology.</p>
 </div>
 </div>
+<div class="sect3">
+<h4 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Other-Definitions">13.3.3. Other Definitions</h4>
+<div class="paragraph">
+<p>We are phasing in direct C&#43;&#43; code generation for types, ports, and
+components.
+Currently we have implemented direct C&#43;&#43; code generation for types
+(arrays, structs, and enums).</p>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="Analyzing-and-Translating-Models_Identifying-Generated-Files">13.4. Identifying Generated Files</h3>
@@ -11149,7 +11169,7 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Public-Symb
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2022-10-20 13:14:16 -0700
+Last updated 2022-10-22 10:24:12 -0700
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

diff --git a/docs/users-guide/Analyzing-and-Translating-Models.adoc b/docs/users-guide/Analyzing-and-Translating-Models.adoc
@@ -347,10 +347,10 @@ in this manual.
 
 === Generating C Plus Plus
 
-As discussed in the previous section, our current strategy is to generate XML 
+As discussed in the previous section, our general strategy is to generate XML 
 and to use the F Prime autocoders to generate
 {cpp}.
-As of the current version of FPP, we make two exceptions to this rule:
+As of the current version of FPP, we make the following exceptions to this rule:
 
 . For
 <<Defining-Constants,constant definitions>>,
@@ -372,6 +372,9 @@ via F Prime XML.
 However, we still use the F Prime XML to generate dictionaries
 for the F Prime ground data system.
 
+. We are phasing in direct {cpp} code generation for types, ports,
+and components.
+
 *Tool name:* The tool for translating FPP to {cpp} is called
 `fpp-to-cpp`.
 
@@ -559,6 +562,13 @@ translating constant definitions>>.
 The `-g` option is ignored, because
 the include guard prefix comes from the name of the topology.
 
+==== Other Definitions
+
+We are phasing in direct {cpp} code generation for types, ports, and
+components.
+Currently we have implemented direct {cpp} code generation for types
+(arrays, structs, and enums).
+
 === Identifying Generated Files
 
 As discussed in the previous section, the `-n` option