Missing entries in the Index pages.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-04-05 10:17:58 -0500

---

Description

Some constants and other information, especially when given in a Latex verbatim environment, are missing in the index.

History

I've done most of this work with the index pages, but some references are still missing. It would be great, if the chapter authors could help in this process.

Based only by my user basis, I know that about 500 persons have used MPI-1.1 and MPI-2.0 printed books, and about 700 MPI-2.1 book are already shipped.

Proposed Solution

E.g. for the constants in table p14.47 - p15.5 (may be extended with MPI_UNWEIGHTED by #33)
one must add
\cdeclindex{MPI_BOTTOM}%[[BR]]
\cdeclindex{MPI_STATUS_IGNORE}%
before the verbatim list and
\cdeclindex{MPI_STATUSES_IGNORE}%[[BR]]
\cdeclindex{MPI_ERRCODES_IGNORE}%[[BR]]
\cdeclindex{MPI_IN_PLACE}%[[BR]]
\cdeclindex{MPI_ARGV_NULL}%[[BR]]
\cdeclindex{MPI_ARGVS_NULL}%
after the list.
(Normally, one can put all before the list. It is not perfect, but better than nothing.)

All chapter authors should check, whether there are other constants in verbatim that should be added to the constants-index.

Other examples of existing bugs:

• p17:9-10 MPI_LB and MPI_UB must be \const and not \func
• p97:2 "MPI_TYPE_UB, MPI_TYPE_LB" must be written in two separate macros
• p350:27-28 "MPI_WIN_POST, MPI_WIN_FENCE" must be written in two separate macros

Impact on Implementations

None.

Impact on Applications / Users

None.

Alternative Solutions

None.

Entry for the Change Log

None.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-04-05 10:32:02 -0500

---

I added all chapter authors to the CC list.

It would be nice if I can get 4 okays (showing that there is no consistncy error) to switch it to reviewed.

It is important to say, that the proposed solution does not change the content of the chapters. It is handled by Latex as if one puts a full comment line.
(The trick is, that the line ends with an % directly after the macro. If you put two such macros on one line, then there must not be a space or % between.)

I.e., this ticket would be in the category "no text change", but this category does not exist ;-)

[mpiforumbot]

Originally by gropp on 2009-04-05 13:30:13 -0500

---

For the chapter authors, there is now a Makefile in each chapter's directory. Running "make" (no options) will built that chapter, including a basic index. This index includes all items for which some index entry will be created; it isn't separated into constant, function, etc. indices. This should make it easier to check your chapter - just print out the index, then go through each page and make sure that all relevant items appear.

[mpiforumbot]

Originally by traff on 2009-04-06 02:57:44 -0500

---

I'm not quite sure what required here, but it's important that such constants appear in the
index, and I'll help with that for you chapters. So the ticket is, I think, fine with me.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-04-07 09:12:20 -0500

---

Status to Reviewed based on Bill's decision.

[mpiforumbot]

Originally by jsquyres on 2009-04-07 09:26:39 -0500

---

This is not a normal ticket, right? It is action required by the chapter authors and does not require a normal Forum process (reading, voting, etc.), right?

So "Reviewed" is kinda meaningless here, right?

[mpiforumbot]

Originally by gropp on 2009-06-17 11:51:24 -0500

---

Note that all authors should check for the use of MPI constants in verbatim environments or in verbs, and add the appropriate indexing macro. Be careful that you do not add extra spaces (e.g., using the indexing macro with spaces around it can add extra spaces).

[mpiforumbot]

Originally by bosilca on 2009-07-20 17:12:26 -0500

---

I would like to help here, but there are several dark areas on what and how I'm supposed to do it. This ticket only talks about MPI constants but when I look in the tex files \cdeclindex is used not only for constants but even for types such as MPI_Errhandler. However, it is not used for MPI_Datatype, MPI_Comm or MPI_Aint. Thus, we should clarify exactly what kind of constants/types/whatever we want to capture in the index table before stating to do the modifications on the tex files as these modifications will be quite intrusive.

Second question, how do we deal with the long tables? As an example, in the chapter 8 there is a 3 pages long table. Where should I add the \cdeclindex in order to capture the interesting information (i.e. the page number I guess) ?

[mpiforumbot]

Originally by jsquyres on 2009-07-21 11:44:24 -0500

---

Replying to bosilca:

I would like to help here, but there are several dark areas on what and how I'm supposed to do it.

Ditto on everything George said -- let us know what you want, and I'll do it in the bindings chapter.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-07-21 13:53:26 -0500

---

• All index possibilities can be found in mpi-macs.tex

-Examples Index:*

• \exindex{MPI_FILE_CLOSE}% in this example, Fortran MPI_FILE_CLOSE is used
• \exindex{MPI_Group_free}% in this example, C MPI_Group_free is used
• \exindex{Intercommunicator}% an intercommunicator example

-Function Index:*

• \mpifuncmainindex{MPI_COMM_CLONE}% [[BR]]
  this is the main entry of MPI::Comm::Clone

  This is a strange thing and introduced because the "MPI Function Index"
  p.581ff shows only language independent names. The main index is normally
  done automatically through \begin{funcdef}{....}, \begin{funcdef2}{....},
  or \begin{funcdefna}{....}.

• \mpifuncmainindex{MPI_COMM_DUP_FN}% [[BR]]
  The routine MPI_COMM_DUP_FN is not regularly declared with
  \begin{funcdef}{....}.
  Therefore, manual indexing is necessary.

• \mpifuncindex{MPI_WAITALL}\mpifuncindex{MPI_WAITANY}%
  is used in combination with
  \mpiskipfunc{MPI_WAIT\textrm{{}ANY$|$ALL\textrm{}}}
  because we do not want the comnbined notations in the index.

• Normally \mpifunc{MPI_WAIT} writes the routine name and produces an index.

• \mpiskipfunc{MPI_WAIT} writes MPI_WAIT but does not produce an index.

-Callback Function Prototype Index:*

• \typedefindex{MPI_Handler_fuction}% [[BR]]
  produces an index in the
  "Callback Function Prototype Index".

  This is done normally automatically through \mpitypedefbind or
  \mpitypedefbindvoid.

-"MPI Constant and Predefined Handle Index" and "MPI Declarations Index":*

• If the name is MPI_.....[A-Z0-9] then it is sorted into the
  "MPI Constant and Predefined Handle Index".
• If the name is MPI_.....[a-z] then it is sorted into the
  "MPI Declarations Index".
• E.g., \cdeclindex{MPI_BOTTOM}%[[BR]]
  or \cdeclindex{MPI_Cartcomm}%[[BR]]
  maybe used if MPI_BOTTOM or MPI_Cartcomm are inside of a verbatim.
• Normally, the index is done automatically through the use of
  \const, \consti, \type, \shorttype, and \error.
• The macros \info and \infoval write a index entries, but they start
  not with MPI_... and are therefore ignored.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-07-21 14:17:21 -0500

---

I forget to say, that the routines mpirun and mpiexec are also in the Function Index. This is done through special coding in MAKE-FUNC-INDEX, which is doing all the index pages.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-07-26 14:31:41 -0500

---

I checked the whole Function Index for wrong entries. I found the following additional bugs (as already mentioned in ticket #142):

• p17:9-10 MPI_LB and MPI_UB must be \const and not \func
• p97:2 "MPI_TYPE_UB, MPI_TYPE_LB" must be written in two separate macros
• p350:27-28 "MPI_WIN_POST, MPI_WIN_FENCE" must be written in two separate macros

I added these to the "proposed solution".

[mpiforumbot]

Originally by gropp on 2009-07-27 09:18:26 -0500

---

Changes such as the ones Rolf notes should be made by the respective chapter author or by the chair, they do not require separate mention in the proposed solution.

[mpiforumbot]

Originally by gropp on 2009-07-30 11:38:02 -0500

---

As a reminder, information on adding index entries is in the README-2.2 file. Please refer to that for any questions about indexing.

[mpiforumbot]

Originally by htor on 2009-07-30 18:15:28 -0500

---

I just checked the collectives chapter. All \func and \const macros seem to be used correctly. The verbatim declindex issue doesn't seem to apply because the examples don't use special constants (yes, we don't have an example for MPI_IN_PLACE). All examples seem to have the correct \exindex macros.

[mpiforumbot]

Originally by bronis on 2009-08-13 18:31:05 -0500

---

I have added entries for the profiling chapter. I will take care of the external interfaces chapter soon. It is not clear to me how these changes will be reviewed. The only applicable PDF is the index. Is the last person done with their chapter supposed to post the PDF? How would anyone check it?

[mpiforumbot]

Originally by asupalov on 2009-08-17 07:24:17 -0500

---

Pray and hope for Annex to be resolved automagically thru cut-and-paste of the similar entries. Someone will need to carefully check this.

[mpiforumbot]

Originally by RolfRabenseifner on 2009-08-29 01:49:40 -0500

---

Because this ticket contains only examples (and all are done), a formal PDF review is not needed.

The MPI-2.2 Latex editing phase should be over. We are now in the review phase.

Therefore switch to "Ticket complete".

[mpiforumbot]

Originally by jsquyres on 2010-09-18 05:08:11 -0500

---

This ticket is (long-since) complete; marking it resolved/text committed.