Funtion name with variable part in doc/man7/ and doc/internal/man3/

We have a few pages where part of function names can be considered
variable.  There are no normative guidelines for such a case, but if
we draw from the formatting convention of variable and argument names,
we can draw the conclusion that this variable part should be italized,
within already given conventions.  In other words, we need to help the
POD processor along in cases like these:

    SPARSE_ARRAY_OF(TYPE)
    ossl_sa_TYPE_num()

These need explicit formatting:

    B<SPARSE_ARRAY_OF>(I<TYPE>)
    B<ossl_sa_I<TYPE>_num>()

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10034)

3 files changed, 44 insertions, 27 deletions

diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
index 8afd48ec4d..60695266a7 100644
--- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
+++ b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
@@ -33,38 +33,46 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
 
 =head1 DESCRIPTION
 
+=begin comment
+
+POD is pretty good at recognising function names and making them appropriately
+bold...  however, when part of the function name is variable, we have to help
+the processor along
+
+=end comment
+
 SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
-B<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
-B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
-element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
-each function name begins with B<ossl_sa_TYPE_>. For example:
+I<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
+I<TYPE>. This will mean that a pointer to type I<TYPE> is stored in each
+element of a sparse array, the type is referenced by B<SPARSE_ARRAY_OF>(I<TYPE>)
+and each function name begins with B<ossl_sa_I<TYPE>_>. For example:
 
  TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
 
-ossl_sa_TYPE_num() returns the number of elements in I<sa> or 0 if I<sa> is
-NULL.
+B<ossl_sa_I<TYPE>_num>() returns the number of elements in I<sa> or 0 if I<sa>
+is NULL.
 
-ossl_sa_TYPE_get() returns element I<idx> in I<sa>, where I<idx> starts at
-zero. If I<idx> refers to a value that has not been set then NULL is
+B<ossl_sa_I<TYPE>_get>() returns element I<idx> in I<sa>, where I<idx> starts
+at zero. If I<idx> refers to a value that has not been set then NULL is
 returned.
 
-ossl_sa_TYPE_set() sets element I<idx> in I<sa> to I<value>, where I<idx>
+B<ossl_sa_I<TYPE>_set>() sets element I<idx> in I<sa> to I<value>, where I<idx>
 starts at zero. The sparse array will be resized as required.
 
-ossl_sa_TYPE_new() allocates a new empty sparse array.
+B<ossl_sa_I<TYPE>_new>() allocates a new empty sparse array.
 
-ossl_sa_TYPE_free() frees up the I<sa> structure. It does I<not> free up any
+B<ossl_sa_I<TYPE>_free>() frees up the I<sa> structure. It does I<not> free up any
 elements of I<sa>. After this call I<sa> is no longer valid.
 
-ossl_sa_TYPE_free_leaves() frees up the I<sa> structure and all of its
+B<ossl_sa_I<TYPE>_free_leaves>() frees up the I<sa> structure and all of its
 elements.  After this call I<sa> is no longer valid.
 
-ossl_sa_TYPE_doall() calls the function I<leaf> for each element in I<sa>
+B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa>
 in ascending index order. The index position, within the sparse array,
 of each item is passed as the first argument to the leaf function and a
 pointer to the associated value is is passed as the second argument.
 
-ossl_sa_TYPE_doall_arg() calls the function I<leaf> for each element in
+B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in
 I<sa> in ascending index order. The index position, within the sparse
 array, of each item is passed as the first argument to the leaf function,
 a pointer to the associated value is passed as the second argument and
@@ -77,9 +85,9 @@ Sparse arrays are an internal data structure and should B<not> be used by user
 applications.
 
 Care should be taken when accessing sparse arrays in multi-threaded
-environments.  The ossl_sa_TYPE_set operation can cause the internal structure
-of the sparse array to change which causes race conditions if the sparse array
-is accessed in a different thread.
+environments.  The B<ossl_sa_I<TYPE>_set>() operation can cause the internal
+structure of the sparse array to change which causes race conditions if the
+sparse array is accessed in a different thread.
 
 SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
 
@@ -90,21 +98,22 @@ OPENSSL_SA_num and OPENSSL_SA_set.
 
 =head1 RETURN VALUES
 
-ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
-if the passed sparse array is NULL.
+B<ossl_sa_I<TYPE>_num>() returns the number of elements in the sparse array or
+B<0> if the passed sparse array is NULL.
 
-ossl_sa_TYPE_get() returns a pointer to a sparse array element or NULL if
+B<ossl_sa_I<TYPE>_get>() returns a pointer to a sparse array element or NULL if
 the element has not be set.
 
-ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
+B<ossl_sa_I<TYPE>_set>() return B<1> on success and B<0> on error. In the latter
 case, the elements of the sparse array remain unchanged, although the internal
 structures might have.
 
-ossl_sa_TYPE_new() returns an empty sparse array or NULL if an error
+B<ossl_sa_I<TYPE>_new>() returns an empty sparse array or NULL if an error
 occurs.
 
-ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
-ossl_sa_TYPE_free_leaves() do not return values.
+B<ossl_sa_I<TYPE>_doall>(), B<ossl_sa_I<TYPE>_doall_arg>(),
+B<ossl_sa_I<TYPE>_free>() and B<ossl_sa_I<TYPE>_free_leaves>()
+do not return values.
 
 =head1 HISTORY
 
diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod
index 2eb838d9a9..fb439f24a6 100644
--- a/doc/internal/man3/ossl_param_bld_init.pod
+++ b/doc/internal/man3/ossl_param_bld_init.pod
@@ -70,7 +70,15 @@ by I<data> of at least I<data_n> bytes in size.
 If required, secure memory for private BIGNUMs should be pointed to by
 I<secure> of at least I<secure_n> bytes in size.
 
-ossl_param_bld_push_TYPE() are a series of functions which will create
+=begin comment
+
+POD is pretty good at recognising function names and making them appropriately
+bold...  however, when part of the function name is variable, we have to help
+the processor along
+
+=end comment
+
+B<ossl_param_bld_push_I<TYPE>>() are a series of functions which will create
 OSSL_PARAM objects of the specified size and correct type for the I<val>
 argument.
 I<val> is stored by value and an expression or auto variable can be used.
diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod
index 1d3276b730..84892e71ac 100644
--- a/doc/man7/bio.pod
+++ b/doc/man7/bio.pod
@@ -49,8 +49,8 @@ BIO_free() on it other than the discarded return value.
 
 Normally the I<type> argument is supplied by a function which returns a
 pointer to a BIO_METHOD. There is a naming convention for such functions:
-a source/sink BIO is normally called BIO_s_*() and a filter BIO
-BIO_f_*();
+a source/sink BIO is normally called B<BIO_s_I<*>>() and a filter BIO
+B<BIO_f_I<*>>();
 
 =head1 EXAMPLES