Add 'examples declaration to halcompile and start using it.

Several HAL components already have examples, but these are not
placed in standardized manual page sections.  Adjust layout of
eoffset_per_angle.comp, moveoff.comp and ohmic.comp.

Also update component documentation to mention this new declaration.

Author: petterreinholdtsen

docs/src/hal/comp.adoc

@@ -125,6 +125,7 @@ Declarations include:
 * 'option OPT (VALUE);'
 * 'variable CTYPE STARREDNAME ([SIZE]);'
 * 'description DOC;'
+* 'examples DOC;'
 * 'notes DOC;'
 * 'see_also DOC;'
 * 'license LICENSE;'

src/hal/components/eoffset_per_angle.comp

@@ -27,9 +27,9 @@ One of the four built-in functions is specified by the \\fBfnum\\fR pin:
   \\fB3\\fR: f3 square wave
 
 Unsupported \\fBfnum\\fR values default to use function f0.
+""";
 
-\\fBNOTES:\\fR
-
+notes """
 \\fBradius-ref\\fR:
 The computed offsets are based on the \\fBradius-ref\\fR pin
 value.  This pin may be set to a constant radius value or
@@ -43,15 +43,15 @@ and velocity limits.  The allocations for coordinate \\fBL\\fR
 are typically controlled by an ini file setting:
 \\fB[AXIS_L]OFFSET_AV_RATIO\\fR.
 
-\\fBNOTES\\fR:
 If unsupported parameters are supplied to a function (for instance
 a polygon with fewer than three sides), the current offset
 will be returned to zero (respecting velocity and acceleration
 constraints).  After correcting the offending parameter, the
 \\fBenable-in\\fR pin must be toggled to resume offset
 computations.
+""";
 
-\\fBEXAMPLE:\\fR
+examples """
 An example simulation configuration is provided at:
 \\fBconfigs/sim/axis/external_offsets/opa.ini\\fR.  A
 simulated XZC machine uses the \\fBC\\fR coordinate angle to

src/hal/components/moveoff.comp

@@ -84,9 +84,13 @@ Use of the names= option for naming is \\fBrequired\\fR for compatibility
 with the gui provided as scripts/moveoff_gui:
   loadrt moveoff names=\\fBmv\\fR personality=number_of_joints
 
-\\fBman moveoff_gui\\fR for more information
+""";
+
+see_also """
+\\fBmoveoff_gui\\fR(1)
+""";
 
-.SH EXAMPLES
+examples """
 Example simulator configs that demonstrate the moveoff component and a simple gui
 (scripts/moveoff_gui) are located in configs/sim/axis/moveoff. The axis gui is
 used for the demonstrations and the configs can be adapted for other guis like

src/hal/components/ohmic.comp

@@ -25,9 +25,9 @@ In this case, the circuit will remain protected by the THCAD's ability to tolera
 .br
 It is optional that power to the Ohmic sensing circuit be disconnected unless probing is in progress ut this adds additional complexity.
 .br
+""";
 
-
-\\fBEXAMPLE:\\fR
+examples """
 .br
 THCAD5 card using a 1/32 frequency setting and a voltage divider internal to the plasma cutter with range extended
 to 24.5 volts with a 390K external resistor as per the manual. Additional information and wiring diagram is contained in the Plasma Primer in the main Linuxcnc documents.

src/hal/utils/halcompile.g

@@ -47,6 +47,7 @@ parser Hal:
       | "see_also" String ";"   {{ see_also(String) }}
       | "notes" String ";"   {{ notes(String) }}
       | "description" String ";"   {{ description(String) }}
+      | "examples" String ";"   {{ examples(String) }}
       | "license" String ";"   {{ license(String) }}
       | "author" String ";"   {{ author(String) }}
       | "include" Header ";"   {{ include(Header) }}
@@ -178,6 +179,9 @@ def comp(name, doc):
 def description(doc):
     docs.append(('descr', doc));
 
+def examples(doc):
+    docs.append(('examples', doc));
+
 def license(doc):
     docs.append(('license', doc));
 
@@ -1017,6 +1021,11 @@ def document(filename, outfilename):
             else:
                 lead = ".br\n.ns\n.TP"
 
+    doc = finddoc('examples')
+    if doc and doc[1]:
+        print(".SH EXAMPLES\n", file=f)
+        print("%s" % doc[1], file=f)
+
     doc = finddoc('see_also')    
     if doc and doc[1]:
         print(".SH SEE ALSO\n", file=f)