Merge pull request #193 from CSol314/patch-5

Minor spelling/grammatical changes

doc/man/cppmicroservices-shellservice.7.rst

@@ -5,12 +5,11 @@
 Shell Service
 =============
 
-The Shell Service provides an interface to interact with a
-C++ Micro Services framework and to issue commands. It does not define
-a user interface, see :any:`usShell3(1)` for a client with a
+The Shell Service provides an interface to interact with and issue commands to
+a C++ Micro Services framework. See :any:`usShell3(1)` for a client with a
 textual interface.
 
 .. warning::
 
    This bundle has not reached a stable version yet. Its design and API
-   may change between releases in a backwards incompatible way.
+   may change between releases in a backwards incompatible way.

framework/doc/resources.rst

@@ -1,58 +1,42 @@
 .. _concept-resources:
 
-The Resources System
-====================
-
-The C++ Micro Services library provides a generic resources system to
-embed arbitrary files into a bundle's shared library (the size
-limitation per resource is 2GB, due to the used ZIP format).
-
-The following features are supported:
-
--  Embed arbitrary data into shared or static bundles or executables.
--  Data is embedded in a compressed format (zip) with a configurable
-   compression level.
--  Resources are accessed via a Bundle instance, providing individual
-   resource lookup and access for each bundle.
--  Resources are managed in a tree hierarchy, modeling the original
-   child - parent relationship on the file-system.
--  The BundleResource class provides a high-level API for accessing
-   resource information and traversing the resource tree.
--  The BundleResourceStream class provides an STL input stream derived
-   class for the seamless usage of embedded resource data in third-party
-   libraries.
-
-The following conventions and limitations apply:
+The Resource System
+===================
+
+The C++ Micro Services library provides a generic resource system that allows you to:
+
+- Embed resources in a bundle.
+- Access resources at runtime.
+
+The features and limitations of the resource system are described in more detail in
+the following sections.
 
--  Resource entries are stored with case-insensitive names. On
-   case-sensitive file systemes, adding resources with the same name but
-   different capitalization will lead to an error.
--  Looking up resources by name at runtime *is* case sensitive.
--  The CppMicroServices library will search for a valid zip file inside
-   a shared library, starting from the end of the file. If other zip
-   files are embedded in the bundle as well (e.g. as an additional
-   resource embedded via the Windows RC compiler or using other
-   techniques), it will stop at the first valid zip file and use it a
-   the resource container.
 
 Embedding Resources in a Bundle
 -------------------------------
 
 Resources are embedded into a bundle's shared or static library (or into
 an executable) by using the :program:`usResourceCompiler3` executable. It will
 create a ZIP archive of all input files and can append it to the bundle
-file. See :any:`usResourceCompiler3(1)` for the command line reference.
+file with a configurable compression level. See :any:`usResourceCompiler3(1)`
+for the command line reference. 
 
 
 Accessing Resources at Runtime
 ------------------------------
 
-Each bundle provides access to its embedded resources via the
-:any:`Bundle <cppmicroservices::Bundle>` class which provides methods
+Each bundle provides individual resource lookup and access to its embedded 
+resources via the :any:`Bundle <cppmicroservices::Bundle>` class which provides methods
 returning :any:`BundleResource <cppmicroservices::BundleResource>`
-objects. The :any:`BundleResourceStream <cppmicroservices::BundleResourceStream>`
-class provides a ``std::istream`` compatible object to access the
-resource contents.
+objects. The BundleResource class provides a high-level API for accessing
+resource information and traversing the resource tree.
+
+The :any:`BundleResourceStream <cppmicroservices::BundleResourceStream>`
+class provides a ``std::istream`` compatible object for the seamless usage of
+embedded resource data in third-party libraries.
+
+Resources are managed in a tree hierarchy, modeling the original parent-child
+relationship on the file-system.
 
 The following example shows how to retrieve a resource from each
 currently installed bundle whose path is specified by a bundle property:
@@ -66,10 +50,10 @@ This example could be enhanced to dynamically react to bundles being
 started and stopped, making use of the popular *extender pattern* from
 OSGi.
 
-Runtime overhead
+Runtime Overhead
 ----------------
 
-The resources system has the following runtime characteristics:
+The resource system has the following runtime characteristics:
 
 -  During static initialization of a bundle, it's ZIP archive header
    data (if available) is parsed and stored in memory.
@@ -79,3 +63,18 @@ The resources system has the following runtime characteristics:
 -  Creating a ``BundleResourceStream`` object will allocate memory for
    the uncompressed resource data and inflate it. The memory will be
    free'ed after the ``BundleResourceStream`` object is destroyed.
+
+Conventions and Limitations
+---------------------------
+
+-  Resources have a size limitation of 2GB due to the use of the ZIP format.
+-  Resource entries are stored with case-insensitive names. On
+   case-sensitive file systems, adding resources with the same name but
+   different capitalization will lead to an error.
+-  Looking up resources by name at runtime *is* case sensitive.
+-  The CppMicroServices library will search for a valid zip file inside
+   a shared library, starting from the end of the file. If other zip
+   files are embedded in the bundle as well (e.g. as an additional
+   resource embedded via the Windows RC compiler or using other
+   techniques), it will stop at the first valid zip file and use it as
+   the resource container.

framework/doc/service_hooks.rst

@@ -12,10 +12,12 @@ intended for use by application bundles but rather by bundles in need of
 *hooking* into the service registry and modifying the behaviour of
 application bundles.
 
-Specific use case for service hooks include proxying of existing
-services by hiding the original service and registering a *proxy
-service* with the same properties or providing services *on demand*
-based on registered service listeners from external bundles.
+Some example use cases for service hooks include:
+
+-  Proxying of existing services by hiding the original service and
+   registering a *proxy service* with the same properties
+-  Providing services *on demand* based on registered service listeners
+   from external bundles
 
 Event Listener Hook
 -------------------
@@ -24,9 +26,11 @@ A bundle can intercept events being delivered to other bundles by
 registering a :any:`ServiceEventListenerHook <cppmicroservices::ServiceEventListenerHook>`
 object as a service. The CppMicroServices library will send all service
 events to all the registered hooks using the reversed ordering of their
-ServiceReference objects. Note that event listener hooks are called
-*after* the event was created but *before* it is filtered by the optional
-filter expression of the service listeners. Hence an event listener hook
+ServiceReference objects. 
+
+Note that event listener hooks are called
+*after* the event was created, but *before* it is filtered by the optional
+filter expression of the service listeners. Therefore, an event listener hook
 receives all
 :any:`SERVICE_REGISTERED <gr_serviceevent::SERVICE_REGISTERED>`,
 :any:`SERVICE_MODIFIED <gr_serviceevent::SERVICE_MODIFIED>`,
@@ -63,9 +67,10 @@ Listener Hook
 The CppMicroServices API provides information about the registration,
 unregistration, and modification of services. However, it does not
 directly allow the introspection of bundles to get information about
-what services a bundle is waiting for. Waiting for a service to arrive
-(via a registered service listener) before performing its function is a
-common pattern for bundles. Listener Hooks provide a mechanism to get
+what services a bundle is waiting for. 
+
+Bundles may need to wait for a service to arrive (via a registered service
+listener) before performing their functions. Listener Hooks provide a mechanism to get
 informed about all existing, newly registered, and removed service
 listeners.
 
@@ -75,11 +80,11 @@ interface will be notified about service listeners by being passed
 :any:`ServiceListenerHook::ListenerInfo <cppmicroservices::ServiceListenerHook::ListenerInfo>`
 objects. Each ``ListenerInfo`` object is related to the registration /
 unregistration cycle of a specific service listener. That is,
-registering the same service listener again, even with a different
-filter, will automatically unregister the previouse registration and
+registering the same service listener again (even with a different
+filter) will automatically unregister the previous registration and
 the newly registered service listener is related to a different
 ``ListenerInfo`` object. ``ListenerInfo`` objects can be stored in
-unordered containers and compared with each other, e.g. to match
+unordered containers and compared with each other- for example, to match
 :any:`ServiceListenerHook::Added() <cppmicroservices::ServiceListenerHook::Added>`
 and :any:`ServiceListenerHook::Removed() <cppmicroservices::ServiceListenerHook::Removed>`
 calls.
@@ -90,7 +95,7 @@ may be reported before its corresponding addition. To handle this case,
 the :any:`ListenerInfo::IsRemoved() <cppmicroservices::ServiceListenerHook::ListenerInfo::IsRemoved>`
 method is provided which can be used in the
 :any:`ServiceListenerHook::Added() <cppmicroservices::ServiceListenerHook::Added>`
-method to detect the out of order delivery. A simple strategy is to
+method to detect a delivery that is out of order. A simple strategy is to
 ignore removed events without corresponding added events and ignore
 added events where the ``ListenerInfo`` object is already removed:
 
@@ -107,12 +112,12 @@ Ordinary Services
 
 All service hooks are treated as ordinary services. If the
 CppMicroServices library uses them, their Service References will show
-that the CppMicroServices bundles is using them, and if a hook is a
+that the CppMicroServices bundles are using them, and if a hook is a
 Service Factory, then the actual instance will be properly created.
 
 The only speciality of the service hooks is that the CppMicroServices
 library does not use them for the hooks themselves. That is, the Service
-Event and Service Find Hooks can not be used to hide the services from
+Event and Service Find Hooks cannot be used to hide the services from
 the CppMicroServices library.
 
 Ordering
@@ -129,10 +134,10 @@ Multi Threading
 ~~~~~~~~~~~~~~~
 
 All hooks must be thread-safe because the hooks can be called at any
-time. All hook methods must be re-entrant, they can be entered at any
+time. All hook methods must be re-entrant, as they can be entered at any
 time and in rare cases in the wrong order. The CppMicroServices library
-calls all hook methods synchronously but the calls might be triggered
+calls all hook methods synchronously, but the calls might be triggered
 from any user thread interacting with the CppMicroServices API. The
-CppMicroServices API can be called from any of the hook methods but
+CppMicroServices API can be called from any of the hook methods, but
 implementers must be careful to not hold any lock while calling
 CppMicroServices methods.

framework/doc/static_bundles.rst

@@ -4,14 +4,14 @@ Static Bundles
 ==============
 
 The normal and most flexible way to add a CppMicroServices bundle to
-an application is to compile it into a shared library that is later
-:any:`installed <cppmicroservices::BundleContext::InstallBundles>` in the application. 
+an application is to compile it into a shared library using the :any:`BundleContext::InstallBundles() <cppmicroservices::BundleContext::InstallBundles>` function at runtime.
 
 However, bundles can be linked statically to your application or shared
 library. This makes the deployment of your application less error-prone
-and in the case of a complete static build also minimizes its binary
-size and start-up time. The disadvantage is that no functionality can be
-added without a rebuild and redistribution of the application.
+and in the case of a complete static build, also minimizes its binary
+size and start-up time. However, in order to add new functionality to
+your application, you must rebuild and redistribute it.
+
 
 Creating Static Bundles
 -----------------------
@@ -24,26 +24,26 @@ Using Static Bundles
 --------------------
 
 Static bundles can be used (imported) in shared or other static
-libraries or in the executable itself. For every static bundle you would
-like to import, you need to put a call to
+libraries, or in the executable itself. For every static bundle you would
+like to import, you need to add a call to
 :any:`CPPMICROSERVICES_IMPORT_BUNDLE` or to
 :any:`CPPMICROSERVICES_INITIALIZE_STATIC_BUNDLE` (if the bundle does not
-provide an activator) into the source code of the importing library.
+provide an activator) in the source code of the importing library.
 
 .. note::
 
    While you can link static bundles to other static bundles, you will
    still need to import *all* of the static bundles into the final
    executable to ensure proper initialization.
 
-There are two main usage scenarios which are explained below together
-with some example code.
+The two main usage scenarios- using a shared or static CppMicroServices library- 
+are explained in the sections below.
 
 Using a Shared CppMicroServices Library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Building the CppMicroServices library as a shared library allows you to
-import static bundles into other shared or static bundles or into the
+import static bundles into other shared or static bundles, or into the
 executable.
 
 .. literalinclude:: snippets/uServices-staticbundles/main.cpp
@@ -55,9 +55,9 @@ executable.
 Using a Static CppMicroServices Library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The CppMicroServices library can be build as a static library. In that
+The CppMicroServices library can be built as a static library. In that
 case, creating shared bundles is not supported. If you create shared
-bundles which link a static version of the CppMicroServices library, the
+bundles that link a static version of the CppMicroServices library, the
 runtime behavior is undefined.
 
 In this usage scenario, every bundle will be statically build and linked
@@ -70,6 +70,6 @@ to an executable:
    :end-before: ImportStaticBundleIntoMain2
 
 Note that the first :any:`CPPMICROSERVICES_IMPORT_BUNDLE` call imports the
-static CppMicroServices library. Then the ``MyStaticBundle2`` bundle is
+static CppMicroServices library. Next, the ``MyStaticBundle2`` bundle is
 imported and finally, the executable itself is initialized (this is
-necessary if the executable itself is a C++ Micro Services bundle).
+necessary if the executable itself is a C++ Micro Services bundle).