Update docs wording

Author: coretl

docs/examples/example_records_calculate.py

@@ -3,11 +3,12 @@
 
 builder.SetDeviceName("XX-XX-XX-01")
 
-softioc_record = builder.aOut("VAL1", initial_value=5)
-iocbuilder_record = records.ao("VAL2", VAL=10)
+py_record = builder.aOut("VAL1", initial_value=5, on_update=print)
+soft_record = records.ao("VAL2", VAL=10)
 
-calc = records.calc("CALC", CALC="A*B", SCAN="1 second",
-                    INPA=softioc_record, INPB=iocbuilder_record)
+calc = records.calc("CALC", CALC="A*B", INPA=builder.CP(py_record), B=1)
+
+soft_record.OUT = builder.PP(calc.B)
 
 builder.LoadDatabase()
 softioc.iocInit()

docs/how-to/use-iocbuilder-records.rst

@@ -0,0 +1,40 @@
+Use soft records in an IOC
+==========================
+
+It is possible to use records with soft device support mixed with pythonSoftIOC
+records (with Python device support). This allows use of ``calc``, ``fanout``
+and other EPICS database soft records.
+
+.. literalinclude:: ../examples/example_records_calculate.py
+
+The ``VAL1`` record is created in the usual pythonSoftIOC way, with Python
+device support. You can :meth:`~softioc.device.ProcessDeviceSupportOut.set` it,
+and `on_update` will be called when you ``caput`` it.
+
+The ``VAL2`` record is created using the lower level
+:attr:`softioc.builder.records` object. You can `dbpf` it, and no Python will
+be called when you ``caput`` to it.
+
+Note that the Device Name is shared between both kinds of records - both will
+have the same prefix.
+
+We construct the ``calc`` record again using :attr:`softioc.builder.records`.
+This record will calculate ``A*B``:
+
+- ``A`` is provided by the record pointed at by ``INPA``, which is
+  ``py_record``, and the `CP` link causes it to be monitored, processing
+  ``calc`` each time it updates.
+
+- ``B`` is initially set to 1. When ``soft_record`` processes, it sends its
+  value to ``calc.B``, and the `PP` link causes it to process.
+
+.. note::
+
+    You could also use ``calc(SCAN="1 second", ...)`` instead of the `PP` and
+    `CP` links, which would fetch the value periodically rather than just on
+    change.
+
+The output of this IOC can be examined by running this IOC in one terminal, and
+then modifying and running the example scripts found in `read-data-from-ioc`.
+Try setting the value of either ``VAL1`` or ``VAL2`` and observe the effect on
+the ``CALC`` output.

docs/how-to/use-soft-records.rst

@@ -61,7 +61,7 @@ Table Of Contents
     how-to/use-asyncio-in-an-ioc
     how-to/make-publishable-ioc
     how-to/read-data-from-ioc
-    how-to/use-iocbuilder-records
+    how-to/use-soft-records
 
 .. toctree::
     :caption: Explanations

docs/index.rst

@@ -351,12 +351,12 @@ The following attributes allow more direct access to record creation.
 
 ..  attribute:: records
 
-    This is the ``iocbuilder`` records object, and is populated with
+    This is the `epicsdbbuilder.records` object, and is populated with
     functions named after each available record type.  Records created with
     these calls are created with soft device support and Python is not involved
     in their processing.
 
-    See `../how-to/use-iocbuilder-records` for a full example of its usage.
+    See `../how-to/use-soft-records` for a full example of its usage.
 
 Finally, the following function is used to load record definitions before
 starting the IOC.

docs/reference/api.rst

@@ -73,8 +73,8 @@ action.
 
 .. note::
     The following section should only be used for debugging purposes, and not
-    for production testing, as the functions used do not necessarily reflect 
-    what a real user would see when querying an IOC over the network. 
+    for production testing, as the functions used do not necessarily reflect
+    what a real user would see when querying an IOC over the network.
     See `../how-to/read-data-from-ioc` for proper network access examples.
 
 In this interpreter there is immediate access to methods defined in the
@@ -128,11 +128,11 @@ following types:
      ``mbbo``, ``stringin``, ``stringout``, ``waveform``
 
 Occasionally it may be desirable to create a soft record without ``Python``
-device support, particularly if any other record type is required.  This can be done using 
-the corresponding record creation functions provided as methods of 
-:attr:`softioc.builder.records`.  For example, if a ``calc`` record is required then this 
-can be created by calling ``softioc.builder.records.calc``. See an example in  
-`../how-to/use-iocbuilder-records`.
+device support, particularly if any other record type is required.  This can be
+done using the corresponding record creation functions provided as methods of
+:attr:`softioc.builder.records`.  For example, if a ``calc`` record is required
+then this can be created by calling ``softioc.builder.records.calc``. See an
+example in `../how-to/use-soft-records`.
 
 For all records created by these methods both
 :meth:`~softioc.device.ProcessDeviceSupportIn.get` and