Improve binding macros

[wgropp]

Problem

The binding macros don't clearly separate routine names from their parameters, making some other processing more difficult. In particular, indexing requires additional processing, since the parameter lists need to be removed in a separate step before running makeindex to generate the indices. In addition, other processing within LaTeX is also made more challenging; for example, it would be easier to automatically generate labels and references to definitions, without resorting to a separate program as is done now.

Proposal

Update the macros in mpi-user-macs.tex to use separate arguments for the routine name and the parameter list. Update (better, replace) the index creation script so that it doesn't need to deal with this case in the future. Update the pythonization code to generate the new macros.

Changes to the Text

None.

Impact on Implementations

None.

Impact on Users

None.

References

[martinruefenacht]

Could you give me a quick overview for the index generation? (what files and what procedure happens from the current Latex)

I think we can just modified the binding_emitter to output whatever is required to build the correct index. The binding_emitter is aware of everything in respect to the Latex.

[wgropp]

There are two distinct items, and I think there is confusion in the language. The indices are mappings from names to pages; this must be implemented with LaTeX/TeX as well as some post-processing since that is where the pages are issued. This process works well at this point; the process is that \index{} generates labeled entries in mpi-report.idx, which are filtered by buildindices and then those filtered subsets are given to makeindex (a standard program in TeX installations) to create the indices. There is no need to change (much) of this, though we can augment these as I've noted above (and to fix the callback PR, I've already implemented some of this).

Where I think the python interface can substantially improve the process is in the construction of the bindings summary, which was until recently done with the old script MAKE-APPLANG, and is now done with buildapplang, which is really just a slightly better implementation of the same approach as in MAKE-APPLANG. These programs extract the various definitions directly from the TeX source files, looking for the various binding macros. Creating these summaries could be better done directly from the pythonization, eliminating MAKE-APPLANG/buildapplang.

Related to this is extracting the constants and handles that are in the summary. This is probably best done by enhancing the index processing in buildindices, e.g. for the predefined info keys and values, and building on the LaTeX macros used to mark the different constants and MPI handles.

[RolfRabenseifner]

I want to remeber my proposal in https://github.com/mpi-forum/mpi-standard/pull/449#discussion_r552035140

I still believe that this can be a short "hack" for MPI-4.0:

• adding the indexing begin{funcdef}{MPI_SEND\mpifuncmainindex{MPI_SEND}(\mbox{buf}, ...
  right after the LIS function name (simple addition to bindinglis.py),

\begin{funcdef}{MPI_SEND\mpifuncmainindex{MPI_SEND}(\mbox{buf}, ... \mbox{comm})}
\funcarg ...

or as currently done, at the end of the parameter list on the procedure declaration statement, i.e.,

\begin{funcdef}{MPI_SEND(\mbox{buf}, ... \mbox{comm})}
\mpifuncmainindex{MPI_SEND}%
\funcarg ...

• removing the \mpifuncmainindex from the funcdef macro

[wgropp]

Rolf, I don't see the value in your proposal. What does it accomplish that changes the PDF?

[RolfRabenseifner]

I do not understand your question. My answer is about, how can the macro-calls be modified that without changeing the pdf, the indexing macros are done only with the function name, and not with the whole argument list, as in the moment. And this was, what you asked for in the "Problems" section.
My proposal is only a change of the .py scripts and one macro (funcdef), not of any chap-/.tex

[wgropp]

And I don't understand your answer. If the current approach is working, and your proposal would only cause additional work for the document editor, as well as introduce a new and inconsistent approach to indexing, why is this needed? Again I ask: What is the value in this proposal?

[RolfRabenseifner]

You wrote

The binding macros don't clearly separate routine names from their parameters, making some other processing more difficult. In particular, indexing requires additional processing, since the parameter lists need to be removed in a separate step before running makeindex to generate the indices.

My proposal is, that the indexing macro is no longer

\indexentry{MPI_SEND(\unhbox \voidb@x \hbox {buf}, \unhbox \voidb@x \hbox {count}, \unhbox \voidb@x \hbox {datatype}, \unhbox \voidb@x \hbox {dest}, \unhbox \voidb@x \hbox {tag}, \unhbox \voidb@x \hbox {comm})|hyperindexformat{\uu}}{30}

but only

\indexentry{MPI_SEND|hyperindexformat{\uu}}{30}

i.e., that such "indexing requires additional processing, since the parameter lists need to be removed in a separate step" is no longer needed.

As far as I understand, funcdef and its use is the only remaining location with this problem.

[wgropp]

But the index files need to be processed anyway, to separate out the different entries. Making the change to something that you agree is working fine is just extra work - and again, it breaks the design approach that I've taken, which is one based on using higher level markup in the document. I still see no value in making a change that adds work to me and doesn't change the document.

[RolfRabenseifner]

Sorry, I wanted only to help. Please forget about my answers.

[VictorEijkhout]

On , 2021Jan15, at 11:11, Rolf Rabenseifner <notifications@github.com<mailto:notifications@github.com>> wrote: \indexentry{MPI_SEND(\unhbox \voidb@x \hbox {buf}, \unhbox \voidb@x \hbox {count}, \unhbox \voidb@x Wow. I thought I knew something about TeX…. The first unhbox puts you in horizontal mode. Not that I see that’s necessary, but…. What’s the second for? Victor.

[RolfRabenseifner]

@VictorEijkhout
As @wgropp wrote in the abstract, there is an "additional processing, since the parameter lists need to be removed in a separate step before running makeindex to generate the indices".
this means for Latex, in this additional shell scipt, this entry is reduced to \indexentry{MPI_SEND|hyperindexformat{\uu}}{30}

[wgropp]

I am closing this as unnecessary.