Document Conventions

[wgropp]

Problem

The style used in the document is inconsistent. This issue lists some for further discussion

Proposal

1. Starting p31 (maybe). Different versions of the equals sign (=) are used in several different contexts.

   a) a = b might mean: (p98 uses both)
   i) a has the value b (in a test)
   ii) a is given the value b (in a result)

   b) both \mpicode{=} and \code{=} are used (see p121, lines 24 and 32 for both uses and p 598, lines 12 and 16). There may also be some $=$ (need to check).

   Should we define \hasvalue{a}{b} for these to make them consistent? p 411, line 8 has a not-equal version (do we need \hasvaluenot?)

2. Position of floats (tables and figures). Top, Here, or something else? Also, provide guidance in the instr.tex.
   Specific examples
   a. page 33, where a table interrupts a fnewbind list.
   b. page 205, figure 6.5, interrupts an example.
   c. page 206, figure 6.6, interrupts an example.
   d. page 215, figure 6.10, interrupts an example.
   e. page 306, figure 6.13, interrupts an example.

3. Use of page numbers. See p36. My preference is: Use \sectionref{} unless the reference is to a particular page, not the entire section. p36 would probably not qualify. Possible exception - the change log, not because it is a good idea to include the page numbers but because there are many existing references that include the page numbers. But going forward, links, not page numbers, should be preferred.

4. \code (language specific, e.g., C or Fortran) and \mpicode (language neutral) are used often interchangeably, which they are not. This is also reflected in Boolean values have inconsistent font; see p 121.

5. p 213 (and elsewhere). Code fragments intended to explain what an MPI routine does (e.g., "outcome is as if ...") are in inconsistent font and language choice. They should be in language-neutal, for which we'd need to define a new language dialect. Compare with p217, lines 22-23, which appears to be in C. Also see p 221, where \cdot is used instead of *, as well as no spacing after commas but a space after (but not before) the \cdot. Similar on p 223, 226. p414 uses C code (in lstlisting format).

6. Tables of constants (e.g., see p 229, lines 7-20). These are a mix of constlist and tabular. In addition, there is no consistency for headings, either in terms of fonts or spacing.

7. Font choices for variables representing processes or buffers. See, e.g., p 251, lines 12-14. $i$ is used for the process with rank $i$. Other places use \mpicode (or \code?). E.g., p 413Need to pick and document one choice and use consistently.

8. The context chapter regularlly inserts \noindent after the language bindings, so that the following paragraph (if any) starts without an indent. This is inconsistent with the rest of the document. Either remove these indents (preferred) or add others everywhere else. A third option is to try to add an auto-no-indent (similar to what the \section macros do), to get uniform behavior.

9. p 341, line 2. Should references to examples (and figures and tables and sections) capitalize example/figure/table/section? Here, example is not capitalized.

10. p 342, line12 and later. Info keys are described in several places, but not consistently. For example, this location uses a format of:
    info-key-name (type, default: value)
    e.g.,
    "mpi_assert_no_any_tag" (boolean, default: "false")
    p 511 does the same, including "no set by default" where there is no default. p 552-3 uses this format.
    p 486, for example, doesn't include the type or default, nor does p 497, p 545.
    p 651 does not include default but does add [SAME} when all processes must provide the same value.

11. p 344, line 16. Is it key/value or (key,value)? Compare p 397, line 5. And is there a space after the comma (see p 447, line 38)

12. p 375 and others (starting p 63), we use XXX to mean "replace with any valid name in this context". On p 375, we use {XXX} instead. Is this instead a formatting error (use XXX only)? Others at p 455 (also uses YYY)

13. p 382-3 Enumerated lists should use enumerate insted of itemize - this is described as two rules, and should give numbered rules.

14. (note only: nothing to change): use .TRUE. (uppercase) for Fortran true value.

15. Never, ever use lower case l as an index (see p422, line 11).

16. p 422, lines 5ff. Note the different fonts for index variables, depending on how they are used. Is this what we want?

17. Spacing in code. Normally, expect spaces before { (or separate line). p448, example 9.1 does not. It also has shallow indentation (3 instead of 4 spaces). Do we want to have a convention(s)?

18. p 491 (and others, e.g., p 498, p546) We also use MPI_{TEST|WAIT}{|ANY|SOME|ALL} instead of the XXX notation. There should be a clear convention on this, and use of this form instead of XXX where appropriate.

19. p 537, line 44, uses "(hostname:port)" (without the quotes) to indicate a string containing a hostname and port number. The use of parenthesis is an odd choice.

20. The phrase 'simply contiguous' (with the quotes) is used in many places. This use of quotes is unusual in the document. Other uses use double quotes (``wrapper'', e.g.). There are a few other places that use a single quote, e.g., `hello world'. Need to pick a convention for single or double quotes. Note that p 803 line 35 uses double quotes.

21. In some places, a routine name is written with parens, as in read() (page 655, line 31). Is this our convention? We rarely (never?) do this for MPI routines. Is this particular place special because these are external routine names? See also p811.

22. p 796 has some MPI_XXXX_FTS and MPI_Xxxx_f08ts. These don't match the other uses of XXX in MPI names.

23. p 1065ff. Do we really need all of these explicit page numbers? Note that by using \sectionref, it is easy to generate a version of the standard that includes the page number.

24. p 1128 and elsewhere. Should the info value "true" be indexed?

Changes to the Text

To be determined

Impact on Implementations

None

Impact on Users

Improved document

References and Pull Requests