Correct man page formatting in RST output

[ric-plt/lib/rmr.git] / doc / src / rtd / developer-guide.xfm

diff --git a/doc/src/rtd/developer-guide.xfm b/doc/src/rtd/developer-guide.xfm
index ebde32a..6ca8b9d 100644 (file)
--- a/doc/src/rtd/developer-guide.xfm
+++ b/doc/src/rtd/developer-guide.xfm
@@ -1,8 +1,8 @@
 .** vim: ts=4 noet sw=4:
 .if false
 ==================================================================================
 .** vim: ts=4 noet sw=4:
 .if false
 ==================================================================================

-       Copyright (c) 2019 Nokia
-       Copyright (c) 2018-2019 AT&T Intellectual Property.
+       Copyright (c) 2019-2020 Nokia
+       Copyright (c) 2018-2020 AT&T Intellectual Property.

 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.


@@ -26,72 +26,83 @@
        Author:         E. Scott Daniels
 .fi
 
        Author:         E. Scott Daniels
 .fi
 

+.dv GEN_TITLE=1
+.dv doc_title Developer's Guide
+

 .im setup.im
 
 .im setup.im
 

-&h1(RMR Developer Guide)
+&h1(Overview)

 
 

-The RIC Message Router (RMR) is a library which applications use to send and receive
-messages where the message routing, endpoint selection, is based on the message type 
-rather than on traditional DNS names or IP addresses. 
-This document contains information that potential developers might need to know 
-in order to contribute to the project
+The RIC Message Router (RMR) is a library for peer-to-peer
+communication.  Applications use the library to send and receive
+messages where the message routing and endpoint selection is based on
+the message type rather than DNS host name-IP port combinations.
+&space
+This document contains information that developers need to know to
+contribute to the RMR project.

 
 &h2(Language)
 
 &h2(Language)

-RMR is written in C, and thus a contributing developer to the core library should 
-have an excellent working knowledge of C.
-There currently is one set of cross languages bindings supporting Python, and a
-developer wishing to contribute to the bindings source should be familiar with 
-Python (version 3.7+) and with the Python &ital(ctypes) library.
+RMR is written in C, and thus a contributing developer to the core
+library should have an excellent working knowledge of C.  There
+currently is one set of cross-languages bindings supporting Python,
+and a developer wishing to contribute to the bindings source should be
+familiar with Python (version 3.7+) and with the Python &ital(ctypes)
+library.

 
 &h2(Code Structure)
 
 &h2(Code Structure)

-RMR is designed to provide an insulation layer between user applications and 
-the actual transport mechanism.  
-Initially RMR was built on top of Nanosmg, and shortly after was ported to NNG
-(Nanomsg Next Generation).  
-Because RMR presents the same API to the user application regardless of the underlying
-transport library, the resulting output when compiling RMR is a transport specific
-library. 
-As an example, &cw(librmr_nng.a) is the library generated for use with the NNG
-transport.
-&space
+RMR is designed to provide an insulation layer between user
+applications and the actual transport mechanism.  Initially RMR was
+built on top of the third-party library Nanosmg, shortly after was
+ported to the third-party library NNG (Nanomsg Next Generation), and
+then was ported to an internally developed socket library called SI95.
+RMR presents the same API to the user application regardless of the
+underlying transport library, but the resulting output when compiling
+RMR is always a transport-specific library.  As an example,
+&cw(librmr_nng.a) is the library generated for use with the NNG
+transport.  &space

 
 As such the library source is organised into multiple components:
 
 &beg_dlist(.75i : ^&bold_font )
 
 
 As such the library source is organised into multiple components:
 
 &beg_dlist(.75i : ^&bold_font )
 

-&di(common) Source in the common directory is agnostic to the underlying transport
-       mechanism (Nanomsg or NNG), and thus can be used when generating either library.
+&ditem(common) Source in the common directory is agnostic to the
+       underlying transport mechanism (Nanomsg, NNG, SI95, ..), and
+       thus can be used when generating either library.

 
 

-&di(nano) Source which is tightly coupled with the underlying Nanomsg library.
+&ditem(nano) Source which is tightly coupled with the underlying Nanomsg library.

        (Nanomsg has been deprecated, but the RMR source remains as an example.)
 
        (Nanomsg has been deprecated, but the RMR source remains as an example.)
 

-&di(nng) Source which is tightly coupled with the underlying NNG library.
+&ditem(nng) Source which is tightly coupled with the underlying NNG library.
+       (NNG has been deprecated, but the RMR source remains as an example.)
+
+&ditem(si) Source which is tightly coupled with the underlying SI95 library.

 
 &end_dlist
 
 &space
 &h3(Internal Function Exposure)
 
 &end_dlist
 
 &space
 &h3(Internal Function Exposure)

-The decision to limit as much as practical the exposure of truely internal RMR functions
-was made, and as a result most of the RMR functions carry a &cw(static) label.
-In order to modularise the code as much as possible, this means that the primary
-module (e.g. rmr_nng.c) will directly include other RMR modules, rather than 
-depending on referencing the internal functions during linking.
-While this is an infrequently used approach, it does mean that there are very 
-few functions visible for the user application to reference, all of them having 
-the prefix &cw(rmr&{esc}_,) while allowing internal functions to have shorter names
-while still being meaningful.
+The decision to limit as much as practical the exposure of truly
+internal RMR functions was made, and as a result most of the RMR
+functions carry a &cw(static) label.  In order to modularise the code
+as much as possible, this means that the primary module
+(e.g. rmr_nng.c) directly includes other RMR modules, rather than
+depending on referencing the internal functions during linking.  While
+this is an infrequently used approach, it does mean that there are
+very few functions visible for the user application to reference, all
+of them having the prefix &cw(rmr&{esc}_). This allows internal
+functions to have shorter names while still being meaningful.

 
 &h2(Coding Style)
 
 &h2(Coding Style)

-There is a list of coding style guidelines in the top level directory, and as such
-they are not expanded upon here. 
-The general practice is to follow the style when editing an existing module, respect
-the author's choice where style alternatives are not frowned upon.
-When creating new modules, select a style that fits the guidelines and is easy
-for you to work with.
-There are a few things that are insisted on by the maintainers of RMR, but for the
-most part style is up to the creator of a module.
+There is a list of coding style guidelines in the top level directory,
+and as such they are not expanded upon here.  The general practice is
+to follow the style when editing an existing module, respect the
+author's choice where style alternatives are not frowned upon.  When
+creating new modules, select a style that fits the guidelines and is
+easy for you to work with.  There are a few things that the RMR
+maintainers insist on, but for the most part style is up to the
+creator of a module.

 
 &h2(Building)
 
 &h2(Building)

-RMR is constructed using CMake.
-While CMake's project description can be more cumbersome than most typical Makefiles, 
-the tool provides convenience especially when it comes to creating packages.
+RMR is constructed using CMake.  While CMake's project description can
+be more cumbersome than most typical Makefiles, the tool provides
+convenience especially when it comes to creating DEB/RPM packages.