Add manual pages to RTD as individual files
This change introduces the code to generate man pages
as individual .rst files and the first set of those
into the scrapable docs directory.
Issue-ID: RIC-328
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: I8d0b7b84b0b4fcadf9767d0ba69db64078a38d69
diff --git a/doc/src/library/failures.im b/doc/src/library/failures.im
index dcea1e3..27949a9 100644
--- a/doc/src/library/failures.im
+++ b/doc/src/library/failures.im
@@ -153,7 +153,7 @@
&di(RMR_ERR_INITFAILED) initialisation of something (probably message) failed
&half_space
- &di(RMR_ERR_NOTSUPP) the request is not supported, or RMr was not initialised for the request
+ &di(RMR_ERR_NOTSUPP) the request is not supported, or RMR was not initialised for the request
&end_dlist
&uindent
.st &textsize
diff --git a/doc/src/man/retry.im b/doc/src/man/retry.im
index 7ffd34a..f5396f2 100644
--- a/doc/src/man/retry.im
+++ b/doc/src/man/retry.im
@@ -46,7 +46,7 @@
calls to &ital(sleep()) or &ital(usleep().)
The number of retry loops defaults to 1, thus a maximum of 1000 send attempts is performed
before returning to the user application.
-This value can be set at any point after RMr initialisation using the &ital(rmr_set_stimeout())
+This value can be set at any point after RMR initialisation using the &ital(rmr_set_stimeout())
function allowing the user application to completely disable retires (set to 0), or to
increase the number of retry loops.
diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm
index a82b42c..e372571 100644
--- a/doc/src/man/rmr.7.xfm
+++ b/doc/src/man/rmr.7.xfm
@@ -18,7 +18,7 @@
.fi
.if false
Mnemonic rmr.7.xfm
- Abstract The manual page for the whole RMr library
+ Abstract The manual page for the whole RMR library
Author E. Scott Daniels
Date 29 January 2019
.fi
@@ -28,17 +28,17 @@
&line_len(6i)
-&h1(RMr Library)
+&h1(RMR Library)
&h2(NAME)
- RMr -- Ric Message Router Library
+ RMR -- Ric Message Router Library
&h2(DESCRIPTION)
-RMr is a library which provides a user application with the ability
-to send and receive messages to/from other RMr based applications
+RMR is a library which provides a user application with the ability
+to send and receive messages to/from other RMR based applications
without having to understand the underlying messaging transport environment (e.g., SI95)
and without needing to know which other endpoint applications are currently
available and accepting messages.
-To do this, RMr depends on a routing table generated by an external source.
+To do this, RMR depends on a routing table generated by an external source.
This table is used to determine the destination endpoint of each message sent by mapping the
message type T (supplied by the user application) to an endpoint entry.
Once determined, the message is sent directly to the endpoint.
@@ -47,7 +47,7 @@
applications.
&space
-RMr functions do provide for the ability to respond to the specific source
+RMR functions do provide for the ability to respond to the specific source
instance of a message allowing for either a request response, or call
response relationship when needed.
@@ -64,7 +64,7 @@
It is the responsibility of the route table generator to know which endpoints
belong to which groups, and which groups accept which message types.
Once understood, the route table generator publishes a table that is ingested
-by RMr and used for mapping messages to end points.
+by RMR and used for mapping messages to end points.
.sp
The following is a simple route table which causes message types 0 through 9 to
@@ -167,10 +167,10 @@
&h3(Environment)
To enable configuration of the library behaviour outside of direct user application
-control, RMr supports a number of environment variables which provide information
+control, RMR supports a number of environment variables which provide information
to the library.
The following is a list of the various environment variables, what they control
-and the defaults which RMr uses if undefined.
+and the defaults which RMR uses if undefined.
&space
.** the list of environment vars supported
diff --git a/doc/src/man/rmr_close.3.xfm b/doc/src/man/rmr_close.3.xfm
index a8c97a9..d6b17ac 100644
--- a/doc/src/man/rmr_close.3.xfm
+++ b/doc/src/man/rmr_close.3.xfm
@@ -24,6 +24,8 @@
Date 21 February 2019
.fi
+.dv doc_title Man Page: rmr_close
+
.gv e LIB lib
.im &{lib}/man/setup.im
diff --git a/doc/src/man/rmr_get_const.3.xfm b/doc/src/man/rmr_get_const.3.xfm
new file mode 100644
index 0000000..26d511e
--- /dev/null
+++ b/doc/src/man/rmr_get_const.3.xfm
@@ -0,0 +1,75 @@
+.if false
+==================================================================================
+ Copyright (c) 2020 Nokia
+ Copyright (c) 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic rmr_get_const.xfm
+ Abstract The manual page for the rmr_get_const function.
+ Author E. Scott Daniels
+ Date 10 April 2020
+.fi
+
+.gv e LIB lib
+.im &{lib}/man/setup.im
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_get_const
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+unsigned char* rmr_get_const();
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_get_const) function is a convenience function for wrappers which do not have
+the ability to "compile in" RMR constants.
+The function will build a nil terminated string containing JSON which defines the
+RMR constants that C and Go applications have at compile time via the &cw(rmr.h) header file.
+.sp
+
+All values are represented as strings and the JSON format is illustrated in the following (partial)
+example:
+&half_space
+
+&ex_start
+{
+ "RMR_MAX_XID": "32",
+ "RMR_OK": "0",
+ "RMR_ERR_BADARG", "1",
+ "RMR_ERR_NOENDPT" "2"
+}
+&ex_end
+
+&h2(RETURN VALUE)
+On success, a pointer to a string containing the JSON defining constant and value pairs.
+On failure a nil pointer is returned.
+
+
+&h2(SEE ALSO )
+.ju off
+rmr(7)
+.ju on
+
diff --git a/doc/src/man/rmr_get_src.3.xfm b/doc/src/man/rmr_get_src.3.xfm
index 31d82ff..eade6d1 100644
--- a/doc/src/man/rmr_get_src.3.xfm
+++ b/doc/src/man/rmr_get_src.3.xfm
@@ -46,14 +46,14 @@
&h2(DESCRIPTION)
The &cw(rmr_get_src) function will copy the &ital(source) information from the message to a buffer
(dest) supplied by the user.
-In an RMr message, the source is the sender's information that is used for return to sender
+In an RMR message, the source is the sender's information that is used for return to sender
function calls, and is generally the hostname and port in the form &ital(name:port).
The source might be an IP address port combination; the data is populated by the sending process
and the only requirement is that it be capable of being used to start a TCP session with the
sender.
.sp
-The maximum size allowed by RMr is 64 bytes (including the nil string terminator), so the user
+The maximum size allowed by RMR is 64 bytes (including the nil string terminator), so the user
must ensure that the destination buffer given is at least 64 bytes.
&h2(RETURN VALUE)
diff --git a/doc/src/man/rmr_get_srcip.3.xfm b/doc/src/man/rmr_get_srcip.3.xfm
index ee55ebf..99708ba 100644
--- a/doc/src/man/rmr_get_srcip.3.xfm
+++ b/doc/src/man/rmr_get_srcip.3.xfm
@@ -46,16 +46,16 @@
&h2(DESCRIPTION)
The &cw(rmr_get_srcip) function will copy the &ital(source IP address) from the message to a buffer
(dest) supplied by the user.
-In an RMr message, the source IP address is the sender's information that is used for return to sender
+In an RMR message, the source IP address is the sender's information that is used for return to sender
function calls; this function makes it available to the user application.
The address is maintained as IP:port where &ital(IP) could be either an IPv6 or IPv4 address depending
on what was provided by the sending application.
.sp
-The maximum size allowed by RMr is 64 bytes (including the nil string terminator), so the user
+The maximum size allowed by RMR is 64 bytes (including the nil string terminator), so the user
must ensure that the destination buffer given is at least 64 bytes. The user application should use
-the RMr constant RMR_MAX_SRC to ensure that the buffer supplied is large enough, and to protect
-against future RMr enhancements which might increase the address buffer size requirement.
+the RMR constant RMR_MAX_SRC to ensure that the buffer supplied is large enough, and to protect
+against future RMR enhancements which might increase the address buffer size requirement.
&h2(RETURN VALUE)
On success, a pointer to the destination buffer is given as a convenience to the user programme.
diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm
index acace5a..4f57b06 100644
--- a/doc/src/man/rmr_init.3.xfm
+++ b/doc/src/man/rmr_init.3.xfm
@@ -73,8 +73,8 @@
size might be a larger memory footprint.
&space
-&ital(Flags) allows for selection of some RMr options at the time of initialisation.
-These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
+&ital(Flags) allows for selection of some RMR options at the time of initialisation.
+These are set by ORing &cw(RMRFL) constants from the RMR header file. Currently the
following flags are supported:
&half_space
@@ -85,7 +85,7 @@
&half_space
&ditem(RMRFL_NOTHREAD)
The route table collector thread is not to be started. This should only be used
- by the route table generator application if it is based on RMr.
+ by the route table generator application if it is based on RMR.
&half_space
&ditem(RMRFL_MTCALL)
@@ -114,10 +114,10 @@
&space
Multi-threaded call support requires the user application to specifically enable it
-when RMr is initialised.
+when RMR is initialised.
This is necessary because a second, dedicated, receiver thread must be started, and
requires all messages to be examined and queued by this thread.
-The additional overhead is minimal, queuing information is all in the RMr message
+The additional overhead is minimal, queuing information is all in the RMR message
header, but as an additional process is necessary the user application must "opt in"
to this approach.
diff --git a/doc/src/man/rmr_init_trace.3.xfm b/doc/src/man/rmr_init_trace.3.xfm
index c698c3a..a4f47a0 100644
--- a/doc/src/man/rmr_init_trace.3.xfm
+++ b/doc/src/man/rmr_init_trace.3.xfm
@@ -66,7 +66,7 @@
&h2(RETURN VALUE)
A value of 1 is returned on success, and 0 on failure. A failure indicates that the
-RMr context (a void pointer passed to this function was not valid.
+RMR context (a void pointer passed to this function was not valid.
&h2(SEE ALSO )
.ju off
diff --git a/doc/src/man/rmr_mt_rcv.3.xfm b/doc/src/man/rmr_mt_rcv.3.xfm
index 25b418a..7f2af20 100644
--- a/doc/src/man/rmr_mt_rcv.3.xfm
+++ b/doc/src/man/rmr_mt_rcv.3.xfm
@@ -44,7 +44,7 @@
&h2(DESCRIPTION)
The &cw(rmr_mt_rcv) function blocks until a message is received, or the timeout
period (milliseconds) has passed.
-The result is an RMr message buffer which references a received message.
+The result is an RMR message buffer which references a received message.
In the case of a timeout the state will be reflected in an "empty buffer" (if old_msg
was not nil, or simply with the return of a nil pointer.
If a timeout value of zero (0) is given, then the function will block until
@@ -79,7 +79,7 @@
&h2(RETURN VALUE)
When a message is received before the timeout period expires, a pointer to the
-RMr message buffer which describes the message is returned.
+RMR message buffer which describes the message is returned.
This will, with a high probability, be a different message buffer than &ital(old_msg;)
the user application should not continue to use &ital(old_msg) after it is passed
to this function.
@@ -107,7 +107,7 @@
message will be 0.
&half_space
-&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMr was
+&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMR was
initialised. See the man page for &ital(rmr_init()) for details.
&half_space
diff --git a/doc/src/man/rmr_set_stimeout.3.xfm b/doc/src/man/rmr_set_stimeout.3.xfm
index ce587c1..3ef3d7a 100644
--- a/doc/src/man/rmr_set_stimeout.3.xfm
+++ b/doc/src/man/rmr_set_stimeout.3.xfm
@@ -43,14 +43,14 @@
&uindent
&h2(DESCRIPTION)
-The &cw(rmr_set_stimeout) function sets the configuration for how RMr will retry
+The &cw(rmr_set_stimeout) function sets the configuration for how RMR will retry
message send operations which complete with either a &ital(timeout) or &ital(again)
completion value. (Send operations include all of the possible message send
functions: &ital(rmr_send_msg(), rmr_call(), rmr_rts_msg()) and &ital(rmr_wh_send_msg().)
The &ital(rloops) parameter sets the maximum number of retry loops
that will be attempted before giving up and returning the unsuccessful state to the user
application.
-Each retry loop is approximately 1000 attempts, and RMr does &bold(not) invoke any sleep
+Each retry loop is approximately 1000 attempts, and RMR does &bold(not) invoke any sleep
function between retries in the loop; a small, 1 mu-sec, sleep is executed between loop
sets if the &ital(rloops) value is greater than 1.
@@ -61,7 +61,7 @@
If the user application does not want to have send operations retry when the underlying
transport mechanism indicates &ital(timeout) or &ital(again,) the application should
invoke this function and pass a value of 0 (zero) for &ital(rloops.)
-With this setting, all RMr send operations will attempt a send operation only &bold(once,)
+With this setting, all RMR send operations will attempt a send operation only &bold(once,)
returning immediately to the caller with the state of that single attempt.
diff --git a/doc/src/man/rmr_wh_open.3.xfm b/doc/src/man/rmr_wh_open.3.xfm
index 738090a..af343dc 100644
--- a/doc/src/man/rmr_wh_open.3.xfm
+++ b/doc/src/man/rmr_wh_open.3.xfm
@@ -45,7 +45,7 @@
&h2(DESCRIPTION)
The &cw(rmr_wh_open) function creates a direct link for sending, a wormhole, to another
-RMr based process.
+RMR based process.
Sending messages through a wormhole requires that the connection be established overtly
by the user application (via this function), and that the ID returned by &cw(rmr_wh_open)
be passed to the &cw(rmr_wh_send_msg) function.
@@ -53,7 +53,7 @@
&space
&ital(Target) is the &ital(name:port,) or &ital(IP-address:port,) combination of the
processess that the wormhole should be connected to.
-&ital(Vctx) is the RMr void context pointer that was returned by the &cw(rmr_init) function.
+&ital(Vctx) is the RMR void context pointer that was returned by the &cw(rmr_init) function.
&space
When invoked, this function immediatly attempts to connect to the target process.
diff --git a/doc/src/man/setup.im b/doc/src/man/setup.im
index 3d36416..a6e0649 100644
--- a/doc/src/man/setup.im
+++ b/doc/src/man/setup.im
@@ -53,5 +53,10 @@
.fi
.fi
+.gv e GEN_TITLE gen_title
+.if "&gen_title" "1" =
+ .im gen_title.im
+.fi
+
.dv _setup_im 1
.fi
diff --git a/doc/src/rst.im b/doc/src/rst.im
index b9c791a..871d340 100644
--- a/doc/src/rst.im
+++ b/doc/src/rst.im
@@ -39,9 +39,13 @@
.** bloody rst has no consistant marking character, and each header level must be different and as long as the text.
.** and of course they don't generate <hx> tags in the resulting HTML, but <section> tags. WTF?
- .dv h1 .sp 1 $1 .br ============================================================================================ .sp 1
- .dv h2 .sp 1 $1 .br -------------------------------------------------------------------------------------------- .sp 1
- .dv h3 .sp 1 $1 .br ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .sp 1
+ .dv many_equals ============================================================================================
+ .dv many_dashes --------------------------------------------------------------------------------------------
+ .dv many_tildas ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ .dv h1 .sp 1 $1 .br &many_equals .sp 1
+ .dv h2 .sp 1 $1 .br &many_dashes .sp 1
+ .dv h3 .sp 1 $1 .br &many_tildas .sp 1
+
.dv h4 **$1**
.** .dv h1 === $1 .br === .sp 1
.** .dv h2 === $1 .br === .sp 1
diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile
index 878229e..f3fbf41 100644
--- a/doc/src/rtd/Makefile
+++ b/doc/src/rtd/Makefile
@@ -56,6 +56,7 @@
# copy the .rst files which have changed into the docs (plural) directory at the root of the repo
publish : $(docs:%=%.rst)
+ bash publish_man.sh;\
for f in *.rst;\
do\
if ! diff -N -q $$f ../../../docs/$$f >/dev/null 2>&1;\
diff --git a/doc/src/rtd/gen_title.im b/doc/src/rtd/gen_title.im
new file mode 100644
index 0000000..98cbb25
--- /dev/null
+++ b/doc/src/rtd/gen_title.im
@@ -0,0 +1,65 @@
+.** vim: ts=4 sw=4 noet:
+.if false
+==================================================================================
+ Copyright (c) 2020 Nokia
+ Copyright (c) 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.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+
+.if false
+ Mnemonic: gen_title.im
+ Abstract: Imbed file to generate a title when requested. Uses doc_title and
+ doc_subtitle strings if available. We will inject a man page title
+ if the INPUT_FILE env variable is set to avoid having to edit
+ all of them to add such a beast which isn't needed for a real
+ man page.
+
+ Date: 10 April 2020
+.fi
+
+.gv e INPUT_FILE in
+.if in
+ .if ! doc_title
+ .dv doc_title Man Page: &in
+ .fi
+.fi
+
+.im license.im
+
+.gv e OUTPUT_TYPE ot
+.if doc_title
+ .if "&ot" "rst" =
+ &many_equals .br
+ &doc_title .br
+ &many_equals .br
+ .if &doc_subtitle
+ &many_dashes .br
+ &doc_subtitle .br
+ &many_dashes .br
+ .fi
+ .ei
+ .sf Helvetica
+ .sp 5
+ .st 18
+ .ce &doc_title
+ .st 12
+ .if &doc_subtitle
+ .ce &doc_subtitle
+ .fi
+ .st &textsize
+ .sf &txtfont
+ .sp 2
+ .fi
+.fi
diff --git a/doc/src/rtd/license.im b/doc/src/rtd/license.im
index 46a413b..c94dd21 100644
--- a/doc/src/rtd/license.im
+++ b/doc/src/rtd/license.im
@@ -27,6 +27,12 @@
only to be overlaid by a regen. Committing output is stupid.
.fi
+.if ! _license_im
+
+.cd 1 14i i=0
+.ll 14i
+.in 0i
+
.dv lic_comment_1 This work is licensed under a Creative Commons Attribution 4.0 International License.
.dv lic_comment_2 SPDX-License-Identifier: CC-BY-4.0
.dv caution_1 CAUTION: this document is generated from source in doc/src/rtd.
@@ -56,3 +62,10 @@
.sp 1
+
+.cd 1 8i i=0
+.ll 8i
+.in 0
+
+.dv _license_im 1
+.fi
diff --git a/doc/src/rtd/publish_man.sh b/doc/src/rtd/publish_man.sh
new file mode 100755
index 0000000..a0f71cd
--- /dev/null
+++ b/doc/src/rtd/publish_man.sh
@@ -0,0 +1,55 @@
+#/usr/bin/env bash
+# vim: sw=4 ts=4 noet :
+
+#==================================================================================
+# Copyright (c) 2020 Nokia
+# Copyright (c) 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.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#==================================================================================
+
+# build separate man pages as .rst files and publish to the scrapable directory if
+# there are changes. We build the .rst and if it is different than what is in the
+# scarper directory we will copy it over there. We inject a title so that the
+# RTD scripts won't object.
+
+sdir="../../../docs" # the scraper dir
+
+if [[ ! -d $sdir ]]
+then
+ echo "cannot find scraper directory: $sdir"
+ exit 1
+fi
+
+mkdir -p stuff
+ls -al ../man/*.xfm|sed 's!^.*man/!!' | while read x
+do
+ if [[ $x != *".7.xfm" ]]
+ then
+ out=stuff/${x%.*}.rst
+ target=${sdir}/${out##*/}
+
+ INPUT_FILE=${x%%.*} GEN_TITLE=1 LIB=".." OUTPUT_TYPE=rst tfm ../man/$x stdout 2>/dev/null | sed 's/^ //' >$out
+ new_m5=$( md5sum $out | sed 's/ .*//' )
+ if [[ ! -f $target || $new_m5 != $( md5sum $target | sed 's/ .*//' ) ]]
+ then
+ cp $out $target
+ fi
+
+ echo "${target##*/}"
+
+ rm $out
+ fi
+done
+
+rmdir stuff
diff --git a/doc/src/rtd/setup.im b/doc/src/rtd/setup.im
index 92f7539..51b5d2b 100644
--- a/doc/src/rtd/setup.im
+++ b/doc/src/rtd/setup.im
@@ -62,5 +62,12 @@
.cd 1 6.5i m=0 i=0
&line_len( 6i)
+.if ! textsize
+ .dv textsize 10
+.fi
+.if ! textfont
+ .dv textfont Helvetica
+.fi
+
.dv _setup_im 1
.fi