Example for Fortran 2008 Wrapper is not in Example environment

[mahermanns]

Problem

An example for creating a wrapper for Fortran 2008 function using PMPI is part of a longer "Advice to Users" but should rather be a proper example and indexed as such.

Proposal

Extract example from advice to users into a proper example environment.

Changes to the Text

https://github.com/mpi-forum/mpi-standard/pull/960

Impact on Implementations

None.

Impact on Users

Improved readability.

References and Pull Requests

mpiexec and PMPI_ in function index: https://github.com/mpi-forum/mpi-issues/issues/785

[wrwilliams]

There are additionally examples in the AtoI immediately preceding this; those should probably also get pulled out into the example environment, no?

[jeffhammond]

i don't understand this issue. can you put explicit references to what you want to change? is the example you discuss in the standard or are you proposing to create it?

[wrwilliams]

i don't understand this issue. can you put explicit references to what you want to change? is the example you discuss in the standard or are you proposing to create it?

The examples are the lstlisting blocks in 19.1.5. Diff of just naively making the atou an example (indexing probably not yet right):

diff --git a/chap-binding/binding-2.tex b/chap-binding/binding-2.tex
index 9e9edb37..8eaf8a14 100644
--- a/chap-binding/binding-2.tex
+++ b/chap-binding/binding-2.tex
@@ -868,7 +868,9 @@ And if interfaces are provided in \code{mpif.h}, they might look like this
 \end{lstlisting}
 \end{implementors}

-\begin{users}
+\begin{example}
+\exindex{Profiling interface!measurement wrapper}%
+\Exindex{Fortran}{Measurement wrapper}{MPI\_ISend}%
 The following is an example of how
 a user-written or middleware profiling routine
 can be implemented:
@@ -889,7 +891,8 @@ SUBROUTINE MPI_Isend_f08ts(buf,count,datatype,dest,tag,comm,request,ierror)
     ! ... some code for the end of profiling
 END SUBROUTINE MPI_Isend_f08ts
 \end{lstlisting}
-
+\end{example}
+\begin{users}
 Note that this routine is used to intercept the existing specific
 procedure name \ffunc{MPI\_Isend\_f08ts} in the \MPI/ library.
 This routine must not be part of a module.

The atoi immediately above has a couple of lstlisting blocks that are also providing examples of binding implementations, which could be changed similarly.

The intent as I recall is improving both indexing and formatting of the listing blocks.

[gcorbin]

I have looked through the rest of chapter 19 and found one additional instance that could be an example: The advice to implementors at the end of 19.1.6.

There is also some usage of the example environment inside an advice to implementors, e.g. in 19.1.9 in the MPI_TYPE_MATCH_SIZE example. This style could also be used here.

[wesbland]

@mahermanns This issue is still on track for 4.2 in terms of timelines. Did you want to announce it for a vote at the December meeting?