Replace alias \Code with \TText (#4714)

Fixed GH-2151

doxygen/aliases

@@ -29,7 +29,7 @@ ALIASES += PLURL="github.com/HDFGroup/hdf5_plugins/blob/master"
 
 ALIASES += Bold{1}="<b>\1</b>"
 ALIASES += Emph{1}="<em>\1</em>"
-ALIASES += Code{1}="<tt>\1</tt>"
+ALIASES += TText{1}="<tt>\1</tt>"
 
 ################################################################################
 # Return values
@@ -249,7 +249,7 @@ ALIASES += es_id{1}="\param[in] \1 Event set identifier"
 # Others
 ################################################################################
 
-ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \Code{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior."
+ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \TText{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior."
 ALIASES += par_compr_note="\attention If you are planning to use compression with parallel HDF5, ensure that calls to H5Dwrite() occur in collective mode. In other words, all MPI ranks (in the relevant communicator) call H5Dwrite() and pass a dataset transfer property list with the MPI-IO collective option property set to #H5FD_MPIO_COLLECTIVE_IO.\n Note that data transformations are currently \Bold{not} supported when writing to datasets in parallel and with compression enabled."
 ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads"
 

doxygen/dox/About.dox

@@ -33,8 +33,8 @@ Please refer to the \ref RMT for guidance on how to create a new reference manua
 
 \subsubsection new_example Adding and Referencing API Examples
 
-For each HDF5 module, such as \Code{H5F}, there is an examples source file called
-\Code{H5*_examples.c}. For example, the \Code{H5F} API examples are located in
+For each HDF5 module, such as \TText{H5F}, there is an examples source file called
+\TText{H5*_examples.c}. For example, the \TText{H5F} API examples are located in
 <a href="https://\SRCURL/doxygen/examples/H5F_examples.c">
 <code>H5F_examples.c</code></a>. Examples are code blocks marked as Doxygen
 <a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet">snippets</a>.
@@ -94,7 +94,7 @@ ask for help if unsure!
 For ease of reference, we define custom commands for each RFC in the <tt>RFCs</tt> section
 of the
 <a href="https://\SRCURL/doxygen/aliases"><tt>aliases</tt></a>
-file. For example the custom command \Code{ref_rfc20141210} can be used to insert a
+file. For example the custom command \TText{ref_rfc20141210} can be used to insert a
 reference to "RFC: Virtual Object Layer". In other words, the markup
 \verbatim
 \ref_rfc20141210
@@ -105,8 +105,8 @@ yields a clickable link:
 
 To add a new RFC, add a custom command for the RFC to the
 <a href="https://\SRCURL/doxygen/aliases"><tt>aliases</tt></a>
-file. The naming convention for the custom command is \Code{ref_rfcYYYYMMDD},
-where \Code{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix
+file. The naming convention for the custom command is \TText{ref_rfcYYYYMMDD},
+where \TText{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix
 \verbatim
 https://\RFCURL/
 \endverbatim
@@ -116,4 +116,4 @@ be
 https://\RFCURL/my_great_rfc_name.pdf
 \endverbatim
 
-*/
+*/

doxygen/dox/H5AC_cache_config_t.dox

@@ -24,7 +24,7 @@
  *     Boolean field indicating whether the trace_file_name
  *     field should be used to open a trace file for the cache.
  *
- *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *     \Emph{*** DEPRECATED ***} Use \TText{H5Fstart/stop} logging functions instead
  *
  *     The trace file is a debugging feature that allow the capture of
  *     top level metadata cache requests for purposes of debugging and/or
@@ -42,7 +42,7 @@
  *     Boolean field indicating whether the current trace
  *     file (if any) should be closed.
  *
- *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *     \Emph{*** DEPRECATED ***} Use \TText{H5Fstart/stop} logging functions instead
  *
  *     See the above comments on the open_trace_file field.  This field
  *     should be set to \c FALSE unless there is an open trace file on the
@@ -54,7 +54,7 @@
  *     Full path of the trace file to be opened if the
  *     open_trace_file field is \c TRUE.
  *
- *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *     \Emph{*** DEPRECATED ***} Use \TText{H5Fstart/stop} logging functions instead
  *
  *     In the parallel case, an ascii representation of the mpi rank of
  *     the process will be appended to the file name to yield a unique
@@ -78,7 +78,7 @@
  *     soon as possible and monitor cache size.
  *
  *     At present, evictions can only be disabled if automatic
- *     cache resizing is also disabled (that is, \Code{(incr_mode ==
+ *     cache resizing is also disabled (that is, \TText{(incr_mode ==
  *     H5C_incr__off ) && ( decr_mode == H5C_decr__off )}).  There
  *     is no logical reason why this should be so, but it simplifies
  *     implementation and testing, and I can't think of any reason
@@ -95,7 +95,7 @@
  * \par initial_size
  *      If enabled, this field contain the size the cache is
  *      to be set to upon receipt of this structure.  Needless to say,
- *      initial_size must lie in the closed interval \Code{[min_size, max_size]}.
+ *      initial_size must lie in the closed interval \TText{[min_size, max_size]}.
  *
  * \par min_clean_fraction
  *      \c double in the range 0 to 1 indicating the fraction
@@ -105,13 +105,13 @@
  * \par max_size
  *      Maximum size to which the cache can be adjusted.  The
  *      supplied value must fall in the closed interval
- *      \Code{[MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE]}.  Also, \c max_size must
+ *      \TText{[MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE]}.  Also, \c max_size must
  *      be greater than or equal to \c min_size.
  *
  * \par min_size
  *      Minimum size to which the cache can be adjusted.  The
  *      supplied value must fall in the closed interval
- *      \Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]}.  Also, \c min_size
+ *      \TText{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]}.  Also, \c min_size
  *      must be less than or equal to \c max_size.
  *
  * \par epoch_length
@@ -122,7 +122,7 @@
  *
  *      At the end of an epoch, we discard prior hit rate data and start
  *      collecting afresh.  The epoch_length must lie in the closed
- *      interval \Code{[H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH]}.
+ *      interval \TText{[H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH]}.
  * \endparblock
  *
  *
@@ -201,8 +201,8 @@
  *      \li \c H5C_flash_incr__add_space:  Let \c x be either the size of a newly
  *          newly inserted entry, or the number of bytes by which the
  *          size of an existing entry has been increased.\n
- *          If \Code{x > flash_threshold * current max cache size},
- *          increase the current maximum cache size by \Code{x * flash_multiple}
+ *          If \TText{x > flash_threshold * current max cache size},
+ *          increase the current maximum cache size by \TText{x * flash_multiple}
  *          less any free space in the cache, and star a new epoch.  For
  *          now at least, pay no attention to the maximum increment.
  *
@@ -213,7 +213,7 @@
  *      With a little thought, it should be obvious that the above flash
  *      cache size increase algorithm is not sufficient for all circumstances
  *      -- for example, suppose the user round robins through
- *      \Code{(1/flash_threshold) +1} groups, adding one data set to each on each
+ *      \TText{(1/flash_threshold) +1} groups, adding one data set to each on each
  *      pass.  Then all will increase in size at about the same time, requiring
  *      the max cache size to at least double to maintain acceptable
  *      performance, however the above flash increment algorithm will not be
@@ -319,7 +319,7 @@
  *      This field contains the number of epochs an entry must remain
  *      unaccessed before it is evicted in an attempt to reduce the
  *      cache size.  If applicable, this field must lie in the range
- *      \Code{[1, H5C__MAX_EPOCH_MARKERS]}.
+ *      \TText{[1, H5C__MAX_EPOCH_MARKERS]}.
  * \endparblock
  *
  * \par apply_empty_reserve
@@ -412,4 +412,4 @@
  *    received from process zero.\n
  *    To avoid possible messages from the past/future, all caches must
  *    wait until all caches are done before leaving the sync point.
- */
+ */

doxygen/dox/MetadataCachingInHDF5.dox

@@ -508,7 +508,7 @@ The \ref H5AC_cache_config_t.min_clean_fraction "min_clean_fraction" sets the
 current minimum clean size as a fraction of the current max cache size. While
 this field was originally used only in the parallel version of the library, it
 now applies to the serial version as well. Its value must lie in the range
-\Code{[0.0, 1.0]}. 0.01 is reasonable in the serial case, and 0.3 in the
+\TText{[0.0, 1.0]}. 0.01 is reasonable in the serial case, and 0.3 in the
 parallel.
 
 A potential interaction, discovered at release 1.8.3, between the enforcement of
@@ -524,15 +524,15 @@ H5AC_cache_config_t.min_size "min_size" fields specify the range of maximum
 sizes that may be set for the cache by the automatic resize code. \ref
 H5AC_cache_config_t.min_size "min_size" must be less than or equal to
 \ref H5AC_cache_config_t.max_size "max_size", and both must lie in the range
-\Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]} -- currently [1 KB,
+\TText{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]} -- currently [1 KB,
 128 MB]. If you routinely run a cache size in the top half of this range, you
 should increase the hash table size. To do this, modify the \c
-H5C__HASH_TABLE_LEN \Code{\#define} in \c H5Cpkg.h and re-compile. At present,
+H5C__HASH_TABLE_LEN \TText{\#define} in \c H5Cpkg.h and re-compile. At present,
 \c H5C__HASH_TABLE_LEN must be a power of two.
 
 The \c epoch_length is the number of cache accesses between runs of the adaptive
 cache size control algorithms. It is ignored if these algorithms are turned
-off. It must lie in the range \Code{[H5C__MIN_AR_EPOCH_LENGTH,
+off. It must lie in the range \TText{[H5C__MIN_AR_EPOCH_LENGTH,
 H5C__MAX_AR_EPOCH_LENGTH]} -- currently [100, 1000000]. The above constants are
 defined in \c H5Cprivate.h. 50000 is a reasonable value.
 
@@ -570,7 +570,7 @@ fields in the section are then used as follows:
 
 \ref H5AC_cache_config_t.lower_hr_threshold "lower_hr_threshold" is the
 threshold below which the hit rate must fall to trigger an increase. The value
-must lie in the range \Code{[0.0 - 1.0]}. In my tests, a relatively high value
+must lie in the range \TText{[0.0 - 1.0]}. In my tests, a relatively high value
 seems to work best -- 0.9 for example.
 
 \ref H5AC_cache_config_t.increment "increment" is the factor by which the old
@@ -601,7 +601,7 @@ Let \c x be either the size of the newly inserted entry, the size of the newly
 loaded entry, or the number of bytes added to the size of the entry under
 consideration for triggering a flash cache size increase.
 
-If \Code{t < x}, the basic condition for a flash cache size increase is met, and
+If \TText{t < x}, the basic condition for a flash cache size increase is met, and
 we proceed as follows:
 
 Let \c space_needed equal \c x less the amount of free space in the cache.
@@ -622,11 +622,11 @@ use.
 
 The use of the \ref H5AC_cache_config_t.flash_threshold "flash_threshold" field
 is discussed above. It must be a floating-point value in the range of
-\Code{[0.1, 1.0]}. 0.25 is a reasonable value.
+\TText{[0.1, 1.0]}. 0.25 is a reasonable value.
 
 The use of the \ref H5AC_cache_config_t.flash_multiple "flash_multiple" field is
 also discussed above. It must be a floating-point value in the range of
-\Code{[0.1, 10.0]}. 1.4 is a reasonable value.
+\TText{[0.1, 10.0]}. 1.4 is a reasonable value.
 
 \subsection decrement Decrement Configuration
 
@@ -649,12 +649,12 @@ the decrement section are used as follows:
 
 \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" is the
 threshold above which the hit rate must rise to trigger cache size reduction. It
-must be in the range \Code{[0.0, 1.0]}. In my synthetic tests, very high values
+must be in the range \TText{[0.0, 1.0]}. In my synthetic tests, very high values
 like .9995 or .99995 seemed to work best.
 
 \ref H5AC_cache_config_t.decrement "decrement" is the factor by which the
 current maximum cache size is multiplied to obtain a tentative new maximum cache
-size. It must lie in the range \Code{[0.0, 1.0]}. Relatively large values like
+size. It must lie in the range \TText{[0.0, 1.0]}. Relatively large values like
 .9 seem to work best in my synthetic tests. Note that the actual size reduction
 may be smaller as required by \ref H5AC_cache_config_t.min_size "min_size" and
 \ref H5AC_cache_config_t.max_decrement "max_decrement" (discussed below).  \ref
@@ -676,7 +676,7 @@ decrement section are used as follows:
 
 \ref H5AC_cache_config_t.epochs_before_eviction "epochs_before_eviction" is the
 number of epochs an entry must reside unaccessed in the cache before it is
-evicted. This value must lie in the range \Code{[1, H5C__MAX_EPOCH_MARKERS]}. \c
+evicted. This value must lie in the range \TText{[1, H5C__MAX_EPOCH_MARKERS]}. \c
 H5C__MAX_EPOCH_MARKERS is defined in H5Cprivate.h, and is currently set to 10.
 
 \ref H5AC_cache_config_t.apply_max_decrement "apply_max_decrement" and \ref
@@ -702,7 +702,7 @@ H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold".
 
 Here, \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" is the
 threshold above which the hit rate must rise to trigger cache size reduction. It
-must be in the range \Code{[0.0, 1.0]}. In my synthetic tests, high values like
+must be in the range \TText{[0.0, 1.0]}. In my synthetic tests, high values like
 .999 seemed to work well.
 
 \subsection parallel Parallel Configuration
@@ -1017,4 +1017,4 @@ and the average successful and unsuccessful search depths in the hash table. If
 these latter figures are significantly above 1, you should increase the size of
 the hash table.
 
- */
+ */

doxygen/dox/ReferenceManual.dox

@@ -151,18 +151,18 @@ Follow these simple rules and stay out of trouble:
     identifiers, which you typically obtain by creating new HDF5 items, copying
     items, or retrieving facets of items. Consequently, \Bold{and most importantly}, you are 
     responsible for releasing the underlying
-    resources via the matching \Code{H5*close()} call, or deal with the consequences
+    resources via the matching \TText{H5*close()} call, or deal with the consequences
     of resource leakage.
 \li \Bold{Closed means closed:} Do not pass identifiers that were previously
-    \Code{H5*close()}-d to other API functions! It will generate an error.
+    \TText{H5*close()}-d to other API functions! It will generate an error.
 \li \Bold{Dynamic memory allocation:} The API contains a few functions in which the
     HDF5 library dynamically allocates memory on the caller's behalf. The caller owns
     this memory and eventually must free it by calling H5free_memory() and not language-explicit memory functions.
 \li \Bold{Don't modify while iterating:} Do not modify the underlying collection when an
     iteration is in progress!
-\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name}
+\li \Bold{Use of locations:} Certain API functions, typically called \TText{H5***_by_name}
     use a combination of identifiers and path names to refer to HDF5 objects.
-    If the identifier fully specifies the object in question, pass \Code{'.'} (a dot)
+    If the identifier fully specifies the object in question, pass \TText{'.'} (a dot)
     for the name!
 
 </td>